Immutable DTO for hocon #106

Arkatufus · 2019-07-29T20:32:03Z

Add immutable support library for materialized Hocon:
- Class types are reduced to Object, Array, and Literal value type
- Object value class emulates ImmutableDictionary, with a custom indexer that can directly take a Hocon path, with an ImmutableSortedDictionary as a backing data source
- Array value class emulates ImmutableList, with an ImmutableArray as a backing data source.
- Literal value is just a wrapper around a string to make it immutable.
Improved data access API for the immutable tree:
- Objects can be accessed directly using string or HoconPath path inside the dictionary-like indexer. Eg. config["root.first-object.first-property"] will treat config as an object value and traverse to the "root.first-object.first-property" path.
- The library is smart enough to deduce data access from indexer type, integer indexer will be automatically interpreted as array access, string indexer will be automatically interpreted as path traversal. Eg. config["root.my-array"][0] will treat the config instance as a Hocon object, traverse it to the "root.my-array" value, and then the [0] indexer will treat that value as an array. It will read array values directly, or if it is an object value, will try to convert it into an array using the "positively numeric keyed object to array convertion" rule. Accessing a literal value using any indexers will throw an exception.
- Literal values are automatically converted/parsed when accessed. Eg. byte value = config["root.byte-value"], the value will be auto convert to byte and assigned to the variable. Auto convert will validate the conversion on the fly and throws an exception if the conversion is invalid.
- Generic getter implementation. You can use the generic getter instead of relying on the auto type conversion. Eg. var myIntArray = config["root.int-array"].Get<int[]>() will return an array of ints from "root.int-array" path, or var myTimeSpan = config["root.time-span"].Get<TimeSpan>() will return a TimeSpan from "root.time-span" path.
- Old style getters are still supported, you can still use myConfig.Value.GetInt(), myConfig.Value.GetInt("my-path") etc. ~~but they will only work on the Literal class instance, you can not pass a Hocon path into them anymore.~~ The .Value property is deprecated, it is included just to maintain backward compatibility with old code.
- Auto-casting and generic getter only works for primitive types, there are no POCO class converter support yet.
- Supported auto-cast and generic types: bool, byte, sbyte, short, ushort, int, uint, long, ulong, BigInteger, float, double, decimal, TimeSpan, string, and their array variant (eg. bool[] and byte[])

Arkatufus · 2019-08-11T15:25:07Z

I'm maintaining full backward compatibility with the old API. Should this be a separate library or should it be folded back into the core project? Ie, should config immutability be the default?

iron9light · 2019-08-12T19:47:25Z

You wanna re-implemented with all immutable data struct?
That's a good idea. It will be easier to do things right and easier to test.
I think backward compatibility is not a must-have.
You can make it HOCON 2.0 and keep maintain a HOCON 1.x branch for bug fixing.

Arkatufus · 2019-08-26T06:21:33Z

The original HOCON API are all immutable, I'm just trying to see if we should stick to the original material, plus immutability does have its advantages. Programmatic HOCON building/materialization is also supported using a builder pattern, instead of using the fluent .With pattern, which I kind of hate, because it is so memory intensive.

Arkatufus

Code documentation for builder pattern API, generic getter API, and API backward compatibility

Arkatufus · 2019-09-07T11:33:56Z

src/Hocon.Immutable/Extensions/HoconImmutableExtensions.cs

+                        .AddRange(value)
+                        .Build();
+                case HoconType.Literal:
+                    return new HoconImmutableLiteralBuilder()


Sample for immutable Hocon literal builder pattern API, it acts/behaves exactly like a string builder.

Arkatufus · 2019-09-07T11:44:35Z

src/Hocon.Immutable/Extensions/HoconImmutableExtensions.cs

+                        .Merge(value.GetObject())
+                        .Build();
+                case HoconType.Array:
+                    return new HoconImmutableArrayBuilder()


Sample for immutable Hocon Array builder pattern API, it inherits from List<HoconImmutableElement>, where HoconImmutableElement is the base class for immutable object, array, and literal. Usage acts/behaves exactly like a List

Arkatufus · 2019-09-07T11:46:33Z

src/Hocon.Immutable/Extensions/HoconImmutableExtensions.cs

+            switch (value.Type)
+            {
+                case HoconType.Object:
+                    return new HoconImmutableObjectBuilder()


Sample for immutable Hocon Object builder pattern API, it inherits from SortedDictionary<string, HoconImmutableElement>, where HoconImmutableElement is the base class for immutable object, array, and literal. Usage acts/behaves exactly like a SortedDictionary

Arkatufus · 2019-09-07T11:49:00Z

src/Hocon.Immutable/Extensions/HoconImmutableExtensions.cs

+
+namespace Hocon.Immutable.Extensions
+{
+    public static class HoconImmutableExtensions


Contains all of the static ToHoconImmutable extension helper class. Converts the old Hocon classes into its immutable variant.

Arkatufus · 2019-09-07T11:51:41Z

src/Hocon.Immutable/Extensions/TypeConverterExtensions.cs

+
+namespace Hocon.Immutable.Extensions
+{
+    public static class TypeConverterExtensions


Contains static helper extension functions to cast HoconImmutableElement class back into immutable object, array, or literal.

Arkatufus · 2019-09-07T13:16:18Z

src/Hocon.Immutable/Extensions/GenericGetterExtensions.cs

+
+namespace Hocon.Immutable.Extensions
+{
+    public static class GenericGetterExtensions


Generic value getter implementation. Converts an immutable Hocon literal string value to another primitive type. Usage: myHoconLiteral.Get<int>()

Arkatufus · 2019-09-07T13:22:10Z

src/Hocon.Immutable/Extensions/ValueGetterExtensions.cs

+
+namespace Hocon.Immutable.Extensions
+{
+    public static class ValueGetterExtensions


Contains static extension convenience helper functions to convert an immutable hocon literal into another primitive type. Sample use: myHoconLiteral.GetDecimal().

Also contains backward compatible getter helper functions that follows the old myHoconObject.GetInt("my.hocon.path") API pattern.

Arkatufus

Code documentation for the immutable API

Arkatufus · 2019-09-07T13:41:56Z

src/Hocon.Immutable.Tests/ApiTest.cs

+  root_2 : 1234
+}";
+            var config = Parser.Parse(hocon).ToHoconImmutable();
+            Assert.True(config["root.bool"].GetBoolean());


Sample use of the new API, it emulates how Microsoft.Extensions.Configuration works, where you can supply a Hocon path into an array indexer to access children values. In this case, config is an immutable Hocon object, and "root.bool" is the path to the "bool" property inside "root" object.

The getter function GetBoolean() acts directly on an ImmutableHoconLiteral object instance. Object instance will be checked during runtime, invalid instance will throw an exception.

Arkatufus · 2019-09-07T13:43:13Z

src/Hocon.Immutable.Tests/ApiTest.cs

+}";
+            var config = Parser.Parse(hocon).ToHoconImmutable();
+            Assert.True(config["root.bool"].GetBoolean());
+            Assert.True(config["root.bool"].Get<bool>());


Generic getter function version (syntactic sugar) of GetBoolean().

Arkatufus · 2019-09-07T14:11:49Z

src/Hocon.Immutable.Tests/ApiTest.cs

+            var config = Parser.Parse(hocon).ToHoconImmutable();
+            Assert.True(config["root.bool"].GetBoolean());
+            Assert.True(config["root.bool"].Get<bool>());
+            Assert.True(config["root.bool"]);


Sample use of the auto-conversion getter. ImmutableHoconLiteral contains implicit cast operator overrides to automatically convert the string value into other primitive types. In this case, it automatically converts the string value to bool

Aaronontheweb · 2019-10-03T02:01:51Z

Have this on my to-do list this Friday

Aaronontheweb

I love this - there's a lot to it but it all looks very well tested and well done.

Question though - why ship it as a separate project? Why not make it part of the whole?

Aaronontheweb · 2019-10-04T20:06:41Z

src/Hocon.Immutable.Tests/ApiTest.cs

+            };
+        [Theory]
+        [MemberData(nameof(ObjectArrayData))]
+        public void CanIntelligentlyUseIndexerTypeToAccessMembers(string hocon)


Very cool - this is a slick addition to the API

Aaronontheweb · 2019-10-04T20:07:06Z

src/Hocon.Immutable.Tests/ApiTest.cs

+  root_2 : 1234
+}";
+            var config = Parser.Parse(hocon).ToHoconImmutable();
+            Assert.True(config["root.bool"].GetBoolean());


Arkatufus · 2019-10-05T11:35:50Z

Question though - why ship it as a separate project? Why not make it part of the whole?

That was what I asked earlier, should I fold this back into the main package or should I keep it separate into an opt-in package.

The main reason I split it up is to make a proof of concept that it works without having to touch the main code; I was not planning on making these backward compatible, but it turns out that making it backward compatible was really trivial.

Aaronontheweb · 2019-10-05T13:04:03Z

Got it - let’s keep it in its own project for now and do a POC while integrating it into Akka.NET

Arkatufus added 2 commits July 30, 2019 02:46

Immutable version of Hocon, Improved value getter API

1f327e9

Merge branch 'dev' into Immutable

6aa0fa4

Arkatufus changed the title ~~Immutable DTO for hocon~~ WIP: Immutable DTO for hocon Jul 29, 2019

Arkatufus added 2 commits August 17, 2019 01:00

Add backward compatibility

98ed44c

Merge branch 'dev' into Immutable

b58a4f6

Arkatufus commented Sep 7, 2019

View reviewed changes

Arkatufus self-assigned this Sep 28, 2019

Arkatufus requested a review from Aaronontheweb September 30, 2019 16:48

Merge branch 'dev' into Immutable

e04ad39

Aaronontheweb reviewed Oct 4, 2019

View reviewed changes

Merge branch 'dev' into Immutable

2810005

Aaronontheweb merged commit 386f3c1 into akkadotnet:dev Oct 5, 2019

Arkatufus changed the title ~~WIP: Immutable DTO for hocon~~ Immutable DTO for hocon Oct 5, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Immutable DTO for hocon #106

Immutable DTO for hocon #106

Arkatufus commented Jul 29, 2019 •

edited

Loading

Arkatufus commented Aug 11, 2019

iron9light commented Aug 12, 2019

Arkatufus commented Aug 26, 2019

Arkatufus left a comment

Arkatufus Sep 7, 2019

Arkatufus Sep 7, 2019

Arkatufus Sep 7, 2019

Arkatufus Sep 7, 2019

Arkatufus Sep 7, 2019

Arkatufus Sep 7, 2019

Arkatufus Sep 7, 2019

Arkatufus left a comment

Arkatufus Sep 7, 2019

Aaronontheweb Oct 4, 2019

Arkatufus Sep 7, 2019

Arkatufus Sep 7, 2019

Aaronontheweb commented Oct 3, 2019

Aaronontheweb left a comment

Aaronontheweb Oct 4, 2019

Aaronontheweb Oct 4, 2019

Arkatufus commented Oct 5, 2019 •

edited

Loading

Aaronontheweb commented Oct 5, 2019

Immutable DTO for hocon #106

Immutable DTO for hocon #106

Conversation

Arkatufus commented Jul 29, 2019 • edited Loading

Arkatufus commented Aug 11, 2019

iron9light commented Aug 12, 2019

Arkatufus commented Aug 26, 2019

Arkatufus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Arkatufus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Aaronontheweb commented Oct 3, 2019

Aaronontheweb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Arkatufus commented Oct 5, 2019 • edited Loading

Aaronontheweb commented Oct 5, 2019

Arkatufus commented Jul 29, 2019 •

edited

Loading

Arkatufus commented Oct 5, 2019 •

edited

Loading