github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/builtins/core/structs/break_doc.yaml

- DocumentID: return
  Title: >+
    `return`
  CategoryID: commands
  Summary: >-
    Exits current function scope
  Description: |-
    `return` will terminate execution of a block at the scope level (eg `function`,
    `private`, etc)

    Conceptually it is the same as `break` except it doesn't require the scope name
    as a parameter and you can specify the exit number rather than defaulting to 0.
  Usage: |-
    ```
    return [ exit-number ]
    ```
  Examples: |-
    **Setting an exit number:**

    ```
    function example {
        out foo
        return 13
        out bar
    }
    example
    exitnum
    ```

    Running the above code would output:

    ```
    foo
    13
    ```

    **Returning withing an exit number:**

    If we were to run the same code as above but with `return` written without any
    parameters (ie instead of `return 13` it would be just `return`), then you
    would see the following output:

    ```
    foo
    0
    ```
  Flags:
  Detail: |-
    Any process that has been initialised within a `return`ed scope will have their
    exit number updated to the value specified in `return` (or `0` if no parameter
    was passed).
  Synonyms:
  Related:
    - exit
    - function
    - private
    - out
    - break
    - continue
    - exitnum

- DocumentID: break
  Title: >+
    `break`
  CategoryID: commands
  Summary: >-
    Terminate execution of a block within your processes scope
  Description: |-
    `break` will terminate execution of a block (eg `function`, `private`,
    `foreach`, `if`, etc).

    `break` requires a parameter and that parameter is the name of the caller
    block you wish to break out of. If it is a `function` or `private`, then it
    will be the name of that function or private. If it is an `if` or `foreach`
    loop, then it will be `if` or `foreach` (respectively).
  Usage: |-
    ```
    break block-name
    ```
  Examples: |-
    **Exiting an iteration block:**

    ```
    function foo {
        %[1..10] -> foreach i {
            out $i
            if { $i == 5 } then {
                out "exit running function"
                break foo
                out "ended"
            }
        }
    }
    ```

    Running the above code would output:

    ```
    » foo
    1
    2
    3
    4
    5
    exit running function
    ```

    **Exiting a function:**

    `break` can be considered to exhibit the behavior of _return_ (from other
    languages) too

    ```
    function example {
        if { $USER == "root" } then {
            err "Don't run this as root"
            break example
        }
        
        # ... do something ...
    }
    ```

    Though in this particular use case it is recommended that you use `return`
    instead, the above code does illustrate how `break` behaves.
  Flags:
  Detail: |-
    `break` cannot escape the bounds of its scope (typically the function it is
    running inside). For example, in the following code we are calling `break
    bar` (which is a different function) inside of the function `foo`:

    ```
    function foo {
        %[1..10] -> foreach i {
            out $i
            if { $i == 5 } then {
                out "exit running function"
                break bar
                out "ended"
            }
        }
    }

    function bar {
        foo
    }
    ```

    Regardless of whether we run `foo` or `bar`, both of those functions will
    raise the following error:

    ```
    Error in `break` (7,17): no block found named `bar` within the scope of `foo`
    ```
  Synonyms:
  Related:
    - exit
    - foreach
    - formap
    - if
    - function
    - private
    - out
    - continue
    - return

- DocumentID: continue
  Title: >+
    `continue`
  CategoryID: commands
  Summary: >-
    Terminate process of a block within a caller function
  Description: |-
    `continue` will terminate execution of a block (eg `function`, `private`,
    `foreach`, `if`, etc) right up until the caller function. In iteration loops
    like `foreach` and `formap` this will result in behavior similar to the
    `continue` statement in other programming languages.
  Usage: |-
    ```
    continue block-name
    ```
  Examples: |-
    ```
    %[1..10] -> foreach i {
        if { $i == 5 } then {
            out "continue"
            continue foreach
            out "skip this code"
        }
        out $i
    }
    ```

    Running the above code would output:

    ```
    » foo
    1
    2
    3
    4
    continue
    6
    7
    8
    9
    10
    ```
  Flags:
  Detail: |-
    `continue` cannot escape the bounds of its scope (typically the function it is
    running inside). For example, in the following code we are calling `continue
    bar` (which is a different function) inside of the function `foo`:

    ```
    function foo {
        %[1..10] -> foreach i {
            out $i
            if { $i == 5 } then {
                out "exit running function"
                continue bar
                out "ended"
            }
        }
    }

    function bar {
        foo
    }
    ```

    Regardless of whether we run `foo` or `bar`, both of those functions will
    raise the following error:

    ```
    Error in `continue` (7,17): no block found named `bar` within the scope of `foo`
    ```
  Synonyms:
  Related:
    - exit
    - foreach
    - formap
    - if
    - function
    - private
    - out
    - break
    - return