feat: add bracket string literal syntax support and enhance path parsing

Author: birdnamoo

docs/CHANGELOG.md

@@ -9,14 +9,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Bracket string literal syntax**: Access keys containing special characters using `["key.name"]` or `['key.name']`
+  - Supports keys with dots: `["my.config"]`
+  - Supports keys with brackets: `["items[0]"]`
+  - Supports escaped quotes: `["key\"quote"]`
+  - Works with JSON, dictionaries, and mixed paths
 - **Enhanced type conversion**: Support for `Enum`, `Guid`, and `Nullable<T>` types in `GetValue<T>()`
 - **Smarter JSON number handling**: JSON integers return `int`/`long`, floats return `double` (previously all returned `decimal`)
 - **XML documentation**: Added comprehensive XML docs to `ToExpando()` method
-- **New tests**: 13 additional test cases for bug fixes and improvements (108 total)
+- **New tests**: 24 additional test cases for new features (119 total)
 - **Cache management**: `ClearCaches()` public method for testing and memory management
 - **Cache size limits**: Automatic cache trimming when exceeding 1000 entries to prevent memory leaks
 - **Dictionary reflection caching**: Cached `IDictionary<string, T>` interface info for improved performance
 
+### Changed
+
+- **Path parser**: Replaced simple `Split()` with stateful tokenizer for bracket literal support
+
 ### Fixed
 
 - **TryGetValue return logic**: Now correctly returns `true` for valid paths even when the value is `null`

src/Directory.Build.props

@@ -7,7 +7,7 @@
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
 
     <!-- Package Metadata -->
-    <Version>1.3.0</Version>
+    <Version>1.4.0</Version>
     <Authors>iyulab</Authors>
     <Company>Iyulab Corporation</Company>
     <Owners>iyulab</Owners>

src/ObjectPath.Tests/ObjectPathTests.cs

@@ -1931,4 +1931,189 @@ public void InvalidArrayIndex_ExceptionIncludesFullPath_ForJsonElement()
     }
 
     #endregion
+
+    #region Path Escape Syntax Tests
+
+    public class BracketStringLiteralTests
+    {
+        [Fact]
+        public void GetValue_DoubleQuoteBracket_AccessesKeyWithDot()
+        {
+            // Arrange
+            var dict = new Dictionary<string, object>
+            {
+                ["my.key"] = "value with dot"
+            };
+
+            // Act
+            var result = ObjectPath.GetValue(dict, "[\"my.key\"]");
+
+            // Assert
+            Assert.Equal("value with dot", result);
+        }
+
+        [Fact]
+        public void GetValue_SingleQuoteBracket_AccessesKeyWithDot()
+        {
+            // Arrange
+            var dict = new Dictionary<string, object>
+            {
+                ["my.key"] = "value with dot"
+            };
+
+            // Act
+            var result = ObjectPath.GetValue(dict, "['my.key']");
+
+            // Assert
+            Assert.Equal("value with dot", result);
+        }
+
+        [Fact]
+        public void GetValue_BracketKey_AccessesKeyWithBrackets()
+        {
+            // Arrange
+            var dict = new Dictionary<string, object>
+            {
+                ["key[0]"] = "value with brackets"
+            };
+
+            // Act
+            var result = ObjectPath.GetValue(dict, "[\"key[0]\"]");
+
+            // Assert
+            Assert.Equal("value with brackets", result);
+        }
+
+        [Fact]
+        public void GetValue_MixedSyntax_WorksCorrectly()
+        {
+            // Arrange
+            var data = new Dictionary<string, object>
+            {
+                ["config.settings"] = new Dictionary<string, object>
+                {
+                    ["value"] = 42
+                }
+            };
+
+            // Act - Access "config.settings" key, then "value" property
+            var result = ObjectPath.GetValue(data, "[\"config.settings\"].value");
+
+            // Assert
+            Assert.Equal(42, result);
+        }
+
+        [Fact]
+        public void GetValue_NestedBracketKeys_WorksCorrectly()
+        {
+            // Arrange
+            var data = new Dictionary<string, object>
+            {
+                ["level.one"] = new Dictionary<string, object>
+                {
+                    ["level.two"] = "nested value"
+                }
+            };
+
+            // Act
+            var result = ObjectPath.GetValue(data, "[\"level.one\"][\"level.two\"]");
+
+            // Assert
+            Assert.Equal("nested value", result);
+        }
+
+        [Fact]
+        public void GetValue_EscapedQuotes_WorksCorrectly()
+        {
+            // Arrange
+            var dict = new Dictionary<string, object>
+            {
+                ["key\"quote"] = "escaped quote value"
+            };
+
+            // Act - Use backslash to escape the quote
+            var result = ObjectPath.GetValue(dict, "[\"key\\\"quote\"]");
+
+            // Assert
+            Assert.Equal("escaped quote value", result);
+        }
+
+        [Fact]
+        public void GetValue_CombinedWithArrayIndex_WorksCorrectly()
+        {
+            // Arrange
+            var data = new Dictionary<string, object>
+            {
+                ["items.list"] = new List<object> { "first", "second", "third" }
+            };
+
+            // Act
+            var result = ObjectPath.GetValue(data, "[\"items.list\"][1]");
+
+            // Assert
+            Assert.Equal("second", result);
+        }
+
+        [Fact]
+        public void GetValue_JsonElement_WithBracketSyntax()
+        {
+            // Arrange
+            var json = """{"data.key": {"nested.prop": "json value"}}""";
+            var doc = JsonDocument.Parse(json);
+
+            // Act
+            var result = ObjectPath.GetValue(doc.RootElement, "[\"data.key\"][\"nested.prop\"]");
+
+            // Assert
+            Assert.Equal("json value", result);
+        }
+
+        [Fact]
+        public void GetValue_RegularObjectAfterBracketKey_WorksCorrectly()
+        {
+            // Arrange
+            var dict = new Dictionary<string, object>
+            {
+                ["my.config"] = new { Name = "Test", Value = 123 }
+            };
+
+            // Act
+            var name = ObjectPath.GetValue(dict, "[\"my.config\"].Name");
+            var value = ObjectPath.GetValue(dict, "[\"my.config\"].Value");
+
+            // Assert
+            Assert.Equal("Test", name);
+            Assert.Equal(123, value);
+        }
+
+        [Fact]
+        public void TryGetValue_WithBracketSyntax_ReturnsTrue()
+        {
+            // Arrange
+            var dict = new Dictionary<string, object> { ["a.b"] = "value" };
+
+            // Act
+            var result = ObjectPath.TryGetValue(dict, "[\"a.b\"]", out var value);
+
+            // Assert
+            Assert.True(result);
+            Assert.Equal("value", value);
+        }
+
+        [Fact]
+        public void TryGetValue_WithInvalidBracketKey_ReturnsFalse()
+        {
+            // Arrange
+            var dict = new Dictionary<string, object> { ["key"] = "value" };
+
+            // Act
+            var result = ObjectPath.TryGetValue(dict, "[\"nonexistent.key\"]", out var value);
+
+            // Assert
+            Assert.False(result);
+            Assert.Null(value);
+        }
+    }
+
+    #endregion
 }

src/ObjectPath/ObjectPath.cs

@@ -8,8 +8,6 @@ namespace ObjectPathLibrary
 {
     public static class ObjectPath
     {
-        private static readonly char[] Separator = new[] { '.', '[', ']' };
-
         /// <summary>
         /// Maximum number of entries in each cache. When exceeded, oldest entries are removed.
         /// </summary>
@@ -24,7 +22,7 @@ public static class ObjectPath
             if (obj == null) return null;
             if (string.IsNullOrEmpty(path)) return obj;
 
-            var segments = path.Split(Separator, StringSplitOptions.RemoveEmptyEntries);
+            var segments = ParsePath(path);
             int index = 0;
 
             while (obj != null && index < segments.Length)
@@ -343,6 +341,109 @@ public static bool TryGetValue<T>(object? obj, string path, out T? value, bool i
             return fieldInfo;
         }
 
+        /// <summary>
+        /// Parses a path expression into segments, supporting:
+        /// - Dot notation: "User.Name" → ["User", "Name"]
+        /// - Bracket index: "Items[0]" → ["Items", "0"]
+        /// - Bracket string literals: "Data[\"my.key\"]" or "Data['my.key']" → ["Data", "my.key"]
+        /// </summary>
+        private static string[] ParsePath(string path)
+        {
+            var segments = new List<string>();
+            var current = new System.Text.StringBuilder();
+            int i = 0;
+
+            while (i < path.Length)
+            {
+                char c = path[i];
+
+                if (c == '.')
+                {
+                    // Dot separator - finish current segment
+                    if (current.Length > 0)
+                    {
+                        segments.Add(current.ToString());
+                        current.Clear();
+                    }
+                    i++;
+                }
+                else if (c == '[')
+                {
+                    // Start of bracket expression
+                    if (current.Length > 0)
+                    {
+                        segments.Add(current.ToString());
+                        current.Clear();
+                    }
+                    i++;
+
+                    if (i < path.Length && (path[i] == '"' || path[i] == '\''))
+                    {
+                        // String literal: ["key"] or ['key']
+                        char quote = path[i];
+                        i++;
+                        while (i < path.Length && path[i] != quote)
+                        {
+                            if (path[i] == '\\' && i + 1 < path.Length)
+                            {
+                                // Handle escape sequences
+                                i++;
+                                current.Append(path[i]);
+                            }
+                            else
+                            {
+                                current.Append(path[i]);
+                            }
+                            i++;
+                        }
+                        if (i < path.Length) i++; // Skip closing quote
+                        if (i < path.Length && path[i] == ']') i++; // Skip closing bracket
+
+                        if (current.Length > 0)
+                        {
+                            segments.Add(current.ToString());
+                            current.Clear();
+                        }
+                    }
+                    else
+                    {
+                        // Numeric index: [0]
+                        while (i < path.Length && path[i] != ']')
+                        {
+                            current.Append(path[i]);
+                            i++;
+                        }
+                        if (i < path.Length) i++; // Skip closing bracket
+
+                        if (current.Length > 0)
+                        {
+                            segments.Add(current.ToString());
+                            current.Clear();
+                        }
+                    }
+                }
+                else if (c == ']')
+                {
+                    // Unexpected closing bracket - skip
+                    i++;
+                }
+                else
+                {
+                    // Regular character
+                    current.Append(c);
+                    i++;
+                }
+            }
+
+            // Add final segment
+            if (current.Length > 0)
+            {
+                segments.Add(current.ToString());
+            }
+
+            return segments.ToArray();
+        }
+
         private static DictionaryTypeInfo? GetCachedDictionaryTypeInfo(Type type)
         {
             if (!DictionaryTypeCache.TryGetValue(type, out var typeInfo))