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

     1  # `<stdin>`
     2  
     3  > Read the STDIN belonging to the parent code block
     4  
     5  ## Description
     6  
     7  This is used inside functions and other code blocks to pass that block's
     8  STDIN down a pipeline
     9  
    10  ## Usage
    11  
    12  ```
    13  <stdin> -> <stdout>
    14  ```
    15  
    16  ## Examples
    17  
    18  When writing more complex scripts, you cannot always invoke your read as the
    19  first command in a code block. For example a simple pipeline might be:
    20  
    21  ```
    22  ยป function example { -> match 2 }
    23  ```
    24  
    25  But this only works if `->` is the very first command. The following would
    26  fail:
    27  
    28  ```
    29  # Incorrect code
    30  function example {
    31      out "only match 2"
    32      -> match 2
    33  }
    34  ```
    35  
    36  This is where `<stdin>` comes to our rescue:
    37  
    38  ```
    39  function example {
    40      out "only match 2"
    41      <stdin> -> match 2
    42  }
    43  ```
    44  
    45  This could also be written as:
    46  
    47  ```
    48  function example { out "only match 2"; <stdin> -> match 2 }
    49  ```
    50  
    51  ## Detail
    52  
    53  `<stdin>` makes use of a feature called **named pipes**, which are a way of
    54  piping data between processes without chaining them together as a single
    55  command pipeline (eg commands delimited with `|`, `->`, `=>`, `?` tokens).
    56  
    57  ### What are Murex named pipes?
    58  
    59  In POSIX, there is a concept of STDIN, STDOUT and STDERR, these are FIFO files
    60  while are "piped" from one executable to another. ie STDOUT for application 'A'
    61  would be the same file as STDIN for application 'B' when A is piped to B:
    62  `A | B`. Murex adds a another layer around this to enable support for passing
    63  data types and builtins which are agnostic to the data serialization format
    64  traversing the pipeline. While this does add overhead the advantage is this new
    65  wrapper can be used as a primitive for channelling any data from one point to
    66  another.
    67  
    68  Murex named pipes are where these pipes are created in a global store,
    69  decoupled from any executing functions, named and can then be used to pass
    70  data along asynchronously.
    71  
    72  For example
    73  
    74  ```
    75  pipe example
    76  
    77  bg {
    78      <example> -> match Hello
    79  }
    80  
    81  out "foobar"        -> <example>
    82  out "Hello, world!" -> <example>
    83  out "foobar"        -> <example>
    84  
    85  !pipe example
    86  ```
    87  
    88  This returns `Hello, world!` because `out` is writing to the **example** named
    89  pipe and `match` is also reading from it in the background (`bg`).
    90  
    91  Named pipes can also be inlined into the command parameters with `<>` tags
    92  
    93  ```
    94  pipe example
    95  
    96  bg {
    97      <example> -> match: Hello
    98  }
    99  
   100  out <example> "foobar"
   101  out <example> "Hello, world!"
   102  out <example> "foobar"
   103  
   104  !pipe example
   105  ```
   106  
   107  > Please note this is also how `test` works.
   108  
   109  Murex named pipes can also represent network sockets, files on a disk or any
   110  other read and/or write endpoint. Custom builtins can also be written in Golang
   111  to support different abstractions so your Murex code can work with those read
   112  or write endpoints transparently.
   113  
   114  To see the different supported types run
   115  
   116  ```
   117  runtime --pipes
   118  ```
   119  
   120  ### Namespaces and usage in modules and packages
   121  
   122  Pipes created via `pipe` are created in the global namespace. This allows pipes
   123  to be used across different functions easily however it does pose a risk with
   124  name clashes where Murex named pipes are used heavily. Thus is it recommended
   125  that pipes created in modules should be prefixed with the name of its package.
   126  
   127  ## Synonyms
   128  
   129  * `<stdin>`
   130  
   131  
   132  ## See Also
   133  
   134  * [Pipeline](../user-guide/pipeline.md):
   135    Overview of what a "pipeline" is
   136  * [`<read-named-pipe>`](../parser/namedpipe.md):
   137    Reads from a Murex named pipe
   138  * [`function`](../commands/function.md):
   139    Define a function block
   140  * [`match`](../commands/match.md):
   141    Match an exact value in an array
   142  * [`out`](../commands/out.md):
   143    Print a string to the STDOUT with a trailing new line character
   144  * [`pipe`](../commands/pipe.md):
   145    Manage Murex named pipes
   146  * [`runtime`](../commands/runtime.md):
   147    Returns runtime information on the internal state of Murex
   148  
   149  <hr/>
   150  
   151  This document was generated from [builtins/core/pipe/namedpipe_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/pipe/namedpipe_doc.yaml).