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

     1  - DocumentID: read
     2    Title: >+
     3      `read`
     4    CategoryID: commands
     5    Summary: >-
     6      `read` a line of input from the user and store as a variable
     7    Description: |-
     8      A readline function to allow a line of data inputed from the terminal.
     9    Usage: |-
    10      Classic usage:
    11  
    12      ```
    13      read "prompt" var_name
    14  
    15      <stdin> -> read var_name
    16      ```
    17  
    18      Script usage:
    19  
    20      ```
    21      read [ --prompt "prompt"         ]
    22           [ --variable var_name       ]
    23           [ --default "default value" ]
    24           [ --datatype data-type      ]
    25           [ --autocomplete { json }   ]
    26           [ --mask character          ]
    27      ```
    28    Examples: |-
    29      **Classic usage:**
    30  
    31      ```
    32      read "What is your name? " name
    33      out "Hello $name"
    34  
    35      out What is your name? -> read name
    36      out "Hello $name"
    37      ```
    38  
    39      **Script usage:**
    40  
    41      ```
    42      read --prompt "Are you sure? [Y/n]" \
    43            --variable yn \
    44            --default Y
    45      ```
    46  
    47      **Secrets:**
    48  
    49      ```
    50      read --prompt "Password: " --variable pw --mask *
    51      ```
    52    Detail: |-
    53      ### Classic Usage
    54  
    55      If `read` is called as a method then the prompt string is taken from STDIN.
    56      Otherwise the prompt string will be the first parameter. However if no prompt
    57      string is given then `read` will not write a prompt.
    58  
    59      The last parameter will be the variable name to store the string read by `read`.
    60      This variable cannot be prefixed by dollar, `$`, otherwise the shell will write
    61      the output of that variable as the last parameter rather than the name of the
    62      variable.
    63  
    64      The data type the `read` line will be stored as is `str` (string). If you
    65      require this to be different then please use `tread` (typed read) or call `read`
    66      with the `--datatype` flag as per the **script usage**.
    67    Flags:
    68      --prompt: User notification to display
    69      --variable: "Variable name to store the read data (default: read)"
    70      --datatype: "Murex data-type for the read data (default: str)"
    71      --default: If a zero length string is returned but neither `ctrl`+`c` nor `ctrl`+`d`
    72                 were pressed, then the default value defined here will be returned
    73      --autocomplete: "Autocompletion suggestions. Can be either a JSON array or a JSON object"
    74      --mask: "Optional password mask, for reading secrets"
    75    Synonyms:
    76    Related:
    77    - tout
    78    - err
    79    - brace-quote
    80    - cast
    81    - greater-than
    82    - greater-than-greater-than
    83    - out
    84    - tread
    85  
    86  
    87  
    88  - DocumentID: tread
    89    Title: >+
    90      `tread`
    91    CategoryID: commands
    92    Summary: >-
    93      `read` a line of input from the user and store as a user defined *typed* variable (deprecated)
    94    Description: |-
    95      A readline function to allow a line of data inputted from the terminal and then
    96      store that as a typed variable.
    97  
    98      **This builtin is now deprecated. Please use `read --datatype ...` instead**
    99    Usage: |-
   100      ```
   101      tread data-type "prompt" var_name
   102  
   103      <stdin> -> tread data-type var_name
   104      ```
   105    Examples: |-
   106      ```
   107      tread qs "Please paste a URL: " url
   108      out "The query string values included were:"
   109      $url -> format json
   110  
   111      out Please paste a URL: -> tread qs url
   112      out "The query string values included were:"
   113      $url -> format json
   114      ```
   115    Detail: |-
   116      If `tread` is called as a method then the prompt string is taken from STDIN.
   117      Otherwise the prompt string will be the first parameter. However if no prompt
   118      string is given then `tread` will not write a prompt.
   119  
   120      The last parameter will be the variable name to store the string read by `tread`.
   121      This variable cannot be prefixed by dollar, `$`, otherwise the shell will write
   122      the output of that variable as the last parameter rather than the name of the
   123      variable.
   124    Synonyms:
   125    Related:
   126    - tout
   127    - err
   128    - brace-quote
   129    - cast
   130    - pretty
   131    - format
   132    - out
   133    - read