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

     1  # `read`
     2  
     3  > `read` a line of input from the user and store as a variable
     4  
     5  ## Description
     6  
     7  A readline function to allow a line of data inputed from the terminal.
     8  
     9  ## Usage
    10  
    11  Classic usage:
    12  
    13  ```
    14  read "prompt" var_name
    15  
    16  <stdin> -> read var_name
    17  ```
    18  
    19  Script usage:
    20  
    21  ```
    22  read [ --prompt "prompt"         ]
    23       [ --variable var_name       ]
    24       [ --default "default value" ]
    25       [ --datatype data-type      ]
    26       [ --autocomplete { json }   ]
    27       [ --mask character          ]
    28  ```
    29  
    30  ## Examples
    31  
    32  **Classic usage:**
    33  
    34  ```
    35  read "What is your name? " name
    36  out "Hello $name"
    37  
    38  out What is your name? -> read name
    39  out "Hello $name"
    40  ```
    41  
    42  **Script usage:**
    43  
    44  ```
    45  read --prompt "Are you sure? [Y/n]" \
    46        --variable yn \
    47        --default Y
    48  ```
    49  
    50  **Secrets:**
    51  
    52  ```
    53  read --prompt "Password: " --variable pw --mask *
    54  ```
    55  
    56  ## Flags
    57  
    58  * `--autocomplete`
    59      Autocompletion suggestions. Can be either a JSON array or a JSON object
    60  * `--datatype`
    61      Murex data-type for the read data (default: str)
    62  * `--default`
    63      If a zero length string is returned but neither `ctrl`+`c` nor `ctrl`+`d` were pressed, then the default value defined here will be returned
    64  * `--mask`
    65      Optional password mask, for reading secrets
    66  * `--prompt`
    67      User notification to display
    68  * `--variable`
    69      Variable name to store the read data (default: read)
    70  
    71  ## Detail
    72  
    73  ### Classic Usage
    74  
    75  If `read` is called as a method then the prompt string is taken from STDIN.
    76  Otherwise the prompt string will be the first parameter. However if no prompt
    77  string is given then `read` will not write a prompt.
    78  
    79  The last parameter will be the variable name to store the string read by `read`.
    80  This variable cannot be prefixed by dollar, `$`, otherwise the shell will write
    81  the output of that variable as the last parameter rather than the name of the
    82  variable.
    83  
    84  The data type the `read` line will be stored as is `str` (string). If you
    85  require this to be different then please use `tread` (typed read) or call `read`
    86  with the `--datatype` flag as per the **script usage**.
    87  
    88  ## See Also
    89  
    90  * [`%(Brace Quote)`](../parser/brace-quote.md):
    91    Initiates or terminates a string (variables expanded)
    92  * [`>>` Append File](../parser/greater-than-greater-than.md):
    93    Writes STDIN to disk - appending contents if file already exists
    94  * [`cast`](../commands/cast.md):
    95    Alters the data type of the previous function without altering it's output
    96  * [`err`](../commands/err.md):
    97    Print a line to the STDERR
    98  * [`out`](../commands/out.md):
    99    Print a string to the STDOUT with a trailing new line character
   100  * [`tout`](../commands/tout.md):
   101    Print a string to the STDOUT and set it's data-type
   102  * [`tread`](../commands/tread.md):
   103    `read` a line of input from the user and store as a user defined *typed* variable (deprecated)
   104  * [`|>` Truncate File](../parser/greater-than.md):
   105    Writes STDIN to disk - overwriting contents if file already exists
   106  
   107  <hr/>
   108  
   109  This document was generated from [builtins/core/io/read_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/io/read_doc.yaml).