First commit

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 265 insertions, 0 deletions

diff --git a/man3/libnormalform_from_string.3 b/man3/libnormalform_from_string.3
new file mode 100644
index 0000000..f0bfc98
--- /dev/null
+++ b/man3/libnormalform_from_string.3
@@ -0,0 +1,265 @@
+.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
+.I ENOMEM
+Insufficient memory was available to
+create the sentence object.
+.TP
+.I EINVAL
+The representation is invalid.
+.TP
+.I EINVAL
+.I end_out
+is
+.I NULL
+but there are non-whitespace characters in
+.I s
+after the detected end of the representation.
+.TP
+.I EDOM
+The described sentence contains an empty clause
+for a connective that does not support empty
+clauses.
+.TP
+.I EDOM
+The described sentence contains a transformation
+somewhere over a qualifer.
+.TP
+.I ENOENT
+The described sentence contains a boolean variable but
+.I spec->get_variable
+was
+.IR NULL .
+.TP
+.I ENOENT
+The described sentence contains a boolean function but
+.I spec->get_function
+was
+.IR NULL .
+.TP
+.I ENOENT
+The described sentence contains (a domain of interest
+for a) qualifier  but
+.I spec->get_map
+was
+.IR NULL .
+.TP
+.I 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)