github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/gen/parser/pipes_doc.yaml

- DocumentID: pipe-arrow
  Title: >-
     `->` Arrow Pipe
  CategoryID: parser
  Summary: >-
    Pipes STDOUT from the left hand command to STDIN of the right hand command
  Description: |-
    This token behaves much like pipe would in Bash or similar shells. It passes
    STDOUT along the pipeline while merging STDERR stream with the parents STDERR
    stream.

    `->` differs from `|` in the interactive terminal where it produces different
    autocompletion suggestion. It returns a list of "methods". That is, commands
    that are known to support the output type of the previous command. `->` helps
    with the discovery of commandline tools.

    In shell scripts, `->` and `|` can be used interchangeably.
  Examples: |-
    ```
    » out Hello, world! -> regexp s/world/Earth/
    Hello, Earth!

    » out Hello, world!->regexp s/world/Earth/
    Hello, Earth!
    ```

    In following example the first command is writing to STDERR rather than STDOUT
    so `Hello, world!` doesn't get pipelined and thus isn't affected by `regexp`:
    
    ```
    » err Hello, world! -> regexp s/world/Earth/
    Hello, world!
    ```
  Detail: |-
  Related:
  - pipe-posix
  - pipe-generic
  - namedpipe
  - pipe-err
  - pipeline
  - out
  - err
  - regexp



- DocumentID: pipe-err
  Title: >-
    `?` STDERR Pipe
  CategoryID: parser
  Summary: >-
    Pipes STDERR from the left hand command to STDIN of the right hand command (DEPRECATED)
  Description: |-
    This token swaps the STDOUT and STDERR streams of the left hand command.

    Please note that this token is only effective when it is prefixed by white
    space.

    > This feature has been deprecated. Please use `<err> <!out>` instead. For example:
    > ```
    > command <err> <!out> parameter-1 parameter-2 -> next-command parameter-1
    > ```
  Examples: |-
    ```
    » err Hello, world! ? regexp s/world/Earth/
    Hello, Earth!
    ```

    In following example the first command is writing to STDOUT rather than STDERR
    so `Hello, world!` doesn't get pipelined and thus isn't affected by `regexp`:
    
    ```
    » out Hello, world! ? regexp s/world/Earth/
    Hello, world!
    ```

    In following example the STDERR token isn't whitespace padded so is treated
    like any ordinary printable character:

    ```
    » err Hello, world!? regexp s/world/Earth/
    Hello, world!? regexp s/world/Earth/
    ```
  Detail: |-
  Related:
  - pipe-arrow
  - pipe-generic
  - namedpipe
  - pipe-posix
  - pipeline
  - out
  - err
  - regexp



- DocumentID: pipe-generic
  Title: >-
    `=>` Generic Pipe
  CategoryID: parser
  Summary: >-
    Pipes a reformatted STDOUT stream from the left hand command to STDIN of the
    right hand command
  Description: |-
    This token behaves much like the `|` pipe would except it injects `format
    generic` into the pipeline. The purpose of a formatted pipe is to support
    piping out to external commands which don't support Murex data types. For
    example they might expect arrays as lists rather than JSON objects).
  Examples: |-
    ```
    » ja [Mon..Wed] => cat
    Mon
    Tue
    Wed
    ```

    The above is literally the same as typing:

    ```
    » ja [Mon..Wed] -> format generic -> cat
    Mon
    Tue
    Wed
    ```

    To demonstrate how the previous pipeline might look without a formatted pipe:
    
    ```
    » ja [Mon..Wed] -> cat
    ["Mon","Tue","Wed"]

    » ja [Mon..Wed] | cat
    ["Mon","Tue","Wed"]

    » ja [Mon..Wed]
    [
        "Mon",
        "Tue",
        "Wed"
    ]
    ```
  Detail: |-
  Related:
  - pipe-arrow
  - pipe-posix
  - namedpipe
  - pipe-err
  - pipeline
  - ja
  - format



- DocumentID: pipe-posix
  Title: >-
    `|` POSIX Pipe
  CategoryID: parser
  Summary: >-
    Pipes STDOUT from the left hand command to STDIN of the right hand command
  Description: |-
    This token behaves much like pipe would in Bash or similar shells. It passes
    STDOUT along the pipeline while merging STDERR stream with the parents STDERR
    stream.

    It can be used interchangeably with the arrow pipe, `->`, in shell scripts.
  Examples: |-
    ```
    » out Hello, world! | regexp s/world/Earth/
    Hello, Earth!

    » out Hello, world!|regexp s/world/Earth/
    Hello, Earth!
    ```

    In this example the first command is writing to STDERR rather than STDOUT so
    `Hello, world!` doesn't get pipelined and thus isn't affected by `regexp`:
    
    ```
    » err Hello, world! | regexp s/world/Earth/
    Hello, world!
    ```
  #Tests: |-
  #  ```go
  #  {{ include "lang/parser_docs/pipeposix_test.go" }}
  #  ```
  Detail: |-
  Related:
  - pipe-arrow
  - pipe-generic
  - namedpipe
  - pipe-err
  - pipeline
  - out
  - err
  - regexp



- DocumentID: pipe-append
  Title: >-
     `>>` Append Pipe
  CategoryID: parser
  Summary: >-
    Redirects STDOUT to a file and append its contents
  Description: |-
    This is used to redirect the STDOUT of a command and append it to a file. If
    that file does not exist, then the file is created.

    This behaves similarly to the [Bash (et al) token](https://www.gnu.org/software/bash/manual/bash.html#Appending-Redirected-Output)
    except it doesn't support adding alternative file descriptor numbers. Instead
    you will need to use named pipes to achieve the same effect in Murex.
  Examples: |-
    ```
    » out "Hello" >> example.txt
    » out "World!" >> example.txt
    » open example.txt
    Hello
    World!
    ```
  Detail: |-
    This is just syntactic sugar for `-> >>`. Thus when the parser reads code like
    the following:
    
    ```
    echo "foobar" >> example.txt
    ```

    it will compile an abstract syntax tree which would reflect the following code
    instead:

    ```
    echo "foobar" | >> example.txt
    ```

    ### Truncating a file

    To truncate a file (ie overwrite its contents) use `|>` instead.
  Related:
  - pipe-arrow
  - pipe-posix
  - namedpipe
  - pipe-err
  - pipeline
  - ja
  - greater-than-greater-than
  - greater-than