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

     1  # `if`
     2  
     3  > Conditional statement to execute different blocks of code depending on the result of the condition
     4  
     5  ## Description
     6  
     7  Conditional control flow
     8  
     9  `if` can be utilized both as a method as well as a standalone function. As a
    10  method, the conditional state is derived from the calling function (eg if the
    11  previous function succeeds then the condition is `true`).
    12  
    13  ## Usage
    14  
    15  ### Function `if`:
    16  
    17  ```
    18  if { code-block } then {
    19      # true
    20  } else {
    21      # false
    22  }
    23  ```
    24  
    25  ### Method `if`:
    26  
    27  ```
    28  command -> if {
    29      # true
    30  } else {
    31      # false
    32  }
    33  ```
    34  
    35  ### Negative Function `if`:
    36  
    37  ```
    38  !if { code-block } then {
    39      # false
    40  }
    41  ```
    42  
    43  ### Negative Method `if`:
    44  
    45  ```
    46  command -> !if {
    47      # false
    48  }
    49  ```
    50  
    51  ### Please Note:
    52  the `then` and `else` statements are optional. So the first usage could
    53  also be written as:
    54  
    55  ```
    56  if { code-block } {
    57      # true
    58  } {
    59      # false
    60  }
    61  ```
    62  
    63  However the practice of omitting those statements isn't recommended beyond
    64  writing short one liners in the interactive command prompt.
    65  
    66  ## Examples
    67  
    68  Check if a file exists:
    69  
    70  ```
    71  if { g somefile.txt } then {
    72      out "File exists"
    73  }
    74  ```
    75  
    76  ...or does not exist (both ways are valid):
    77  
    78  ```
    79  !if { g somefile.txt } then {
    80      out "File does not exist"
    81  }
    82  ```
    83  
    84  ```
    85  if { g somefile.txt } else {
    86      out "File does not exist"
    87  }
    88  ```
    89  
    90  ## Detail
    91  
    92  ### Pipelines and Output
    93  
    94  The conditional block can contain entire pipelines - even multiple lines of code
    95  let alone a single pipeline - as well as solitary commands as demonstrated in
    96  the examples above. However the conditional block does not output STDOUT nor
    97  STDERR to the rest of the pipeline so you don't have to worry about redirecting
    98  the output streams to `null`.
    99  
   100  If you require output from the conditional blocks STDOUT then you will need to
   101  use either a Murex named pipe to redirect the output, or test or debug flags
   102  (depending on your use case) if you only need to occasionally inspect the
   103  conditionals output.
   104  
   105  ### Exit Numbers
   106  
   107  When evaluating a command or code block, `if` will treat an exit number less
   108  than 0 as true, and one greater than 0 as false. When the exit number is 0, `if`
   109  will examine the stdout of the command or code block. If there is no output, or
   110  the output is one of the following strings, `if` will evaluate the command or
   111  code block as false. Otherwise, it will be considered true.
   112  
   113  * `0`
   114  * `disabled`
   115  * `fail`
   116  * `failed`
   117  * `false`
   118  * `no`
   119  * `null`
   120  * `off`
   121  
   122  ## Synonyms
   123  
   124  * `if`
   125  * `!if`
   126  
   127  
   128  ## See Also
   129  
   130  * [`!` (not)](../parser/not-func.md):
   131    Reads the STDIN and exit number from previous process and not's it's condition
   132  * [`and`](../commands/and.md):
   133    Returns `true` or `false` depending on whether multiple conditions are met
   134  * [`catch`](../commands/catch.md):
   135    Handles the exception code raised by `try` or `trypipe`
   136  * [`debug`](../commands/debug.md):
   137    Debugging information
   138  * [`false`](../commands/false.md):
   139    Returns a `false` value
   140  * [`or`](../commands/or.md):
   141    Returns `true` or `false` depending on whether one code-block out of multiple ones supplied is successful or unsuccessful.
   142  * [`switch`](../commands/switch.md):
   143    Blocks of cascading conditionals
   144  * [`test`](../commands/test.md):
   145    Murex's test framework - define tests, run tests and debug shell scripts
   146  * [`true`](../commands/true.md):
   147    Returns a `true` value
   148  * [`try`](../commands/try.md):
   149    Handles non-zero exits inside a block of code
   150  * [`trypipe`](../commands/trypipe.md):
   151    Checks for non-zero exits of each function in a pipeline
   152  
   153  <hr/>
   154  
   155  This document was generated from [builtins/core/structs/if_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/structs/if_doc.yaml).