main

sharpchen · sharpchen · commit 1642883c86df · 2025-07-17T02:49:20.000+08:00
diff --git a/docs/document/Articles/docs/Duck Typing in CSharp.md b/docs/document/Articles/docs/Duck Typing in CSharp.md
diff --git a/docs/document/Articles/docs/Writing Treesitter Parser.md b/docs/document/Articles/docs/Writing Treesitter Parser.md
@@ -0,0 +1,136 @@
+# Writing Treesitter Parser
+
+## Treesitter CLI Util
+
+## AST & CTS
+
+- A tree only contains **named nodes** is a abstract syntax tree(AST)
+- A tree contains **both named and unnamed nodes** is a concrete syntax tree(CST)
+
+## Grammar Structure
+
+- `name`: name of that parser
+- `rules`: rules for generating nodes
+- see [doc](https://tree-sitter.github.io/tree-sitter/creating-parsers/2-the-grammar-dsl.html) for more properties of a grammar.
+
+## Tree Structure
+
+Treesitter syntax tree(and its query) is generally represented in scheme language, a lisp dialect.
+Each `()` initializes a new list, each element in the list is either presented as node type(named nodes) or string literal(unnamed nodes).
+The **node type** is name of rule that matched the section.
+
+- **field** : Each element might have a *field name* such as `kind: "const"` to give the element(node) a **descriptive** name in context.
+- **token**: Each atomic node is considered as a token, such as `(number)` and `(comment)` in the example.
+
+> [!NOTE]
+> A unnamed node could have *field name*, the field name is for node representation in tree, not the nominal identity of that node.
+
+```query
+; generated tree for javascript code
+; const foo = 1 + 2 // this is foo
+(program ; [0, 0] - [1, 0]
+  (lexical_declaration ; [0, 0] - [0, 18]
+    kind: "const" ; [0, 0] - [0, 5]
+    (variable_declarator ; [0, 6] - [0, 17]
+      name: (identifier) ; [0, 6] - [0, 9]
+      "=" ; [0, 10] - [0, 11]
+      value: (binary_expression ; [0, 12] - [0, 17]
+        left: (number) ; [0, 12] - [0, 13]
+        operator: "+" ; [0, 14] - [0, 15]
+        right: (number))) ; [0, 16] - [0, 17]
+    ";") ; [0, 17] - [0, 18]
+  (comment)) ; [0, 19] - [0, 33]
+```
+
+
+
+## Writing Rules
+
+1. **The top level rule**: the most generic wrapper rule to cover all possible content to be parsed.
+    - **top level rule MUST be the first rule property declared in `rules` field.**
+    - the name of top level rule can be arbitrary, usually depend on language specification.
+        - `C#` for example uses the `compilation_unit` as the name of top level rule.
+```js
+module.exports = grammar({
+  name: 'c_sharp',
+  rules: {
+    /*...*/
+    compilation_unit: $ => seq( // must be the first rule // [!code highlight]
+      optional($.shebang_directive),
+      repeat($._top_level_item),
+    ),
+    _top_level_item: $ => prec(2, choice(
+      $._top_level_item_no_statement,
+      $.global_statement,
+    )),
+    /*...*/
+  }
+});
+```
+
+### Named & Unnamed Nodes
+
+A node generated by a rule that was assigned to a property of `rules` is called a *named node*.
+A node generated by a rule that was written in literal string/regex is *unnamed nodes*.
+
+```js
+module.exports = grammar({
+  name: 'foo',
+  rules: {
+    if_statement: $ => seq("if", "(", $._expression, ")", $._statement);
+  },
+});
+```
+
+> [!NOTE]
+> Unnamed nodes are not visible from treesitter CST by default, but they does exist in the structure and can be inspected.
+> They just don't have a node type.
+
+### Aliased Rule
+
+
+### Tokenized Rule
+
+`token(rule)` made a complex rule as a **atomic** node, tree-sitter would only match but does not generate the concrete sub-tree for this node.
+The following rule would made comment as `(comment)` in concrete tree, it does not include the unnamed nodes match that pattern.
+
+```js
+module.exports = grammar({
+  name: 'foo',
+  rules: {
+    /* ... */
+    comment: _ => token(choice(
+      seq('//', /[^\n\r]*/),
+      seq(
+        '/*',
+        /[^*]*\*+([^/*][^*]*\*+)*/,
+        '/',
+      ),
+    )),
+  },
+});
+```
+
+### Node Description
+
+A field of node is a **descriptive name** for semantic of that node in certain context.
+
+The following rule defines descriptive name for each node of that function node.
+
+```js
+module.exports = grammar({
+  name: 'foo',
+  rules: {
+    /* ... */
+    function_definition: $ =>
+      seq(
+        "func",
+        field("name", $.identifier),
+        field("parameters", $.parameter_list),
+        field("return_type", $._type),
+        field("body", $.block),
+      )
+  },
+});
+```
+
diff --git a/docs/document/Skill/Modern CSharp/docs/Duck Typing.md b/docs/document/Skill/Modern CSharp/docs/Duck Typing.md
@@ -0,0 +1,56 @@
+# Duck Typing in CSharp
+
+## **List Initializer**
+
+Any type implemented `IEnumerable` and has a `Add(T item): void` method can use *list initializer* syntax.
+- `Add(T item): void` can be implemented as extension method
+- `ICollection` is more generally used to have *list initializer* enabled, because it's an extension of `IEnumerable` with `Add` method.
+
+```cs
+_ = new FooCollection<int>() { 1, 2, 3 }; // [!code highlight]
+
+class FooCollection<T> : IEnumerable<T> {
+    public void Add(T item) { Console.WriteLine(item); } // [!code highlight]
+    public IEnumerator<T> GetEnumerator() {
+        throw new NotImplementedException();
+    }
+    IEnumerator IEnumerable.GetEnumerator() {
+        return GetEnumerator();
+    }
+}
+// or implement it as extension method
+static class Ext {
+    public static void Add<T>(this FooCollection<T> self, T item) { } // [!code highlight]
+}
+```
+
+## **Deconstruction**
+
+```cs
+var (a, b) = new Foo(); // [!code highlight]
+
+class Foo { };
+
+static class FooExtension {
+    public static void Deconstruct(this Foo self, out int a, out int b) { a = b = 1; } // [!code highlight]
+}
+```
+## **Iteration**
+
+Any type with a `GetEnumerator` implementation can be iterated by `foreach` statement.
+- can be implemented as an extension method
+
+```cs
+using System.Collections;
+
+foreach (var _ in new FooIterable()) { } // [!code highlight]
+
+class FooIterable { };
+
+static class FooExtension {
+    public static IEnumerator GetEnumerator(this FooIterable _) { // [!code highlight]
+        for (int i = 0; i < 100; i++) // [!code highlight]
+            yield return i; // [!code highlight]
+    } // [!code highlight]
+}
+```
diff --git a/docs/document/Skill/PowerShell/docs/Language/Array.md b/docs/document/Skill/PowerShell/docs/Language/Array.md
@@ -1,6 +1,6 @@
-# Array
+# Collection
 
-## Creation
+## Array Creation
 
 ```ps1
 $foo = 1,2,3
@@ -94,7 +94,7 @@ If the *end* is less than the *start*, the array counts down from *start* to *en
 5..-1 # 5 4 3 2 1 0 -1
 ```
 
-## Access Item
+## Item Accessor
 
 Powershell allows indexer syntax to access one or more items at a time or use `Select-Object`.
 
@@ -108,6 +108,24 @@ Powershell allows indexer syntax to access one or more items at a time or use `S
 > The default value of a array item is `$null`.
 > Since it's a dynamic language, there's no error raised when index is out of the range.
 
+### Singular as Collection
+
+Variables storing singular value are intrinsically collections in PowerShell, so you don't have to check on the length when an return might be singular or a collection.
+Value at index `0` is the value stored by variable itself, otherwise it returns `$null`.
+
+```ps1
+$foo = 1
+$foo[0] # 1
+$foo[1] # $null
+
+if (Get-Command foo -OutVariable exe) {
+    # Get-Command might return one or more instances,
+    # but we don't need to check on length.
+    # everything is an collection!
+    & $exe[0]
+}
+```
+
 ## Concatenation
 
 Generates new array from two concatenated or with new item.
diff --git a/docs/document/Skill/PowerShell/docs/Language/Control Flow.md b/docs/document/Skill/PowerShell/docs/Language/Control Flow.md
@@ -27,10 +27,10 @@ gci `
 
 > [!warning]
 > **A space is required before the backtick.**
-> **And no any chacracter is allowed after the backtick.**
+> **And no any character is allowed after the backtick.**
 
 > [!TIP]
-> Stop using backticks! They're ugly! Use hashtable splatting instead.
+> Stop using backticks! They're ugly! Use HashTable splatting instead.
 >```ps1
 >$table = @{
 >  Filter = '*.mp4';
@@ -43,7 +43,7 @@ gci `
 
 ### Trailing Piper
 
-In multiple piping, we can use trailing `|` to indicate the new line, PowerShell regconizes these lines as a whole command piping.
+In multiple piping, we can use trailing `|` to indicate the new line, PowerShell recognizes these lines as a whole command piping.
 
 ```ps1
 gps |
@@ -53,7 +53,7 @@ gps |
 
 ### Leading Piper <Badge type="info" text="PowerShell 7+" />
 
-Starting with PowerShell 7, `|` is allowed as the first non-space chacracter in a new line.
+Starting with PowerShell 7, `|` is allowed as the first non-space character in a new line.
 
 ```ps1
 gps | foreach CPU
@@ -127,17 +127,20 @@ It has a few different patterns available:
 - use `continue` to skip current enumeration
     ```ps1
     switch (1, 2) {
-        1 { continue } # I don't want to preceed with this value 1, next!
+        1 { continue } # I don't want to proceed with this value 1, next!
         2 { "aha" }
     } # aha
     ```
 
-There's options available for `switch`(specifically for `string` macthing):
+There's options available for `switch`(specifically for `string` matching):
 - `-Exact`: the default option that matches the string by literal, can be elided
 - `-Regex`: match by regex condition
 - `-Wildcard`: match by wildcard condition
 - `-CaseSensetive`: case-sensitive matching, can be combined with any of other three options
 
+> [!NOTE]
+> `-File` and `-Parallel` flag are not mentioned here because they're more specific to other topics.
+
 ### Constant Pattern
 
 Constant pattern is specifically for numbers and strings.
@@ -277,3 +280,22 @@ if (Get-Command foo -ErrorAction SilentlyContinue -ErrorVariable err) {
 
 > [!NOTE]
 > If you're not interested in error at all, you can use `-ErrorAction Ignore` which never even register err to variable.
+
+## Named/Labeled Loop
+
+Named loop allows you to break any parent level of loops including `for`, `foreach`, `while`, `do..until` and `switch`
+
+```ps1
+:fileList foreach($path in $logs) {
+    :logFile switch -Wildcard -File $path {
+        'Error*' {
+            break filelist # break the whole foreach loop labeled as fileList
+        }
+        'Warning*' {
+            break logFile # redundant label break, simply use break
+        }
+        default {
+        }
+    }
+}
+```
diff --git a/docs/document/Skill/PowerShell/docs/Standard IO/File IO.md b/docs/document/Skill/PowerShell/docs/Standard IO/File IO.md
@@ -0,0 +1,25 @@
+# File IO
+
+## Line by Line
+
+`Get-Content` is bad practice when the file is larger enough to process line by line, the memory might overflow during runtime.
+Using `.NET` class such as `FileStream` can be just fine but a little complicated. The most direct solution is using `switch -File` statement.
+A `switch` statement with `-File` flag enumerates the whole file line by line, each line was matched with given pattern, and such pattern can combine with other flags such as `-CaseSensitive`.
+You may use `break` to terminate the whole loop or `continue` to skip to next iteration.
+
+```ps1
+switch -CaseSensitive -Wildcard -File ~/.local/state/nvim/lsp.log {
+    'fsautocomplete' {
+        if ($shouldSkip) { continue }
+        $_ # current line
+    }
+    'ERROR' {
+        break; # the whole switch is terminated
+    }
+    default {
+    }
+}
+```
+
+> [!NOTE]
+> There should not exist brackets around file name in `switch -File <filename>`
