feat(cli-args): allow sub-commands in grammar

MKRhere · MKRhere · commit fa5207b5a45c · 2023-02-22T02:56:00.000+05:30
diff --git a/assets/cli-railroad/diagram/AlphanumericAnd.svg b/assets/cli-railroad/diagram/AlphanumericAnd.svg
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="161" height="213">
+   <defs>
+      <style type="text/css">
+    @namespace "http://www.w3.org/2000/svg";
+    .line                 {fill: none; stroke: #332900; stroke-width: 1;}
+    .bold-line            {stroke: #141000; shape-rendering: crispEdges; stroke-width: 2;}
+    .thin-line            {stroke: #1F1800; shape-rendering: crispEdges}
+    .filled               {fill: #332900; stroke: none;}
+    text.terminal         {font-family: Verdana, Sans-serif;
+                            font-size: 12px;
+                            fill: #141000;
+                            font-weight: bold;
+                          }
+    text.nonterminal      {font-family: Verdana, Sans-serif;
+                            font-size: 12px;
+                            fill: #1A1400;
+                            font-weight: normal;
+                          }
+    text.regexp           {font-family: Verdana, Sans-serif;
+                            font-size: 12px;
+                            fill: #1F1800;
+                            font-weight: normal;
+                          }
+    rect, circle, polygon {fill: #332900; stroke: #332900;}
+    rect.terminal         {fill: #FFDB4D; stroke: #332900; stroke-width: 1;}
+    rect.nonterminal      {fill: #FFEC9E; stroke: #332900; stroke-width: 1;}
+    rect.text             {fill: none; stroke: none;}
+    polygon.regexp        {fill: #FFF4C7; stroke: #332900; stroke-width: 1;}
+  </style>
+   </defs>
+   <polygon points="9 17 1 13 1 21"/>
+   <polygon points="17 17 9 13 9 21"/>
+   <polygon points="51 19 58 3 106 3 113 19 106 35 58 35"/>
+   <polygon points="49 17 56 1 104 1 111 17 104 33 56 33" class="regexp"/>
+   <text class="regexp" x="64" y="21">[0-9]</text>
+   <polygon points="51 63 58 47 104 47 111 63 104 79 58 79"/>
+   <polygon points="49 61 56 45 102 45 109 61 102 77 56 77" class="regexp"/>
+   <text class="regexp" x="64" y="65">[a-z]</text>
+   <polygon points="51 107 58 91 106 91 113 107 106 123 58 123"/>
+   <polygon points="49 105 56 89 104 89 111 105 104 121 56 121" class="regexp"/>
+   <text class="regexp" x="64" y="109">[A-Z]</text>
+   <rect x="51" y="135" width="26" height="32" rx="10"/>
+   <rect x="49"
+          y="133"
+          width="26"
+          height="32"
+          class="terminal"
+          rx="10"/>
+   <text class="terminal" x="59" y="153">-</text>
+   <rect x="51" y="179" width="28" height="32" rx="10"/>
+   <rect x="49"
+          y="177"
+          width="28"
+          height="32"
+          class="terminal"
+          rx="10"/>
+   <text class="terminal" x="59" y="197">_</text>
+   <path class="line"
+          d="m17 17 h2 m20 0 h10 m62 0 h10 m-102 0 h20 m82 0 h20 m-122 0 q10 0 10 10 m102 0 q0 -10 10 -10 m-112 10 v24 m102 0 v-24 m-102 24 q0 10 10 10 m82 0 q10 0 10 -10 m-92 10 h10 m60 0 h10 m0 0 h2 m-92 -10 v20 m102 0 v-20 m-102 20 v24 m102 0 v-24 m-102 24 q0 10 10 10 m82 0 q10 0 10 -10 m-92 10 h10 m62 0 h10 m-92 -10 v20 m102 0 v-20 m-102 20 v24 m102 0 v-24 m-102 24 q0 10 10 10 m82 0 q10 0 10 -10 m-92 10 h10 m26 0 h10 m0 0 h36 m-92 -10 v20 m102 0 v-20 m-102 20 v24 m102 0 v-24 m-102 24 q0 10 10 10 m82 0 q10 0 10 -10 m-92 10 h10 m28 0 h10 m0 0 h34 m23 -176 h-3"/>
+   <polygon points="151 17 159 13 159 21"/>
+   <polygon points="151 17 143 13 143 21"/>
+</svg>
diff --git a/assets/cli-railroad/diagram/CmdIdentifier.svg b/assets/cli-railroad/diagram/CmdIdentifier.svg
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="205" height="57">
+<svg xmlns="http://www.w3.org/2000/svg" width="229" height="57">
    <defs>
       <style type="text/css">
     @namespace "http://www.w3.org/2000/svg";
@@ -32,14 +32,14 @@
    <polygon points="9 51 1 47 1 55"/>
    <polygon points="17 51 9 47 9 55"/>
    <a xmlns:xlink="http://www.w3.org/1999/xlink"
-       xlink:href="#Alphanumeric"
-       xlink:title="Alphanumeric">
-      <rect x="51" y="3" width="106" height="32"/>
-      <rect x="49" y="1" width="106" height="32" class="nonterminal"/>
-      <text class="nonterminal" x="59" y="21">Alphanumeric</text>
+       xlink:href="#AlphanumericAnd"
+       xlink:title="AlphanumericAnd">
+      <rect x="51" y="3" width="130" height="32"/>
+      <rect x="49" y="1" width="130" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="59" y="21">AlphanumericAnd</text>
    </a>
    <path class="line"
-          d="m17 51 h2 m20 0 h10 m0 0 h116 m-146 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -14 q0 -10 10 -10 m126 34 l20 0 m-20 0 q10 0 10 -10 l0 -14 q0 -10 -10 -10 m-126 0 h10 m106 0 h10 m23 34 h-3"/>
-   <polygon points="195 51 203 47 203 55"/>
-   <polygon points="195 51 187 47 187 55"/>
+          d="m17 51 h2 m20 0 h10 m0 0 h140 m-170 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -14 q0 -10 10 -10 m150 34 l20 0 m-20 0 q10 0 10 -10 l0 -14 q0 -10 -10 -10 m-150 0 h10 m130 0 h10 m23 34 h-3"/>
+   <polygon points="219 51 227 47 227 55"/>
+   <polygon points="219 51 211 47 211 55"/>
 </svg>
diff --git a/assets/cli-railroad/diagram/Command.svg b/assets/cli-railroad/diagram/Command.svg
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="421" height="71">
+<svg xmlns="http://www.w3.org/2000/svg" width="471" height="153">
    <defs>
       <style type="text/css">
     @namespace "http://www.w3.org/2000/svg";
@@ -48,12 +48,19 @@
    <a xmlns:xlink="http://www.w3.org/1999/xlink"
        xlink:href="#Operand"
        xlink:title="Operand">
-      <rect x="299" y="3" width="74" height="32"/>
-      <rect x="297" y="1" width="74" height="32" class="nonterminal"/>
-      <text class="nonterminal" x="307" y="21">Operand</text>
+      <rect x="319" y="37" width="74" height="32"/>
+      <rect x="317" y="35" width="74" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="327" y="55">Operand</text>
+   </a>
+   <a xmlns:xlink="http://www.w3.org/1999/xlink"
+       xlink:href="#Command"
+       xlink:title="Command">
+      <rect x="319" y="103" width="84" height="32"/>
+      <rect x="317" y="101" width="84" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="327" y="121">Command</text>
    </a>
    <path class="line"
-          d="m17 51 h2 m0 0 h10 m106 0 h10 m20 0 h10 m0 0 h72 m-102 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -14 q0 -10 10 -10 m82 34 l20 0 m-20 0 q10 0 10 -10 l0 -14 q0 -10 -10 -10 m-82 0 h10 m62 0 h10 m40 34 h10 m0 0 h84 m-114 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -14 q0 -10 10 -10 m94 34 l20 0 m-20 0 q10 0 10 -10 l0 -14 q0 -10 -10 -10 m-94 0 h10 m74 0 h10 m23 34 h-3"/>
-   <polygon points="411 51 419 47 419 55"/>
-   <polygon points="411 51 403 47 403 55"/>
+          d="m17 51 h2 m0 0 h10 m106 0 h10 m20 0 h10 m0 0 h72 m-102 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -14 q0 -10 10 -10 m82 34 l20 0 m-20 0 q10 0 10 -10 l0 -14 q0 -10 -10 -10 m-82 0 h10 m62 0 h10 m60 34 h10 m74 0 h10 m-114 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -12 q0 -10 10 -10 m94 32 l20 0 m-20 0 q10 0 10 -10 l0 -12 q0 -10 -10 -10 m-94 0 h10 m0 0 h84 m20 32 h10 m-164 0 h20 m144 0 h20 m-184 0 q10 0 10 10 m164 0 q0 -10 10 -10 m-174 10 v46 m164 0 v-46 m-164 46 q0 10 10 10 m144 0 q10 0 10 -10 m-134 10 h10 m84 0 h10 m-124 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -12 q0 -10 10 -10 m104 32 l20 0 m-20 0 q10 0 10 -10 l0 -12 q0 -10 -10 -10 m-104 0 h10 m0 0 h94 m-134 22 v20 m164 0 v-20 m-164 20 v14 m164 0 v-14 m-164 14 q0 10 10 10 m144 0 q10 0 10 -10 m-154 10 h10 m0 0 h134 m23 -100 h-3"/>
+   <polygon points="461 51 469 47 469 55"/>
+   <polygon points="461 51 453 47 453 55"/>
 </svg>
diff --git a/assets/cli-railroad/diagram/LongFlagOption.svg b/assets/cli-railroad/diagram/LongFlagOption.svg
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="257" height="53">
+<svg xmlns="http://www.w3.org/2000/svg" width="407" height="71">
    <defs>
       <style type="text/css">
     @namespace "http://www.w3.org/2000/svg";
@@ -29,25 +29,32 @@
     polygon.regexp        {fill: #FFF4C7; stroke: #332900; stroke-width: 1;}
   </style>
    </defs>
-   <polygon points="9 33 1 29 1 37"/>
-   <polygon points="17 33 9 29 9 37"/>
-   <rect x="31" y="19" width="32" height="32" rx="10"/>
+   <polygon points="9 51 1 47 1 55"/>
+   <polygon points="17 51 9 47 9 55"/>
+   <rect x="31" y="37" width="32" height="32" rx="10"/>
    <rect x="29"
-          y="17"
+          y="35"
           width="32"
           height="32"
           class="terminal"
           rx="10"/>
-   <text class="terminal" x="39" y="37">--</text>
+   <text class="terminal" x="39" y="55">--</text>
    <a xmlns:xlink="http://www.w3.org/1999/xlink"
        xlink:href="#Alphanumeric"
        xlink:title="Alphanumeric">
-      <rect x="103" y="19" width="106" height="32"/>
-      <rect x="101" y="17" width="106" height="32" class="nonterminal"/>
-      <text class="nonterminal" x="111" y="37">Alphanumeric</text>
+      <rect x="83" y="37" width="106" height="32"/>
+      <rect x="81" y="35" width="106" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="91" y="55">Alphanumeric</text>
+   </a>
+   <a xmlns:xlink="http://www.w3.org/1999/xlink"
+       xlink:href="#AlphanumericAnd"
+       xlink:title="AlphanumericAnd">
+      <rect x="229" y="3" width="130" height="32"/>
+      <rect x="227" y="1" width="130" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="237" y="21">AlphanumericAnd</text>
    </a>
    <path class="line"
-          d="m17 33 h2 m0 0 h10 m32 0 h10 m20 0 h10 m106 0 h10 m-146 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -12 q0 -10 10 -10 m126 32 l20 0 m-20 0 q10 0 10 -10 l0 -12 q0 -10 -10 -10 m-126 0 h10 m0 0 h116 m23 32 h-3"/>
-   <polygon points="247 33 255 29 255 37"/>
-   <polygon points="247 33 239 29 239 37"/>
+          d="m17 51 h2 m0 0 h10 m32 0 h10 m0 0 h10 m106 0 h10 m20 0 h10 m0 0 h140 m-170 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -14 q0 -10 10 -10 m150 34 l20 0 m-20 0 q10 0 10 -10 l0 -14 q0 -10 -10 -10 m-150 0 h10 m130 0 h10 m23 34 h-3"/>
+   <polygon points="397 51 405 47 405 55"/>
+   <polygon points="397 51 389 47 389 55"/>
 </svg>
diff --git a/assets/cli-railroad/diagram/LongValueOption.svg b/assets/cli-railroad/diagram/LongValueOption.svg
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<svg xmlns="http://www.w3.org/2000/svg" width="507" height="53">
+<svg xmlns="http://www.w3.org/2000/svg" width="657" height="71">
    <defs>
       <style type="text/css">
     @namespace "http://www.w3.org/2000/svg";
@@ -29,39 +29,46 @@
     polygon.regexp        {fill: #FFF4C7; stroke: #332900; stroke-width: 1;}
   </style>
    </defs>
-   <polygon points="9 33 1 29 1 37"/>
-   <polygon points="17 33 9 29 9 37"/>
-   <rect x="31" y="19" width="32" height="32" rx="10"/>
+   <polygon points="9 51 1 47 1 55"/>
+   <polygon points="17 51 9 47 9 55"/>
+   <rect x="31" y="37" width="32" height="32" rx="10"/>
    <rect x="29"
-          y="17"
+          y="35"
           width="32"
           height="32"
           class="terminal"
           rx="10"/>
-   <text class="terminal" x="39" y="37">--</text>
+   <text class="terminal" x="39" y="55">--</text>
    <a xmlns:xlink="http://www.w3.org/1999/xlink"
        xlink:href="#Alphanumeric"
        xlink:title="Alphanumeric">
-      <rect x="103" y="19" width="106" height="32"/>
-      <rect x="101" y="17" width="106" height="32" class="nonterminal"/>
-      <text class="nonterminal" x="111" y="37">Alphanumeric</text>
+      <rect x="83" y="37" width="106" height="32"/>
+      <rect x="81" y="35" width="106" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="91" y="55">Alphanumeric</text>
+   </a>
+   <a xmlns:xlink="http://www.w3.org/1999/xlink"
+       xlink:href="#AlphanumericAnd"
+       xlink:title="AlphanumericAnd">
+      <rect x="229" y="3" width="130" height="32"/>
+      <rect x="227" y="1" width="130" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="237" y="21">AlphanumericAnd</text>
    </a>
    <a xmlns:xlink="http://www.w3.org/1999/xlink"
        xlink:href="#OptionValueDelimiter"
        xlink:title="OptionValueDelimiter">
-      <rect x="249" y="19" width="154" height="32"/>
-      <rect x="247" y="17" width="154" height="32" class="nonterminal"/>
-      <text class="nonterminal" x="257" y="37">OptionValueDelimiter</text>
+      <rect x="399" y="37" width="154" height="32"/>
+      <rect x="397" y="35" width="154" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="407" y="55">OptionValueDelimiter</text>
    </a>
    <a xmlns:xlink="http://www.w3.org/1999/xlink"
        xlink:href="#Value"
        xlink:title="Value">
-      <rect x="423" y="19" width="56" height="32"/>
-      <rect x="421" y="17" width="56" height="32" class="nonterminal"/>
-      <text class="nonterminal" x="431" y="37">Value</text>
+      <rect x="573" y="37" width="56" height="32"/>
+      <rect x="571" y="35" width="56" height="32" class="nonterminal"/>
+      <text class="nonterminal" x="581" y="55">Value</text>
    </a>
    <path class="line"
-          d="m17 33 h2 m0 0 h10 m32 0 h10 m20 0 h10 m106 0 h10 m-146 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -12 q0 -10 10 -10 m126 32 l20 0 m-20 0 q10 0 10 -10 l0 -12 q0 -10 -10 -10 m-126 0 h10 m0 0 h116 m20 32 h10 m154 0 h10 m0 0 h10 m56 0 h10 m3 0 h-3"/>
-   <polygon points="497 33 505 29 505 37"/>
-   <polygon points="497 33 489 29 489 37"/>
+          d="m17 51 h2 m0 0 h10 m32 0 h10 m0 0 h10 m106 0 h10 m20 0 h10 m0 0 h140 m-170 0 l20 0 m-1 0 q-9 0 -9 -10 l0 -14 q0 -10 10 -10 m150 34 l20 0 m-20 0 q10 0 10 -10 l0 -14 q0 -10 -10 -10 m-150 0 h10 m130 0 h10 m20 34 h10 m154 0 h10 m0 0 h10 m56 0 h10 m3 0 h-3"/>
+   <polygon points="647 51 655 47 655 55"/>
+   <polygon points="647 51 639 47 639 55"/>
 </svg>
diff --git a/assets/cli-railroad/index.md b/assets/cli-railroad/index.md
@@ -3,16 +3,20 @@
 ![Command](diagram/Command.svg)
 
 ```
-Command  ::= CmdIdentifier Option* Operand*
+Command  ::= CmdIdentifier Option* ( Operand* | Command+ )
 ```
 
+referenced by:
+
+- Command
+
 **CmdIdentifier:**
 
 ![CmdIdentifier](diagram/CmdIdentifier.svg)
 
 ```
 CmdIdentifier
-         ::= Alphanumeric*
+         ::= AlphanumericAnd*
 ```
 
 referenced by:
@@ -92,7 +96,7 @@ referenced by:
 
 ```
 LongFlagOption
-         ::= '--' Alphanumeric+
+         ::= '--' Alphanumeric AlphanumericAnd*
 ```
 
 referenced by:
@@ -105,7 +109,7 @@ referenced by:
 
 ```
 LongValueOption
-         ::= '--' Alphanumeric+ OptionValueDelimiter Value
+         ::= '--' Alphanumeric AlphanumericAnd* OptionValueDelimiter Value
 ```
 
 referenced by:
@@ -138,12 +142,26 @@ Alphanumeric
 
 referenced by:
 
-- CmdIdentifier
 - LongFlagOption
 - LongValueOption
 - ShortFlagOption
 - ShortValueOption
 
+**AlphanumericAnd:**
+
+![AlphanumericAnd](diagram/AlphanumericAnd.svg)
+
+```
+AlphanumericAnd
+         ::= [0-9a-zA-Z_#x2D]
+```
+
+referenced by:
+
+- CmdIdentifier
+- LongFlagOption
+- LongValueOption
+
 **Value:**
 
 ![Value](diagram/Value.svg)
diff --git a/cli-args.md b/cli-args.md
@@ -15,6 +15,8 @@ The POSIX standard is often cited when designing command line interfaces. Howeve
 
 A command MAY accept sub-commands, options, and operands.
 
+##### Note: This specification is available as a [formal grammar](#formal-grammar), or as a [railroad diagram](./assets/cli-railroad/index.md).
+
 ### Sub-commands
 
 -   A sub-command is a part of the command that acts as a command by itself. In other words, a sub-command is a recursive command.
@@ -65,23 +67,26 @@ A command MAY accept sub-commands, options, and operands.
 
 ## Formal Grammar
 
-```grammar
+```C
 Command ::= CmdIdentifier
 Command ::= CmdIdentifier Operand*
 Command ::= CmdIdentifier Option* Operand*
-CmdIdentifier ::= Alphanumeric*
+Command ::= CmdIdentifier Command*
+Command ::= CmdIdentifier Option* Command*
+CmdIdentifier ::= AlphanumericAnd*
 Option ::= ShortOption | LongOption
 ShortOption ::= ShortFlagOption | ShortValueOption
 LongOption ::= LongFlagOption | LongValueOption
 ShortFlagOption ::= '-' Alphanumeric
 ShortValueOption ::= '-' Alphanumeric OptionValueDelimiter Value
-LongFlagOption ::= '--' Alphanumeric Alphanumeric*
-LongValueOption ::= '--' Alphanumeric Alphanumeric* OptionValueDelimiter Value
+LongFlagOption ::= '--' Alphanumeric AlphanumericAnd*
+LongValueOption ::= '--' Alphanumeric AlphanumericAnd* OptionValueDelimiter Value
 OptionValueDelimiter ::= Space | '='
 Alphanumeric ::= [0-9a-zA-Z]
+AlphanumericAnd ::= [0-9a-zA-Z-_]
 Value ::= Char* | '"' ( Char | Space )* '"'
 Char ::= ( UnicodeExceptDoubleQuotes | '\"' )
-Space ::= ( U+0020 )\*
+Space ::= ( U+0020 )*
 Operand ::= Value
 ```
 
