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

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