.TH LIBNORMALFORM_FROM_STRING 3 LIBNORMALFORM
.SH NAME
libnormalform_from_string \- Deserialise a sentence from a string

.SH SYNOPSIS
.nf
#include <libnormalform.h>

struct libnormalform_representation_spec {
	void *\fIuser_data\fP;
	struct libnormalform_variable *(*\fIget_variable\fP)(char *, char **, void *);
	struct libnormalform_function *(*\fIget_function\fP)(char *, char **, void *);
	struct libnormalform_map *(*\fIget_map\fP)(char *, char **, void *);
	struct libnormalform_transformer *(*\fIget_transformer\fP)(char *, char **, void *);
};

LIBNORMALFORM_SENTENCE *libnormalform_from_string(/* optionally const */ char *\fIs\fP,
                                                  /* at least as const as \fIs\fP */ char **\fIend_out\fP,
                                                  const struct libnormalform_representation_spec *\fIspec\fP);
.fi
.PP
Link with
.IR -lnormalform .

.SH DESCRIPTION
The
.BR libnormalform_from_string ()
function parse
\fIs\fP
and returns an equivalent sentence.
.P
If
.I end_out
is
.RI non- NULL ,
the position in
.I s
after the end of the representation is stored in
.IR *end_out
upon successful terminate (unspecified on failure),
otherwise the function will validate that it
only contains whitespace after the end of the
representation.
.PP
.I s
will not be modified by the
.BR libnormalform_from_string ()
function, however it will let user provided
functions modify
.IR s ,
therefore
.I s
may be read-only if, and only if, the user provided
functions do not modify
.IR s .
.PP
.IR spec->get_variable ,
.IR spec->get_function ,
.IR spec->get_map ,
and
.IR spec->get_transformer ,
may each be either
.I NULL
or a function pointers returns an object,
according to their return type, described in
the sentence. The functions shall return
.I NULL
on and only on failure. When these functions
are called by the
.BR libnormalform_from_string ()
function, the first argument will be the beginning
of the string they shall parse — these strings will
not be properly terminated, — the second argument
will be pointer that the end (the position immediately
after the last byte) of the parsed string shall be
stored (on success), and the third argument will be
.I spec->user_data
which is only used by the application for
application-defined purposes.
.I spec->user_data
may be
.IR NULL .
.PP
Neither
.I s
nor
.I spec
may be
.IR NULL .
.PP
The returned pointer shall either be
deallocated with the
.BR libnormalform_free (3)
function or be relinquished by being
used as part of another sentence.

.SH RETURN VALUE
Upon successful completion, the
.BR libnormalform_from_string ()
sentence object equivalent to the sentence
described by
.IR s ;
otherwise, the function returns
.I NULL
and sets
.I errno
to indicate the error.

.SH ERRORS
The
.BR libnormalform_from_string ()
function fails if:
.TP
.B ENOMEM
Insufficient memory was available to
create the sentence object.
.TP
.B EINVAL
The representation is invalid.
.TP
.B EINVAL
.I end_out
is
.I NULL
but there are non-whitespace characters in
.I s
after the detected end of the representation.
.TP
.B EDOM
The described sentence contains an empty clause
for a connective that does not support empty
clauses.
.TP
.B EDOM
The described sentence contains a transformation
somewhere over a qualifer.
.TP
.B ENOENT
The described sentence contains a boolean variable but
.I spec->get_variable
was
.IR NULL .
.TP
.B ENOENT
The described sentence contains a boolean function but
.I spec->get_function
was
.IR NULL .
.TP
.B ENOENT
The described sentence contains (a domain of interest
for a) qualifier  but
.I spec->get_map
was
.IR NULL .
.TP
.B ENOENT
The described sentence contains a transformation
(a input transformation function) but
.I spec->get_transformer
was
.IR NULL .
.PP
The
.BR libnormalform_from_string ()
function will also fail if
.IR spec->get_variable ,
.IR spec->get_function ,
.IR spec->get_map ,
or
.IR spec->get_transformer
fails, and will retain
.I errno
as set by the function that failed, or leave
.I errno
unmodified if the failing function did not
modify
.IR errno .

.SH ATTRIBUTES
For an explanation of the terms used in this
section, see
.BR attributes (7)
and
.IR "info \(dq(libc)POSIX Safety Concepts\(dq" .
.TS
allbox;
lb lb lb
l l l.
Interface	Attribute	Value
T{
.BR libnormalform_from_string ()
T}	Thread safety	MT-Safe
T{
.BR libnormalform_from_string ()
T}	Async-signal safety	AS-Unsafe heap
T{
.BR libnormalform_from_string ()
T}	Async-cancel safety	AC-Safe mem, AC-Unsafe heap
.TE

.SH EXTENDED DESCRIPTION
The representation shall be on the whitespace-insensitive form:
.PP
.RS
.nf
\fIconstant\fP         ::= "\fBTRUE\fP" | "\fBFALSE\fP";
\fIconnective1\fP      ::= "\fBNOT\fP";
\fIconnective2\fP      ::= "\fBAND\fP" | "\fBOR\fP" | "\fBXOR\fP" | "\fBIF\fP" | "\fBIMPLY\fP" |
                     "\fBNAND\fP" | "\fBNOR\fP" | "\fBXNOR\fP" | "\fBNIF\fP" | "\fBNIMPLY\fP";
\fIqualifier0\fP       ::= "\fBEMPTY\fP" | "\fBNONEMPTY\fP" | "\fBSINGLETON\fP";
\fIqualifier1\fP       ::= "\fBEXISTS\fP" | "\fBNEXISTS\fP" | "\fBUNIQUE\fP"
                     "\fBEXISTENTIALLY\fP" | "\fBUNIVERSALLY\fP" | "\fBUNIQUELY\fP";
\fIqualifier2\fP       ::= "\fBALL\fP" | "\fBANY\fP" | "\fBONE\fP";
\fIunary\fP            ::= \fIconnective1\fP [\fIreference-point\fP] "\fB(\fP" \fIsentence\fP "\fB)\fP";
\fIvariadic\fP         ::= \fIconnective2\fP [\fIreference-point\fP] "\fB(\fP" [\fIsentence-list\fP] "\fB)\fP";
\fIsentence-list\fP    ::= \fIsentence\fP ["\fB,\fP" \fIsentence-list\fP];
\fIqualified0\fP       ::= \fIqualifier0\fP [\fIreference-point\fP] "\fB(\fP" \fImap\fP "\fB)\fP";
\fIqualified1\fP       ::= \fIqualifier1\fP [\fIreference-point\fP] "\fB(\fP" \fImap\fP "\fB,\fP" \fIsentence\fP "\fB)\fP";
\fIqualified2\fP       ::= \fIqualifier2\fP [\fIreference-point\fP] "\fB(\fP" \fImap\fP "\fB,\fP" \fIsentence\fP "\fB,\fP" \fIsentence\fP "\fB)\fP";
\fIatom\fP             ::= \fIatom-var\fP | \fIatom-fun\fP;
\fIatom-var\fP         ::= "\fBVARIABLE\fP" [\fIreference-point\fP] "\fB(\fP" \fIvariable\fP "\fB)\fP";
\fIatom-fun\fP         ::= "\fBFUNCTION\fP" [\fIreference-point\fP] "\fB(\fP" \fIfunction\fP "\fB)\fP";
\fItransformation\fP   ::= "\fBTRANSFORMATION\fP" [\fIreference-point\fP] "\fB(\fP" \fItransformer\fP "\fB,\fP" \fIsentence\fP "\fB)\fP";
\fIreference-point\fP  ::= "\fB@\fP" \fIdecimal-number\fP;
\fIreference\fP        ::= "\fBREF(\fP" \fIdecimal-number\fP "\fB)\fP";
\fIone-to-nine\fP      ::= "\fB1\fP" | "\fB2\fP" | "\fB3\fP" | "\fB4\fP" | "\fB5\fP" | "\fB6\fP" | "\fB7\fP" | "\fB8\fP" | "\fB9\fP";
\fIzero-to-nine\fP     ::= "\fB0\fP" | \fIone-to-nine\fP;
\fIdecimal-number\fP   ::= "\fB0\fP" | \fIpositive-decimal\fP;
\fIpositive-decimal\fP ::= \fIone-to-nine\fP [\fIdigits\fP];
\fIdigits\fP           ::= \fIzero-to-nine\fP [\fIdigits\fP];
\fIsentence\fP         ::= \fIconstant\fP | \fIunary\fP | \fIvariadic\fP | \fIqualified0\fP | \fIqualified1\fP |
                     \fIqualified2\fP |\fIatom\fP | \fItransformation\fP | \fIreference\fP;
.fi
.RE
.PP
where
.I sentence
is the root, and where
.I map
is parsed by
.IR *spec->get_map ,
.I variable
is parsed by
.IR *spec->get_variable ,
.I function
is parsed by
.IR spec->get_function ,
and
.I transformer
is parsed by
.IR *spec->get_transformer .
References must start at 0 and increment by one,
in left-to-right order, every time a reference point
is specified, and forward-references are not allowed
(this includes reference to containing sentence (whose
reference ID is lower because it is written earlier)).

.SH NOTES
The function will not attempt to deduplicate identical
subsentences, but it will use any explicit deduplication.

.SH SEE ALSO
.BR libnormalform (7),
.BR libnormalform_from_string (3)