Commit 42db644a authored by Jamie A. Jennings's avatar Jamie A. Jennings

Added to librosie doc

parent 042e3d0f
Pipeline #51861631 passed with stage
in 1 minute and 20 seconds
...@@ -279,23 +279,133 @@ The client is responsible for freeing **err** with **rosie_free_string_ptr**. ...@@ -279,23 +279,133 @@ The client is responsible for freeing **err** with **rosie_free_string_ptr**.
**int rosie_trace(Engine \*e, int pat, int start, char \*trace_style, str \*input, int \*matched, str \*trace)** **int rosie_trace(Engine \*e, int pat, int start, char \*trace_style, str \*input, int \*matched, str \*trace)**
Like **rosie_match**, but executes the trace operation where **trace_style** is
a null-terminated C string argument analogous to **encoder**.
Return values are the boolean **matched** (0 for false, 1 for true) and the
string **trace** (which holds the trace output as a string). As with the
**data** field in a match result, a null pointer field in **trace** requires
checking the length field to determine whether an error occurred.
When the **trace** pointer is null and its length is also null, then no trace
data was returned. (Currently, all trace styles produce some data, so this
outcome is not possible.) A non-zero length with a null pointer indicates one
of the errors listed above in the
[interpreting match results](#interpreting-match-results) section.
The client is responsible for freeing **trace** with **rosie_free_string_ptr**.
### Configuration
**int rosie_config(Engine \*e, str \*retvals)**
The **rosie_config** API provides a way to read the configuration of an engine
and of the Rosie installation that created it. The string returned in
**retvals** is a JSON-encoded list of 3 configuration tables:
(1) The first table describes the engine-independent Rosie installation
configuration.
(2) The second table describes the engine configuration.
(3) The third table is a set of configuration parameters that is passed to every
output encoder. (An encoder may use any, all, or none of these.)
Each of the tables is a list of items. Each item has the following structure,
where all JSON values are strings:
- `name`: a unique name for this item of the configuration
- `set_by`: **distribution** if this aspect of the configuration is set by the
Rosie distribution that was installed; **build** if set at build-time;
**default** if it is a run-time default that can be customized; **rcfile** if
set in the Rosie init file **.rosierc**; **CLI** if set on the command line
(CLI only); other values, including the empty string, are possible
- `value`: the current value for this item
- `description`: a human-readable description of the item
- Additional (undocumented) keys may be present.
### Init file processing
These functions have two intended uses: writing a new CLI, and using the Rosie
init file format to customize an application that uses Rosie.
**int rosie_read_rcfile(Engine \*e, str \*filename, int \*file_exists, str \*options, str \*messages)**
Given a **filename**, return whether **file_exists** (1) or not (0), the
**options** declared in the file, and any processing **messages**. The
**options** string is returned as a JSON-encoded list of items, where each item
is a structure containing a single key/value pair. The key is the name of a
configuration parameter set in **filename**, e.g. `libpath`. The value is a
JSON string containing the value set in the init file.
Important notes:
- The init file is allowed to contain keys that are not recognized by Rosie,
though using these as custom keys runs the risk of a name collision in the
future, should Rosie start using that key name. (When it becomes necessary,
we can easily mitigate this with namespaces.)
- A configuration key is allowed to be repeated in an init file. When this
occurs, the item list returned by **rosie_config** returns the settings in the
order they appeared.
- Certain Rosie configuration keys, like `libpath` and `colors`, are treated by
Rosie as additive when used multiple times. When this happens, Rosie coalesces
the multiple values into a single value string. (E.g. multiple `colors`
settings are appended into a single colon-separated string.)
A better interface would be to accept a string instead of a filename, and let
the client program read the init file and slurp the contents into a string. A
future **rosie_read_configuration** API may replace **rosie_read_rcfile**.
The client is responsible for freeing **options** and **messages** with **rosie_free_string_ptr**.
**int rosie_execute_rcfile(Engine \*e, str \*filename, int \*file_exists, int \*no_errors, str \*messages)**
Processes **filename** the same way the Rosie CLI does. Returns two boolean
flags, **file_exists** and **no_errors**, and possibly also **messages**.
Because of the race condition that can occur between reading an init file with
**rosie_read_rcfile** and executing it, this API will very likely be replaced by
one that accepts a JSON-encoded configuration as input. The usage pattern will
then become:
(1) Read a configuration file or string, returning a JSON-encoded structure.
(2) Analyze it, making changes as needed, for example processing and then
removing custom settings.
(3) Execute the resulting configuration (via a future
**rosie_execute_configuration**).
The client is responsible for freeing **messages** with **rosie_free_string_ptr**.
### String management
Rosie strings are contiguous sequences of bytes, represented by a pointer to the
start and a length.
**str rosie_new_string(byte_ptr msg, size_t len)** **str rosie_new_string(byte_ptr msg, size_t len)**
Copies **len** bytes at the pointer **msg** into newly allocated space. Returns
a new string structure initialized such that it refers to the copy.
**str \*rosie_new_string_ptr(byte_ptr msg, size_t len)** **str \*rosie_new_string_ptr(byte_ptr msg, size_t len)**
**str \*rosie_string_ptr_from(byte_ptr msg, size_t len)**
Copies **len** bytes at the pointer **msg** into newly allocated space, and
allocates a new string structure initialized such that it refers to the copy.
Returns a pointer to the structure.
**str rosie_string_from(byte_ptr msg, size_t len)** **str rosie_string_from(byte_ptr msg, size_t len)**
**void rosie_free_string(str s)**
**void rosie_free_string_ptr(str \*s)**
**int rosie_read_rcfile(Engine \*e, str \*filename, int \*file_exists, str \*options, str \*messages)**
**int rosie_execute_rcfile(Engine \*e, str \*filename, int \*file_exists, int \*no_errors, str \*messages)**
**str \*rosie_string_ptr_from(byte_ptr msg, size_t len)**
**void rosie_free_string(str s)**
**void rosie_free_string_ptr(str \*s)**
**int rosie_config(Engine \*e, str \*retvals)**
**int rosie_expression_refs(Engine \*e, str \*input, str \*refs, str \*messages)** **int rosie_expression_refs(Engine \*e, str \*input, str \*refs, str \*messages)**
**int rosie_block_refs(Engine \*e, str \*input, str \*refs, str \*messages)** **int rosie_block_refs(Engine \*e, str \*input, str \*refs, str \*messages)**
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment