## dist_github-zostay-P6W.md
## Chunk 2 of 2
. However, applications SHOULD check to make sure that the `wapix.h2.push-promise` variable is set to a defined value before using this extension.

This extension is implemented by providing a variable named `wapix.h2.push-promise`. When provided, this MUST be a [Supplier](http://doc.perl6.org/type/Supplier).

When the application wishes to invoke a server push, it MUST emit a message describing the request the server is pushing. The application server will receive this request and make a new, separate call to the application to fulfill that request.

Push-promise messages are sent as an [Array](http://doc.perl6.org/type/Array) of [Pair](http://doc.perl6.org/type/Pair)s. This is a set of headers to send with the PUSH\_PROMISE frame, including HTTP/2 pseudo-headers like ":path" and ":authority".

Upon receiving a message to `wapix.h2.push-promise`, the server SHOULD schedule a followup call to the application to fulfill the push-promise as if the push-promise were an incoming request from the client. (The push-promise could be canceled by the client, so the call to the application might not actually happen.)

# 4 Application Protocol Implementation

One goal of RakuWAPI application servers is to allow the application to focus on building web applications without having to implement the mundane details of web protocols. In times past, this was simply a matter of implementing HTTP/1.x or some kind of front-end to HTTP/1.x (such as CGI or FastCGI). While HTTP/1.x is still relevant to the web today, new protocols have also become important to modern web applications, such as HTTP/2 and WebSocket.

These protocols may have different interfaces that do not lend themselves to the request-response pattern specifed by PSGI. Therefore, we provide a means by which servers and applications may implement these alternate protocols, which each may have different requirements. These protocols are called application protocols to differentiate them from network protocols. For example, rather than providing a protocol for HTTP, we provide the "request-response" protocol. The underlying network protocol may be HTTP/1.0, HTTP/1.1, HTTP/2 or it may be something else that operates according to a similar pattern.

The application and application server MUST communicate according to the application protocol used for the current application call. For many applications, just implementing the basic request-response protocol is enough. However, to allow for more complete applications, RakuWAPI provides additional tools to help application and application server to communicate through a variety of situations. This is handled primarily via the `wapi.protocol`, `wapi.protocol.support`, and `wapi.protocol.enabled` values in the environment.

The application SHOULD check the value in `wapi.protocol`. If the application needs to make a decision based upon the network protocol, the application SHOULD check the `SERVER_PROTOCOL`.

The application SHOULD check `wapi.protocol.support` to discover which protocols are supported by the application server. An application that is not able to support all supported protocols SHOULD modify `wapi.protocol.enabled` to only include protocols supported by the application as early as possible.

The application server MUST provide the `wapi.protocol.support` and `wapi.protocol.enabled` values as part of the configuration environment. The application server MUST NOT use any protocol that is not a member of the `wapi.protocol.enabled` set.

This specification defines the following protocols:

* **request-response** for request-response protocols, including HTTP
* **framed-socket** for framed-socket protocols, such as WebSocket
* **psgi** for legacy PSGI applications
* **socket** for raw, plain socket protocols, which send and receive data with no expectation of special server handling

It is recommended that an application server that implements all of these protocols only enable the request-response protocol within `wapi.protocol.enabled` by default. This allows simple RakuWAPI applications to safely operate without having to perform any special configuration.

## 4.0 Request-Response Protocol

The "request-response" protocol SHOULD be used for any HTTP-style client-server web protocol, this include HTTP/1.x and HTTP/2 connections over plain text and TLS or SSL.

### 4.0.0 Response

Here is an example application that implements the "request-response" protocol:

```
    sub app(%env) {
        start {
            200,
            [ Content-Type => 'text/plain' ],
            supply {
                emit "Hello World"
            },
        }
    }

```

The runtime routine for the application MUST return a [Promise](http://doc.perl6.org/type/Promise). This Promise MUST be kept with a [Capture](http://doc.perl6.org/type/Capture) (or something that becomes one on return) and MAY be broken. The Capture MUST contain 3 positional elements, which are the status code, the list of headers, and the response payload.

* The status code MUST be an [Int](http://doc.perl6.org/type/Int) or an object that coerces to an Int. It MUST be a valid status code for the [SERVER\_PROTOCOL](http://doc.perl6.org/type/SERVER_PROTOCOL).
* The headers MUST be a [List](http://doc.perl6.org/type/List) of [Pair](http://doc.perl6.org/type/Pair)s or an object that when coerced into a List becomes a List of Pairs. These pairs name the headers to return with the response. Header names MAY be repeated.
* The message payload MUST be a *sane* [Supply](http://doc.perl6.org/type/Supply) or an object that coerces into a *sane* Supply, such as a [List](http://doc.perl6.org/type/List).

Here is a more interesting example application of this interface:

```
    sub app(%env) {
        start {
            my $n = %env<QUERY_STRING>.Int;
            200,
            [ Content-Type => 'text/plain' ],
            supply {
                my $acc = 1.FatRat;
                for 1..$n -> $v {
                    emit $acc *= $v;
                    emit "\n";
                }
            },
        }
    }

```

The example application above will print out all the values of factorial from 1 to N where N is given in the query string. The header may be returned immediately and the lines of the body may be returned as the values of factorial are calculated by the application server.

And here is an example demonstrating a couple ways in which coercion can be used by an application to simplify the result:

```
    sub app(%env) {
        my enum HttpStatus (OK => 200, NotFound => 404, ServerError => 500);
        start {
            OK, [ Content-Type => 'text/plain' ], [ 'Hello World' ]
        }
    }

```

In this example, the status is returned using an enumeration which coerces to an appropriate integer value. The payload is returned as a list, which is automatically coerced into a Supply.

Applications SHOULD return a Promise as soon as possible. It is recommended that applications wrap all operations within a `start` block to make this automatic.

Application servers SHOULD NOT assume that the returned [Promise](http://doc.perl6.org/type/Promise) will be kept. It SHOULD assume that the Promise has been vowed and MUST NOT try to keep or break the Promise from the application.

### 4.0.1 Response Payload

The response payload, in the result of the application's promise, must be a *sane* [Supply](http://doc.perl6.org/type/Supply). This supply MUST emit nothing for requests whose response must be empty.

For any other request, the application MAY emit zero or more messages in the returned payload Supply. The messages SHOULD be handled as follows:

* [Blob](http://doc.perl6.org/type/Blob). Any Blob emitted by the application SHOULD be treated as binary data to be passed through to the origin as-is.
* [List](http://doc.perl6.org/type/List) of [Pair](http://doc.perl6.org/type/Pair)s. Some response payloads may contain trailing headers. Any List of Pairs emitted should be treated as trailing headers.
* [Associative](http://doc.perl6.org/type/Associative). Any Associative object emitted should be treated as a message to communicate between layers of the application, middleware, and server. These should be ignored and passed on by middleware to the next layer unless consumed by the current middleware. Any message that reaches the application server but is not consumed by the application server MAY result in a warning being reported, but SHOULD otherwise be ignored. These objects MUST NOT be transmitted to the origin.
* [Mu](http://doc.perl6.org/type/Mu). Any other Mu SHOULD be stringified with the `Str` method and encoded by the application server. If an object given cannot be stringified, the server SHOULD report a warning.

### 4.0.2 Encoding

The application server SHOULD handle encoding of strings or stringified objects emitted to it. When performing encoding, the application server SHOULD honor the `charset` set within the `Content-Type` header, if given. If it does not honor the `charset` or no `charset` is set by the application, it MUST encode any strings in the response payload according to the encoding named in `wapi.body.encoding`.

### 4.0.3 Request-Response Lifecycle

The application server performs the following during a single request-response interaction:

* Receive a request from an origin and begin parsing the request according to the network protocol.
* Construct a runtime environment and combine it with the configuration environment. The `wapi.input` part of the environment should continue reading data from the origin as it arrives until the request has been completely read.
* Call the application runtime routine with the constructed environment and await a value from the returned [Promise](http://doc.perl6.org/type/Promise).
* Return the start of the response using the HTTP status code and headers provided, formatted according to the protocol requirements.
* Tap the supply part of the response and return data to the origin, formatted in ways appropriate for the environment settings and the network protocol in place.

The server processes requests from an origin, passes the processed request information to the application by calling the application, waits for the application's response, and then returns the response to the origin. In the simplest example this means handling an HTTP roundtrip. Yet, it may also mean implementing a related protocol like CGI or FastCGI or SCGI or something else entirely.

In the modern web, an application may want to implement a variety of complex HTTP interactions. These use-cases are not described by the typical HTTP request-response roundtrip with which most web developers are familiar. For example, an interactive Accept-Continue response or a data stream to or from the origin or an upgrade request to switch protocols. As such, application servers SHOULD make a best effort to be implemented in such a way as to make this variety applications possible.

The application server SHOULD pass control to the application as soon as the headers have been received and the environment can be constructed. The application server MAY continue processing the request payload while the application server begins its work. The server SHOULD NOT emit the request payload to `wapi.input` yet.

Once the application has returned the its [Promise](http://doc.perl6.org/type/Promise) to respond, the server SHOULD wait until the promise is kept. Once kept, the server SHOULD tap the response payload as soon as possible. After tapping the Supply, the application server SHOULD keep the [Promise](http://doc.perl6.org/type/Promise) in `wapi.ready` (the application server SHOULD NOT break this Promise). Once that promise has been kept, only then SHOULD the server start emitting the contents of the request payload, if any, to `wapi.input`.

The server SHOULD return the application response headers back to the origin as soon as they are received. After which, the server SHOULD return each chunk emitted by the response body from the application as soon as possible.

This particular order of operations during the application call will ensure that the application has the greatest opportunity to perform well and be able to execute a variety of novel HTTP interactions.

### 4.0.4 HTTP/1.1 Keep Alive

When an application server supports HTTP/1.1 with keep-alive, each request sent on the connection MUST be handled as a separate call to the application.

### 4.0.4 HTTP/2 Handling

When a server supports HTTP/2 it SHOULD implement the HTTP/2 Push Promise Extension defined in section 3.10. An application server MAY want to consider implementing HTTP/2 protocol upgrades using the extension described in section 3.8 or MAY perform such upgrades automatically instead.

The application MUST be called once for each request or push-promise made on an HTTP/2 stream.

## 4.1 Framed-Socket Protocol

The "framed-socket" protocol is appropriate for WebSocket-style peer-to-peer TCP connections. The following sections assume a WebSocket connection, but might be adaptable for use with other framed message exchanges, such as message queues or chat servers.

### 4.1.0 Response

Any application server implementing WebSocket MUST adhere to all the requirements described above with the following modifications when calling the application for a WebSocket:

* The `REQUEST_METHOD` MUST be set to the HTTP method used when the WebSocket connection was negotiated, i.e., usually "GET". Similarly, `SCRIPT_NAME`, `PATH_INFO`, `REQUEST_URI`, `QUERY_STRING`, `SERVER_NAME`, `SERVER_PORT`, `CONTENT_TYPE`, and `HTTP_*` variables in the environment MUST be set to the values from the original upgrade request sent from the origin.
* The `SERVER_PROTOCOL` MUST be set to "WebSocket/13" or a similar string representing the revision of the WebSocket network protocol which in use.
* The `CONTENT_LENGTH` SHOULD be set to an undefined [Int](http://doc.perl6.org/type/Int).
* The `wapi.url-scheme` MUST be set to "ws" for plain text WebSocket connections or "wss" for encrypted WebSocket connections.
* The `wapi.protocol` MUST be set to "framed-socket".
* The server MUST decode frames received from the client and emit each of them to `wapi.input`. The frames MUST NOT be buffered or concatenated.
* The server's supplied `wapi.input` [Supply](http://doc.perl6.org/type/Supply) must be *sane*. The server SHOULD signal `done` through the Supply when either the client or server closes the WebSocket connection normally and `quit` on abnormal termination of the connection.
* The server MUST encode frames emitted by the application in the message payload as data frames sent to the client. The frames MUST be separated out as emitted by the application without any buffering or concatenation.

The application MUST return a [Promise](http://doc.perl6.org/type/Promise) that is kept with just a [Supply](http://doc.perl6.org/type/Supply) (i.e., not a 3-element Capture as is used with the request-response protocol). The application MAY break this Promise. The application will emit frames to send back to the origin using the promised Supply.

### 4.1.1 Response Payload

Applications MUST return a *sane* [Supply](http://doc.perl6.org/type/Supply) that emits an object for every frame it wishes to return to the origin. The application MAY emit zero or more messages to this supply. The application MAY emit `done` to signal that the connection is to be terminated with the client.

The messages MUST be framed and returned to the origin by the application server as follows, based on message type:

* [Blob](http://doc.perl6.org/type/Blob). Any Blob emitted by the application SHOULD be treated as binary data, framed exactly as is, and returned to the client.
* [Associative](http://doc.perl6.org/type/Associative). Any Associative object emitted should be treated as a message to communicate between layers of the application, middleware, and server. These should be ignored and passed on by middleware to the next layer unless consumed by the current middleware. Any message that reaches the application server but is not consumed by the application server MAY result in a warning being reported, but SHOULD otherwise be ignored. These objects MUST NOT be transmitted to the origin.
* [Mu](http://doc.perl6.org/type/Mu). Any other Mu SHOULD be stringified, if possible, and encoded by the application server. If an object given cannot be stringified, the server SHOULD report a warning.

### 4.1.2 Encoding

The application server SHOULD handle encoding of strings or stringified objects emitted to it. The server MUST encode any strings in the message payload according to the encoding named in `wapi.body.encoding`.

## 4.2 PSGI Protocol

To handle legacy applications, this specification defines the "psgi" protocol. If `wapi.protocol.enabled` has both "psgi" and "request-response" enabled, the "request-response" protocol SHOULD be preferred.

### 4.2.0 Response

The application SHOULD return a 3-element [Capture](http://doc.perl6.org/type/Capture) directly. The first element being the numeric status code, the second being an array of pairs naming the headers to return in the response, and finally an array of values representing the response payload.

### 4.2.1 Payload

The payload SHOULD be delivered as an array of strings, never as a supply.

### 4.2.2 Encoding

String encoding is not defined by this document.

## 4.3 Socket Protocol

The "socket" protocol can be provided by an application server wishing to allow the application to basically take over the socket connection with the origin. This allows the application to implement an arbitrary protocol. It does so, however, in a way that is aimed toward providing better portability than using the socket extension.

The socket provided sends and receives data directly to and from the application without any framing, buffering, or modification.

The "socket" protocol SHOULD only be used when it is enabled in `wapi.protocol.enabled` and no other protocol enabled there can fulfill the current application call.

## 4.3.0 Response

Here's an example application that implements the "socket" protocol to create a naïve HTTP server:

```
    sub app(%env) {
        start {
            supply {
                whenever %env<wapi.input> -> $msg {
                    my $req = parse-http-request($msg);

                    if $req.method eq 'GET' {
                        emit "200 OK HTTP/1.0\r\n";
                        emit "\r\n";
                        emit "Custom HTTP Server";
                    }
                }
            }
        }
    }

```

The socket protocol behaves very much like "framed-socket", but with fewer specified details in the environment. Some of the mandatory environment are not mandatory for the socket protocol.

The following parts of the environment SHOULD be provided as undefined values:

* REQUEST\_METHOD
* SCRIPT\_NAME
* PATH\_INFO
* REQUEST\_URI
* QUERY\_STRING
* SERVER\_NAME
* SERVER\_PORT
* CONTENT\_TYPE
* HTTP\_\*
* wapi.url-scheme
* wapi.ready
* wapi.body.encoding
* SERVER\_PROTOCOL

The `wapi.protocol` must be set to "socket".

The application server SHOULD provide data sent by the origin to the application through the `wapi.input` supply as it arrives. It MUST still be a *sane* supply.

The application server MAY tunnel the connection through another socket, stream, file handle, or what-not. That is, the application MAY NOT assume the communication is being performed over any particular medium. The application server SHOULD transmit the data to the origin as faithfully as possible, keeping the intent of the application as much as possible.

The application server SHOULD forward on data emitted by the application in the returned payload supply as it arrives. The application server SHOULD send no other data to the origin over that socket once the application is handed control, unless related to how the data is being tunneled or handled by the server. The application server SHOULD close the connection with the origin when the application server sends the "done" message to the supply. Similarly, the application server SHOULD send "done" the `wapi.input` supply when the connection is closed by the client or server.

### 4.3.1 Response Payload

Applications MUST return a *sane* [Supply](http://doc.perl6.org/type/Supply) which emits a string of bytes for every message to be sent. The messages returned on this stream MUST be [Blob](http://doc.perl6.org/type/Blob) objects.

### 4.3.2 Encoding

The application server SHOULD reject any object other than a [Blob](http://doc.perl6.org/type/Blob) sent as part of the message payload. The application server is not expected to perform any encoding or stringification of messages.

# Changes

## 0.9.Draft

* The error stream is now defined to be a `Supplierish` object, defined in Section 1.1.
* Section 2.2.0.0 has been changed to forbid runtime routines from having a `Callable` return type.
* Section 2.1.2 was rewritten to disallow what was previously allowed: the modification of the input stream.
* Eliminated ambiguity regarding typing of environment in the middleware section.
* Added a section for type constraints and made better use of subset types to streamline and simplify some of the documentation.
* Cleaned up some old language left over from previous versions of the specification.
* Eliminated some ambiguities in the type required for undefined environment values. The undefined environment values MUST match the given type constraint and be set to type objects of that type if they are not defined.
* Changed the abbreviation from P6WAPI to RakuWAPI.
* Changed all `p6w.*` environment prefixes to `wapi.*`
* Changed all `p6wx.*` environment prefixes to `wapix.*`
* Changed all `P6Wx-*` header names to `WAPIx-*` header names
* Renamed all example `*.p6w` files to `*.wapi`

## 0.8.Draft

* Changed the abbreviation from P6W to P6WAPI.

## 0.7.Draft

* Renamed the standard from Perl 6 Standard Gateway Interface (P6SGI) to the Web API for Perl 6 (P6W).
* Some grammar fixes, typo fixes, and general verbiage cleanup and simplification.
* Renaming `p6sgi.*` to `p6w.*` and `p6sgix.*` to `p6wx.*`.
* The errors stream is now a `Supplier` rather than a `Supply` because of recent changes to the Supply interface in Perl 6. Made other supply-related syntax changes because of design changes to S17.
* Eliminating the requirement that things emitted in the response payload be [Cool](http://doc.perl6.org/type/Cool) if they are to be stringified and encoded. Any stringifiable [Mu](http://doc.perl6.org/type/Mu) is permitted.
* Adding `p6w.protocol`, `p6w.protocol.support`, and `p6w.protocol.enabled` to handle server-to-application notification of the required response protocol.
* Breaking sections 2.0.4, 2.1.4, and 2.2.4 up to discuss the difference between the HTTP and WebSocket protocol response requirements.
* Moving 2.0.5, 2.1.5, and 2.2.5 under 2.*.4 because of the protocol changes made in 2.*.4.
* Changed `p6wx.protocol.upgrade` from an [Array](http://doc.perl6.org/type/Array) to a [Set](http://doc.perl6.org/type/Set) of supported protocol names.
* Split the environment and the application into two parts: configuration and runtime.
* Added Section 4 to describe protocol-specific features of the specification. Section 4.0 is for HTTP, 4.1 is for WebSocket, 4.2 is for PSGI, and 4.3 is for Socket.

## 0.6.Draft

* Added Protocol-specific details and modifications to the standard HTTP/1.x environment.
* Adding the Protocol Upgrade extension and started details for HTTP/2 and WebSocket upgrade handling.
* Adding the Transfer Encoding extension because leaving this to the application or unspecified can lead to tricky scenarios.

## 0.5.Draft

* Adding `p6sgi.ready` and added the Application Lifecycle section to describe the ideal lifecycle of an application.
* Changed `p6sgi.input` and `p6sgi.errors` to Supply objects.
* Porting extensions from PSGI and moving the existing extensions into the extension section.
* Adding some notes about middleware encoding.
* Renamed `p6sgi.encoding` to `p6sgi.body.encoding`.
* Renamed `p6sgix.response.sent` to `p6sgix.body.done`.
* Added `p6sgix.header.done` as a new P6SGI extension.

## 0.4.Draft

* Cutting back on some more verbose or unnecessary statements in the standard, trying to stick with just what is important and nothing more.
* The application response has been completely restructured in a form that is both easy on applications and easy on middleware, mainly taking advantage of the fact that a List easily coerces into a Supply.
* Eliminating the P6SGI compilation unit again as it is no longer necessary.
* Change the Supply to emit Cool and Blob rather than just Str and Blob.

## 0.3.Draft

* Splitting the standard formally into layers: Application, Server, and Middleware.
* Bringing back the legacy standards and bringing back the variety of standard response forms.
* Middleware is given a higher priority in this revision and more explanation.
* Adding the P6SGI compilation unit to provide basic tools that allow middleware and possibly servers to easily process all standard response forms.
* Section numbering has been added.
* Added the Changes section.
* Use `p6sgi.` prefixes in the environment rather than `psgi.`

## 0.2.Draft

This second revision eliminates the legacy standard and requires that all P6SGI responses be returned as a [Promise](http://doc.perl6.org/type/Promise). The goal is to try and gain some uniformity in the responses the server must deal with.

## 0.1.Draft

This is the first published version. It was heavily influenced by PSGI and included interfaces based on the standard, deferred, and streaming responses of PSGI. Instead of callbacks, however, it used [Promise](http://doc.perl6.org/type/Promise) to handle deferred responses and [Channel](http://doc.perl6.org/type/Channel) to handle streaming. It mentioned middleware in passing.


## dist_zef-wayland-TOP.md
# Raku TOP: Table-Oriented Programming (TOP) in the Raku programming language

This package implements TOP in Raku.

For more information on TOP (Table Oriented Programming): [What is Table-Oriented Programming?](https://wayland.github.io/table-oriented-programming/TOP/Introduction/What.xml)

## Raku TOP Introductory Documents

[Raku Introductory Docs](https://wayland.github.io/table-oriented-programming/Raku-TOP/Introduction.xml)

## The Object Model Overview

Any classes below in () are not implemented yet

Conceptually, what we're moddeling is:

* Relation

  * Table

    * (DataDictionary)
  * (View)
  * (TupleSet)
* Tuple
* (Section)

  * Field
  * (Lot)
* Database
* Join

Most of the above concepts are directly from Relational Set Theory. The exceptions are:

* DataDictionary: Just a set of tables that explain what the rest of the database is doing; may be implemented differently
* Lot: A group of columns
* TupleSet: A set of tuples, usually that are the result of a query

In addition to the above, we have:

* Storage: This is data we can read/write; used for modelling SQL databases, but could also be in-memory tables, spreadsheets, CSV files, etc
* Formatters: This is for outputting data. Could be tables drawn with CLI box characters, CSV files, etc
* Parsers: This is for reading from tables. This includes reading in space-separated data, CSV files, etc

# Formats and their Parameters

Some formats are only really used as storage (eg. Memory, Postgres). Some things are only ever used as input/output (eg. WithBorders is generally not very useful except as output).

| Format | Storage | Parser | Formatter | Tree Format |
| --- | --- | --- | --- | --- |
| Memory | Yes | No | No |  |
| Postgres | Yes | No | No |  |
| HalfHuman | No | Yes | Yes |  |
| WithBorders | No | No | Yes |  |
| CSV | Yes | Yes | Make |  |
| HTML | Make | Make | Make | XML |
| Spreadsheet | Make | No | No | XML |
| JSON | Make | Make | Make | JSON |
| Pod6 | ? | ? | Make | AST |
| SQLite | Accept | No | No |  |
| MySQL | Accept | No | No |  |
| Postgres option with not using cursors (has to support both cursor and non-cursor) | Accept | No | No |  |
| Dan | Accept | ? | ? |  |  |
| DataQueryWorkflows | Accept | ? | ? |  |

## Key to Formats

* **Yes**: This item exists
* **No**: No plans for this
* **Make**: Plans for this, but nothing yet
* **Accept**: No plans to make this, but would gladly accept it if someone made it
* **Tree**: These ones will be made, but not until Tree-Oriented Programming has been inaugurated

## Raku TOP Class References

Note that the following links don't yet work on raku.land -- you'll need to go to github to read them.

Also, Database::Storage::CSV doesn't work yet (TODO), but the others should; probably start with TOP, then go to Memory, then as you please.

* [class TOP::Parser::CSV](docs/Markdown/Reference/TOP/Parser/CSV.md)
* [class TOP::Parser::HalfHuman](docs/Markdown/Reference/TOP/Parser/HalfHuman.md)
* [class TOP::FieldMode::Error](docs/Markdown/Reference/TOP/FieldMode/Error.md)
* [class TOP::FieldMode::Automatic](docs/Markdown/Reference/TOP/FieldMode/Automatic.md)
* [class TOP::FieldMode::Overflow](docs/Markdown/Reference/TOP/FieldMode/Overflow.md)
* [class TOP::Formatter::WithBorders](docs/Markdown/Reference/TOP/Formatter/WithBorders.md)
* [class TOP::Formatter::HalfHuman](docs/Markdown/Reference/TOP/Formatter/HalfHuman.md)
* [class TOP::FieldMode](docs/Markdown/Reference/TOP/FieldMode.md)
* [class Database::Storage](docs/Markdown/Reference/Database/Storage.md)
* [class Database::Storage::CSV](docs/Markdown/Reference/Database/Storage/CSV.md)
* [class Database::Storage::Memory](docs/Markdown/Reference/Database/Storage/Memory.md)
* [class Database::Storage::Postgres](docs/Markdown/Reference/Database/Storage/Postgres.md)
* [class TOP](docs/Markdown/Reference//TOP.md)

## Plans for Raku TOP

For more information on the plans for Raku TOP, see [Raku TOP TODO](https://wayland.github.io/table-oriented-programming/Raku-TOP/TODO.xml)


## dist_cpan-CONO-Algorithm-Heap-Binary.md
[![Build Status](https://travis-ci.org/cono/p6-algorithm-heap-binary.svg?branch=master)](https://travis-ci.org/cono/p6-algorithm-heap-binary)

# NAME

Algorithm::Heap::Binary - Implementation of a BinaryHeap

# SYNOPSIS

```
    use Algorithm::Heap::Binary;

    my Algorithm::Heap::Binary $heap .= new(
        comparator => * <=> *,
        3 => 'c',
        2 => 'b',
        1 => 'a'
    );

    $heap.size.say; # 3

    # heap-sort example
    $heap.delete-min.value.say; # a
    $heap.delete-min.value.say; # b
    $heap.delete-min.value.say; # c

```

# DESCRIPTION

Algorithm::Heap::Binary provides to you BinaryHeap data structure with basic heap operations defined in Algorithm::Heap role:

## peek

find a maximum item of a max-heap, or a minimum item of a min-heap, respectively

## push

returns the node of maximum value from a max heap [or minimum value from a min heap] after removing it from the heap

## pop

removing the root node of a max heap [or min heap]

## replace

pop root and push a new key. More efficient than pop followed by push, since only need to balance once, not twice, and appropriate for fixed-size heaps

## is-empty

return true if the heap is empty, false otherwise

## size

return the number of items in the heap

## merge

joining two heaps to form a valid new heap containing all the elements of both, preserving the original heaps

# METHODS

## Constructor

BinaryHeap contains `Pair` objects and define order between `Pair.key` by the comparator. Comparator - is a `Code` which defines how to order elements internally. With help of the comparator you can create Min-heap or Max-heap.

* empty constructor

  ```
  my $heap = Algorithm::Heap::Binary.new;

  ```

Default comparator is: `* <=> *`

* named constructor

  ```
  my $heap = Algorithm::Heap::Binary.new(comparator => -> $a, $b {$b cmp $a});

  ```
* constructor with heapify

  ```
  my @numbers = 1 .. *;
  my @letters = 'a' .. *;
  my @data = @numbers Z=> @letters;

  my $heap = Algorithm::Heap::Binary.new(comparator => * <=> *, |@data[^5]);

  ```

This will automatically heapify data for you.

## clone

Clones heap object for you with all internal data.

## is-empty

Returns `Bool` result as to empty Heap or not.

## size

Returns `Int` which corresponds to amount elements in the Heap data structure.

## push(Pair)

Adds new Pair to the heap and resort it.

## insert(Pair)

Alias for push method.

## peek

Returns `Pair` from the top of the Heap.

## find-max

Just an syntatic alias for peek method.

## find-min

Just an syntatic alias for peek method.

## pop

Returns `Piar` from the top of the Heap and also removes it from the Heap.

## delete-max

Just an syntatic alias for pop method.

## delete-min

Just an syntatic alias for pop method.

## replace(Pair)

Replace top element with another Pair. Returns replaced element as a result.

## merge(Algorithm::Heap)

Construct a new Heap merging current one and passed to as an argument.

## Seq

Returns `Seq` of Heap elements. This will clone the data for you, so initial data structure going to be untouched.

## Str

Prints internal representation of the Heap (as an `Array`).

## iterator

Method wich provides iterator (`role Iterable`). Will clone current Heap for you.

## sift-up

Internal method to make sift-up operation.

## sift-down

Internal method to make sift-down operation.

# AUTHOR

[cono](mailto:q@cono.org.ua)

# COPYRIGHT AND LICENSE

Copyright 2018 cono

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

# LINKS

* <https://en.wikipedia.org/wiki/Heap_(data_structure)>
* <https://en.wikipedia.org/wiki/Binary_heap>


## dist_cpan-MARTIMM-Gnome-N.md
![](https://martimm.github.io/gnome-gtk3/content-docs/images/gtk-raku.png)

# Gnome::N - Native Raku Interface to Gnome

![L](http://martimm.github.io/label/License-label.svg)

# Description

This package holds the native object description as well as the interface description to connect to the Gnome libraries. This set of modules will never act on their own. They will be used by other packages such as `Gnome::Gtk3` and the like.

Note that all modules are now in `:api<1>`. This is done to prevent clashes with future distributions having the same class names only differing in this api string. So, add this string to your import statements and dependency modules of these classes in META6.json. Furthermore add this api string also when installing with zef.

Example;

```
use Gnome::Gtk3::Main:api<1>;
use Gnome::Gtk3::Window:api<1>;
use Gnome::Gtk3::Grid:api<1>;
use Gnome::Gtk3::Button:api<1>;

my Gnome::Gtk3::Main $m .= new;
… etcetera …

```

## Documentation

* [🔗 License document](http://www.perlfoundation.org/artistic_license_2_0)
* [🔗 Release notes](https://github.com/MARTIMM/gnome-native/blob/master/CHANGES.md)
* [🔗 Issues](https://github.com/MARTIMM/gnome-gtk3/issues)

# Installation

Do not install this package on its own. Instead install `Gnome::Gtk3:api<1>`.

`zef install 'Gnome::Gtk3:api<1>'`

# Author

Name: **Marcel Timmerman**
Github account name: **MARTIMM**

# Issues

There are always some problems! If you find one, please help by filing an issue at [my Gnome::Gtk3 github project](https://github.com/MARTIMM/gnome-gtk3/issues).

# Attribution

* The developers of Raku of course and the writers of the documentation which helped me out every time again and again.
* The builders of all the Gnome libraries and its documentation.
* Other helpful modules for their insight and use.


## duckmap.md
duckmap

Combined from primary sources listed below.

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

See primary documentation
[in context](/type/Any#method_duckmap)
for **method duckmap**.

```raku
method duckmap(&block) is rw is nodal
```

`duckmap` will apply `&block` on each element that behaves in such a way that `&block` can be applied. If it fails, it will descend recursively if possible, or otherwise return the item without any transformation. It will act on values if the object is [`Associative`](/type/Associative).

```raku
<a b c d e f g>.duckmap(-> $_ where <c d e>.any { .uc }).say;
# OUTPUT: «(a b C D E f g)␤»
(('d', 'e'), 'f').duckmap(-> $_ where <e f>.any { .uc }).say;
# OUTPUT: «((d E) F)␤»
{ first => ('d', 'e'), second => 'f'}.duckmap(-> $_ where <e f>.any { .uc }).say;
# OUTPUT: «{first => (d E), second => F}␤»

```

In the first case, it is applied to `c`, `d` and `e` which are the ones that meet the conditions for the block (`{ .uc }`) to be applied; the rest are returned as is.

In the second case, the first item is a list that does not meet the condition, so it's visited; that flat list will behave in the same way as the first one. In this case:

```raku
say [[1,2,3],[[4,5],6,7]].duckmap( *² ); # OUTPUT: «[9 9]␤»
```

You can square anything as long as it behaves like a number. In this case, there are two arrays with 3 elements each; these arrays will be converted into the number 3 and squared. In the next case, however

```raku
say [[1,2,3],[[4,5],6.1,7.2]].duckmap( -> Rat $_ { $_²} );
# OUTPUT: «[[1 2 3] [[4 5] 37.21 51.84]]␤»
```

3-item lists are not [`Rat`](/type/Rat), so it descends recursively, but eventually only applies the operation to those that walk (or slither, as the case may be) like a [`Rat`](/type/Rat).

Although on the surface (and name), `duckmap` might look similar to [`deepmap`](/routine/deepmap), the latter is applied recursively regardless of the type of the item.


## dist_zef-jforget-Date-Calendar-Hebrew.md
# NAME

Date::Calendar::Hebrew - Conversions from / to the Hebrew calendar

# SYNOPSIS

Converting a Gregorian date (e.g. 16th June 2019) into Hebrew

```
use Date::Calendar::Hebrew;
my Date                   $TPC2019-Pittsburgh-grg;
my Date::Calendar::Hebrew $TPC2019-Pittsburgh-heb;

$TPC2019-Pittsburgh-grg .= new(2019, 6, 16);
$TPC2019-Pittsburgh-heb .= new-from-date($TPC2019-Pittsburgh-grg);

say $TPC2019-Pittsburgh-heb;
# --> 5779-03-13
say "{.day-name} {.day} {.month-name} {.year}" with $TPC2019-Pittsburgh-heb;
# --> Yom Rishon 13 Sivan 5779

```

Converting a Hebrew date (e.g. 6 Av 5779) into Gregorian

```
use Date::Calendar::Hebrew;
my Date::Calendar::Hebrew $Perlcon-Riga-heb;
my Date                   $Perlcon-Riga-grg;

$Perlcon-Riga-heb .= new(year  => 5779
                       , month =>    5
                       , day   =>    6);
$Perlcon-Riga-grg = $Perlcon-Riga-heb.to-date;

say $Perlcon-Riga-grg;

```

# INSTALLATION

```
zef install Date::Calendar::Hebrew

```

or

```
git clone https://github.com/jforget/raku-Date-Calendar-Hebrew.git
cd raku-Date-Calendar-Hebrew
zef install .

```

# DESCRIPTION

Date::Calendar::Hebrew is a class representing dates in the Hebrew
calendar. It allows you to convert an Hebrew date into Gregorian (or
possibly other) calendar and the other way.

# AUTHOR

Jean Forget

# COPYRIGHT AND LICENSE

Copyright (c) 2019, 2020, 2023, 2024 Jean Forget, all rights reserved

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


## dist_zef-ohmycloudy-FeiShuBot.md
# NAME

FeiShuBot - A mini tool for sending message to feishu group.

# SYNOPSIS

```
use FeiShuBot;

use FeiShuBot;

my $hook-url = "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
my $secret = "xxxxxxxxxxxxxxxxxxxxxx";
my $client = FeiShuBot.new(:$hook-url, :$secret);

my $msg = "I'm a bot";
$client.send($msg);

```

# DESCRIPTION

FeiShuBot is a mini tool for sending message to feishu group.

# AUTHOR

[ohmycloud@gmail.com](mailto:ohmycloud@gmail.com)

# COPYRIGHT AND LICENSE

Copyright 2022

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


## dist_github-peelle-LendingClub.md
# LendingClub

[Lending Club API](https://www.lendingclub.com/developers/lc-api.action).

# SYNOPSIS

A wrapper for the Lending Club API. It wraps all of the functions they currently provide. In the below examples, I modified the return #'s for my example query.

# EXAMPLE

```
use LendingClub;
use Data::Dump;

my $lc = LendingClub.new(token => 'somesecrettoken', accountId => 12345 );

say Dump $lc.summary;'

=begin output
{
  accountTotal         => 1000000000.00.Rat,
  accruedInterest      => 1.00.Rat,
  availableCash        => 100.00.Rat,
  infundingBalance     => 100.Int,
  investorId           => 12345.Int,
  outstandingPrincipal => 100000000.Rat,
  receivedInterest     => 1.00.Rat,
  receivedLateFees     => 0.Int,
  receivedPrincipal    => 10.00.Rat,
  totalNotes           => 111.Int,
  totalPortfolios      => 5.Int,
}
=end output

my $dt = DateTime.new( year => 2016, month => 3, day => 3);
my $transfer = $lc.transferFunds( "LOAD_ONCE", 50.00, $dt.Str );

$lc.cancelTransfers( [ $transfer<transfers>[0]<transferId> ] );

my $avail_notes = $lc.listing;

# .... Some code to decide what notes to invest in from the list.....

$lc.submitOrders( 12345, @some_notes_i_want );

```

# INSTALLATION

```
 > zef install LendingClub

```

# DEPENDENCIES

* [JSON::Tiny](https://github.com/moritz/json)
* [Net::HTTP](https://github.com/ugexe/Perl6-Net--HTTP)

# METHODS

> Queries for info.

* summary
* availableCash
* pending
* notes
* detailedNotes
* portfolios
* listing( Bool $showAll = False )

> Actions that affect your account.

* transerFunds( Str $transferFrequency, Rat() $amount, Str $startDate?, Str $endDate?, )
* cancelTransfers( @transferIds )
* createPortfolio( Int $aid, Str $portfolioName, Str $portfolioDescription? )
* submitOrders( Int $aid, @orders )
  \*\* aid is your account number.

# BUGS

* I haven't tested it as thoroughly as I wanted. Specifically I don't have multiple account types(investing, and retirement) so I don't know if it works right for people with both.
* Setting listing to true attempts to get ALL notes on the Lending Club platform. Using a true value for the listing method crashes on my system. I haven't looked into why.

# NOTE ON FRESHNESS

I no longer use Lending Club, but from time to time I will check if they've updated their API. If you notice an update, feel free to contact me via github or email.

# TODO/HELP PLEASE

* More/better tests.

# AUTHOR

James (Jeremy) Carman [developer@peelle.org](mailto:developer@peelle.org)

# ACKNOWLEDGEMENTS

* Mad thanks to [ugexe](https://github.com/ugexe) for accepting my pull request. Without his awesome [Net::HTTP::\*](https://github.com/ugexe/Perl6-Net--HTTP) modules, I would have given up on this module. It was the third module of this type I tried.


## dist_zef-raku-community-modules-Marpa.md
## Chunk 1 of 3
[![Actions Status](https://github.com/raku-community-modules/Marpa/workflows/test/badge.svg)](https://github.com/raku-community-modules/Marpa/actions)

# NAME

Marpa - Raku interface to the libmarpa C library.

# SYNOPSIS

```
use Marpa;

```

# DESCRIPTION

Marpa is a Raku interface to the libmarpa C library.

Marpa requires libmarpa to be present. I'd recommend installing from packages, or just look on the libmarpa website for install instructions.

# AUTHOR

Jeffrey Goff, aka DrForr

Source can be located at: <https://github.com/raku-community-modules/Marpa> . Comments and Pull Requests are welcome.

# COPYRIGHT AND LICENSE

Copyright 2015 - 2018 Jeffrey Goff

Copyright 2019 - 2022 Raku Community

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

### sub marpa\_check\_version

```
sub marpa_check_version(
    Int $required_major,
    Int $required_minor,
    Int $required_micro
) returns Marpa-Error-Code

```

Checks that the Marpa library in use is compatible with the given version. Generally you will pass in the constants MARPA-MAJOR-VERSION, MARPA-MINOR-VERSION, MARPA-MICRO-VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of Libmarpa the application or module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version required\_major.required\_minor.required\_micro. Second the running library must be binary compatible with the version required\_major.required\_minor.required\_micro (same major version.) Success value: MARPA-ERR-NONE if the Marpa library is compatible with the requested version. Failure value: If the library is not compatible, one of the following is returned, indicating the nature of the mismatch: MARPA-ERR-MAJOR-VERSION-MISMATCH, MARPA-ERR-MINOR-VERSION-MISMATCH MARPA-ERR-MICRO-VERSION-MISMATCH

### sub marpa\_version

```
sub marpa_version(
    NativeCall::Types::Pointer[Int] $version
) returns Marpa-Error-Code

```

Returns the version number in version, which must have room for three int's. Success value: A non-negative number. Failure value: −2.

### sub marpa\_c\_init

```
sub marpa_c_init(
    NativeCall::Types::Pointer[Marpa::Marpa-Config] $config
) returns Int

```

Initialize the config information to “safe” default values. Unspecified behavior will result if an initialized configuration is used to create a grammar. Success value: A non-negative value. Failure value: Always succeeds.

### sub marpa\_c\_error

```
sub marpa_c_error(
    NativeCall::Types::Pointer[Marpa::Marpa-Config] $config,
    NativeCall::Types::Pointer[Str] $p_error_string
) returns Marpa-Error-Code

```

Error codes are usually kept in the base grammar, which leaves marpa\_g\_new() no place to put its error code on failure. Objects of the Marpa-Config class provide such a place. p\_error\_string is reserved for use by the internals. Applications should set it to NULL. Success value: The error code in config. Failure value: Always succeeds.

### sub marpa\_g\_new

```
sub marpa_g_new(
    NativeCall::Types::Pointer[Marpa::Marpa-Config] $configuration
) returns Marpa::g

```

Creates a new grammar time object. The returned grammar object is not yet precomputed, and will have no symbols and rules. Its reference count will be 1. Unless the application calls marpa\_c\_error, Libmarpa will not reference the location pointed to by the configuration argument after marpa\_g\_new returns. The configuration argument may be NULL, but if it is, there will be no way to determine the error code on failure. Success value: the grammar object. Failure value: NULL, and the error code is set in configuration.

### sub marpa\_g\_force\_valued

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

```

It is recommended that this call be made immediately after the grammar constructor. It turns off a deprecated feature. The marpa\_g\_force\_valued forces all the symbols in a grammar to be “valued”. The opposite of a valued symbol is one about whose value you do not care. This distinction has been made in the past in hope of gaining efficiencies at evaluation time. Current thinking is that the gains do not repay the extra complexity. Success value: a non-negative integer. Failure value: a negative integer.

### sub marpa\_g\_ref

```
sub marpa_g_ref(
    Marpa::Marpa-Grammar $g
) returns Marpa::g

```

Increases the reference count by 1. Not needed by most applications. Success value: the grammar object it was called with. Failure value: NULL.

### sub marpa\_g\_unref

```
sub marpa_g_unref(
    Marpa::g $g
) returns Mu

```

Decreases the reference count by 1, destroying g once the reference count reaches zero.

### sub marpa\_g\_start\_symbol

```
sub marpa_g_start_symbol(
    Marpa::g $g
) returns Marpa::Marpa-Symbol-ID

```

Returns current value of the start symbol of grammar g. The value is that specified in the marpa\_g\_start\_symbol\_set() call, if there has been one. Success value: The new start symbol. Failure value: -1 if there is no start symbol, otherwise -2.

### sub marpa\_g\_start\_symbol\_set

```
sub marpa_g_start_symbol_set(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Marpa::Marpa-Symbol-ID

```

Sets the start symbol of grammar g to symbol id. Success value: The ID of the new start symbol. Failure value: -1 if sym\_id is well-formed but there is no such symbol, otherwise -2.

### sub marpa\_g\_highest\_symbol\_id

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

```

Success value: the numerically largest symbol ID of $g. Failure value: -2.

### sub marpa\_g\_symbol\_is\_accessible

```
sub marpa_g_symbol_is_accessible(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

A symbol is accessible if it can be reached from the start symbol. Success value: 1 if symbol sym\_id is accessible, 0 if not. If sym\_id is well-formed, but there is no such symbol, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: -2.

### sub marpa\_g\_symbol\_is\_nullable

```
sub marpa_g_symbol_is_nullable(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

A symbol is nullable if it sometimes produces the empty string. A nulling symbol is always a nullable symbol, but not all nullable symbols are nulling symbols. Success value: 1 if symbol sym\_id is nullable, 0 if not. If sym\_id is well-formed, but there is no such symbol, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: -2.

### sub marpa\_g\_symbol\_is\_nulling

```
sub marpa_g_symbol_is_nulling(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

A symbol is nulling if it always produces the empty string. Success value: 1 if symbol sym\_id is nulling, 0 if not. If sym\_id is well-formed, but there is no such symbol, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: -2.

### sub marpa\_g\_symbol\_is\_productive

```
sub marpa_g_symbol_is_productive(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

A symbol is productive if it can produce a string of terminals. All nullable symbols are considered productive. Success value: 1 if symbol sym\_id is productive, 0 if not. If sym\_id is well-formed, but there is no such symbol, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: -2.

### sub marpa\_g\_symbol\_is\_start

```
sub marpa_g_symbol_is_start(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

This return value of this call indicates whether sym\_id is the start symbol. Success value: 1 if sym\_id is the start symbol. 0 if sym\_id is not the start symbol, either because the start symbol is different from sym\_id, or because the start symbol has not been set yet. Failure value: -1 if sym\_id is well-formed, but there is no such symbol. -2 on other failure.

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

```
sub marpa_g_symbol_is_terminal_set(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $value
) returns Int

```

These methods, respectively, set and query the “terminal status” of a symbol. To be used as an input symbol in the marpa\_r\_alternative() method, a symbol must be a terminal. This function flags symbol sym\_id as a terminal if value is 1, or flags it as a non-terminal if value is 0. Once set to a value with the marpa\_g\_symbol\_is\_terminal\_set() method, the terminal status of a symbol is “locked” at that value. A subsequent call to marpa\_g\_symbol\_is\_terminal\_set() that attempts to change the terminal status of sym\_id to a value different from its current one will fail. The error code will be MARPA-ERR-TERMINAL-IS-LOCKED. By default, a symbol is a terminal if and only if it does not appear on the LHS of any rule. An attempt to flag a nulling symbol as a terminal will cause a failure, but this is not necessarily detected before precomputation. Success returns: When successful, these methods return 1 if symbol sym\_id is a terminal symbol after the call, 0 otherwise. Failure returns: If sym\_id is well-formed, but there is no such symbol, −1. On all other failures, −2. Other failures include when value is not 0 or 1; when the terminal status is locked and value is different from its current value; and, in the case of marpa\_g\_symbol\_is\_terminal\_set(), when the grammar g is precomputed.

### sub marpa\_g\_symbol\_new

```
sub marpa_g_symbol_new(
    Marpa::g $g
) returns Marpa::Marpa-Symbol-ID

```

Creates a new symbol. The symbol ID will be a non-negative integer. Success value: The ID of a new symbol. Failure value: −2.

### sub marpa\_g\_highest\_rule\_id

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

```

Success value: The ID of the numerically largest rule ID of $g. Failure value: −2.

### sub marpa\_g\_rule\_is\_accessible

```
sub marpa_g_rule_is_accessible(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id
) returns Int

```

A rule is accessible if it can be reached from the start symbol. A rule is accessible if and only if its LHS symbol is accessible. The start rule is always an accessible rule. Success value: 1 if rule rule\_id is accessible, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.

### sub marpa\_g\_rule\_is\_nullable

```
sub marpa_g_rule_is_nullable(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $ruleid
) returns Int

```

A rule is nullable if it sometimes produces the empty string. A nulling rule is always a nullable rule, but not all nullable rules are nulling rules. Success value: 1 if rule ruleid is nullable, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.

### sub marpa\_g\_rule\_is\_nulling

```
sub marpa_g_rule_is_nulling(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $ruleid
) returns Int

```

A rule is nulling if it always produces the empty string. Success value: 1 if rule ruleid is nulling, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.

### sub marpa\_g\_rule\_is\_loop

```
sub marpa_g_rule_is_loop(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id
) returns Int

```

A rule is a loop rule if it non-trivially produces the string of length one which consists only of its LHS symbol. Such a derivation takes the parse back to where it started, hence the term “loop”. “Non-trivially” means the zero-step derivation does not count — the derivation must have at least one step. The presence of a loop rule makes a grammar infinitely ambiguous, and applications will typically want to treat them as fatal errors. But nothing forces an application to do this, and Marpa will successfully parse and evaluate grammars with loop rules. Success value: 1 if rule rule\_id is a loop rule, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.

### sub marpa\_g\_rule\_is\_productive

```
sub marpa_g_rule_is_productive(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id
) returns Int

```

A rule is productive if it can produce a string of terminals. An rule is productive if and only if all the symbols on its RHS are productive. The empty string counts as a string of terminals, so that a nullable rule is always a productive rule. For that same reason, an empty rule is considered productive. Success value: 1 if rule rule\_id is productive, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.

### sub marpa\_g\_rule\_length

```
sub marpa_g_rule_length(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id
) returns Int

```

The length of a rule is the number of symbols on its RHS. Success value: The length of rule $rule\_id. Failure value: −2.

### sub marpa\_g\_rule\_lhs

```
sub marpa_g_rule_lhs(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id
) returns Marpa::Marpa-Symbol-ID

```

Success value: The LHS symbol of rule rule\_id. If rule\_id is well-formed, but there is no such rule, −1. Failure value: −2.

### sub marpa\_g\_rule\_new

```
sub marpa_g_rule_new(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $lhs_id,
    NativeCall::Types::Pointer[Marpa::Marpa-Symbol-ID] $rhs_ids,
    Int $length
) returns Marpa::Marpa-Rule-ID

```

Creates a new external BNF rule in grammar g. The ID of the new rule will be a non-negative integer, which will be unique to that rule. In addition to BNF rules, Marpa also allows sequence rules, which are created by another method: marpa\_g\_sequence\_new(). Sequence rules and BNF rules are numbered in the same series, so that a BNF rule will never have the same rule ID as a sequence rule, and vice versa. The LHS symbol is lhs\_id, and there are length symbols on the RHS. The RHS symbols are in an array pointed to by rhs\_ids. Possible failures, with their error codes, include: MARPA-ERR-SEQUENCE-LHS-NOT-UNIQUE: The LHS symbol is the same as that of a sequence rule. MARPA-ERR-DUPLICATE-RULE: The new rule would duplicate another BNF rule. Another BNF rule is considered the duplicate of the new one, if its LHS symbol is the same as symbol lhs\_id, if its length is the same as length, and if its RHS symbols match one for one those in the array of symbols rhs\_ids. Success value: the ID of new external rule. Failure value: −2.

### sub marpa\_g\_rule\_rhs

```
sub marpa_g_rule_rhs(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id,
    int $ix
) returns Marpa::Marpa-Symbol-ID

```

Returns the ID of the symbol in position ix in the RHS of rule rule\_id. The RHS position, ix, is zero-based. Success value: The ID of the symbol in position ix on the rules RHS. If rule\_id is well-formed, but there is no such rule, −1. If ix is greater than or equal to the length of the rule, or on other failure, −2. Failure value: −2.

### sub marpa\_g\_rule\_is\_proper\_separation

```
sub marpa_g_rule_is_proper_separation(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id
) returns Int

```

Success returns: marpa\_g\_rule\_is\_proper\_separation() succeeds if and only if rule\_id is valid. If rule rule\_id is a sequence rule where the proper separation flag is set, returns 1. On other success, including the case where rule rule\_id is not a sequence rule, returns 0. Failure returns: If rule\_id is well-formed, but there is no such rule, returns −1. On other failure, −2.

### sub marpa\_g\_sequence\_min

```
sub marpa_g_sequence_min(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id
) returns Int

```

Returns the mininum length of a sequence rule. This accessor can be also be used to test whether or not a rule is a sequence rule. −1 is returned if and only if the rule is valid but not a sequence rule. Success value: If rule rule\_id is a sequence rule, its minimum length. If rule rule\_id is valid, but is not the rule ID of sequence rule, −1. If rule\_id is well-formed, but there is no such rule, or on other failure, −2. Failure value: −2.

### sub marpa\_g\_sequence\_new

```
sub marpa_g_sequence_new(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $lhs_id,
    Marpa::Marpa-Symbol-ID $rhs_id,
    Marpa::Marpa-Symbol-ID $separator_id,
    Int $min,
    Int $flags
) returns Marpa::Marpa-Rule-ID

```

Adds a new sequence rule to grammar g. The ID of the new sequence rule will be a non-negative integer, which is unique to that rule. Sequence rules and BNF rules are numbered in the same series, so that a BNF rule will never have the same rule ID as a sequence rule, and vice versa. The sequence is lhs\_id, and the item to be repeated in the sequence is rhs\_id. The sequence must be repeated at least min times, where min is 0 or 1. If separator\_id is non-negative, it is a separator symbol. If flags & MARPA-PROPER-SEPARATION is non-zero, separation is “proper”, that is, a trailing separator is not allowed. The term proper is based on the idea that properly-speaking, separators should actually separate items. Some higher-level Marpa interfaces offer the ability to discard separators in the semantics, and in fact will do this by default. At the Libmarpa level, sequences always “keep separators”. It is up to the programmer to arrange to discard separators, if that is what is desired. The sequence RHS, or item, is restricted to a single symbol, and that symbol cannot be nullable. If separator\_id is a symbol, it also cannot be a nullable symbol. Nullables on the RHS of sequences are restricted because they lead to highly ambiguous grammars. Grammars of this kind are allowed by Libmarpa, but they must be expressed using BNF rules, not sequence rules. This is for two reasons: First, sequence optimizations would not work in the presence of nullables. Second, since it is not completely clear what an application intends when it asks for a sequence of identical items, some of which are nullable, the user's intent can be more clearly expressed directly in BNF. The LHS symbol cannot be the LHS of any other rule, whether a BNF rule or a sequence rule. On an attempt to create an sequence rule with a duplicate LHS, marpa\_g\_sequence\_new() fails, setting the error code to MARPA-ERR-SEQUENCE-LHS-NOT-UNIQUE. Sequence rules do not add to the classes of grammar parsed by Libmarpa — a sequence can always be written as BNF rules. When a rule is created with the marpa\_g\_sequence\_new() method, Libmarpa will understand that it is a sequence, and will optimize accordingly. The speedup is often considerable. Success value: The ID of the external rule. Failure value: −2.

### sub marpa\_g\_sequence\_separator

```
sub marpa_g_sequence_separator(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id
) returns Int

```

Success value: If rule rule\_id is a sequence rule, its separator. If rule rule\_id is a sequence rule, but there is no separator, −1. If rule\_id is not a sequence rule, does not exist or is not well-formed; or on other failure, −2. Failure value: −2.

### sub marpa\_g\_symbol\_is\_counted

```
sub marpa_g_symbol_is_counted(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

A symbol is counted if it appears on the RHS of a sequence rule, or if it is used as the separator symbol of a sequence rule. Success return: Returns 1 if symbol sym\_id is counted, 0 if not. Failure return: If sym\_id is well-formed, but there is no such symbol, −1. If sym\_id is not well-formed, and on other failure, −2.

### sub marpa\_g\_rule\_rank\_set

```
sub marpa_g_rule_rank_set(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id,
    Marpa::Marpa-Rank $rank
) returns Marpa::Marpa-Rank

```

These methods, respectively, set and query the rank of a rule rule\_id. When rule\_id is created, its rank initialized to the default rank of the grammar. Initially, the default rank of the grammar is 0. Methods to reset the grammar's default rank are currently in the experimental stage. 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\_rule\_null\_high\_set

```
sub marpa_g_rule_null_high_set(
    Marpa::g $g,
    Marpa::Marpa-Rule-ID $rule_id,
    Int $flag
) returns Int

```

These methods, respectively, set and query the “null ranks high” setting of the rule rule\_id. The “null ranks high” setting is either 0 or 1. When rule\_id is created, its “null ranks high” setting is initialized to 0. The “null ranks high” setting affects the ranking of rules with properly nullable symbols on their right hand side. If a rule has properly nullable symbols on its RHS, each instance in which it appears in a parse will have a pattern of nulled and non-nulled symbols. Such a pattern is called a “null variant”. If the “null ranks high” setting is 0 (the default), nulled symbols rank low. If the “null ranks high” setting is 1, nulled symbols rank high. Ranking of a null variants is done from left-to-right. The marpa\_g\_rule\_null\_high\_set() method will return failure after the grammar has been precomputed. If there is no other cause of failure, the marpa\_g\_rule\_null\_high() method succeeds on both precomputed and unprecomputed grammars. Success value: The value of the “null ranks high” flag after the call. Failure value: If rule\_id is well-formed, but there is no such rule, −1. On all other failures, −2.

### sub marpa\_g\_completion\_symbol\_activate

```
sub marpa_g_completion_symbol_activate(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $reactivate
) returns Int

```

Allows the user to deactivate and reactivate symbol completion events in the grammar. When a recognizer is created, the activation status of each of its events is initialized to the activation status of that event in the base grammar. If reactivate is zero, the event is deactivated in the grammar. If reactivate is one, the event is activated in the grammar. 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. The activation status of a completion event in the grammar can only be changed if the symbol is marked as a completion event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a completion event symbol in the recognizer, the completion event can be deactivated and reactivated in the recognizer. Success cases: On success, the method returns the value of reactivate. The method succeeds trivially if the symbol is already set as indicated by reactivate. Failure cases: 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\_g\_nulled\_symbol\_activate

```
sub marpa_g_nulled_symbol_activate(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $reactivate
) returns Int

```

Allows the user to deactivate and reactivate symbol nulled events in the grammar. When a recognizer is created, the activation status of each of its events is initialized to the activation status of that event in the base grammar. If reactivate is zero, the event is deactivated in the grammar. If reactivate is one, the event is activated in the grammar. 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. The activation status of a nulled event in the grammar can only be changed if the symbol is marked as a nulled event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a nulled event symbol in the recognizer, the nulled event can be deactivated and reactivated in the recognizer. Success value: On success, 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 nulled event for sym\_id cannot be set as indicated by reactivate, the method fails. On failure, −2 is returned.

### sub marpa\_g\_prediction\_symbol\_activate

```
sub marpa_g_prediction_symbol_activate(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $reactivate
) returns Int

```

Allows the user to deactivate and reactivate symbol prediction events in the grammar. When a recognizer is created, the activation status of each of its events is initialized to the activation status of that event in the base grammar. If reactivate is zero, the event is deactivated in the grammar. If reactivate is one, the event is activated in the grammar. 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. The activation status of a prediction event in the grammar can only be changed if the symbol is marked as a prediction event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a prediction event symbol in the recognizer, the prediction event can be deactivated and reactivated in the recognizer. Success cases: On success, the method returns the value of reactivate. The method succeeds trivially if the symbol is already set as indicated by reactivate. Failure cases: If the active status of the prediction event for sym\_id cannot be set as indicated by reactivate, the method fails. On failure, −2 is returned.

### sub marpa\_g\_symbol\_is\_completion\_event

```
sub marpa_g_symbol_is_completion_event(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

Libmarpa can be set up to generate an MARPA-EVENT-SYMBOL-COMPLETED event whenever the symbol is completed. A symbol is said to be completed when a non-nulling rule with that symbol on its LHS is completed. For completion events to occur, the symbol must be marked as a completion event symbol. The marpa\_g\_symbol\_is\_completion\_event\_set() function marks symbol sym\_id as a completion event symbol if value is 1, and unmarks it it as a completion event symbol if value is 0. The marpa\_g\_symbol\_is\_completion\_event() method returns the current value of the completion event marking for symbol sym\_id. Marking a completion event sets its activation status to on. Unmarking a completion event sets its activation status to off. The completion event marking cannot be changed once the grammar is precomputed. If a completion event is marked, its activation status can be changed using the marpa\_g\_completion\_symbol\_activate() method. Note that, if a symbol is marked as a completion event symbol in the recognizer, its completion event can be deactivated and reactivated in the recognizer. Nulled rules and symbols will never cause completion events. Nullable symbols may be marked as completion event symbols, but this will have an effect only when the symbol is not nulled. Nulling symbols may be marked as completion event symbols, but no completion events will ever be generated for a nulling symbol. Note that this implies at no completion event will ever be generated at earleme 0, the start of parsing. Success value: On success, 1 if symbol sym\_id is a completion event symbol after the call, 0 otherwise. Failure value: 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\_symbol\_is\_nulled\_event

```
sub marpa_g_symbol_is_nulled_event(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

Libmarpa can set up to generate an MARPA-EVENT-SYMBOL-NULLED event whenever the symbol is nulled. A symbol is said to be nulled when a zero length instance of that symbol is recognized. For nulled events to occur, the symbol must be marked as a nulled event symbol. The marpa\_g\_symbol\_is\_nulled\_event\_set() function marks symbol sym\_id as a nulled event symbol if value is 1, and unmarks it it as a nulled event symbol if value is 0. The marpa\_g\_symbol\_is\_nulled\_event() method returns the current value of the nulled event marking for symbol sym\_id. Marking a nulled event sets its activation status to on. Unmarking a nulled event sets its activation status to off. The nulled event marking cannot be changed once the grammar is precomputed. If a nulled event is marked, its activation status can be changed using the marpa\_g\_nulled\_symbol\_activate() method. Note that, if a symbol is marked as a nulled event symbol in the recognizer, its nulled event can be deactivated and reactivated in the recognizer. As a reminder, a symbol instance is a symbol at a specific location in the input, and with a specific length. Also, whenever a nulled symbol instance is recognized at a location, it is acceptable at that location, and vice versa. When a symbol instance is recognized at a location, it will generate a nulled event or a prediction event, but never both. A symbol instance of zero length, when recognized at a location, generates a nulled event at that location, and does not generate a completion event. A symbol instance of non-zero length, when acceptable at a location, generates a completion event at that location, and does not generate a nulled event. When a symbol instance is acceptable at a location, it will generate a nulled event or a prediction event, but never both. A symbol instance of zero length, when acceptable at a location, generates a nulled event at that location, and does not generate a prediction event. A symbol instance of non-zero length, when acceptable at a location, generates a prediction event at that location, and does not generate a nulled event. While it is not possible for a symbol instance to generate both a nulled event and a completion event at a location, it is quite possible that a symbol might generate both kinds of event at that location. This is because multiple instances of the same symbol may be recognized at a given location, and these instances will have different lengths. If one instance is recognized at a given location as zero length and a second, non-zero-length, instance is recognized at the same location, the first will generate only nulled events, while the second will generate only completion events. For similar reasons, while a symbol instance will never generate both a null event and a prediction event at a location, multiple instances of the same symbol may do so. Zero length derivations can be ambiguous. When a zero length symbol is recognized, all of its zero-length derivations are also considered to be recognized. Success: On success, 1 if symbol sym\_id is a nulled 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\_symbol\_is\_prediction\_event

```
sub marpa_g_symbol_is_prediction_event(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id
) returns Int

```

Libmarpa can be set up to generate a MARPA-EVENT-SYMBOL-PREDICTED event when a non-nulled symbol is predicted. A non-nulled symbol is said to be predicted when a instance of it is acceptable at the current earleme according to the grammar. Nulled symbols do not generate predictions. For predicted events to occur, the symbol must be marked as a predicted event symbol. The marpa\_g\_symbol\_is\_predicted\_event\_set() function marks symbol sym\_id as a predicted event symbol if value is 1, and unmarks it it as a predicted event symbol if value is 0. The marpa\_g