Brought back editorconfig

- Fully commented CSTNet code :D

.editorconfig

@@ -0,0 +1,132 @@
+# editorconfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Default settings:
+# A newline ending every file
+# Use 4 spaces as indentation
+[*]
+charset                  = utf-8
+end_of_line              = crlf
+indent_style             = space
+indent_size              = 4
+insert_final_newline     = false
+trim_trailing_whitespace = true
+dotnet_style_operator_placement_when_wrapping = beginning_of_line
+tab_width = 4
+
+# C# files
+[*.cs]
+# New line preferences
+csharp_new_line_before_open_brace = all
+csharp_new_line_before_else = true
+csharp_new_line_before_catch = true
+csharp_new_line_before_finally = true
+csharp_new_line_before_members_in_object_initializers = true
+csharp_new_line_before_members_in_anonymous_types = true
+csharp_new_line_between_query_expression_clauses = true
+
+# Indentation preferences
+csharp_indent_block_contents = true
+csharp_indent_braces = false
+csharp_indent_case_contents = true
+csharp_indent_switch_labels = true
+csharp_indent_labels = one_less_than_current
+
+# avoid this. unless absolutely necessary
+dotnet_style_qualification_for_field = false:suggestion
+dotnet_style_qualification_for_property = false:suggestion
+dotnet_style_qualification_for_method = false:suggestion
+dotnet_style_qualification_for_event = false:suggestion
+
+# only use var when it's obvious what the variable type is
+csharp_style_var_for_built_in_types = true:none
+csharp_style_var_when_type_is_apparent = true:none
+csharp_style_var_elsewhere = true:suggestion
+
+# use language keywords instead of BCL types
+dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
+dotnet_style_predefined_type_for_member_access = true:suggestion
+
+# Use camel_case for private or internal constant fields
+dotnet_naming_rule.constant_fields_should_be_pascal_case.severity = suggestion
+dotnet_naming_rule.constant_fields_should_be_pascal_case.symbols  = constant_fields
+dotnet_naming_rule.constant_fields_should_be_pascal_case.style = pascal_case_style
+
+dotnet_naming_symbols.constant_fields.applicable_kinds   = field
+dotnet_naming_symbols.constant_fields.required_modifiers = const
+
+dotnet_naming_style.pascal_case_style.capitalization = pascal_case
+
+# Comment this group and uncomment out the next group if you don't want _ prefixed fields.
+
+# internal and private fields should be _camel_case
+dotnet_naming_rule.camel_case_for_private_internal_fields.severity = suggestion
+dotnet_naming_rule.camel_case_for_private_internal_fields.symbols  = private_internal_fields
+dotnet_naming_rule.camel_case_for_private_internal_fields.style = camel_case_underscore_style
+
+dotnet_naming_symbols.private_internal_fields.applicable_kinds = field
+dotnet_naming_symbols.private_internal_fields.applicable_accessibilities = private, internal
+
+dotnet_naming_style.camel_case_underscore_style.required_prefix = _
+dotnet_naming_style.camel_case_underscore_style.capitalization = camel_case
+
+# Code style defaults
+dotnet_sort_system_directives_first = true
+csharp_preserve_single_line_blocks = true
+csharp_preserve_single_line_statements = false
+
+# Expression-level preferences
+dotnet_style_object_initializer = true:suggestion
+dotnet_style_collection_initializer = true:suggestion
+dotnet_style_explicit_tuple_names = true:suggestion
+dotnet_style_coalesce_expression = true:suggestion
+dotnet_style_null_propagation = true:suggestion
+
+# Expression-bodied members
+csharp_style_expression_bodied_methods = false:none
+csharp_style_expression_bodied_constructors = false:none
+csharp_style_expression_bodied_operators = false:none
+csharp_style_expression_bodied_properties = true:none
+csharp_style_expression_bodied_indexers = true:none
+csharp_style_expression_bodied_accessors = true:none
+
+# Pattern matching
+csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
+csharp_style_pattern_matching_over_as_with_null_check = true:suggestion
+csharp_style_inlined_variable_declaration = true:suggestion
+
+# Null checking preferences
+csharp_style_throw_expression = true:suggestion
+csharp_style_conditional_delegate_call = true:suggestion
+
+# Space preferences
+csharp_space_after_cast = false
+csharp_space_after_colon_in_inheritance_clause = true
+csharp_space_after_comma = true
+csharp_space_after_dot = false
+csharp_space_after_keywords_in_control_flow_statements = true
+csharp_space_after_semicolon_in_for_statement = true
+csharp_space_around_binary_operators = before_and_after
+csharp_space_around_declaration_statements = do_not_ignore
+csharp_space_before_colon_in_inheritance_clause = true
+csharp_space_before_comma = false
+csharp_space_before_dot = false
+csharp_space_before_open_square_brackets = false
+csharp_space_before_semicolon_in_for_statement = false
+csharp_space_between_empty_square_brackets = false
+csharp_space_between_method_call_empty_parameter_list_parentheses = false
+csharp_space_between_method_call_name_and_opening_parenthesis = false
+csharp_space_between_method_call_parameter_list_parentheses = false
+csharp_space_between_method_declaration_empty_parameter_list_parentheses = false
+csharp_space_between_method_declaration_name_and_open_parenthesis = false
+csharp_space_between_method_declaration_parameter_list_parentheses = false
+csharp_space_between_parentheses = false
+csharp_space_between_square_brackets = false
+csharp_using_directive_placement = outside_namespace:silent
+csharp_prefer_simple_using_statement = true:suggestion
+csharp_prefer_braces = when_multiline:silent
+csharp_style_namespace_declarations = file_scoped:silent
+csharp_style_prefer_method_group_conversion = true:silent
+csharp_style_prefer_top_level_statements = true:silent

CSTNet.sln

@@ -1,10 +1,11 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
-# Visual Studio Version 16
+# Visual Studio Version 17
-VisualStudioVersion = 16.0.30717.126
+VisualStudioVersion = 17.4.33205.214
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{CCFCE2DB-C18F-4D88-B025-19ED62BD2A1D}"
 	ProjectSection(SolutionItems) = preProject
+		.editorconfig = .editorconfig
 		changelog.md = changelog.md
 		README.md = README.md
 		usage.md = usage.md

CSTNet/CST.cs

@@ -34,10 +34,14 @@ public class CST
     /// Replaces the document's line endings with the native system line endings.
     /// </summary>
     /// <remarks>This stage ensures there are no crashes during parsing.</remarks>
+    /// <param name="content">The content of the document.</param>
+    /// <returns>The document's content with native system line endings.</returns>
     static IEnumerable<string> NormalizeEntries(string content)
     {
+        // Check if the document already uses native system line endings.
         if (!content.Contains(Environment.NewLine))
         {
+            // If not, check for and replace other line ending types.
             if (content.Contains(LF))
                 content = content.Replace(LF, Environment.NewLine);
 
@@ -51,9 +55,11 @@ public class CST
                 content = content.Replace(LS, Environment.NewLine);
         }
 
+        // Split the content by the caret and newline characters.
         var lines = content.Split(new[] { $"{CARET}{Environment.NewLine}" },
             StringSplitOptions.RemoveEmptyEntries);
 
+        // Filter out any lines that start with "//", "#", "/*", or end with "*/".
         return lines.Where(line =>
             !line.StartsWith("//") &&
             !line.StartsWith("#") &&
@@ -62,24 +68,34 @@ public class CST
             .AsEnumerable();
     }
 
+    /// <summary>
+    /// Retrieves the value for the specified key from the given entries.
+    /// </summary>
+    /// <param name="entries">The entries to search through.</param>
+    /// <param name="key">The key to search for.</param>
+    /// <returns>The value for the specified key, or a default string if not found.</returns>
     static string GetEntry(IEnumerable<string> entries, string key)
     {
-        // Search through list
+        // Iterate through the entries.
         foreach (var entry in entries)
         {
             // If the line doesn't start with the key, keep searching.
             if (!entry.StartsWith(key))
                 continue;
 
-            // Locate index, trim carets and return translation.
+            // Locate the index of the caret character.
             var startIndex = entry.IndexOf(CARET);
-            var line = entry.Substring(startIndex);
+            // Get the line from the caret character to the end of the string.
+            var line = entry[startIndex..];
 
+            // Return the line with the caret characters trimmed.
             return line.TrimStart(CARET).TrimEnd(CARET);
         }
 
+        // If no entry is found, return a default string.
         return "***MISSING***";
     }
+
 }
 
 

CSTNet/CSTNet.csproj

@@ -2,7 +2,7 @@
 
     <PropertyGroup>
         <TargetFrameworks>net6.0</TargetFrameworks>
-        <Version>2.0.101-beta1</Version>
+        <Version>2.0.102</Version>
         <Nullable>enable</Nullable>
         <LangVersion>latest</LangVersion>
         <ImplicitUsings>enable</ImplicitUsings>

CSTNet/IUIText.cs

@@ -4,6 +4,16 @@ namespace CSTNet;
 
 public interface IUIText
 {
+    /// <summary>
+    /// The base directory for the language files.
+    /// </summary>
     string[] BasePath { get; set; }
+
+    /// <summary>
+    /// Get the text for the given id and key.
+    /// </summary>
+    /// <param name="id">The id of the text.</param>
+    /// <param name="key">The key of the text.</param>
+    /// <returns>The text for the given id and key.</returns>
     string GetText(int id, int key);
 }

CSTNet/UIText.cs

@@ -4,14 +4,24 @@ namespace CSTNet;
 
 public class UIText : IUIText
 {
+    /// <summary>
+    /// The language of the text.
+    /// </summary>
     string Language { get; set; } = "english";
 
+    /// <summary>
+    /// The base directory for the language files.
+    /// </summary>
     public string[] BasePath { get; set; } = { AppContext.BaseDirectory, "uitext" };
 
+    /// <summary>
+    /// Constructor for the UIText class.
+    /// </summary>
     public UIText() { }
 
     /// <summary>
-    /// Loads the language file.
+    /// Constructor for the UIText class.
+    /// Loads the language file for the specified language.
     /// </summary>
     /// <param name="language">Language to load</param>
     public UIText(string language)
@@ -19,9 +29,9 @@ public class UIText : IUIText
         Language = language;
     }
 
-
     /// <summary>
-    /// Loads the language file.
+    /// Constructor for the UIText class.
+    /// Loads the language file for the specified language and base directory.
     /// </summary>
     /// <param name="language">Language to load</param>
     /// <param name="basePath">Base directory for the language files.</param>
@@ -47,15 +57,21 @@ public class UIText : IUIText
     /// <returns>The text for the given id and key.</returns>
     public string GetText(int id, string key)
     {
+        // Combine the base path and language path to get the full path of the language file.
         var basePath = Path.Combine(BasePath);
         var langPath = Path.Combine(basePath, $"{Language}.dir");
+
+        // Get all the files in the language directory.
         var files = Directory.GetFiles(langPath);
 
+        // Iterate through the files in the language directory.
         foreach (var file in files)
         {
+            // Skip files that do not have the ".cst" extension.
             if (!file.Contains(".cst"))
                 continue;
 
+            // Get the id of the current file.
             var ids = Path.GetFileName(file);
             var second = ids.IndexOf("_", 1, StringComparison.InvariantCultureIgnoreCase);
 
@@ -64,14 +80,21 @@ public class UIText : IUIText
 
             ids = ids.Substring(1, second - 1);
 
+            // If the id of the current file does not match the id passed to the function,
+            // skip to the next file.
             if (ids != id.ToString())
                 continue;
 
+            // Read the content of the current file.
             var content = File.ReadAllText(file);
+
+            // Return the text for the specified key.
             return CST.Parse(content, key);
         }
 
+        // If no text is found, return a default string.
         return "***MISSING***";
     }
+
 }
 

changelog.md

@@ -1,5 +1,9 @@
 # Change Log
 
+## 2.0.102
+
+- Properly commented and documented the rest of the code.
+
 ## 2.0.100
 
 This version supports both .NET Standard 2.1 and .NET 6 and brings with it (much needed) quality of life changes internally. Apart from that, nothing has changed to the API itself apart from much needed documentation.