First commit

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

1 files changed, 245 insertions, 0 deletions

diff --git a/man3/libnormalform_transformation.3 b/man3/libnormalform_transformation.3
new file mode 100644
index 0000000..7bb129e
--- /dev/null
+++ b/man3/libnormalform_transformation.3
@@ -0,0 +1,245 @@
+.TH LIBNORMALFORM_TRANSFORMATION 3 LIBNORMALFORM
+.SH PROLOGUE
+This document describes the function
+.BR libnormalform_transformation ,
+refer to
+.BR struct_libnormalform_transformation (3)
+for the type
+.IR "struct libnormalform_transformation" .
+
+.SH NAME
+libnormalform_transformation \- Function morphism
+
+.SH SYNOPSIS
+.nf
+#include <libnormalform.h>
+
+enum libnormalform_builtin_transformer {
+        \fILIBNORMALFORM_NOT_BUILT_IN\fP = 0,
+        \fILIBNORMALFORM_DOMAIN_VIEW\fP,
+        \fILIBNORMALFORM_IMAGE_VIEW\fP
+};
+
+struct libnormalform_transformer {
+        void *(*\fItransform\fP)(void *user_data, void *input);
+        void (*\fIdeallocate\fP)(void *user_data, void *output);
+        void *\fIuser_data\fP;
+        const char *\fIidentifier\fP;
+        struct libnormalform_transformer *\fIcopy_for_clone\fP;
+        int \fIrequires_elimination\fP;
+	enum libnormalform_builtin_transformer \fIbuiltin\fP;
+};
+
+LIBNORMALFORM_SENTENCE *libnormalform_transformation(struct libnormalform_transformer *\fIfunction\fP,
+                                                     LIBNORMALFORM_SENTENCE *\fIsentence\fP);
+.fi
+.PP
+Link with
+.IR -lnormalform .
+
+.SH DESCRIPTION
+The
+.BR libnormalform_transformation ()
+function creates a sentence output
+the transformation with the application-defined
+.I function
+over a
+.IR sentence.
+The pointer
+.I function
+is application-managed, and must exists while
+the returned sentece exists.
+.PP
+.I function->transform
+is used only be the
+.BR libnormalform_evaluate (3)
+function to modify input to other
+functions (both
+.I struct libnormalform_function
+and
+.IR "struct libnormalform_transformer" ).
+.I function->user_data is passed to
+.I *function->transform
+as its first argument, and the function
+input is passed as its second argument.
+The function is expected to return a
+.RI non- NULL
+pointer upon successful completion and
+.I NULL
+on failure; on failure the function may
+optionally set
+.IR errno .
+If
+.I function->deallocate
+is
+.IR non -NULL ,
+but unless
+.I *function->transform
+returns
+.IR NULL ,
+the library will call
+.I *function->deallocate
+when the pointer returned by
+.I *function->transform
+is no longer needed.
+.I function->user_data is passed to
+.I *function->deallocate
+as its first argument, and the returned
+pointer is passed as its second argument.
+.I function->user_data
+is only used by the application for
+application-defined purposes.
+.I function->user_data
+and
+.I function->deallocate
+may, unlike
+.IR function->transform ,
+be
+.IR NULL ;
+however
+.IR function->transform ,
+.IR function->deallocate ,
+and
+.I function->user_data
+need not be set before the
+.BR libnormalform_evaluate (3)
+function is called.
+.PP
+See
+.BR libnormalform_to_string (3)
+for the purpose of
+.IR function->identifier ,
+it need not be set before the
+.BR libnormalform_to_string (3)
+function is called.
+.PP
+See
+.BR libnormalform_clone (3)
+for the purpose of
+.IR function->copy_for_clone ,
+it need not be set before the
+.BR libnormalform_clone (3)
+function is called.
+.PP
+See
+.BR libnormalform_express (3)
+for the purpose of
+.IR function->requires_elimination ,
+it need not be set before any of the
+.BR libnormalform_express (3),
+.BR libnormalform_dnf (3),
+and
+.BR libnormalform_cnf (3)
+functions are called.
+.PP
+See
+.BR libnormalform_express (3)
+for the purpose of
+.IR function->builtin ,
+the
+.BR libnormalform_transformation ()
+function always sets it to
+.IR LIBNORMALFORM_NOT_BUILT_IN .
+.PP
+.I function
+must not 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.
+.PP
+The
+.BR libnormalform_transformation ()
+function adopt the ownership of
+.IR sentence .
+Therefore, the user shall not attempt to
+deallocate
+.IR sentence .
+This holds even on failure: if the function
+fails,
+.I sentence
+is deallocated.
+.PP
+.I *function->transform
+may be called multiple types for the same
+input even if it is only specified in a sentence
+once, therefore calling it multiple times must
+not have undesirable side effects. The function
+shall return equivalent output given equivalent
+input. Additionally for any functions F, G,
+T(F # G) must be equivalent to T(F) # T(G) for
+any operator #, where T is
+.IR *function->transform .
+Transformations over constants and variables
+are removed as these do not take any input.
+Transformations over qualifiers are illegal.
+
+.SH RETURN VALUE
+Upon successful completion, the
+.BR libnormalform_transformation ()
+function returns an sentence object of
+the transformation; otherwise, the function
+returns
+.I NULL
+and sets
+.I errno
+to indicate the error.
+.PP
+The
+.BR libnormalform_transformation ()
+function also fails without setting
+.I errno
+if
+.I sentence
+is
+.IR NULL .
+
+.SH ERRORS
+The
+.BR libnormalform_transformation ()
+function fails if:
+.TP
+.I ENOMEM
+Insufficient memory was available to
+create the sentence object.
+.TP
+.I EDOM
+.I sentence
+contains a qualifier.
+
+.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_transformation ()
+T}	Thread safety	MT-Safe race:\fIsentence\fP
+T{
+.BR libnormalform_transformation ()
+T}	Async-signal safety	AS-Unsafe heap
+T{
+.BR libnormalform_transformation ()
+T}	Async-cancel safety	AC-Safe mem, AC-Unsafe heap
+.TE
+
+.SH NOTES
+Sentences created with the
+.BR libnormalform_empty (),
+.BR libnormalform_nonempty (),
+and
+.BR libnormalform_singleton ()
+functions count as qualifiers and
+cannot be used in a transformation.
+
+.SH SEE ALSO
+.BR libnormalform (7)