github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/builtins/core/management/shell_doc.yaml (about)

     1  - DocumentID: summary
     2    Title: >+
     3      `summary` 
     4    CategoryID: commands
     5    Summary: >-
     6      Defines a summary help text for a command
     7    Description: |-
     8      `summary` define help text for a command. This is effectively like a tooltip
     9      message that appears, by default, in blue in the interactive shell.
    10  
    11      Normally this text is populated from the `man` pages or `murex-docs`, however
    12      if neither exist or if you wish to override their text, then you can use
    13      `summary` to define that text.
    14    Usage: |-
    15      Define a commands summary
    16  
    17      ```
    18      summary command description
    19      ```
    20  
    21      Undefine a summary
    22  
    23      ```
    24      !summary command
    25      ```
    26  
    27    Examples: |-
    28      Define a commands summary
    29  
    30      ```
    31      » summary foobar "Hello, world!"
    32      » runtime --summaries -> [ foobar ]
    33      Hello, world! 
    34      ```
    35  
    36      Undefine a summary
    37  
    38      ```
    39      » !summary foobar
    40      ```
    41    Flags:
    42    Detail:
    43    Synonyms:
    44    - summary
    45    - "!summary"
    46    Related:
    47    - config
    48    - runtime
    49    - murex-docs
    50    - murex-update-exe-list
    51    - builtins
    52    - bexists
    53    - exec
    54    - fid-list
    55  
    56  
    57  
    58  - DocumentID: murex-parser
    59    Title: >+
    60      `murex-parser` 
    61    CategoryID: commands
    62    Summary: >-
    63      Runs the Murex parser against a block of code 
    64    Description: |-
    65      `summary` define help text for a command. This is effectively like a tooltip
    66      message that appears, by default, in blue in the interactive shell.
    67  
    68      Normally this text is populated from the `man` pages or `murex-docs`, however
    69      if neither exist or if you wish to override their text, then you can use
    70      `summary` to define that text.
    71    Usage: |-
    72      ```
    73      <stdin> -> murex-parser -> <stdout>
    74  
    75      murex-parser { code-block } -> <stdout>
    76      ```
    77    Examples:
    78    Flags:
    79    Detail:
    80      Please note this command is still very much in beta and is likely to change
    81      in incompatible ways in the future. If you do happen to like this command
    82      and/or have any suggestions on how to improve it, then please leave your
    83      feedback on the GitHub repository, https://github.com/lmorg/murex
    84    Synonyms:
    85    Related:
    86    - config
    87    - runtime
    88    - murex-docs
    89  
    90  
    91  
    92  - DocumentID: args
    93    Title: >+
    94      `args` 
    95    CategoryID: commands
    96    Summary: >-
    97      Command line flag parser for Murex shell scripting
    98    Description: |-
    99      One of the nuisances of shell scripts is handling flags. More often than not
   100      your script will be littered with `$1` still variables and not handle flags
   101      shifting in placement amongst a group of parameters. `args` aims to fix that by
   102      providing a common tool for parsing flags.
   103  
   104      `args` takes a name of a variable to assign the result of the parsed parameters
   105      as well as a JSON structure containing the result. It also returns a non-zero
   106      exit number if there is an error when parsing.
   107    Usage: |-
   108      ```
   109      args var-name { json-block } -> <stdout>
   110      ```
   111    Examples: |-
   112      ```
   113      {{ include "examples/flags.mx" }}
   114      ```
   115    Flags:
   116    Detail:
   117    Synonyms:
   118    Related:
   119    - reserved-vars
   120  
   121  
   122  
   123  - DocumentID: man-get-flags
   124    Title: >+
   125      `man-get-flags` 
   126    CategoryID: commands
   127    Summary: >-
   128      Parses man page files for command line flags 
   129    Description: |-
   130      Sometimes you might want to programmatically search `man` pages for any
   131      supported flag. Particularly if you're writing a dynamic autocompletion.
   132      `man-get-flags` does this and returns a JSON document.
   133  
   134      You can either pipe a man page to `man-get-flags`, or pass the name of the
   135      command as a parameter.
   136  
   137      `man-get-flags` returns a JSON document. Either an array or an object,
   138      depending on what flags (if any) are passed.
   139  
   140      If no flags are passed, `man-get-flags` will default to just parsing the man
   141      page for anything that looks like a flag (ie no descriptions or other detail).
   142    Usage: |-
   143      ```
   144      <stdin> -> man-get-flags [--descriptions] -> <stdout>
   145  
   146      man-get-flags command [--descriptions] -> <stdout>
   147      ```
   148    Examples: |-
   149      ```
   150      » man-get-flags --descriptions find -> [{$.key =~ 'regex'}]
   151      {
   152          "-iregex": "eg: pattern -- Like -regex, but the match is case insensitive.",
   153          "-regex": "eg: pattern -- True if the whole path of the file matches pattern using regular expression.  To match a file named “./foo/xyzzy”, you can use the regular expression “.*/[xyz]*” or “.*/foo/.*”, but not “xyzzy” or “/foo/”."
   154      }
   155      ```
   156    Flags:
   157      --descriptions: >-
   158        return a map of flags with their described usage
   159      -d: >-
   160        shorthand for `--descriptions`
   161    Detail: |-
   162      ### Limitations
   163  
   164      Due to the freeform nature of man pages - that they're intended to be human
   165      readable rather than machine readable - and the flexibility that developers
   166      have to parse command line parameters however they wish, there will always be
   167      a margin for error with how reliably any parser can autodetect parameters. one
   168      requirement is that flags are hyphen prefixed, eg `--flag`.
   169    Synonyms:
   170    Related:
   171    - murex-docs
   172    - summary
   173    - man-summary