ORT(3) | Library Functions Manual | ORT(3) |
ort
— ort code
generator library
library “libort”
#include
<sys/queue.h>
#include <stdio.h>
#include <ort.h>
struct bitf
struct bitidx
struct config
struct eitem
struct enm
struct label
struct role
struct rolemap
struct strct
The ort
library parses
ort(5) configuration files. The most common usage is as
follows:
To compile applications with ort
, include
the ort.h as follows:
#include <sys/queue.h> #include <stdio.h> /* FILE */ #include <ort.h>
To compile and link, use pkg-config(1):
% cc `pkg-config --cflags ort` -c -o sample.o sample.c % cc -o sample sample.o `pkg-config --libs ort`
The ort
library is built to operate in
security-sensitive environments, including pledge(2) on
OpenBSD. The only promise required is
"stdio".
In this documentation, all structures ending in "q",
such as "struct bitidxq", are represented as tail-queue macros in
<sys/queue.h>
.
The central structure of ort
is
struct config, which represents one or more
configuration files. It is allocated with
ort_config_alloc(3), filled with
ort_parse_file(3), and finalised with
ort_parse_close(3). It must be freed with
ort_config_free(3).
CONFIG_HAS_PASS
if any passwords are declared in
the configuration.The central component of struct config is the queue of struct strct. These collectively represent the data, operations, and other properties. It may be represented as an SQL table, a C structure, a TypeScript class, or a JavaScript object.
NULL
, free-form documentation. May be
empty.NULL
, the row identifier field.NULL
, the insert statement for the
structure. Inserts are used to create data.STRCT_HAS_QUEUE
if any list queries are defined,
STRCT_HAS_ITERATOR
if any iterator queries are
defined, STRCT_HAS_BLOB
if any blob fields are
defined, and STRCT_HAS_NULLREFS
if any reference
structures can be null.The data of struct strct is defined by its queue of struct field. It may be represented as a column in an SQL table, a field of a C structure, or a member of a JavaScript object.
FTYPE_STRUCT
fields or references
to other structures. Otherwise it is NULL
.FTYPE_ENUM
fields to the enumeration.
Otherwise it is NULL
.FTYPE_BITFIELD
fields to the bitfield.
Otherwise it is NULL
.NULL
, free-form documentation. May be
empty.FTYPE_DATE
, FTYPE_BIT
,
FTYPE_BITFIELD
,
FTYPE_EPOCH
, FTYPE_INT
),
double decimal for a default real value
FTYPE_REAL
, char *string for
a default string type (one of FTYPE_EMAIL
or
FTYPE_TEXT
), or struct eitem
*eitem for a default enumeration.UPACT_NONE
for not specifying a delete handler,
UPACT_RESTRICT
for inhibiting the default,
UPACT_NULLIFY
for nullifying the field,
UPACT_CASCADE
from propogating changes to the
field, or UPACT_DEFAULT
for the default
behaviour.NULL
, role assignments for not exporting
this field.FIELD_ROWID
if being the
structure's unique row identifier (only available for
FTYPE_INT
), FIELD_UNIQUE
if a unique field within the structure, FIELD_NULL
if the field may be null, FIELD_NOEXPORT
if the
field may not be exported ever, and FIELD_HASDEF
if the field has a default type-specific value set.References are a central part of ort
and
allow fields to link to other fields. These are governed by
struct ref in struct field. Any
field not of type FTYPE_STRUCT
may link to any other
field in another structure that has the same type. This is called a foreign
reference. Fields with the special FTYPE_STRUCT
type
have a reference that points to a foreign reference in the same structure.
This is called a local reference.
Validation allows constraining the data accepted for native types,
i.e., not enum
or bits
. A
struct field may contain zero or more validation
statements in fvq:
FTYPE_BIT
,
FTYPE_BITFIELD
,
FTYPE_DATE
, FTYPE_EPOCH
,
or FTYPE_INT
, this is int64_t
integer; if FTYPE_REAL
, this is
double decimal; otherwise, it is
size_t len.Unique data is stipulated on a per-field basis with
FIELD_UNIQUE
or using struct
unique for the concatenation of multiple fields.
The data in struct field may be typed as an enumeration or bit-field, both of which are defined within the configuration. In short, both of these limit the integers accepted to those defined as enumeration values or bit masks.
The user-defined enumerations in eq limit integer types to specific values. Its struct enm is defined as follows:
NULL
, free-form documentation. May be
empty.Each enumeration has a non-empty list of struct eitem that define the enumeration's values.
INT64_MAX
and greater than
INT64_MIN
. It is unique among other items in the
enumeration.NULL
, free-form documentation. May be
empty.EITEM_AUTO
if the
value was assigned dynamically. Dynamic assignment
occurs after parsing and works by taking the maximum assigned value (bound
below at zero), adding one, then assigning and adding one in the order of
declaration.The label queue of struct label is exported, so its contents must be considered public. It consists of names for each item.
The user-defined bit-field struct bitf is similar to an enumeration:
NULL
, free-form documentation. May be
empty.The bit-field is composed of multiple struct bitidx bits that are recognised by the application.
NULL
, free-form documentation. May be
empty.User-based types all have text representations of their numeric values. These labels may be assigned in any number of languages. All languages are defined in the char **langs array in struct config. Labels are defined in queues of type struct label in all user-defined types:
The role-based access control of the system is defined by struct role. If the rq queue in the top-level struct config is empty, there are no roles defined. (This should not change a generated API.) Roles are hierarchical, so the roles in struct config are top-level roles. Roles inherit the operations (defined by struct rolemap) available to the parent.
NULL
, free-form documentation. May be
empty.NULL
, this is a top-level
role.One or more role are assigned to operations or data with struct rolemap.
ROLEMAP_ALL
, which is an alias for all types
except
ROLEMAP_NOEXPORT
;
ROLEMAP_COUNT
,
ROLEMAP_ITERATE
,
ROLEMAP_LIST
, and
ROLEMAP_SEARCH
for queries;
ROLEMAP_DELETE
for deletions;
ROLEMAP_UPDATE
for updates;
ROLEMAP_INSERT
for insertions; and
ROLEMAP_NOEXPORT
for making specific fields
unexportable to the role.ROLEMAP_NOEXPORT
, the field that shouldn't be
exported.ROLEMAP_COUNT
,
ROLEMAP_ITERATE
,
ROLEMAP_LIST
, or
ROLEMAP_SEARCH
, the query to receive the
assignment.ROLEMAP_DELETE
or
ROLEMAP_UPDATE
, the deletion or update to receive
the assignment.Data may be modified or deleted as defined by struct update, used in uq and dq, respectively, in struct strct.
NULL
if
anonymous.NULL
, free-form documentation. May be
empty.UP_MODIFY
to modify data or
UP_DELETE
to delete.NULL
, roles allowed to perform the
operation.UPDATE_ALL
if the operation is an update
and all modifier fields were specified by leaving the modifier field empty
during configuration.Fields by which operations are constrained or modified are defined in struct uref:
UP_DELETE
references.UP_MODIFY
references.New data may be inserted as defined by struct insert, which is only used in ins of struct strct.
NULL
, roles allowed to perform
insertions.Data may be extracted by using queries. These are defined for each struct strct. The foundation for all queries is struct search, which is used for all types of query.
NULL
, how to aggregate search results. This
is used with group.NULL
, the field that is used for grouping
results. This field will be unique among the results, with the choice of
which object to use for the unique result being set by
aggr.NULL
, only return distinct results of a
reference within the query. It may be set to the current structure.NULL
to have an automatically-generated
name.NULL
, free-form documentation. May be
empty.STYPE_COUNT
to return
only the count of results, STYPE_SEARCH
to query
for a single result, STYPE_LIST
to return all
results, or STYPE_ITERATE
to provide a callback to
iterate over results.NULL
, roles allowed to perform this
query.SEARCH_IS_UNIQUE
if the query
will return a single result. (That is, it queries unique values.)Search parameters are listed in a queue of struct sent. The queue may have multiple parameters of the same field, as there may be multiple ways of indirecting to the same field.
NULL
if within the same
structure as parent.Ordering within query results is dictated by the queue of struct ord. By default, search results are ordered arbitrarily.
NULL
if in the current
structure.ORDTYPE_ASC
for ascending (1, 2,
3...) and ORDTYPE_DESC
for descending (...3, 2,
1).The dst field of type struct dstnct allows results to be returned from unique sub-structures (referenced structures).
Result aggregation is effected through a group, which defines the grouping field (i.e., results are placed into buckets having the same field value); and the aggregator, which defines how groups are distilled into a single value.
The group pointer, if not
NULL
, is a struct group with
the following. If not NULL
, it must be pair with a
aggr that is also not
NULL
.
NULL
if in the current
structure.The aggregate function is in aggr of type
struct aggr, which if not
NULL
, implies that group is
also not NULL
.
NULL
if in the
current structure.AGGR_MAXROW
to
select the maximum row or AGGR_MINROW
. If there
are multiple maxima or minima, the selection criterion is not yet
specified.Messages are generated by parsing, linking, and front-end formatting to indicate some sort of bad condition. These messages are accumulated in struct config and should be reported to the operator. They are represented by struct msg.
NULL
.MSGTYPE_WARN
for a
message that may be ignored, MSGTYPE_ERROR
when a
parse/format sequence should be stopped due to errors, or
MSGTYPE_FATAL
when a system error has
occurred.NULL
, usually used
in conjunction with er. If both
buf and er aren't set, the
message is considered a noop.The following parses standard input and repeats the parsed, canonicalised configuration on standard output.
struct config *cfg; if ((cfg = ort_config_alloc()) == NULL) err(1, NULL); if (!ort_parse_file(cfg, stdin, "<stdin>"); errx(1, "ort_parse_file"); if (!ort_parse_close(cfg)) errx(1, "ort_parse_close"); if (!ort_write_file(stdout, cfg)) errx(1, "ort_write_file"); ort_config_free(cfg);
October 25, 2021 | OpenBSD 6.7 |