## dist_zef-raku-community-modules-Marpa.md
## Chunk 2 of 3
\_symbol\_is\_predicted\_event() method returns the current value of the predicted event marking for symbol sym\_id. Marking a prediction event sets its activation status to on. Unmarking a prediction event sets its activation status to off. The prediction event marking cannot be changed once the grammar is precomputed. If a prediction event is marked, its activation status can be changed using the marpa\_g\_prediction\_symbol\_activate() method. Note that, if a symbol is marked as a prediction event symbol in the recognizer, its prediction event can be deactivated and reactivated in the recognizer. Success: On success, 1 if symbol sym\_id is a predicted event symbol after the call, 0 otherwise. Failures: If sym\_id is well-formed, but there is no such symbol, −1. If the grammar g is precomputed; or on other failure, −2.

### sub marpa\_g\_precompute

```
sub marpa_g_precompute(
    Marpa::g $g
) returns Int

```

Precomputation is necessary for a recognizer to be generated from a grammar. On success, marpa\_g\_precompute returns a non-negative number to indicate that it precomputed the grammar without issues. On failure, marpa\_g\_precompute returns −2. Precomputation may return one or more events, which may be queried using the marpa\_g\_event() method. At this point events only occur when failure is reported, and events always report issues. But application writers should expect future versions to have events which are reported on success, as well as events which do not represent issues. A MARPA-EVENT-LOOP-RULES event occurs when there are infinite loop rules (cycles) in the grammar. The presence of one or more of these will cause failure to be reported, but will not prevent the grammar from being precomputed. Each MARPA-EVENT-COUNTED-NULLABLE event is a symbol which is a nullable on the right hand side of a sequence rule — a “counted” symbol. The presence of one or more of these will cause failure to be reported, and will prevent the grammar from being precomputed. So that the programmer can fix several at once, these failures are delayed until events are created for all of the counted nullables. Each MARPA-EVENT-NULLING-TERMINAL event is a nulling symbol which is also flagged as a terminal. Since terminals cannot be of zero length, this is a logical impossibility. The presence of one or more of these will cause failure to be reported, and will prevent the grammar from being precomputed. So that the programmer can fix several at once, the failure is delayed until events are created for all of the counted nullables. Precomputation involves freezing and then thoroughly checking the grammar. Among the reasons for precomputation to fail are the following: MARPA-ERR-NO-RULES: The grammar has no rules. MARPA-ERR-NO-START-SYMBOL: No start symbol was specified. MARPA-ERR-INVALID-START-SYMBOL: A start symbol ID was specified, but it is not the ID of a valid symbol. MARPA-ERR-START-NOT-LHS: The start symbol is not on the LHS of any rule. MARPA-ERR-UNPRODUCTIVE-START: The start symbol is not productive. MARPA-ERR-COUNTED-NULLABLE: A symbol on the RHS of a sequence rule is nullable. Libmarpa does not allow this. MARPA-ERR-NULLING-TERMINAL: A terminal is also a nulling symbol. Libmarpa does not allow this. More details of these can be found under the description of the appropriate code. See External error codes. marpa\_g\_precompute() is unusual in that it is possible to treat one of its failures as “advisory”, and to proceed with parsing. If marpa\_g\_precompute() fails with an error code of MARPA-ERR-GRAMMAR-HAS-CYCLE, parsing can proceed, just as it typically would for success. The grammar will have been precomputed, as calling the marpa\_g\_is\_precomputed() method will confirm. Most applications, however, will want to simply treat failure with MARPA-ERR-GRAMMAR-HAS-CYCLE, as simply another failure, and fix the cycles before parsing. Cycles make a grammar infinitely ambiguous, and are considered useless in current practice. Cycles make processing the grammar less efficient, sometimes considerably so. Detection of cycles is returned as failure because that is by far the convenient thing to do for the vast majority of applications. Success value: A non-negative number. Failure value: −2.

### sub marpa\_g\_is\_precomputed

```
sub marpa_g_is_precomputed(
    Marpa::g $g
) returns Int

```

Success value: 1 if grammar g is already precomputed, 0 otherwise. Failure value: −2.

### sub marpa\_g\_has\_cycle

```
sub marpa_g_has_cycle(
    Marpa::g $g
) returns Int

```

This function allows the application to determine if grammar g has a cycle. As mentioned, most applications will want to treat these as fatal errors. To determine which rules are in the cycle, marpa\_g\_rule\_is\_loop() can be used. Success value: 1 if the grammar has a cycle, 0 otherwise. Failure value: −2.

### sub marpa\_r\_new

```
sub marpa_r_new(
    Marpa::g $g
) returns Marpa::Marpa-Recognizer

```

Creates a new recognizer. The reference count of the recognizer will be 1. The reference count of g, the base grammar, will be incremented by one. Success value: The newly created recognizer. If g is not precomputed, or on other failure, NULL. Failure value: NULL.

### sub marpa\_r\_ref

```
sub marpa_r_ref(
    Marpa::Marpa-Recognizer $r
) returns Marpa::Marpa-Recognizer

```

Increases the reference count by 1. Not needed by most applications. Success value: The recognizer object, $r. Failure value: NULL.

### sub marpa\_r\_unref

```
sub marpa_r_unref(
    Marpa::Marpa-Recognizer $r
) returns Mu

```

Decreases the reference count by 1, destroying r once the reference count reaches zero. When r is destroyed, the reference count of its base grammar is decreased by one. If this takes the reference count of the base grammar to zero, it too is destroyed.

### sub marpa\_r\_start\_input

```
sub marpa_r_start_input(
    Marpa::Marpa-Recognizer $r
) returns Int

```

Makes r ready to accept input. The first Earley set, the one at earleme 0, will be completed during this call. Because the call to marpa\_r\_start\_input() completes an Earley set, it may generate events. For details about the events that may be generated during Earley set completion, see the description of the marpa\_r\_earleme\_complete() method. Success value: A non-negative value. Failure value: −2.

### sub marpa\_r\_alternative

```
sub marpa_r_alternative(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Symbol-ID $token_id,
    Int $value,
    Int $length
) returns Int

```

Reads a token into r. The token will start at the current earleme. Libmarpa allows tokens to be ambiguous, to be of variable length and to overlap. token\_id is the symbol ID of the token, which must be a terminal. length is the length of the token. value is an integer that represents the value of the token. In applications where the token's actual value is not an integer, it is expected that the application will use this value as a “virtual” value, perhaps finding the actual value by using value to index an array. value is not used inside Libmarpa — it is simply stored to be returned by the valuator as a convenience for the application. Some applications may prefer to track token values on their own, perhaps based on the earleme location and token\_id, instead of using Libmarpa's token values. A value of 0 is reserved for a now-deprecated feature. Do not use it. For more details on that feature, see the section Valued and unvalued symbols. When marpa\_r\_alternative() is successful, the value of the furthest earleme is set to the greater of its value before the call, and current+length, where current is the value of the current earleme. The values of the current and latest earlemes are unchanged by calls to marpa\_r\_alternative(). Several error codes leave the recognizer in a fully recoverable state, allowing the application to retry the marpa\_r\_alternative() method. Retry is efficient, and quite useable as a parsing technique. The error code of primary interest from this point of view is MARPA-ERR-UNEXPECTED-TOKEN-ID, which indicates that the token was not accepted because of its token ID. Retry after this condition is used in several applications, and is called “the Ruby Slippers technique”. The error codes MARPA-ERR-DUPLICATE-TOKEN, MARPA-ERR-NO-TOKEN-EXPECTED-HERE and MARPA-ERR-INACCESSIBLE-TOKEN also leave the recognizer in a fully recoverable state, and may also be useable for the Ruby Slippers or similar techniques. At this writing, the author knows of no applications which attempt to recover from these errors. Success value: MARPA-ERR-NONE. Failure value: Some other error code.

### sub marpa\_r\_earleme\_complete

```
sub marpa_r_earleme_complete(
    Marpa::Marpa-Recognizer $r
) returns Int

```

This method does the final processing for the current earleme. It then advances the current earleme by one. Note that marpa\_r\_earleme\_complete() may be called even when no tokens have been read at the current earleme — in the character-per-earleme input model, for example, tokens can span many characters and, if the input is unambiguous over that span, there will be no other tokens that start inside it. As mentioned, marpa\_r\_earleme\_complete() always advances the current earleme, incrementing its value by 1. This means that value of the current earleme after the call will be the one plus the value of the earleme processed by the call to marpa\_r\_earleme\_complete(). If any token was accepted at the earleme being processed, marpa\_r\_earleme\_complete() creates a new Earley set which will be the latest Earley set and, after the call, the latest earleme will be equal to the new current earleme. If no token was accepted at the earleme being processed, no Earley set is created, and the value of the latest earleme remains unchanged. The value of the furthest earleme is never changed by a call to marpa\_r\_earleme\_complete(). During this method, one or more events may occur. On success, this function returns the number of events generated, but it is important to note that events may be created whether earleme completion fails or succeeds. When this method fails, the application must call marpa\_g\_event() if it wants to determine if any events occurred. Since the reason for failure to complete an earleme is often detailed in the events, applications that fail will often be at least as interested in the events as those that succeed. The MARPA-EVENT-EARLEY-ITEM-THRESHOLD event indicates that an application-settable threshold on the number of Earley items has been reached or exceeded. What this means depends on the application, but when the default threshold is exceeded, it means that it is very likely that the time and space resources consumed by the parse will prove excessive. A parse is “exhausted” when it can accept no more input. This can happen both on success and on failure. Note that the failure due to parse exhaustion only means failure at the current earleme. There may be successful parses at earlier earlemes. If a parse is exhausted, but successful, an event with the event code MARPA-EVENT-EXHAUSTED occurs. Because the parse is exhausted, no input will be accepted at later earlemes. It is quite common for a parse to become exhausted when it succeeds. Many practical grammars are designed so that a successful parse cannot be extended. An exhausted parse may cause a failure, in which case marpa\_r\_earleme\_complete() returns an error whose error code is MARPA-ERR-PARSE-EXHAUSTED. For a parse to fail at an earleme due to exhaustion, it must be the case that no alternatives were accepted at that earleme. In fact, in the standard input model, a failure due to parse exhaustion occurs if and only if no alternatives were accepted at the current earleme. The circumstances under which failure due to parse exhaustion occurs are slightly more complicated when variable length tokens are in use. Informally, a parse will never fail due to exhaustion as long as it is possible that a token ending at some future earleme will continue the parse. More precisely, a call to marpa\_r\_earleme\_complete() fails due to parse exhaustion if and only if, first, no alternatives were added at the current earleme and, second, that call left the current earleme equal to the furthest earleme. Success value: The number of events generated. Failure value: −2.

### sub marpa\_r\_current\_earleme

```
sub marpa_r_current_earleme(
    Marpa::Marpa-Recognizer $r
) returns Marpa::Marpa-Earleme

```

Success value: If input has started, the current earleme. If input has not started, −1. Failure value: Always succeeds.

### sub marpa\_r\_earleme

```
sub marpa_r_earleme(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Earley-Set-ID $set_id
) returns Marpa::Marpa-Earleme

```

In the default, token-stream model, Earley set ID and earleme are always equal, but this is not the case in other input models. (The ID of an Earley set ID is also called its ordinal.) If there is no Earley set whose ID is set\_id, marpa\_r\_earleme() fails. If set\_id was negative, the error code is set to MARPA-ERR-INVALID-LOCATION. If set\_id is greater than the ordinal of the latest Earley set, the error code is set to MARPA-ERR-NO-EARLEY-SET-AT-LOCATION. At this writing, there is no method for the inverse operation (conversion of an earleme to an Earley set ID). One consideration in writing such a method is that not all earlemes correspond to Earley sets. Applications that want to map earlemes to Earley sets will have no trouble if they are using the standard input model — the Earley set ID is always exactly equal to the earleme in that model. For other applications that want an earleme-to-ID mapping, the most general method is create an ID-to-earleme array using the marpa\_r\_earleme() method and invert it. Success value: The earleme corresponding to Earley set set\_id. Failure value: −2.

### sub marpa\_r\_earley\_set\_value

```
sub marpa_r_earley_set_value(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Earley-Set-ID $earley_set
) returns Int

```

Returns the integer value of earley\_set. For more details, see the description of marpa\_r\_earley\_set\_values(). Success value: The value of earley\_set. Failure value: −2.

### sub marpa\_r\_earley\_set\_values

```
sub marpa_r_earley_set_values(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Earley-Set-ID $earley_set,
    NativeCall::Types::Pointer[Int] $p_value,
    NativeCall::Types::Pointer[NativeCall::Types::Pointer[NativeCall::Types::void]] $p_pvalue
) returns Int

```

If p\_value is non-zero, sets the location pointed to by p\_value to the integer value of the Earley set. Similarly, if p\_pvalue is non-zero, sets the location pointed to by p\_pvalue to the pointer value of the Earley set. The “value” and “pointer” of an Earley set are an arbitrary integer and an arbitrary pointer that the application can use for its own purposes. In character-per-earleme input models, for example, the integer can be the codepoint of the current character. In a traditional token-per-earleme input model, they could be used to indicate the string value of the token – the pointer could point to the start of the string, and the integer could indicate its length. The Earley set value and pointer can be set using the marpa\_r\_latest\_earley\_set\_values\_set() method. The Earley set integer value defaults to −1, and the pointer value defaults to NULL. Success value: returns a non-negative integer. Failure value: −2.

### sub marpa\_r\_furthest\_earleme

```
sub marpa_r_furthest_earleme(
    Marpa::Marpa-Recognizer $r
) returns UInt

```

Success value: The furthest earleme. Failure value: Always succeeds.

### sub marpa\_r\_latest\_earley\_set

```
sub marpa_r_latest_earley_set(
    Marpa::Marpa-Recognizer $r
) returns Marpa::Marpa-Earley-Set-ID

```

This method returns the Earley set ID (ordinal) of the latest Earley set. Applications that want the value of the latest earleme can convert this value using the marpa\_r\_earleme() method. Success value: the ID of the latest Earley set. Failure value: Always succeeds.

### sub marpa\_r\_latest\_earley\_set\_value\_set

```
sub marpa_r_latest_earley_set_value_set(
    Marpa::Marpa-Recognizer $r,
    Int $value
) returns Int

```

Sets the integer value of the latest Earley set. For more details, see the description of marpa\_r\_latest\_earley\_set\_values\_set(). Success value: The new value of earley\_set. Failure value: −2.

### sub marpa\_r\_latest\_earley\_set\_values\_set

```
sub marpa_r_latest_earley_set_values_set(
    Marpa::Marpa-Recognizer $r,
    Int $value,
    NativeCall::Types::Pointer[NativeCall::Types::void] $pvalue
) returns Int

```

Sets the integer and pointer value of the latest Earley set. For more about the “integer value” and “pointer value” of an Earley set, see the description of the marpa\_r\_earley\_set\_values() method. Success value: Returns a non-negative integer. Failure value: −2.

### sub marpa\_r\_completion\_symbol\_activate

```
sub marpa_r_completion_symbol_activate(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $reactivate
) returns Int

```

Allows the user to deactivate and reactivate symbol completion events in the recognizer. If reactivate is zero, the event is deactivated. If reactivate is one, the event is activated. Symbol completion events are active by default if the symbol was set up for completion events in the grammar. If a symbol was not set up for completion events in the grammar, symbol completion events are inactive by default and any attempt to change that is a fatal error. Success value: The method returns the value of reactivate. The method succeeds trivially if the symbol is already set as indicated by reactivate. Failure value: If the active status of the completion event for sym\_id cannot be set as indicated by reactivate, the method fails. On failure, −2 is returned.

### sub marpa\_r\_earley\_item\_warning\_threshold\_set

```
sub marpa_r_earley_item_warning_threshold_set(
    Marpa::Marpa-Recognizer $r,
    Int $threshold
) returns Int

```

These methods, respectively, set and query the Earley item warning threshold. The Earley item warning threshold is a number that is compared with the count of Earley items in each Earley set. When it is matched or exceeded, a MARPA-EVENT-EARLEY-ITEM-THRESHOLD event is created. If threshold is zero or less, an unlimited number of Earley items will be allowed without warning. This will rarely be what the user wants. By default, Libmarpa calculates a value based on the grammar. The formula Libmarpa uses is the result of some experience, and most applications will be happy with it. Success value: The value that the Earley item warning threshold has after the method call is finished. Failure value: Always succeeds.

### sub marpa\_r\_expected\_symbol\_event\_set

```
sub marpa_r_expected_symbol_event_set(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Symbol-ID $symbol_id,
    Int $value
) returns Int

```

Sets the “expected symbol event bit” for symbol\_id to value. A recognizer event is created whenever symbol symbol\_id is expected at the current earleme. if and only if the expected symbol event bit for symbol\_id is 1. The “expected symbol event bit” must be 1 or 0. In this context, “expected” means “expected as a terminal”. Even if a symbol is predicted at the current earleme, if it is not acceptable as a terminal, it does not trigger an “expected symbol event”. By default, the “expected symbol event bit” is 0. It is an error to attempt to set the “expected symbol event bit” to 1 for a nulling symbol, an inaccessible symbol, or an unproductive symbol. Success value: The value of the event bit after the method call is finished. Failure value: -2 if symbol\_id is not the ID of a valid symbol; if it is the ID of an nulling, inaccessible for unproductive symbol; or on other failure.

### sub marpa\_r\_is\_exhausted

```
sub marpa_r_is_exhausted(
    Marpa::Marpa-Recognizer $r
) returns Int

```

A parser is “exhausted” if it cannot accept any more input. Both successful and failed parses can be exhausted. In many grammars, the parse is always exhausted as soon as it succeeds. Good parses may also exist at earlemes prior to the current one. Success value: 1 if the parser is exhausted, 0 otherwise. Failure value: Always succeeds.

### sub marpa\_r\_nulled\_symbol\_activate

```
sub marpa_r_nulled_symbol_activate(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $boolean
) returns Int

```

Allows the user to deactivate and reactivate symbol nulled events in the recognizer. If boolean is zero, the event is deactivated. If boolean is one, the event is activated. Symbol nulled events are active by default if the symbol was set up for nulled events in the grammar. If a symbol was not set up for nulled events in the grammar, symbol nulled events are inactive by default and any attempt to change that is a fatal error. Success cases: On success, the method returns the value of boolean. The method succeeds trivially if the symbol is already set as indicated by boolean. Failure cases: If the active status of the nulled event for sym\_id cannot be set as indicated by boolean, the method fails. On failure, −2 is returned.

### sub marpa\_r\_prediction\_symbol\_activate

```
sub marpa_r_prediction_symbol_activate(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $boolean
) returns Int

```

Allows the user to deactivate and reactivate symbol prediction events in the recognizer. If boolean is zero, the event is deactivated. If boolean is one, the event is activated. Symbol prediction events are active by default if the symbol was set up for prediction events in the grammar. If a symbol was not set up for prediction events in the grammar, symbol prediction events are inactive by default and any attempt to change that is a fatal error. Success value: The method returns the value of boolean. The method succeeds trivially if the symbol is already set as indicated by boolean. Failure value: If the active status of the prediction event for sym\_id cannot be set as indicated by boolean, the method fails. On failure, −2 is returned.

### sub marpa\_r\_terminals\_expected

```
sub marpa_r_terminals_expected(
    Marpa::Marpa-Recognizer $r,
    NativeCall::Types::Pointer[Marpa::Marpa-Symbol-ID] $buffer
) returns Int

```

Returns a list of the ID's of the symbols that are acceptable as tokens at the current earleme. buffer is expected to be large enough to hold the result. This is guaranteed to be the case if the buffer is large enough to hold a number of Marpa-Symbol-ID's that is greater than or equal to the number of symbols in the grammar. Success value: The number of Marpa-Symbol-ID's in buffer. Failure value: −2.

### sub marpa\_r\_terminal\_is\_expected

```
sub marpa_r_terminal_is_expected(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Symbol-ID $symbol_id
) returns Int

```

Success value: If symbol\_id is the ID of a valid terminal symbol that is expected at the current earleme, a number greater than zero. If symbol\_id is the ID of a valid terminal symbol that is not expected at the current earleme, or if symbol\_id is the ID of a valid symbol that is not a terminal, zero. Failure value: −2. It is a failure if symbol\_id is not the ID of a valid symbol.

### sub marpa\_r\_progress\_report\_reset

```
sub marpa_r_progress_report_reset(
    Marpa::Marpa-Recognizer $r
) returns Int

```

Resets the progress report. Assumes a report of the progress has already been initialized at some Earley set for recognizer r, with marpa\_r\_progress\_report\_start(). The reset progress report will be positioned before its first item. Success value: A non-negative value. Failure value: −2.

### sub marpa\_r\_progress\_report\_start

```
sub marpa_r_progress_report_start(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Earley-Set-ID $set_id
) returns Int

```

Initializes a report of the progress at Earley set set\_id for recognizer r. If a progress report already exists, it is destroyed and its memory is freed. Initially, the progress report is positioned before its first item. If no Earley set with ID set\_id exists, marpa\_r\_progress\_report\_start() fails. The error code is MARPA-ERR-INVALID-LOCATION if set\_id is negative. The error code is MARPA-ERR-NO-EARLEY-SET-AT-LOCATION if set\_id is greater than the ID of the latest Earley set. Success value: the number of report items available. If the recognizer has not been started; if set\_id does not exist; or on other failure, −2. Failure value: −2.

### sub marpa\_r\_progress\_report\_finish

```
sub marpa_r_progress_report_finish(
    Marpa::Marpa-Recognizer $r
) returns Int

```

Destroys the report of the progress at Earley set set\_id for recognizer r, freeing the memory and other resources. It is often not necessary to call this method. Any previously existing progress report is destroyed automatically whenever a new progress report is started, and when the recognizer is destroyed. Success value: A non-negative value. Failure value: −2 if no progress report has been started, or on other failure.

### sub marpa\_r\_progress\_item

```
sub marpa_r_progress_item(
    Marpa::Marpa-Recognizer $r,
    NativeCall::Types::Pointer[Int] $position,
    NativeCall::Types::Pointer[Marpa::Marpa-Earley-Set-ID] $origin
) returns Marpa::Marpa-Rule-ID

```

This method allows access to the data for the next item of a progress report. If there are no more progress report items, it returns −1 as a termination indicator and sets the error code to MARPA-ERR-PROGRESS-REPORT-EXHAUSTED. Either the termination indicator, or the item count returned by marpa\_r\_progress\_report\_start(), can be used to determine when the last item has been seen. On success, the dot position is returned in the location pointed to by the position argument, and the origin is returned in the location pointed to by the origin argument. On failure, the locations pointed to by the position and origin arguments are unchanged. Success value: The rule ID of the next progress report item. If there are no more progress report items, −1. If either the position or the origin argument is NULL, or on other failure, −2. Failure value: −2.

### sub marpa\_b\_new

```
sub marpa_b_new(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Earley-Set-ID $earley_set_ID
) returns Marpa::Marpa-Bocage

```

Creates a new bocage object, with a reference count of 1. The reference count of its parent recognizer object, r, is increased by 1. If earley\_set\_ID is −1, the Earley set at the current earleme is used, if there is one. If earley\_set\_ID is −1 and there is no Earley set at the current earleme; or if earley\_set\_ID is −1 and there is no parse ending at Earley set earley\_set\_ID, marpa\_b\_new() fails and the error code is set to MARPA-ERR-NO-PARSE. Success value: The new bocage object. Failure value: NULL.

### sub marpa\_b\_ref

```
sub marpa_b_ref(
    Marpa::Marpa-Bocage $b
) returns Marpa::Marpa-Bocage

```

Increases the reference count by 1. Not needed by most applications. Success value: $b. Failure value: NULL.

### sub marpa\_b\_unref

```
sub marpa_b_unref(
    Marpa::Marpa-Bocage $b
) returns Mu

```

Decreases the reference count by 1, destroying b once the reference count reaches zero. When b is destroyed, the reference count of its parent recognizer is decreased by 1. If this takes the reference count of the parent recognizer to zero, it too is destroyed. If the parent recognizer is destroyed, the reference count of its base grammar is decreased by 1. If this takes the reference count of the base grammar to zero, it too is destroyed.

### sub marpa\_b\_ambiguity\_metric

```
sub marpa_b_ambiguity_metric(
    Marpa::Marpa-Bocage $b
) returns Int

```

Returns an ambiguity metric. The metric is 1 is the parse is unambiguous. If the metric is 2 or greater, the parse is ambiguous. It was originally intended to have values greater than 2 be an cheaply computed estimate of the degree of ambiguity, but a satisfactory scheme for this has yet to be implemented. Success value: 1 if the bocage is not for an ambiguous parse; 2 or greater if the bocage is for an ambiguous parse. Failure value: −2.

### sub marpa\_b\_is\_null

```
sub marpa_b_is_null(
    Marpa::Marpa-Bocage $b
) returns Int

```

Success value: A number greater than or equal to 1 if the bocage is for a null parse; otherwise, 0. Failure value: −2.

### sub marpa\_o\_new

```
sub marpa_o_new(
    Marpa::Marpa-Bocage $b
) returns Marpa::Marpa-Order

```

Creates a new ordering object, with a reference count of 1. The reference count of its parent bocage object, b, is increased by 1. Success value: the new ordering object. Failure value: NULL.

### sub marpa\_o\_ref

```
sub marpa_o_ref(
    Marpa::Marpa-Order $o
) returns Marpa::Marpa-Order

```

Increases the reference count by 1. Not needed by most applications. Success value: o. Failure value: NULL.

### sub marpa\_o\_unref

```
sub marpa_o_unref(
    Marpa::Marpa-Order $o
) returns Mu

```

Decreases the reference count by 1, destroying o once the reference count reaches zero. Beginning with o's parent bocage, Libmarpa then proceeds up the chain of parent objects. Every time a child is destroyed, the reference count of its parent is decreased by 1. Every time the reference count of an object is decreased by 1, if that reference count is now zero, that object is destroyed. Libmarpa follows this chain of decrements and destructions as required, all the way back to the base grammar, if necessary.

### sub marpa\_o\_ambiguity\_metric

```
sub marpa_o_ambiguity_metric(
    Marpa::Marpa-Order $o
) returns Int

```

Returns an ambiguity metric. The metric is 1 is the parse is unambiguous. If the metric is 2 or greater, the parse is ambiguous. It was originally intended to have values greater than 2 be an cheaply computed estimate of the degree of ambiguity, but a satisfactory scheme for this has yet to be implemented. If the ordering is not already frozen, it will be frozen on return from marpa\_o\_ambiguity\_metric(). marpa\_o\_ambiguity\_metric() is considered an “accessor”, because it is assumed that the ordering is frozen when marpa\_o\_ambiguity\_metric() is called. Success value: 1 if the ordering is not for an ambiguous parse; 2 or greater if the ordering is for an ambiguous parse. Failure value: −2.

### sub marpa\_o\_is\_null

```
sub marpa_o_is_null(
    Marpa::Marpa-Order $o
) returns Int

```

Success value: A number greater than or equal to 1 if the ordering is for a null parse; otherwise, 0. Failure value: −2.

### sub marpa\_o\_high\_rank\_only\_set

```
sub marpa_o_high_rank_only_set(
    Marpa::Marpa-Order $o,
    Int $flag
) returns Int

```

These methods, respectively, set and query the “high rank only” flag of ordering o. A flag of 1 indicates that, when ranking, all choices should be discarded except those of the highest rank. A flag of 0 indicates that no choices should be discarded on the basis of their rank. A value of 1 is the default. The value of the “high rank only” flag has no effect unless ranking has been turned on using the marpa\_o\_rank() method. Success value: the value of the “high rank only” flag after the call. Failure value: −2.

### sub marpa\_o\_rank

```
sub marpa_o_rank(
    Marpa::Marpa-Order $o
) returns Int

```

By default, the ordering of parse trees is arbitrary. This method causes the ordering to be ranked according to the ranks of symbols and rules, the “null ranks high” flags of the rules, and the “high rank only” flag of the ordering. Once this method returns, the ordering is frozen. Success value: A non-negative value. Failure value: −2.

### sub marpa\_t\_new

```
sub marpa_t_new(
    Marpa::Marpa-Order $o
) returns Marpa::Marpa-Tree

```

Creates a new tree iterator, with a reference count of 1. The reference count of its parent ordering object, o, is increased by 1. When initialized, a tree iterator is positioned before the first parse tree. To position the tree iterator to the first parse, the application must call marpa\_t\_next(). Success value: A newly created tree. Failure value: NULL.

### sub marpa\_t\_ref

```
sub marpa_t_ref(
    Marpa::Marpa-Tree $t
) returns Marpa::Marpa-Tree

```

Increases the reference count by 1. Not needed by most applications. Success value: t. Failure value: NULL.

### sub marpa\_t\_unref

```
sub marpa_t_unref(
    Marpa::Marpa


## dist_zef-raku-community-modules-Marpa.md
## Chunk 3 of 3
-Tree $t
) returns Mu

```

Decreases the reference count by 1, destroying t once the reference count reaches zero. Beginning with t's parent ordering, Libmarpa then proceeds up the chain of parent objects. Every time a child is destroyed, the reference count of its parent is decreased by 1. Every time the reference count of an object is decreased by 1, if that reference count is now zero, that object is destroyed. Libmarpa follows this chain of decrements and destructions as required, all the way back to the base grammar, if necessary.

### sub marpa\_t\_next

```
sub marpa_t_next(
    Marpa::Marpa-Tree $t
) returns Int

```

Positions t at the next parse tree in the iteration. Tree iterators are initialized to the position before the first parse tree, so this method must be called before creating a valuator from a tree. If a tree iterator is positioned after the last parse, the tree is said to be “exhausted”. A tree iterator for a bocage with no parse trees is considered to be “exhausted” when initialized. If the tree iterator is exhausted, marpa\_t\_next() returns −1 as a termination indicator, and sets the error code to MARPA-ERR-TREE-EXHAUSTED. Success value: A non-negative value. If the tree iterator is exhausted, −1. Failure value: −2.

### sub marpa\_t\_parse\_count

```
sub marpa_t_parse_count(
    Marpa::Marpa-Tree $t
) returns Int

```

The parse counter counts the number of parse trees traversed so far. The count includes the current iteration of the tree, so that a value of 0 indicates that the tree iterator is at its initialized position, before the first parse tree. Success value: The number of parses traversed so far. Failure value: Always succeeds.

### sub marpa\_v\_new

```
sub marpa_v_new(
    Marpa::Marpa-Tree $t
) returns Marpa::Marpa-Value

```

Creates a new valuator. The parent object of the new valuator will be the tree iterator t, and the reference count of the new valuator will be 1. The reference count of t is increased by 1. The parent tree iterator is “paused”, so that the tree iterator cannot move on to a new parse tree until the valuator is destroyed. Many valuators of the same parse tree can exist at once. A tree iterator is “unpaused” when all of the valuators of that tree iterator are destroyed. Success value: The newly created valuator. Failure value: NULL.

### sub marpa\_v\_ref

```
sub marpa_v_ref(
    Marpa::Marpa-Value $v
) returns Marpa::Marpa-Value

```

Increases the reference count by 1. Not needed by most applications. Success value: v. Failure value: NULL.

### sub marpa\_v\_unref

```
sub marpa_v_unref(
    Marpa::Marpa-Value $v
) returns Mu

```

Decreases the reference count by 1, destroying v once the reference count reaches zero. Beginning with v's parent tree, Libmarpa then proceeds up the chain of parent objects. Every time a child is destroyed, the reference count of its parent is decreased by 1. Every time the reference count of an object is decreased by 1, if that reference count is now zero, that object is destroyed. Libmarpa follows this chain of decrements and destructions as required, all the way back to the base grammar, if necessary.

### sub marpa\_v\_step

```
sub marpa_v_step(
    Marpa::Marpa-Value $v
) returns Marpa::Marpa-Step-Type

```

This method “steps through” the valuator. The return value is a Marpa-Step\_Type, an integer which indicates the type of step. How the application is expected to act on each step is described below. See Valuator steps by type. When the iteration through the steps is finished, marpa\_v\_step returns MARPA-STEP-INACTIVE. Success value: The type of the step to be performed. This will always be a non-negative number. Failure value: −2.

### sub marpa\_g\_event

```
sub marpa_g_event(
    Marpa::g $g,
    NativeCall::Types::Pointer[Marpa::Marpa-Event] $event,
    Int $ix
) returns Marpa-Event-Code

```

On success, the type of the ix'th event is returned and the data for the ix'th event is placed in the location pointed to by event. Event indexes are in sequence. Valid events will be in the range from 0 to n, where n is one less than the event count. The event count can be queried using the marpa\_g\_event\_count() method. Success value: The type of event ix. If there is no ix'th event, if ix is negative, or on other failure, −2. Failure value: −2. The locations pointed to by event are not changed.

### sub marpa\_g\_event\_count

```
sub marpa_g_event_count(
    Marpa::g $g
) returns Int

```

Success value: The number of events. Failure value: −2.

### sub marpa\_g\_error

```
sub marpa_g_error(
    Marpa::g $g,
    NativeCall::Types::Pointer[Str] $p_error_string
) returns Marpa-Error-Code

```

When a method fails, this method allows the application to read the error code. p\_error\_string is reserved for use by the internals. Applications should set it to NULL. Success value: The last error code from a Libmarpa method. Failure value: Always succeeds.

### sub marpa\_g\_error\_clear

```
sub marpa_g_error_clear(
    Marpa::g $g
) returns Marpa-Error-Code

```

Sets the error code to MARPA-ERR-NONE. Not often used, but now and then it can be useful to force the error code to a known state. Success value: MARPA-ERR-NONE. Failure value: Always succeeds.

### sub marpa\_g\_default\_rank\_set

```
sub marpa_g_default_rank_set(
    Marpa::g $g,
    Marpa::Marpa-Rank $rank
) returns Marpa::Marpa-Rank

```

These methods, respectively, set and query the default rank of the grammar. When a grammar is created, the default rank is 0. When rules and symbols are created, their rank is the default rank of the grammar. Changing the grammar's default rank does not affect those rules and symbols already created, only those that will be created. This means that the grammar's default rank can be used to, in effect, assign ranks to groups of rules and symbols. Applications may find this behavior useful. Success value: Returns the rank after the call, and sets the error code to MARPA-ERR-NONE. On failure, returns −2, and sets the error code to an appropriate value, which will never be MARPA-ERR-NONE. Note that when the rank is −2, the error code is the only way to distinguish success from failure. The error code can be determined by using the marpa\_g\_error() call. Failure value: −2.

### sub marpa\_g\_symbol\_rank\_set

```
sub marpa_g_symbol_rank_set(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id,
    Marpa::Marpa-Rank $rank
) returns Marpa::Marpa-Rank

```

These methods, respectively, set and query the rank of a symbol sym\_id. When sym\_id is created, its rank initialized to the default rank of the grammar. Success value: Returns the rank after the call, and sets the error code to MARPA-ERR-NONE. On failure, returns −2, and sets the error code to an appropriate value, which will never be MARPA-ERR-NONE. Note that when the rank is −2, the error code is the only way to distinguish success from failure. The error code can be determined by using the marpa\_g\_error() call. Failure value: −2.

### sub marpa\_g\_zwa\_new

```
sub marpa_g_zwa_new(
    Marpa::g $g,
    Int $default_value
) returns Marpa::Marpa-Assertion-ID

```

On success, returns previous default value of the assertion.

### sub marpa\_r\_zwa\_default\_set

```
sub marpa_r_zwa_default_set(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Assertion-ID $zwaid,
    Int $default_value
) returns Int

```

Changes default value to default\_value. On success, returns previous default value of the assertion.

### sub marpa\_g\_symbol\_is\_valued\_set

```
sub marpa_g_symbol_is_valued_set(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $symbol_id,
    Int $value
) returns Int

```

These methods, respectively, set and query the “valued status” of a symbol. Once set to a value with the marpa\_g\_symbol\_is\_valued\_set() method, the valued status of a symbol is “locked” at that value. It cannot thereafter be changed. Subsequent calls to marpa\_g\_symbol\_is\_valued\_set() for the same sym\_id will fail, leaving sym\_id's valued status unchanged, unless value is the same as the locked-in value. Success value: 1 if the symbol symbol\_id is valued after the call, 0 if not. If the valued status is locked and value is different from the current status, −2. If value is not 0 or 1; or on other failure, −2. Failure value: −2.

### sub marpa\_v\_symbol\_is\_valued\_set

```
sub marpa_v_symbol_is_valued_set(
    Marpa::Marpa-Value $v,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $status
) returns Int

```

These methods, respectively, set and query the valued status of symbol sym\_id. marpa\_v\_symbol\_is\_valued\_set() will set the valued status to the value of its status argument. A valued status of 1 indicates that the symbol is valued. A valued status of 0 indicates that the symbol is unvalued. If the valued status is locked, an attempt to change to a status different from the current one will fail (error code MARPA-ERR-VALUED-IS-LOCKED). Success value: The valued status after the call. If value is not either 0 or 1, or on other failure, −2. Failure value: −2.

### sub marpa\_v\_rule\_is\_valued\_set

```
sub marpa_v_rule_is_valued_set(
    Marpa::Marpa-Value $v,
    Marpa::Marpa-Rule-ID $rule_id,
    Int $status
) returns Int

```

These methods, respectively, set and query the valued status for the LHS symbol of rule rule\_id. marpa\_v\_rule\_is\_valued\_set() sets the valued status to the value of its status argument. A valued status of 1 indicates that the symbol is valued. A valued status of 0 indicates that the symbol is unvalued. If the valued status is locked, an attempt to change to a status different from the current one will fail (error code MARPA-ERR-VALUED-IS-LOCKED). Rules have no valued status of their own. The valued status of a rule is always that of its LHS symbol. These methods are conveniences — they save the application the trouble of looking up the rule's LHS. Success value: The valued status of the rule rule\_id's LHS symbol after the call. If value is not either 0 or 1, or on other failure, −2. Failure value: −2.

### sub marpa\_v\_valued\_force

```
sub marpa_v_valued_force(
    Marpa::Marpa-Value $v
) returns Int

```

This methods locks the valued status of all symbols to 1, indicated that the symbol is valued. If this is not possible, for example because one of the grammar's symbols already is locked at a valued status of 0, failure is returned. Success value: A non-negative number. Failure value: −2, and sets the error code to an appropriate value, which will never be MARPA-ERR-NONE.


## dist_github-moritz-Math-Model.md
`Math::Model` lets you write mathematical and physical models in an easy and
natural way.

Please see <https://perlgeek.de/blog-en/perl-6/physical-modelling.html> for a
longer description and tutorial.

This module may be used under the terms of the [Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0).
Its accompanying tests and examples are public domain, as defined by the [CC0 1.0 Universal (CC0 1.0) Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/).


## dist_github-fayland-Gravatar-URL.md
# perl6-Gravatar-URL - Make URLs for Gravatars from an email address

[![Build Status](https://travis-ci.org/fayland/perl6-Gravatar-URL.svg?branch=master)](https://travis-ci.org/fayland/perl6-Gravatar-URL)

## SYNOPSIS

```
use Gravatar::URL;

my $gravatar_id = gravatar_id('whatever@wherever.whichever'); # 'a60fc0828e808b9a6a9d50f1792240c8'

my $gravator_url = gravatar_url(
    :email<whatever@wherever.whichever>,
    :size<32>
);

my $gravator_url = gravatar_url(
    :email<whatever@wherever.whichever>,
    default => '/local.png',
    :rating<R>,
    :size<80>,
    :short_keys<0>,
    :https<1>
);

```

## DESCRIPTION

* email - required, if Str.chars=32 passed, we'll treat it as id
* default - default image
* rating - G, PG, R, X
* size - Int 1 to 512
* short\_keys - use r instead of rating, d instead of default in url
* https - use <https://secure.gravatar.com/avatar/> instead of <http://www.gravatar.com/avatar/> as the base


## dist_zef-FCO-MergeOrderedSeqs.md
[![Actions Status](https://github.com/FCO/MergeOrderedSeqs/actions/workflows/test.yml/badge.svg)](https://github.com/FCO/MergeOrderedSeqs/actions)

# NAME

MergeOrderedSeqs - Merge multiple ordered Seqs into a single ordered one.

# SYNOPSIS

```
use MergeOrderedSeqs;

my @ordered = merge-ordered-seqs                      [1, 3, 5], [2, 4, 6];
my @ord2    = merge-ordered-seqs :before(More),       [6, 4, 2], [5, 3, 1];
my @ord3    = merge-ordered-seqs :before{(-2) ** $_}, [5, 3, 1], [2, 4, 6];
my @ord4    = merge-ordered-seqs :before{$^a < $^b},  [1, 3, 5], [2, 4, 6];

```

# DESCRIPTION

merge\_ordered\_seqs() is a function that receives multiple iterables that should be ordered and returns a single Seq also ordered.

# AUTHOR

Fernando Corrêa [fernandocorrea@gmail.com](mailto:fernandocorrea@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2023 Fernando Corrêa de Oliveira

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-tony-o-CSV-Parser.md
# NAME

`CSV::Parser` - parses binary CSV file and reads it line by line.

# SYNOPSIS

This module is pretty badass. It reads CSV files line by line and can handle individual lines so you can handle your own file reads or you can let me do the damn work for you. It handles binary files with relative ease so you can parse your binary 'Comma Separated Value' files like a pro.

```
use CSV::Parser;

my $file_handle = open 'some.csv', :r;
my $parser = CSV::Parser.new(
    :$file_handle,
    :contains_header_row,
);

# Option 1
until $file_handle.eof {
  my %data = %($parser.get_line());
  # do something here with your hashish data
}

$parser.reset;

# Option 2
my %data;
while %data = %($parser.get_line()) {
  # do something with data here
}

$file_handle.close; # don't forget to close

```

# INSTALLATION

```
$ zef install CSV::Parser

```

# METHODS

## method new

```
method new(
    IO::Handle :$file_handle,
    Bool       :$binary,
    Bool       :$contains_header_row,
               :$field_separator,
               :$line_separator,
               :$field_operator,
               :$escape_operator,
    int        :$chunk_size,
)

```

Constructs a CSV parser and sets its attributes to the provided options.

### `file_handle`

File handle opened with [`read`](https://docs.raku.org/routine/read).

### `binary`

* Default: `False`
* Type: `Bool`

Indicates if file was opened in binary mode. If `True`, the file was opened as binary and all operator/separator options are **REQUIRED** to be passed as `Buf` objects (instead of `Str`).

### `contains_header_row`

* Default: `False`
* Type: `Bool`

Indicates if the first line should be intepreted as column names. If `False`, the first line won't be interpreted as column names and each parsed line will be returned as a hash with keys `0..X-1`, where `X` is the number of columns. If `True`, the first line will be interpreted as column names, and each subsequent line will be returned as a hash whose keys are the column names.

### `field_normalizer`

* Default: `-> $k, $v, :$header = False { $v }`.
* Type: `Callable`

A `Callable` with signature `($key, $value, :$header = False)` to normalize the key-value pair for each CSV row. The `$key` is the header value if available, otherwise the column index. The `$value` is the value of the column. The `$header` boolean flag indicates whether we're parsing a header or a row value. The return value is the column's final value, i.e., a `Str`.

### `field_separator`

* Default: `,`
* Type: `Str` or `Buf`

Specifies a single-character string used as the the column separator for each row.

### `line_separator`

* Default: `\n`
* Type: `Str`

Specifies the separator between CSV rows. See `field_separator` - this will be included in a parsed value if found in an open `field_operator`.

### `field_operator`

* Default: `"`
* Type: `Str`

Specifies the character [sequence] used to escape a field (can handle `line_separator` encapsulation). See `field_separator`.

### `escape_operator`

* Default: `\\`
* Type: `Str`

Specifies the single-character string used to escape strings in a CSV row. See `field_separator`.

### `chunk_size`

* Default: `1024`
* Type: `Int`

Specifies how many bytes to read from the file handle. It can be increased to improve performance if you are parsing some huge lined binary file. 1024 should be sufficient.

## method headers

Returns the parsed headers, if available.

## method get\_line

```
method get_line()

```

Reads a line or chunk from a file and return the parsed line. If this is the first call to this function and `contains_header_row` is set then this will parse the first 2 lines and use the first row's values as the column values.

## method parse

```
method parse($line, :$header = False) returns Hash

```

Parses a `Str` or `Buf` in accordance with the options set in `new`. Set the `binary` flag in `new` if you are going to pass a `Buf`.

## method reset

```
method reset()

```

Closes and re-opens the file handle provided in `new`.

# AUTHOR

tony-o <https://github.com/tony-o/>

# COPYRIGHT AND LICENSE

Copyright 2023 tony-o

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-raku-community-modules-Math-Arrow.md
[![Actions Status](https://github.com/raku-community-modules/Math-Arrow/actions/workflows/linux.yml/badge.svg)](https://github.com/raku-community-modules/Math-Arrow/actions) [![Actions Status](https://github.com/raku-community-modules/Math-Arrow/actions/workflows/macos.yml/badge.svg)](https://github.com/raku-community-modules/Math-Arrow/actions) [![Actions Status](https://github.com/raku-community-modules/Math-Arrow/actions/workflows/windows.yml/badge.svg)](https://github.com/raku-community-modules/Math-Arrow/actions)

# NAME

Math::Arrow - Handle Knuth-style arrow notation

# SYNOPSIS

In Knuth arrow notation, one arrow is simple exponentiation:

```
2 ↑ 3 # gives 8

```

Every additional arrow in the operator implies a layer of reduction of the form:

```
a ↑{n number of ↑'s} b =
  a ↑{n-1 ↑'s} ( a ↑{n-1 ↑'s (... a)...)

```

where there are `b` number of `a`s in the second form.

But this module only implements up to five arrows (really, if you need more than five, I question what the hell you think Raku is going to do for you...)

More concretely:

```
4 ↑↑↑↑ 3 =
4 ↑↑↑ ( 4 ↑↑↑ 4 ) =
4 ↑↑↑ ( 4 ↑↑ ( 4 ↑↑ ( 4 ↑↑ 4 ))) =
4 ↑↑↑ ( 4 ↑↑ ( 4 ↑↑ ( 4 ↑ (4 ↑ (4 ↑ 4 ))))) =
4 ↑↑↑ ( 4 ↑↑ ( 4 ↑↑ ( 4 ** 4 ** 4 ** 4))) = ...

```

As you can see, this quickly gets out of hand. In fact, there are very few arrow-notation expressions which can be evaluated in a practical period of time (the above example would take longer to fully evaluate than the universe has been around, even on the fastest computers available, today.

Probably the best-known arrow-notation example is Graham's Number (G) which is defined as:

```
$g1 = 3 ↑↑↑↑ 3;
$g2 = arrow(3, 3, $g1);
...
$g64 = arrow(3, 3, $g63);
use constant G = $g64;

```

## operator ↑

The `↑` operator is an infix operator which is equivalent to `arrow(left-hand-side, right-hand-side, 1)` and `**` and performs simple exponentiation. It is right-associative, just like `**`.

## operator ↑↑

The `↑↑` operator is also a right-associative infix operator and is equivalent to `arrow(lhs, rhs, 2)`.

## operator ↑↑↑

See `↑↑` for details. Equivalent to `arrow(lhs, rhs, 3)`.

## operator ↑↑↑↑

See `↑↑` for details. Equivalent to `arrow(lhs, rhs, 4)`.

## operator ↑↑↑↑↑

See <↑↑> for details. Equivalent to `arrow(lhs, rhs, 5)`.

## arrow($a, $b, $arrows)

Returns the arrow-notation expansion for `$a ↑[$arrows] $b` where `↑[$arrows]` denotes `$arrows` many `↑` in the final operator. Thus these two are equivalent:

```
arrow(3, 3, 4) == (3 ↑↑↑↑ 3)

```

## term G

```
use Math::Arrow :constants;
say G;  # you won't have enough CPU or memory to see it

```

Only exported via the `:constants` tag.

The value `G` is defined as a more-or-less humorous element of this module. It can never be used for anything practical, as evaluating its value would take such a mind-bogglingly large amount of time and memory that you might as well simply shoot your computer. But... don't do that.

This value is Graham's number, defined as described above.

# AUTHOR

Aaron Sherman

# COPYRIGHT AND LICENSE

Copyright 2016-2017 Aaron Sherman

Copyright 2024 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-FRITH-Math-Libgsl-Interpolation.md
[![Actions Status](https://github.com/frithnanth/raku-Math-Libgsl-Interpolation/workflows/test/badge.svg)](https://github.com/frithnanth/raku-Math-Libgsl-Interpolation/actions)

# NAME

Math::Libgsl::Interpolation - An interface to libgsl, the Gnu Scientific Library - Interpolation

# SYNOPSIS

```
use Math::Libgsl::Constants;
use Math::Libgsl::Interpolation;

my constant \N = 4;
my Num @x = 0e0, .1e0, .27e0, .3e0;
my Num @y = .15e0, .7e0, -.1e0, .15e0;

my $s = Math::Libgsl::Interpolation::OneD.new(:type(CSPLINE_PERIODIC), :size(N), :spline).init(@x, @y);

for ^100 -> $i {
  my Num $xi = (1 - $i / 100) * @x[0] + ($i / 100) * @x[N - 1];
  my Num $yi = $s.eval: $xi;
  printf "%g %g\n", $xi, $yi;
}

```

# DESCRIPTION

Math::Libgsl::Interpolation is an interface to the interpolation functions of libgsl, the Gnu Scientific Library. This module exports two classes:

* Math::Libgsl::Interpolation::OneD
* Math::Libgsl::Interpolation::TwoD

## Math::Libgsl::Interpolation::OneD

### new(Int $type!, Int $size!)

### new(Int :$type!, Int :$size!)

This **multi method** constructor requires two simple or named arguments, the type of interpolation and the size of the array of data points.

All the following methods *throw* on error if they return **self**, otherwise they *fail* on error.

### init(Num() @xarray where ([<] @xarray), Num() @yarray --> Math::Libgsl::Interpolation::OneD)

This method initializes the interpolation internal data using the X and Y coordinate arrays. It must be called each time one wants to use the object to evaluate interpolation points on another data set. The X array has to be strictly ordered, with increasing x values. This method returns **self**, so it may be chained.

### min-size(--> UInt)

This method returns the minimum number of points required by the interpolation object.

### name(--> Str)

This method returns the name of the interpolation type.

### find(Num() @xarray, Num() $x --> UInt)

This method performs a lookup action on the data array **@xarray** and returns the index i such that @xarray[i] <= $x < @xarray[i+1].

### reset(--> Math::Libgsl::Interpolation::OneD)

This method reinitializes the internal data structure and deletes the cache. It should be used when switching to a new dataset. This method returns **self**, so it may be chained.

### eval(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax --> Num)

This method returns the interpolated value of y for a given point x, which is inside the range of the x data set.

### eval-deriv(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax --> Num)

This method returns the derivative of an interpolated function for a given point x, which is inside the range of the x data set.

### eval-deriv2(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax --> Num)

This method returns the second derivative of an interpolated function for a given point x, which is inside the range of the x data set.

### eval-integ(Num() $a where $!spline.interp.xmin ≤ \*, Num() $b where { $b ≤ $!spline.interp.xmax && $b ≥ $a } --> Num)

This method returns the numerical integral result of an interpolated function over the range [$a, $b], two points inside the x data set.

## Math::Libgsl::Interpolation::TwoD

### new(Int $type!, Int $xsize!, Int $ysize!)

### new(Int :$type!, Int :$xsize!, Int :$ysize!)

This **multi method** constructor requires three simple or named arguments, the type of interpolation and the size of the arrays of the x and y data points.

### init(Num() @xarray where ([<] @xarray), Num() @yarray where ([<] @yarray), Num() @zarray where \*.elems == @xarray.elems \* @yarray.elems --> Math::Libgsl::Interpolation::TwoD)

This method initializes the interpolation internal data using the X, Y, and Z coordinate arrays. It must be called each time one wants to use the object to evaluate interpolation points on another data set. The X and Y arrays have to be strictly ordered, with increasing values. The Z array, which represents a grid, must have a dimension of size xsize \* ysize. The position of grid point (x, y) is given by y \* xsize + x (see also the zidx method). This method returns **self**, so it may be chained.

### zidx(UInt $x, UInt $y --> UInt)

This method returns the index of the Z array element corresponding to grid coordinates (x, y).

### min-size(--> UInt)

This method returns the minimum number of points required by the interpolation object.

### name(--> Str)

This method returns the name of the interpolation type.

### eval(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax, Num() $y where $!spline.interp.ymin ≤ \* ≤ $!spline.interp.ymax --> Num)

This method returns the interpolated value of z for a given point (x, y), which is inside the range of the x and y data sets.

### extrap(Num() $x, Num() $y --> Num)

This method returns the interpolated value of z for a given point (x, y), with no bounds checking, so when the point (x, y) is outside the range, an extrapolation is performed.

### deriv-x(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax, Num() $y where $!spline.interp.ymin ≤ \* ≤ $!spline.interp.ymax --> Num)

This method returns the interpolated value of ∂z/∂x for a given point (x, y), which is inside the range of the x and y data sets.

### deriv-y(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax, Num() $y where $!spline.interp.ymin ≤ \* ≤ $!spline.interp.ymax --> Num)

This method returns the interpolated value of ∂z/∂y for a given point (x, y), which is inside the range of the x and y data sets.

### deriv-xx(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax, Num() $y where $!spline.interp.ymin ≤ \* ≤ $!spline.interp.ymax --> Num)

This method returns the interpolated value of ∂²z/∂²x for a given point (x, y), which is inside the range of the x and y data sets.

### deriv-yy(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax, Num() $y where $!spline.interp.ymin ≤ \* ≤ $!spline.interp.ymax --> Num)

This method returns the interpolated value of ∂²z/∂²y for a given point (x, y), which is inside the range of the x and y data sets.

### deriv-xy(Num() $x where $!spline.interp.xmin ≤ \* ≤ $!spline.interp.xmax, Num() $y where $!spline.interp.ymin ≤ \* ≤ $!spline.interp.ymax --> Num)

This method returns the interpolated value of ∂²z/∂x∂y for a given point (x, y), which is inside the range of the x and y data sets.

## Accessory subroutines

### bsearch(Num() @xarray, Num() $x, UInt $idx-lo = 0, UInt $idx-hi = @xarray.elems - 1 --> UInt)

This sub returns the index i of the array @xarray such that @xarray[i] <= $x < @xarray[i+1]. The index is searched for in the range [$idx-lo, $idx-hi].

### min-size(Int $type --> UInt)

### min-size1d(Int $type --> UInt)

### min-size2d(Int $type --> UInt)

These subs return the minimum number of points required by the interpolation object, without the need to create an object. min-size is an alias for min-size1d.

# C Library Documentation

For more details on libgsl see <https://www.gnu.org/software/gsl/>. The excellent C Library manual is available here <https://www.gnu.org/software/gsl/doc/html/index.html>, or here <https://www.gnu.org/software/gsl/doc/latex/gsl-ref.pdf> in PDF format.

# Prerequisites

This module requires the libgsl library to be installed. Please follow the instructions below based on your platform:

## Debian Linux and Ubuntu 20.04+

```
sudo apt install libgsl23 libgsl-dev libgslcblas0

```

That command will install libgslcblas0 as well, since it's used by the GSL.

## Ubuntu 18.04

libgsl23 and libgslcblas0 have a missing symbol on Ubuntu 18.04. I solved the issue installing the Debian Buster version of those three libraries:

* <http://http.us.debian.org/debian/pool/main/g/gsl/libgslcblas0_2.5+dfsg-6_amd64.deb>
* <http://http.us.debian.org/debian/pool/main/g/gsl/libgsl23_2.5+dfsg-6_amd64.deb>
* <http://http.us.debian.org/debian/pool/main/g/gsl/libgsl-dev_2.5+dfsg-6_amd64.deb>

# Installation

To install it using zef (a module management tool):

```
$ zef install Math::Libgsl::Interpolation

```

# AUTHOR

Fernando Santagata [nando.santagata@gmail.com](mailto:nando.santagata@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2021 Fernando Santagata

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## file.md
file

Combined from primary sources listed below.

# [In CallFrame](#___top "go to top of document")[§](#(CallFrame)_method_file "direct link")

See primary documentation
[in context](/type/CallFrame#method_file)
for **method file**.

```raku
method file()
```

This is a shortcut for looking up the `file` annotation. Therefore, the following code prints `True`.

```raku
my $frame = callframe(0);
say $frame.file eq $frame.annotations<file>;
```

# [In Backtrace::Frame](#___top "go to top of document")[§](#(Backtrace::Frame)_method_file "direct link")

See primary documentation
[in context](/type/Backtrace/Frame#method_file)
for **method file**.

```raku
method file(Backtrace::Frame:D --> Str)
```

Returns the file name.

```raku
my $bt = Backtrace.new;
my $btf = $bt[0];
say $btf.file;
```

# [In Label](#___top "go to top of document")[§](#(Label)_method_file "direct link")

See primary documentation
[in context](/type/Label#method_file)
for **method file**.

Returns the file the label is defined in.

# [In Code](#___top "go to top of document")[§](#(Code)_method_file "direct link")

See primary documentation
[in context](/type/Code#method_file)
for **method file**.

```raku
method file(Code:D: --> Str:D)
```

Returns the name of the file in which the code object was declared.

```raku
say &infix:<+>.file;   # OUTPUT: «SETTING::src/core.c/Numeric.rakumod␤»
```


## dist_zef-elcaro-Point.md
# NAME

Point - Point class

# SYNOPSIS

This is a simple immutable Point class for Raku. It's implementation is loosely based on [Tuple](https://modules.raku.org/dist/Tuple:cpan:ELIZABETH) but is restricted to only accepting 2 Real numbers: an `x` and a `y`.

Internally, the values are stored as native `num`'s for speed, as well as allowing for decimal values, also useful when calculating the Euclidean distance (with the usual floating-point precision caveats).

Like `Tuple`, the `Point` is a value type, so `Point` objects will behave inside data structures such as `Set`.

```
use Point; # exports a 'point' sub

my $p = point(1,  1);
my $q = point(2, -3);

# addition between points returns a new point
say $p + $q;  # (3, -2)

# point values will behave inside a Set
say set($p, $p, $q);  # set((1, 1) (2, -3))

# maybe these subs will be included with the module in future?

sub cityblock-distance($p, $q = point(0, 0)) {
    abs($p.x + $q.x) + abs($p.y + $q.y)
}

sub euclidean-distance($p, $q = point(0, 0)) {
    (($p.x - $q.x)² + ($p.y - $q.y)²) ** 0.5
}

say cityblock-distance($p, $q);  # 5
say euclidean-distance($p, $q);  # 4.123105625617661

```

An addition (`+`) infix op is exported to support addition of points.

From Version 1.2.0, infix ops are also exported for

* subtraction (infix `-` and `−`)
* multipliction (infix `*` and `×`)
* division (infix `/`, `÷`)

... as well as unary prefix negation.

Here's a simple Eclidean vector implementation using some of those features

```
use Point;

class Vec {
    has $.pos = point(0, 0);  # position
    has $.vel = point(0, 0);  # velocity
    has $.acc = point(0, 0);  # acceleration
    has $.mas = 1;            # mass

    # magnitude of velocity
    method speed() {
        (.x² + .y²).sqrt given $!vel;
    }

    method apply-force(Point $f) {
        $!acc += $f ÷ $!mas;
    }

    method update() {
        $!vel += $!acc;
        $!pos += $!vel;
        $!acc ×= 0;
    }
}

```

I stopped short of export multi's for other math functions (`abs`, `floor`, etc) but if there is a great crying out of need for these, I would consider it. In the meantime, implementing these multi's in your own code is easy enough.

# CAVEATS

A `Point` object is not a `List`. It cannot be directly indexed into; just use the `.x` and `.y` methods. It will try to stay in `item` context most of the time. However if you want to (eg. to slip `x` and `y` to some external function) you can call `.list` (or any other method that indirectly calls `.list`) to get the `Num` values as a list, eg.

```
my @p = |$p;
say @p.raku;  # [1e0, 1e0]

```

# LICENCE

```
The Artistic License 2.0

```

See LICENSE file in the repository for the full license text.


## dist_zef-grizzlysmit-GUI-Editors.md
# GUI::Editors

## Table of Contents

* [NAME](#name)
* [AUTHOR](#author)
* [VERSION](#version)
* [TITLE](#title)
* [SUBTITLE](#subtitle)
* [COPYRIGHT](#copyright)
* [Introduction](#introduction)
* [$editor-config](#editor-config)
* [@config-files](#config-files)
* [grammar Editors & action class EditorsActions](#grammar-editors--action-class-editorsactions)
* [grammar EditorLine & class EditorLineActions](#grammar-editorline--class-editorlineactions)
* [grammar OverrideGUIEditor & actions class OverrideGUIEditorActions](#grammar-overrideguieditor--actions-class-overrideguieditoractions)
* [Some useful variables](#some-useful-variables)

  * [$GUI\_EDITOR](#gui_editor)

    * [$GUI\_EDITOR](#gui-editor)
  * [$VISUAL](#visual)
  * [$EDITOR](#editor)
  * [@GUIEDITORS](#guieditors-2)
  * [@gui-editors](#gui-editors)
  * [@default-editors](#default-editors)
  * [@override-gui\_editor](#override-gui_editor) or [on raku.land @override-gui\_editor](#override-gui-editor)
  * [$override-GUI\_EDITOR](#override-gui_editor-1) or [on raku.land $override-GUI\_EDITOR](#override-gui-editor-1)

    * [In **`init-gui-editors`**](#in-init-gui-editors)
  * [$editor](#editor-1)
* [edit-configs()](#edit-configs)
* [Editor functions](#editor-functions)

  * [list-editors(…)](#list-editors)
  * [editors-stats(…)](#editors-stats)
  * [BadEditor](#badeditor)
  * [set-editor](#set-editor)
  * [add-gui-editor(…)](#add-gui-editor)
  * [set-override-GUI\_EDITOR(…)](#set-override-gui_editor) or [on raku.land set-override-GUI\_EDITOR(…)](#set-override-gui-editor)
  * [backup-editors(…)](#backup-editors)
  * [restore-editors(…)](#restore-editors)
  * [list-editors-backups(…)](#list-editors-backups)
  * [backups-menu-restore-editors(…)](#backups-menu-restore-editors)
  * [edit-files(…)](#edit-files)

# NAME

GUI::Editors

# AUTHOR

Francis Grizzly Smit ([grizzly@smit.id.au](mailto:grizzly@smit.id.au))

# VERSION

0.1.12

# TITLE

GUI::Editors

# SUBTITLE

A Raku module for managing the users GUI Editor preferences in a variety of programs.

# COPYRIGHT

LGPL V3.0+ [LICENSE](https://github.com/grizzlysmit/GUI-Editors/blob/main/LICENSE)

[Top of Document](#table-of-contents)

# Introduction

A **Raku** module for managing the users GUI Editor preferences in a variety of programs.

## $editor-config

A constant which contains the location of the users editors file

```
# the home dir #
constant $home = %*ENV<HOME>.Str();

# config files
constant $editor-config is export = "$home/.local/share/gui-editors";

```

**NB: the `$home` is the value of the users HOME environment variable.**

[Top of Document](#table-of-contents)

## @config-files

An array containing the configuration files of the program, by default it is set to contain **editors** the editors configuration file the remainder should be added by **`init-gui-editors(...)`** the initialization procedure for the module.

```
# The config files to test for #
my Str:D @config-files = qw{editors};

sub config-files( --> Array[Str:D]) is export {
    return @config-files;
}

```

## @guieditors

An array of known **GUI** editors.

```
my Str:D @guieditors;

sub guieditors( --> Array[Str:D]) is export {
    return @guieditors;
}

```

[Top of Document](#table-of-contents)

## grammar Editors & action class EditorsActions

```
grammar Editors is BasePaths is export {
    regex TOP                 { [ <line> [ \v+ <line> ]* \v* ]? }
    regex line                { [ <white-space-line> || <override-gui_editor> || <config-line> || <editor-to-use> || <comment-line> ] }
    regex white-space-line    { ^^ \h* $$ }
    regex override-gui_editor { ^^ \h* 'override' \h+ 'GUI_EDITOR' [ \h+ '#' <comment> ]? \h* $$ }
    regex comment-line        { ^^ \h* '#' <-[\v]>* $$ }
    regex config-line         { ^^ \h* 'guieditors' \h* '+'? '=' \h* <editor> \h* [ '#' <comment> \h* ]? $$ }
    regex editor-to-use       { ^^ \h* 'editor' \h* ':'? '=' \h* <editor> \h* [ '#' <comment> \h* ]? $$ }
    regex editor              { <editor-name> || <base-path> <editor-name> }
    regex comment             { <-[\n]>* }
    token editor-name         { <with-other-stuff> }
}

class EditorsActions does BasePathsActions is export {
    method white-space-line($/) {
        my %wspln = type => 'white-space-line', value => ~$/;
        make %wspln;
    }
    method comment-line($/) {
        my %comln = type => 'comment-line', value => ~$/;
        make %comln;
    }
    #token editor-name         { <with-other-stuff> }
    method editor-name($/) {
        my $edname = $/<with-other-stuff>.made;
        make $edname;
    }
    method editor($/) {
        my $ed-name;
        if $/<base-path> {
            $ed-name = $/<base-path>.made ~ $/<editor-name>.made;
        } else {
            $ed-name = $/<editor-name>.made;
        }
        make $ed-name;
    }
    method comment($/) {
        my $comm = (~$/).trim;
        make $comm;
    }
    method config-line($/) {
        my %cfg-line = type => 'config-line', value => $/<editor>.made;
        if $/<comment> {
            my $com = $/<comment>.made;
            %cfg-line«comment» = $com;
        }
        make %cfg-line;
    }
    method editor-to-use($/) {
        my %editor-to-use = type => 'editor-to-use', value => $/<editor>.made;
        if $/<comment> {
            my $com = $/<comment>.made;
            %editor-to-use«comment» = $com;
        }
        make %editor-to-use;
    }
    method override-gui_editor($/) {
        my %override-gui_editor = type => 'override-gui_editor', :value;
        if $/<comment> {
            my $com = $/<comment>.made;
            %override-gui_editor«comment» = $com;
        }
        make %override-gui_editor;
    }
    method line($/) {
        my %ln;
        if $/<white-space-line> {
            %ln = $/<white-space-line>.made;
        } elsif $/<comment-line> {
            %ln = $/<comment-line>.made;
        } elsif $/<config-line> {
            %ln = $/<config-line>.made;
        } elsif $/<editor-to-use> {
            %ln = $/<editor-to-use>.made;
        } elsif $/<override-gui_editor> {
            %ln = $/<override-gui_editor>.made;
        }
        make %ln;
    }
    method TOP($made) {
        my @top = $made<line>».made;
        $made.make: @top;
    }
} # class EditorsActions does BasePathsActions is export #

```

[Top of Document](#table-of-contents)

### grammar EditorLine & class EditorLineActions

A grammar and associated action class to parse and recognise the **`editor := value # comment`** lines in the **editors** file.

```
grammar EditorLine is BasePaths is export {
    regex TOP                 { ^ \h* 'editor' \h* ':'? '=' \h* <editor> \h* [ '#' <comment> \h* ]? $ }
    regex editor              { <editor-name> || <base-path> <editor-name> }
    regex comment             { <-[\n]>* }
    token editor-name         { <with-other-stuff> }
}

class EditorLineActions does BasePathsActions is export {
    #token editor-name         { <with-other-stuff> }
    method editor-name($/) {
        my $edname = $/<with-other-stuff>.made;
        make $edname;
    }
    method editor($/) {
        my $ed-name;
        if $/<base-path> {
            $ed-name = $/<base-path>.made ~ '/' ~ $/<editor-name>.made;
        } else {
            $ed-name = $/<editor-name>.made;
        }
        make $ed-name;
    }
    method comment($/) {
        my $comm = (~$/).trim;
        make $comm;
    }
    method config-line($/) {
        my %cfg-line = type => 'config-line', value => $/<editor>.made;
        if $/<comment> {
            my $com = $/<comment>.made;
            %cfg-line«comment» = $com;
        }
        make %cfg-line;
    }
    method TOP($made) {
        my %top = type => 'editor-to-use', value => $made<editor>.made;
        if $made<comment> {
            my $com = $made<comment>.made;
            %top«comment» = $com;
        }
        $made.make: %top;
    }
} # class EditorLineActions does BasePathsActions is export #

```

[Top of Document](#table-of-contents)

### grammar OverrideGUIEditor & actions class OverrideGUIEditorActions

A grammar to parse/recognise the **`override GUI_EDITOR # comment`** line.

```
grammar OverrideGUIEditor is export {
    regex TOP     { ^ \h* [ <commented> \h* ]? 'override' \h+ 'GUI_EDITOR' [ \h+ '#' <comment> ]? \h* $ }
    regex comment { <-[\n]>* }
    token commented { '#' }
}

class OverrideGUIEditorActions is export {
    method comment($/) {
        my $comment = (~$/).trim;
        make $comment;
    }
    method commented($/) {
        my $commented = (~$/).trim;
        make $commented;
    }
    method TOP($made) {
        my %top = type => 'override-gui_editor', :value;
        if $made<commented> {
            %top«value» = False;
        }
        if $made<comment> {
            my $com = $made<comment>.made;
            %top«comment» = $com;
        }
        $made.make: %top;
    }
} # class OverrideGUIEditorActions #

```

[Top of Document](#table-of-contents)

## Some useful variables

**NB: All these variables are available outside of the module as a sub of the same name. That way I can give read only access to them.**

### $GUI\_EDITOR

The value of the **`%*ENV«GUI_EDITOR»`** environment variable or **`''`** if not set.

### $VISUAL

The value of the **`%*ENV«VISUAL»`** environment variable or **`''`** if not set.

### $EDITOR

The value of the **`%*ENV«EDITOR»`** environment variable or **`''`** if not set.

```
my Str:D $GUI_EDITOR = ((%*ENV<GUI_EDITOR>:exists) ?? ~%*ENV<GUI_EDITOR> !! '');
my Str:D $VISUAL     = ((%*ENV<VISUAL>:exists) ?? ~%*ENV<VISUAL> !! '');
my Str:D $EDITOR     = ((%*ENV<EDITOR>:exists) ?? ~%*ENV<EDITOR> !! '');

sub GUI_EDITOR( --> Str:D) is export {
    return $GUI_EDITOR;
}

sub VISUAL( --> Str:D) is export {
    return $VISUAL;
}

sub EDITOR( --> Str:D) is export {
    return $EDITOR;
}

```

[Top of Document](#table-of-contents)

### @GUIEDITORS

The Array of Hashes that the **`Editors`** grammar and **`EditorsActions`** generate from parsing the **editors** file.

### @gui-editors

The Array of GUI Editors defined in the **editors** file.

### @default-editors

The array of **editors** selected in the file should have only **one** element otherwise the file is miss configured.

```
my Hash @GUIEDITORS;
my Str:D @gui-editors;
my Str:D @default-editors;

sub GUIEDITORS( --> Array[Hash]) is export {
    return @GUIEDITORS;
}

sub gui-editors( --> Array[Str:D]) is export {
    return @gui-editors;
}

sub default-editors( --> Array[Str:D]) is export {
    return @default-editors;
}

```

[Top of Document](#table-of-contents)

### @override-gui\_editor

An array of **True** values one for each of the times the **`override GUI_EDITOR`** directive appears in the **editors** file, it is an error for it to appear more than once, (it's a zero or one rule).

### $override-GUI\_EDITOR

True if the **`override GUI_EDITOR`** directive is present in the **editors** file. If **True** then the setting in the file overrides the **`%*ENV«GUI_EDITOR»`** variable, otherwise **`%*ENV«GUI_EDITOR»`** wins.

```
my Bool:D @override-gui_editor;

sub override-gui_editor( --> Array[Bool:D]) is export {
    return @override-gui_editor;
}

my Bool:D $override-GUI_EDITOR = False;

sub override-GUI_EDITOR( --> Bool:D) is export {
    return $override-GUI_EDITOR;
}

```

[Top of Document](#table-of-contents)

#### In **`init-gui-editors`**

```
sub init-gui-editors(Str:D @client-config-files, Str:D $client-config-path,
                              &gen-configs:(Str:D, Str:D --> Bool:D),
                                  &check:(Str:D @cfg-files, Str:D $config --> Bool:D)
                                                                    --> Bool:D) is  export

```

...

...

...

```
@GUIEDITORS = Editors.parse(@editors-file.join("\x0A"), :enc('UTF-8'), :$actions).made;
@gui-editors = @GUIEDITORS.grep( -> %l { %l«type» eq 'config-line' } ).map: -> %ln { %ln«value»; };
@default-editors = @GUIEDITORS.grep( -> %l { %l«type» eq 'editor-to-use' } ).map: -> %ln { %ln«value»; };
if @default-editors > 1 {
    $*ERR.say: "Error: file $editor-config/editors is miss configured  more than one editor defined should be 0 or 1";
}
@override-gui_editor = @GUIEDITORS.grep( -> %l { %l«type» eq 'override-gui_editor' } ).map: -> %ln { %ln«value»; };
if @override-gui_editor > 1 {
    my Int:D $elems = @override-gui_editor.elems;
    $*ERR.say: qq[Make up your mind only one "override GUI_EDITOR" is required, you supplied $elems are you insane???];
    $override-GUI_EDITOR = True;
} elsif @override-gui_editor == 1 {
    $override-GUI_EDITOR = True;
}
if @gui-editors {
    #@gui-editors.raku.say;
    for @gui-editors -> $geditor {
        if !@guieditors.grep: { $geditor } {
            my Str $guieditor = $geditor;
            $guieditor .=trim;
            @guieditors.append($guieditor);
        }
    }
}

if $override-GUI_EDITOR && @default-editors {
    $editor = @default-editors[@default-editors - 1];
}elsif %*ENV<GUI_EDITOR>:exists {
    my Str $guieditor = ~%*ENV<GUI_EDITOR>;
    if ! @guieditors.grep( { $_ eq $guieditor.IO.basename } ) {
        @guieditors.prepend($guieditor.IO.basename);
    }
} elsif $editor-guessed && @default-editors {
    $editor = @default-editors[@default-editors - 1];
}

```

[Top of Document](#table-of-contents)

### $editor

The editor the user has chosen.

```
# the editor to use #
my Str:D $editor = '';

sub editor( --> Str:D) is export {
    return $editor;
}

```

## edit-configs()

A function to open the users configuration files in their chosen editor.

```
sub edit-configs() returns Bool:D is export {
    if $editor {
        my $option = '';
        my @args;
        my $edbase = $editor.IO.basename;
        if $edbase eq 'gvim' {
            $option = '-p';
            @args.append('-p');
        }
        for @config-files -> $file {
            if $file eq 'editors' {
                @args.append("$editor-config/$file");
            } else {
                @args.append("$client-config/$file");
            }
        }
        my $proc = run($editor, |@args);
        return $proc.exitcode == 0 || $proc.exitcode == -1;
    } else {
        $*ERR.say: "no editor found please set GUI_EDITOR, VISUAL or EDITOR to your preferred editor.";
        $*ERR.say: "e.g. export GUI_EDITOR=/usr/bin/gvim";
        $*ERR.say: "or set editor in the $editor-config/editors file this can be done with the set editor command.";
        $*ERR.say: qq[NB: the editor will be set by first checking GUI_EDITOR then VISUAL then EDITOR and
                    finally editor in the config file so GUI_EDITOR will win over all.
                    Unless you supply the "override GUI_EDITOR" directive in the $editor-config/editors file
                    and also supplied the "editor := <editor>" directive];
        return False;
    }
}

```

[Top of Document](#table-of-contents)

## Editor functions

### list-editors(…)

List all known GUI Editors, flagging the selected editor with **'\*'** note if none is flagged either **`$editor`** is set to a non GUI Editor or **`$editor`** is set to the empty string.

```
sub list-editors(Str:D $prefix,
                 Bool:D $colour,
                 Bool:D $syntax,
                 Int:D $page-length,
                 Regex:D $pattern --> Bool) is export

```

### editors-stats(…)

Show the values of some editors parameters.

```
sub editors-stats(Str:D $prefix,
                  Bool:D $colour,
                  Bool:D $syntax,
                  Int:D $page-length,
                  Regex:D $pattern --> Bool) is export

```

[Top of Document](#table-of-contents)

### BadEditor

**`BadEditor`** is an Exception class for the **`GUI::Editors`** module.

```
class BadEditor is Exception is export {
    has Str:D $.msg = 'Error: bad editor specified';
    method message( --> Str:D) {
        $!msg;
    }
}

```

### set-editor(…)

A function to set the editor of choice.

```
sub set-editor(Str:D $editor, Str $comment = Str --> Bool:D) is export

```

**NB: this will still be overridden by `%*ENV«GUI_EDITOR»` unless you set **override GUI\_EDITOR****.

### add-gui-editor(…)

Add an editor to the list of known GUI Editors.

```
sub add-gui-editor(Str:D $editor, Str $comment = Str --> Bool:D) is export

```

**NB: please make sure it really is a GUI Editor otherwise this module will not work correctly. You are completely free to set the chosen editor to what ever you like.**

### set-override-GUI\_EDITOR(…)

Set or unset the **override GUI\_EDITOR** flag.

```
sub set-override-GUI_EDITOR(Bool:D $value, Str $comment = Str --> Bool:D) is export

```

If set then the file always wins else **`%*ENV«GUI_EDITOR»`** always wins if set.

[Top of Document](#table-of-contents)

### backup-editors(…)

Backup the editors file.

```
sub backup-editors(Bool:D $use-windows-formatting --> Bool) is export

```

**NB: if $use-windows-formatting is true or the program is running on windows then `.` will become `·` and `:` will become `.`, this is to avoid problems with the special meaning of `:` on windows.**

[Top of Document](#table-of-contents)

### restore-editors(…)

Restore the editors file from a backup.

```
sub restore-editors(IO::Path $restore-from --> Bool) is export

```

If **`$restore-from`** is relative and not found from the current directory **`$editor-config/$restore-from`** will be tried.

### list-editors-backups(…)

List all the available backups in the **`$editor-config`**.

```
sub list-editors-backups(Str:D $prefix,
                         Bool:D $colour is copy,
                         Bool:D $syntax,
                         Regex:D $pattern,
                         Int:D $page-length --> Bool:D) is export

```

* Where

  * **`$prefix`** a filter only files starting with this are included in the result.
  * **`$colour`** colour the output.
  * **`$syntax`** syntax highlight the results colour on steroids.
  * **`$pattern`** a regex to filter the results by only files matching this will be included in the results.
  * **`$page-length`** set the length of the pages before it repeats the header.

[Top of Document](#table-of-contents)

### backups-menu-restore-editors(…)

Presents a menu so you can choose which backup to restore from.

```
sub backups-menu-restore-editors(Bool:D $colour,
                                 Bool:D $syntax,
                                 Str:D $message = "" --> Bool:D) is export

```

* Where:

  * **`$colour`** if **`True`** represents the menu in colours.
  * **`$syntax`** if **`True`** represents the menu syntax highlighted.

    * basically colour on steroids.

      * uses the **`Gzz::Text::Utils::menu(…)`**, which uses the **`Gzz::Text::Utils::dropdown(…)`** function for colour and syntax.

[Top of Document](#table-of-contents)

### edit-files(…)

Edit arbitrary files using chosen editor.

```
sub edit-files(Str:D @files --> Bool:D) is export

```

* Where

  * **`@files`** a list of files to open in the chosen GUI editor.

[Top of Document](#table-of-contents)


## sendonclosed.md
class X::Channel::SendOnClosed

Error due to calling send on a closed channel

```raku
class X::Channel::SendOnClosed {}
```

This exception is thrown when a calling `send` on a [`Channel`](/type/Channel) that has been closed:

```raku
my $s = Channel.new;
$s.close;
$s.send(42);
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::Channel::SendOnClosed: Cannot send a message on a closed channel␤»
```

# [Methods](#class_X::Channel::SendOnClosed "go to top of document")[§](#Methods "direct link")

## [method channel](#class_X::Channel::SendOnClosed "go to top of document")[§](#method_channel "direct link")

```raku
method Channel(X::Channel::SendOnClosed:D: --> Channel:D)
```

Returns the Channel object on which the `send` method was called.


## currentthreadscheduler.md
class CurrentThreadScheduler

Scheduler that synchronously executes code on the current thread

```raku
class CurrentThreadScheduler does Scheduler {}

```

`CurrentThreadScheduler` executes tasks on the current threads. This means that [method cue](/type/Scheduler#method_cue) blocks until the code has finished executing.

# [Typegraph](# "go to top of document")[§](#typegraphrelations "direct link")

Type relations for `CurrentThreadScheduler`

raku-type-graph

CurrentThreadScheduler
CurrentThreadScheduler

Any
Any

CurrentThreadScheduler->Any

Scheduler
Scheduler

CurrentThreadScheduler->Scheduler

Mu
Mu

Any->Mu

[Expand chart above](/assets/typegraphs/CurrentThreadScheduler.svg)


## dist_zef-lizmat-HTTP-Status.md
[![Actions Status](https://github.com/lizmat/HTTP-Status/actions/workflows/linux.yml/badge.svg)](https://github.com/lizmat/HTTP-Status/actions) [![Actions Status](https://github.com/lizmat/HTTP-Status/actions/workflows/macos.yml/badge.svg)](https://github.com/lizmat/HTTP-Status/actions) [![Actions Status](https://github.com/lizmat/HTTP-Status/actions/workflows/windows.yml/badge.svg)](https://github.com/lizmat/HTTP-Status/actions)

# NAME

HTTP::Status - Information about HTTP Status Codes

# SYNOPSIS

```
use HTTP::Status;

say HTTP::Status(200);          # OK

say HTTP::Status(200).title;    # OK

say HTTP::Status(200).type;     # Success

say HTTP::Status(200).summary;  # Standard response for successful HTTP...

say HTTP::Status(200).origin;   # IANA

say HTTP::Status(200).since;    # HTTP/1.0

say HTTP::Status(200).RFC;      # 7231

say HTTP::Status(200).code;     # 200

say HTTP::Status.source;        # https://en.wikipedia.org/....

# Legacy interface
say get_http_status_msg(200);   # OK

say "Informational" if is-info($code);
say "Success" if is-success($code);
say "Redirection" if is-redirect($code):
say "Error" if  is-error($code);
say "Client Error" if is-client-error($code);
say "Server Error" if is-server-error($code);

my %status := HTTP::Status.Map;

```

# DESCRIPTION

The `HTTP::Status` class contains information about HTTP Status Codes as can be found on [Wikipedia](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).

To obtain the information about a given HTTP Status Code, one calls the `HTTP::Status` class with the code in question:

```
my $status = HTTP::Status(200);

```

This returns **the** `HTTP::Status` object for the given code, or it returns `Nil` if the code is unknown.

The `HTTP::Status` object stringifies to its `title`, and numifies to its `code`:

```
say $status;   # OK

say +$status;  # 200

```

It also contains the type of status code and a summary of additional information about that status code that may be useful as a further help in debugging issues:

```
say $status.type;     # Success

say $status.summary;  # Standard response for successful...

```

Apart from `title`, `type`, `code` and `summary`, the object also contains information about the applicable `RFC`, its `origin` and `since` which version of the HTTP protocol it has been available:

```
say $status.origin;  # IANA

say $status.RFC;     # 7231

say $status.since;   # HTTP/1.0

```

Finally, if you want to know the source of the information that is provided by this module, use the `source` class method, which returns the URL of the Wikipedia page that was used:

```
say HTTP::Status.source;  # https://en.wikipedia.org/....

```

# CLASS METHODS

In this class methods, the `HTTP::Status` class could be considered as an `Associative`.

## keys

Returns a `Seq` with the codes for which there is a defined HTTP status.

## values

Returns a `Seq` with the `HTTP::Status` objects for which there is a defined HTTP status.

## kv

Returns a `Seq` with code / `HTTP::Status` object for which there is a defined HTTP Status.

## pairs

Returns a `Seq` with code => `HTTP::Status` object pairs for which there is a defined HTTP Status.

## Hash

Returns a `Hash` with the code => `HTTP::Status` object mappings for which there is a defined HTTP Status.

## Map

Returns a `Map` with the code => `HTTP::Status` object mappings for which there is a defined HTTP Status.

# LEGACY INTERFACE

The legacy interface is identical to the version originally created by `Timothy Totten`.

## get\_http\_status\_msg

Returns the string for the given HTTP Status code, or `Unknown`.

## is-info

Returns whether the given HTTP Status code is informational (100..199).

## is-success

Returns whether the given HTTP Status code indicates success (200..299).

## is-redirect

Returns whether the given HTTP Status code indicates a redirection of some kind (300..399).

## is-error

Returns whether the given HTTP Status code indicates a some kind of error (400..599).

## is-client-error

Returns whether the given HTTP Status code indicates a some kind of client error (400..499).

## is-server-error

Returns whether the given HTTP Status code indicates a some kind of server error (500..599).

# ADAPTING INFORMATION

If you want to add or adapt the information as provided by this class, you can easily do that by creating a new `HTTP::Status` object in sink context.

```
HTTP::Status.new(
  code    => 137,
  title   => "Very Special Prime",
  summary => "Really the answer!",
  origin  => "Mathematics",
  since   => "HTTP/2.1",
  RFC     => 13377,
);

say HTTP::Status(137);  # Very Special Prime

```

# AUTHOR

Elizabeth Mattijsen

Source can be located at: <https://github.com/lizmat/HTTP-Status> . Comments and Pull Requests are welcome.

If you like this module, or what I’m doing more generally, committing to a [small sponsorship](https://github.com/sponsors/lizmat/) would mean a great deal to me!

# COPYRIGHT AND LICENSE

Copyright 2012 - 2020 Timothy Totten

Copyright 2021, 2022, 2025 Elizabeth Mattijsen

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-lizmat-P5readlink.md
[![Actions Status](https://github.com/lizmat/P5readlink/workflows/test/badge.svg)](https://github.com/lizmat/P5readlink/actions)

# NAME

Raku port of Perl's readlink() built-in

# SYNOPSIS

```
use P5readlink;

say readlink("foobar"); # string if symlink, Nil if not

with "foobar" {
    say readlink; # string if symlink, Nil if not
}

```

# DESCRIPTION

This module tries to mimic the behaviour of Perl's `readlink` built-in as closely as possible in the Raku Programming Language.

# ORIGINAL PERL DOCUMENTATION

```
readlink EXPR
readlink
        Returns the value of a symbolic link, if symbolic links are
        implemented. If not, raises an exception. If there is a system
        error, returns the undefined value and sets $! (errno). If EXPR is
        omitted, uses $_.

        Portability issues: "readlink" in perlport.

```

# PORTING CAVEATS

## $! not always set

Currently `$!` is **not** set when Nil is returned.

## $\_ no longer accessible from caller's scope

In future language versions of Raku, it will become impossible to access the `$_` variable of the caller's scope, because it will not have been marked as a dynamic variable. So please consider changing:

```
readlink;

```

to either:

```
readlink($_);

```

or, using the subroutine as a method syntax, with the prefix `.` shortcut to use that scope's `$_` as the invocant:

```
.&readlink;

```

# AUTHOR

Elizabeth Mattijsen [liz@raku.rocks](mailto:liz@raku.rocks)

If you like this module, or what I’m doing more generally, committing to a [small sponsorship](https://github.com/sponsors/lizmat/) would mean a great deal to me!

Source can be located at: <https://github.com/lizmat/P5readlink> . Comments and Pull Requests are welcome.

# COPYRIGHT AND LICENSE

Copyright 2018, 2019, 2020, 2021, 2023 Elizabeth Mattijsen

Re-imagined from Perl as part of the CPAN Butterfly Plan.

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_zef-FCO-Cromponent.md
[![Actions Status](https://github.com/FCO/Cromponent/actions/workflows/test.yml/badge.svg)](https://github.com/FCO/Cromponent/actions)

# NAME

Cromponent - A way create web components with cro templates

# SYNOPSIS

```
use Cromponent;
class AComponent does Cromponent {
	has $.data;

	method RENDER {
		Q:to/END/
		<h1><.data></h1>
		END
	}
}

sub EXPORT { AComponent.^exports }

```

# DESCRIPTION

Cromponent is a way create web components with cro templates

You can use Cromponents in 3 distinct (and complementar) ways

* In a template only way: If wou just want your Cromponent to be a "fancy substitute for cro-template sub/macro", You can simpley create your Cromponent, and on yout template, <:use> it, it with export a sub (or a macro if you used the `is macro` trait) to your template, that sub (or macro) will accept any arguments you pass it and will pass it to your Cromponent's conscructor (new), and use the result of that as the value to be used.

  Ex:

  ```
  use Cromponent;

  class H1 does Cromponent is macro {
      has Str $.prefix = "My fancy H1";

      method RENDER {
  	    Q[<h1><.prefix><:body></h1>]
      }
  }

  sub EXPORT { H1.^exports }

  ```

  On your template:

  ```
  <:use H1>
  <|H1(:prefix('Something very important: '))>
      That was it
  </|>

  ```
* As a value passed as data to the template. If a Cromponent is passed as a value to a template, you can simply "print" it inside the template to have its rendered version, it will probably be an HTML, so it will need to be called inside a <&HTML()> call (I'm still trying to figureout how to avoid that requirement).

  Ex:

  ```
  use Cromponent;

  class Todo does Cromponent {
      has Str  $.text is required;
      has Bool &.done = False;

      method RENDER {
  	    Q:to/END/
  	    <tr>
  		    <td>
  			    <input type='checkbox' <?.done>checked</?>>
  		    </td>
  		    <td>
  			    <.text>
  		    </td>
  	    </tr>
  	    END
      }
  }

  sub EXPORT { Todo.^exports }

  ```

  On your route:

  ```
  template "todos.crotmp", { :todos(<bla ble bli>.map: -> $text { Todo.new: :$text }) }

  ```

  On your template:

  ```
  <@.todos: $todo>
      <&HTML($todo)>
  </@>

  ```
* You can also use a Cromponent to auto-generate cro routes

  Ex:

  ```
  use Cromponent;

  class Text does Cromponent {
      my UInt $next-id = 1;
      my %texts;

      has UInt $.id      = $next-id++;
      has Str  $.text is required;
      has Bool $.deleted = False;

      method TWEAK(|) { %tests{$!id} = self }

      method LOAD($id) { %tests{$id} }

      method all { %texts.values }

      method toggle is accessoble {
  	    $!deleted = !$!deleted
      }

      method RENDER {
  	    Q:to/END/
  	    <?.deleted><del><.text></del></?>
  	    <!><.text></!>
  	    END
      }
  }

  sub EXPORT { Todo.^exports }

  ```

  On your route:

  ```
  use Text;
  route {
      Text.^add-cromponent-routes;

      get -> {
  	    template "texts.crotmp", { :texts[ Texts.all ] }
      }
  }

  ```

  The call to the .^add-cromponent-routes method will create (on this case) 2 endpoints:

  * `/text/<id>` -- that will return the HTML ot the obj with that id rendered (it will use the method `LOAD` to get the object)
  * `/text/<id>/toggle` -- that will load the object using the method `LOAD` and call `toggle` on it

  You can also define the method `ADD`, `DELETE`, and `UPDATE` to allow it to create other endpoints.

# AUTHOR

Fernando Corrêa de Oliveira [fco@cpan.com](mailto:fco@cpan.com)

# COPYRIGHT AND LICENSE

Copyright 2024 Fernando Corrêa de Oliveira

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


## dist_cpan-JGOFF-ANTLR4-Grammar.md
# ANTLR4

ANTLR4 proides an ANTLR4 to Perl6 Grammar converter.

The grammar, AST and Perl6 bindings are provided as separate modules, so you can view both the raw abstract syntax tree and the final Perl6 converted output.

# Installation

* Using panda (a module management tool bundled with Rakudo Star):

```
    panda update && panda install ANTLR4

```

* Using ufo (a project Makefile creation script bundled with Rakudo Star) and make:

```
    ufo
    make
    make test
    make install

```

## Testing

To run tests:

```
    prove -e perl6

```

## Author

Jeffrey Goff, DrFOrr on #perl6, <https://github.com/drforr/>

## License

Artistic License 2.0


## dist_zef-tony-o-Archive-Tar-PP.md
# usage

since i know this is all you care about

## new tar

```
use Archive::Tar::PP;

my $new-archive = new-tar('x.tar');

$new-archive.push('some file'); #adds file data to buffer;

$new-archive.write; #now you have some tarball

```

## crusty tar

```
use Archive::Tar::PP;

my $crusty = read-tar('x.tar');

$crusty.ls; #returns files
$crusty.peek('file-name to get contents of');
#  returns Nil for dir, empty Buf for an empty file, and a Buf with the contents otherwise

```

# limitations

* doesn't keep user or group names
* stores the buffers in memory so, beware
* rewrites entire tar file every time you write, so use sparingly