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

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