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

     1  # `break`
     2  
     3  > Terminate execution of a block within your processes scope
     4  
     5  ## Description
     6  
     7  `break` will terminate execution of a block (eg `function`, `private`,
     8  `foreach`, `if`, etc).
     9  
    10  `break` requires a parameter and that parameter is the name of the caller
    11  block you wish to break out of. If it is a `function` or `private`, then it
    12  will be the name of that function or private. If it is an `if` or `foreach`
    13  loop, then it will be `if` or `foreach` (respectively).
    14  
    15  ## Usage
    16  
    17  ```
    18  break block-name
    19  ```
    20  
    21  ## Examples
    22  
    23  **Exiting an iteration block:**
    24  
    25  ```
    26  function foo {
    27      %[1..10] -> foreach i {
    28          out $i
    29          if { $i == 5 } then {
    30              out "exit running function"
    31              break foo
    32              out "ended"
    33          }
    34      }
    35  }
    36  ```
    37  
    38  Running the above code would output:
    39  
    40  ```
    41  ยป foo
    42  1
    43  2
    44  3
    45  4
    46  5
    47  exit running function
    48  ```
    49  
    50  **Exiting a function:**
    51  
    52  `break` can be considered to exhibit the behavior of _return_ (from other
    53  languages) too
    54  
    55  ```
    56  function example {
    57      if { $USER == "root" } then {
    58          err "Don't run this as root"
    59          break example
    60      }
    61      
    62      # ... do something ...
    63  }
    64  ```
    65  
    66  Though in this particular use case it is recommended that you use `return`
    67  instead, the above code does illustrate how `break` behaves.
    68  
    69  ## Detail
    70  
    71  `break` cannot escape the bounds of its scope (typically the function it is
    72  running inside). For example, in the following code we are calling `break
    73  bar` (which is a different function) inside of the function `foo`:
    74  
    75  ```
    76  function foo {
    77      %[1..10] -> foreach i {
    78          out $i
    79          if { $i == 5 } then {
    80              out "exit running function"
    81              break bar
    82              out "ended"
    83          }
    84      }
    85  }
    86  
    87  function bar {
    88      foo
    89  }
    90  ```
    91  
    92  Regardless of whether we run `foo` or `bar`, both of those functions will
    93  raise the following error:
    94  
    95  ```
    96  Error in `break` (7,17): no block found named `bar` within the scope of `foo`
    97  ```
    98  
    99  ## See Also
   100  
   101  * [`continue`](../commands/continue.md):
   102    Terminate process of a block within a caller function
   103  * [`exit`](../commands/exit.md):
   104    Exit murex
   105  * [`foreach`](../commands/foreach.md):
   106    Iterate through an array
   107  * [`formap`](../commands/formap.md):
   108    Iterate through a map or other collection of data
   109  * [`function`](../commands/function.md):
   110    Define a function block
   111  * [`if`](../commands/if.md):
   112    Conditional statement to execute different blocks of code depending on the result of the condition
   113  * [`out`](../commands/out.md):
   114    Print a string to the STDOUT with a trailing new line character
   115  * [`private`](../commands/private.md):
   116    Define a private function block
   117  * [`return`](../commands/return.md):
   118    Exits current function scope
   119  
   120  <hr/>
   121  
   122  This document was generated from [builtins/core/structs/break_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/structs/break_doc.yaml).