<commit_before>
# Overview #

"Inlined State" is the name of a language-level feature in Circa, which allows for persisted state
data to be declared inside the code where it is used. This construct is the primary method for
an author to declare persisted state.

The benefits of using inlined state are:

1. Convenience for the author
2. Introspection; the system is able to understand exactly which data is stateful.

# Syntax #

State is declared with the `state` keyword, with one of the following syntaxes:

    state <name>
    state <name> = <initial value expression>
    state <type> <name>
    state <type> <name> = <initial value expression>

Examples:

    state a
    state height = get_current_height()
    state List people
    state List people = ['Adam']

A type can be provided. If no type or initial value is provided, then the type is 'any'. If there
is an initial value and no declared type then the type is inferred. In either case, if no initial
value is provided, then the value starts off with the type's default value.

# Behavior #

Inlined state is mainly for preserving *short-term* state: values that persist between
frames. In the future, it's planned to also use this feature for long-term state
(values that persist
between program invocations), but this hasn't been implemented.

A simple example is:

    state int button_presses
    if button_pressed()
        button_presses += 1
    end

Every time this script is run, if `button_pressed()` is true then the `button_presses` count will go up.

# Nesting #

State can be nested in function definitions. An example:

    def my_counting_func(bool trigger) -> int
        state int count
        if trigger
            count += 1
        end
        return count
    end

    def function_that_has_three_counts()
        my_counting_func()
        my_counting_func()
        my_counting_func()
    end

If a piece of code calls a function with inlined state, that code also becomes stateful. Also,
there is a separate piece of state for each call to a stateful function. In the above example,
`function_that_has_three_counts` has three different ints in its state, one for each call.
(So, don't confuse this feature with C's static local variables).

The structure of state data can have many levels of nesting, if the function call graph is nested.
It's also possible to have a recursive function with inlined state (although this doesn't
work in the current implementation). Each recursive call will lazily initialize its state,
so the state data acts like a recursive data type.
<commit_msg>Fix some misleading docs (thanks electronicwhisper)<commit_after>
# Overview #

"Inlined State" is the name of a language-level feature in Circa, which allows for persisted state
data to be declared inside the code where it is used. This construct is the primary method for
an author to declare persisted state.

The benefits of using inlined state are:

1. Convenience for the author
2. Introspection; the system is able to understand exactly which data is stateful.

# Syntax #

State is declared with the `state` keyword, with one of the following syntaxes:

    state <name>
    state <name> = <initial value expression>
    state <type> <name>
    state <type> <name> = <initial value expression>

Examples:

    state a
    state height = get_current_height()
    state List people
    state List people = ['Adam']

A type can be provided. If no type or initial value is provided, then the type is 'any'. If there
is an initial value and no declared type then the type is inferred. In either case, if no initial
value is provided, then the value starts off with the type's default value.

# Behavior #

Inlined state is mainly for preserving *short-term* state: values that persist between
frames. In the future, it's planned to also use this feature for long-term state
(values that persist
between program invocations), but this hasn't been implemented.

A simple example is:

    state int button_presses
    if button_pressed()
        button_presses += 1
    end

Every time this script is run, if `button_pressed()` is true then the `button_presses` count will go up.

# Nesting #

State can be nested in function definitions. An example:

    def my_func_with_state()
        state int i
    end

    def function_that_has_three_integers()
        my_counting_func()
        my_counting_func()
        my_counting_func()
    end

If a piece of code calls a function with inlined state, that code also becomes stateful. Also,
there is a separate piece of state for each call to a stateful function. In the above example,
`function_that_has_three_integers` has three different copies of the state of `my_func_with_state`,
which includes one integer each. (So, don't confuse this with C's static local variables, as
data is not shared across separate calls to the same function)

The structure of state data can have many levels of nesting, if the function call graph is nested.
It's also possible to have a recursive function with inlined state (although this doesn't
work in the current implementation). Each recursive call will lazily initialize its state,
so the state data acts like a recursive data type.

{'fraction_non_alphanumeric': 0.04962492787074437, 'fraction_numerical': 0.0013464127716868628, 'mean_word_length': 3.7058823529411766, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 20, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4121958', 'n_tokens_mistral': 1401, 'n_tokens_neox': 1333, 'n_words': 754}