github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/commands/args.md (about)

     1  # `args` 
     2  
     3  > Command line flag parser for Murex shell scripting
     4  
     5  ## Description
     6  
     7  One of the nuisances of shell scripts is handling flags. More often than not
     8  your script will be littered with `$1` still variables and not handle flags
     9  shifting in placement amongst a group of parameters. `args` aims to fix that by
    10  providing a common tool for parsing flags.
    11  
    12  `args` takes a name of a variable to assign the result of the parsed parameters
    13  as well as a JSON structure containing the result. It also returns a non-zero
    14  exit number if there is an error when parsing.
    15  
    16  ## Usage
    17  
    18  ```
    19  args var-name { json-block } -> <stdout>
    20  ```
    21  
    22  ## Examples
    23  
    24  ```
    25  #!/usr/bin/env murex
    26  
    27  # First we define what parameters to accept:
    28  # Pass the `args` function a JSON string (because JSON objects share the same braces as murex block, you can enter JSON
    29  # directly as unescaped values as parameters in murex).
    30  #
    31  # --str: str == string data type
    32  # --num: num == numeric data type
    33  # --bool: bool == flag used == true, missing == false
    34  # -b: --bool == alias of --bool flag
    35  args args %{
    36      AllowAdditional: true
    37      Flags: {
    38          --str:  str
    39          --num:  num
    40          --bool: bool
    41          -b: --bool
    42      }
    43  }
    44  catch {
    45      # Lets check for errors in the command line parameters. If they exist then
    46      # print the error and then exit.
    47      err $args.error
    48      exit 1
    49  }
    50  
    51  out "The structure of \$args is: ${$args->pretty}\n\n"
    52  
    53  
    54  # Some example usage:
    55  # -------------------
    56  
    57  !if { $(args.Flags.--bool) } {
    58      out "Flag `--bool` was not set."
    59  }
    60  
    61  # `<!null>` redirects the STDERR to a named pipe. In this instance it's the 'null' pipe so equivalent to 2>/dev/null
    62  # thus we are just suppressing any error messages.
    63  try <!null> {
    64      $(args.Flags.--str) -> set fStr
    65      $(args.Flags.--num) -> set fNum
    66  
    67      out "Defined Flags:"
    68      out "  --str == $(fStr)"
    69      out "  --num == $(fNum)"
    70  }
    71  
    72  catch {
    73      err "Missing `--str` and/or `--num` flags."
    74  }
    75  
    76  $args[Additional] -> foreach flag {
    77      out "Additional argument (ie not assigned to a flag): `$(flag)`."
    78  }
    79  ```
    80  
    81  ## See Also
    82  
    83  * [Reserved Variables](../user-guide/reserved-vars.md):
    84    Special variables reserved by Murex
    85  
    86  <hr/>
    87  
    88  This document was generated from [builtins/core/management/shell_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/management/shell_doc.yaml).