doc/CLI arguments processing.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
   5 <head>
   6 <!-- 2023-10-12 Thu 23:05 -->
   7 <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
   8 <meta name="viewport" content="width=device-width, initial-scale=1" />
   9 <title>Commandline interface arguments processing</title>
  10 <meta name="author" content="Svjatoslav Agejenko" />
  11 <meta name="generator" content="Org Mode" />
  12 <style>
  13   #content { max-width: 60em; margin: auto; }
  14   .title  { text-align: center;
  15              margin-bottom: .2em; }
  16   .subtitle { text-align: center;
  17               font-size: medium;
  18               font-weight: bold;
  19               margin-top:0; }
  20   .todo   { font-family: monospace; color: red; }
  21   .done   { font-family: monospace; color: green; }
  22   .priority { font-family: monospace; color: orange; }
  23   .tag    { background-color: #eee; font-family: monospace;
  24             padding: 2px; font-size: 80%; font-weight: normal; }
  25   .timestamp { color: #bebebe; }
  26   .timestamp-kwd { color: #5f9ea0; }
  27   .org-right  { margin-left: auto; margin-right: 0px;  text-align: right; }
  28   .org-left   { margin-left: 0px;  margin-right: auto; text-align: left; }
  29   .org-center { margin-left: auto; margin-right: auto; text-align: center; }
  30   .underline { text-decoration: underline; }
  31   #postamble p, #preamble p { font-size: 90%; margin: .2em; }
  32   p.verse { margin-left: 3%; }
  33   pre {
  34     border: 1px solid #e6e6e6;
  35     border-radius: 3px;
  36     background-color: #f2f2f2;
  37     padding: 8pt;
  38     font-family: monospace;
  39     overflow: auto;
  40     margin: 1.2em;
  41   }
  42   pre.src {
  43     position: relative;
  44     overflow: auto;
  45   }
  46   pre.src:before {
  47     display: none;
  48     position: absolute;
  49     top: -8px;
  50     right: 12px;
  51     padding: 3px;
  52     color: #555;
  53     background-color: #f2f2f299;
  54   }
  55   pre.src:hover:before { display: inline; margin-top: 14px;}
  56   /* Languages per Org manual */
  57   pre.src-asymptote:before { content: 'Asymptote'; }
  58   pre.src-awk:before { content: 'Awk'; }
  59   pre.src-authinfo::before { content: 'Authinfo'; }
  60   pre.src-C:before { content: 'C'; }
  61   /* pre.src-C++ doesn't work in CSS */
  62   pre.src-clojure:before { content: 'Clojure'; }
  63   pre.src-css:before { content: 'CSS'; }
  64   pre.src-D:before { content: 'D'; }
  65   pre.src-ditaa:before { content: 'ditaa'; }
  66   pre.src-dot:before { content: 'Graphviz'; }
  67   pre.src-calc:before { content: 'Emacs Calc'; }
  68   pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
  69   pre.src-fortran:before { content: 'Fortran'; }
  70   pre.src-gnuplot:before { content: 'gnuplot'; }
  71   pre.src-haskell:before { content: 'Haskell'; }
  72   pre.src-hledger:before { content: 'hledger'; }
  73   pre.src-java:before { content: 'Java'; }
  74   pre.src-js:before { content: 'Javascript'; }
  75   pre.src-latex:before { content: 'LaTeX'; }
  76   pre.src-ledger:before { content: 'Ledger'; }
  77   pre.src-lisp:before { content: 'Lisp'; }
  78   pre.src-lilypond:before { content: 'Lilypond'; }
  79   pre.src-lua:before { content: 'Lua'; }
  80   pre.src-matlab:before { content: 'MATLAB'; }
  81   pre.src-mscgen:before { content: 'Mscgen'; }
  82   pre.src-ocaml:before { content: 'Objective Caml'; }
  83   pre.src-octave:before { content: 'Octave'; }
  84   pre.src-org:before { content: 'Org mode'; }
  85   pre.src-oz:before { content: 'OZ'; }
  86   pre.src-plantuml:before { content: 'Plantuml'; }
  87   pre.src-processing:before { content: 'Processing.js'; }
  88   pre.src-python:before { content: 'Python'; }
  89   pre.src-R:before { content: 'R'; }
  90   pre.src-ruby:before { content: 'Ruby'; }
  91   pre.src-sass:before { content: 'Sass'; }
  92   pre.src-scheme:before { content: 'Scheme'; }
  93   pre.src-screen:before { content: 'Gnu Screen'; }
  94   pre.src-sed:before { content: 'Sed'; }
  95   pre.src-sh:before { content: 'shell'; }
  96   pre.src-sql:before { content: 'SQL'; }
  97   pre.src-sqlite:before { content: 'SQLite'; }
  98   /* additional languages in org.el's org-babel-load-languages alist */
  99   pre.src-forth:before { content: 'Forth'; }
 100   pre.src-io:before { content: 'IO'; }
 101   pre.src-J:before { content: 'J'; }
 102   pre.src-makefile:before { content: 'Makefile'; }
 103   pre.src-maxima:before { content: 'Maxima'; }
 104   pre.src-perl:before { content: 'Perl'; }
 105   pre.src-picolisp:before { content: 'Pico Lisp'; }
 106   pre.src-scala:before { content: 'Scala'; }
 107   pre.src-shell:before { content: 'Shell Script'; }
 108   pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
 109   /* additional language identifiers per "defun org-babel-execute"
 110        in ob-*.el */
 111   pre.src-cpp:before  { content: 'C++'; }
 112   pre.src-abc:before  { content: 'ABC'; }
 113   pre.src-coq:before  { content: 'Coq'; }
 114   pre.src-groovy:before  { content: 'Groovy'; }
 115   /* additional language identifiers from org-babel-shell-names in
 116      ob-shell.el: ob-shell is the only babel language using a lambda to put
 117      the execution function name together. */
 118   pre.src-bash:before  { content: 'bash'; }
 119   pre.src-csh:before  { content: 'csh'; }
 120   pre.src-ash:before  { content: 'ash'; }
 121   pre.src-dash:before  { content: 'dash'; }
 122   pre.src-ksh:before  { content: 'ksh'; }
 123   pre.src-mksh:before  { content: 'mksh'; }
 124   pre.src-posh:before  { content: 'posh'; }
 125   /* Additional Emacs modes also supported by the LaTeX listings package */
 126   pre.src-ada:before { content: 'Ada'; }
 127   pre.src-asm:before { content: 'Assembler'; }
 128   pre.src-caml:before { content: 'Caml'; }
 129   pre.src-delphi:before { content: 'Delphi'; }
 130   pre.src-html:before { content: 'HTML'; }
 131   pre.src-idl:before { content: 'IDL'; }
 132   pre.src-mercury:before { content: 'Mercury'; }
 133   pre.src-metapost:before { content: 'MetaPost'; }
 134   pre.src-modula-2:before { content: 'Modula-2'; }
 135   pre.src-pascal:before { content: 'Pascal'; }
 136   pre.src-ps:before { content: 'PostScript'; }
 137   pre.src-prolog:before { content: 'Prolog'; }
 138   pre.src-simula:before { content: 'Simula'; }
 139   pre.src-tcl:before { content: 'tcl'; }
 140   pre.src-tex:before { content: 'TeX'; }
 141   pre.src-plain-tex:before { content: 'Plain TeX'; }
 142   pre.src-verilog:before { content: 'Verilog'; }
 143   pre.src-vhdl:before { content: 'VHDL'; }
 144   pre.src-xml:before { content: 'XML'; }
 145   pre.src-nxml:before { content: 'XML'; }
 146   /* add a generic configuration mode; LaTeX export needs an additional
 147      (add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
 148   pre.src-conf:before { content: 'Configuration File'; }
 149
 150   table { border-collapse:collapse; }
 151   caption.t-above { caption-side: top; }
 152   caption.t-bottom { caption-side: bottom; }
 153   td, th { vertical-align:top;  }
 154   th.org-right  { text-align: center;  }
 155   th.org-left   { text-align: center;   }
 156   th.org-center { text-align: center; }
 157   td.org-right  { text-align: right;  }
 158   td.org-left   { text-align: left;   }
 159   td.org-center { text-align: center; }
 160   dt { font-weight: bold; }
 161   .footpara { display: inline; }
 162   .footdef  { margin-bottom: 1em; }
 163   .figure { padding: 1em; }
 164   .figure p { text-align: center; }
 165   .equation-container {
 166     display: table;
 167     text-align: center;
 168     width: 100%;
 169   }
 170   .equation {
 171     vertical-align: middle;
 172   }
 173   .equation-label {
 174     display: table-cell;
 175     text-align: right;
 176     vertical-align: middle;
 177   }
 178   .inlinetask {
 179     padding: 10px;
 180     border: 2px solid gray;
 181     margin: 10px;
 182     background: #ffffcc;
 183   }
 184   #org-div-home-and-up
 185    { text-align: right; font-size: 70%; white-space: nowrap; }
 186   textarea { overflow-x: auto; }
 187   .linenr { font-size: smaller }
 188   .code-highlighted { background-color: #ffff00; }
 189   .org-info-js_info-navigation { border-style: none; }
 190   #org-info-js_console-label
 191     { font-size: 10px; font-weight: bold; white-space: nowrap; }
 192   .org-info-js_search-highlight
 193     { background-color: #ffff00; color: #000000; font-weight: bold; }
 194   .org-svg { }
 195 </style>
 196 <link rel="stylesheet" type="text/css" href="https://thomasf.github.io/solarized-css/solarized-dark.min.css" />
 197 </head>
 198 <body>
 199 <div id="content" class="content">
 200 <h1 class="title">Commandline interface arguments processing</h1>
 201 <div id="table-of-contents" role="doc-toc">
 202 <h2>Table of Contents</h2>
 203 <div id="text-table-of-contents" role="doc-toc">
 204 <ul>
 205 <li><a href="#orga388043">1. Terminology</a>
 206 <ul>
 207 <li><a href="#orgc364e3e">1.1. Command and argument</a></li>
 208 <li><a href="#org607ea14">1.2. Subcommand</a></li>
 209 <li><a href="#org3f1a445">1.3. Option</a></li>
 210 <li><a href="#orgf5c6947">1.4. Parameter</a></li>
 211 </ul>
 212 </li>
 213 </ul>
 214 </div>
 215 </div>
 216 <ul class="org-ul">
 217 <li><a href="index.html#ID-bb4f96cd-458c-495b-a605-313b2e3e28d2">Back to CLI Helper - library main page</a></li>
 218 </ul>
 219
 220 <div id="outline-container-orga388043" class="outline-2">
 221 <h2 id="orga388043"><span class="section-number-2">1.</span> Terminology</h2>
 222 <div class="outline-text-2" id="text-1">
 223 </div>
 224 <div id="outline-container-orgc364e3e" class="outline-3">
 225 <h3 id="orgc364e3e"><span class="section-number-3">1.1.</span> Command and argument</h3>
 226 <div class="outline-text-3" id="text-1-1">
 227 <p>
 228 Every command-line application has a way of receiving input from
 229 users, usually in the form of command-line arguments. A command-line
 230 argument is a piece of information provided to the command-line
 231 application when it's invoked. These arguments are provided as an
 232 array of strings. The first element of the array (argument 0) is
 233 typically the name of the command itself.
 234 </p>
 235
 236 <p>
 237 In the example below, 'my-video-coder' is our command, and the rest
 238 are arguments:
 239 </p>
 240
 241 <div class="org-src-container">
 242 <pre class="src src-shell">my-video-coder encode --input vid1.mp4 vid2.mp4 vid3.mp4 --quality 5
 243 </pre>
 244 </div>
 245
 246 <p>
 247 To better understand how these concepts work together, let's break
 248 down our example command:
 249 </p>
 250
 251 <table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
 252
 253
 254 <colgroup>
 255 <col  class="org-right" />
 256
 257 <col  class="org-left" />
 258
 259 <col  class="org-left" />
 260 </colgroup>
 261 <thead>
 262 <tr>
 263 <th scope="col" class="org-right">argument #</th>
 264 <th scope="col" class="org-left">value(s)</th>
 265 <th scope="col" class="org-left">type</th>
 266 </tr>
 267 </thead>
 268 <tbody>
 269 <tr>
 270 <td class="org-right">0</td>
 271 <td class="org-left">my-video-coder</td>
 272 <td class="org-left">command</td>
 273 </tr>
 274
 275 <tr>
 276 <td class="org-right">1</td>
 277 <td class="org-left">encode</td>
 278 <td class="org-left"><a href="#org607ea14">subcommand</a></td>
 279 </tr>
 280
 281 <tr>
 282 <td class="org-right">2</td>
 283 <td class="org-left">&#x2013;input</td>
 284 <td class="org-left"><a href="#org3f1a445">option1</a></td>
 285 </tr>
 286
 287 <tr>
 288 <td class="org-right">3, 4, 5</td>
 289 <td class="org-left">vid1.mp4 vid2.mp4 vid3.mp4</td>
 290 <td class="org-left"><a href="#orgf5c6947">parameters for &#x2013;input option</a></td>
 291 </tr>
 292
 293 <tr>
 294 <td class="org-right">6</td>
 295 <td class="org-left">&#x2013;quality</td>
 296 <td class="org-left"><a href="#org3f1a445">option2</a></td>
 297 </tr>
 298
 299 <tr>
 300 <td class="org-right">7</td>
 301 <td class="org-left">5</td>
 302 <td class="org-left"><a href="#orgf5c6947">parameter for &#x2013;quaily option</a></td>
 303 </tr>
 304 </tbody>
 305 </table>
 306 </div>
 307 </div>
 308
 309 <div id="outline-container-org607ea14" class="outline-3">
 310 <h3 id="org607ea14"><span class="section-number-3">1.2.</span> Subcommand</h3>
 311 <div class="outline-text-3" id="text-1-2">
 312 <p>
 313 Subcommands are arguments that invoke more specific action that a
 314 command can perform. They are often used with commands that have
 315 multiple functions. In our example, <b>encode</b> is a subcommand of
 316 <b>my-video-coder</b>.
 317 </p>
 318 </div>
 319 </div>
 320
 321 <div id="outline-container-org3f1a445" class="outline-3">
 322 <h3 id="org3f1a445"><span class="section-number-3">1.3.</span> Option</h3>
 323 <div class="outline-text-3" id="text-1-3">
 324 <p>
 325 Options are arguments that change the behavior of a command or
 326 subcommand. They usually start with a dash (-) or double dash
 327 (&#x2013;). For instance, <b>&#x2013;input</b> and <b>&#x2013;quality</b> are options in our
 328 example command.
 329 </p>
 330 </div>
 331 </div>
 332
 333 <div id="outline-container-orgf5c6947" class="outline-3">
 334 <h3 id="orgf5c6947"><span class="section-number-3">1.4.</span> Parameter</h3>
 335 <div class="outline-text-3" id="text-1-4">
 336 <p>
 337 Parameter provides additional information to a command, subcommand or
 338 option.
 339 </p>
 340
 341 <p>
 342 For instance, in our example:
 343 </p>
 344 <ul class="org-ul">
 345 <li>'vid1.mp4 vid2.mp4 vid3.mp4' are parameters for the <b>&#x2013;input</b> option.</li>
 346 <li>'5' is a parameter for the <b>&#x2013;quality</b> option.</li>
 347 </ul>
 348 </div>
 349 </div>
 350 </div>
 351 </div>
 352 <div id="postamble" class="status">
 353 <p class="author">Author: Svjatoslav Agejenko</p>
 354 <p class="date">Created: 2023-10-12 Thu 23:05</p>
 355 <p class="validation"><a href="https://validator.w3.org/check?uri=referer">Validate</a></p>
 356 </div>
 357 </body>
 358 </html>