m + add libterminput_init and libterminput_destroy

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

10 files changed, 205 insertions, 5 deletions

diff --git a/Makefile b/Makefile
index 3bf532c..7ea07c4 100644
--- a/Makefile
+++ b/Makefile
@@ -23,7 +23,9 @@ MAN3 =\
 	libterminput_marshal_input.3\
 	libterminput_marshal_state.3\
 	libterminput_unmarshal_input.3\
-	libterminput_unmarshal_state.3
+	libterminput_unmarshal_state.3\
+	libterminput_init.3\
+	libterminput_destroy.3
 
 OBJ =\
 	$(MAN3:.3=.o)\
diff --git a/interactive-test.c b/interactive-test.c
index 687e391..00b5776 100644
--- a/interactive-test.c
+++ b/interactive-test.c
@@ -32,6 +32,10 @@ main(void)
 	struct sigaction sa;
 
 	memset(&ctx, 0, sizeof(ctx));
+	if (libterminput_init(&ctx, STDIN_FILENO)) {
+		perror("libterminput_init STDIN_FILENO");
+		return 1;
+	}
 
 	memset(&sa, 0, sizeof(sa)); /* importantly, SA_RESTART is cleared from sa.sa_flags */
 	sa.sa_handler = &sigint_handler;
@@ -243,5 +247,7 @@ again:
 	if (!(flags & O_NONBLOCK))
 		fcntl(STDIN_FILENO, F_SETFL, flags);
 	tcsetattr(STDERR_FILENO, TCSAFLUSH, &saved_stty);
+
+	libterminput_destroy(&ctx);
 	return -r && !interrupted;
 }
diff --git a/libterminput.7 b/libterminput.7
index d56a6d3..287b71b 100644
--- a/libterminput.7
+++ b/libterminput.7
@@ -10,6 +10,12 @@ does not use terminfo, but recognises common sequences.
 .PP
 libterminput provides the following functions:
 .TP
+.BR libterminput_init (3)
+Configure library for terminal quirks.
+.TP
+.BR libterminput_destroy (3)
+Deallocate library configuration resources.
+.TP
 .BR libterminput_read (3)
 Read and parse input from the terminal.
 .TP
@@ -21,8 +27,17 @@ Add input parsing flags.
 .TP
 .BR libterminput_clear_flags (3)
 Remove input parsing flags.
+.TP
+.BR libterminput_marshal_state "(3), " libterminput_marshal_input (3)
+Marshal library state.
+.TP
+.BR libterminput_unmarshal_state "(3), " libterminput_unmarshal_input (3)
+Unmarshal library state.
 
 .SH SEE ALSO
+.BR libterminput_init (3),
 .BR libterminput_is_ready (3),
+.BR libterminput_marshal_state (3),
 .BR libterminput_read (3),
-.BR libterminput_set_flags (3)
+.BR libterminput_set_flags (3),
+.BR libterminput_unmarshal_state (3)
diff --git a/libterminput.h b/libterminput.h
index ce82ad0..5cd634d 100644
--- a/libterminput.h
+++ b/libterminput.h
@@ -692,6 +692,46 @@ struct libterminput_unmarshaller {
 
 
 /**
+ * Initialises the parser
+ * 
+ * Calling this function is optional
+ * 
+ * Before calling this function, it is important to call
+ * `memset(ctx, 0, sizeof(*ctx))` so that `ctx` is properly
+ * marked as fully uninitialised (this is needed because
+ * the execution of the function is resumed by calling it
+ * again after EINTR or EAGAIN failure)
+ * 
+ * In the current version, this function doesn't do anything,
+ * however future versions (or other implementations) may
+ * read to and write from the terminal, read the process's
+ * environment variables, or read from the filesystem in
+ * order to detect the particular quirks of the terminal
+ * 
+ * @param   ctx  Parser state
+ * @param   fd   The file descriptor to the terminal
+ * @return       0 on success, -1 on failure
+ * 
+ * It is unspecified which errors will cause this function
+ * to fail, however it should avoid failing for any other
+ * reason than EINTR and EAGAIN
+ * 
+ * @since  1.1
+ */
+int libterminput_init(struct libterminput_state *ctx, int fd);
+
+/**
+ * Deallocate any resources allocated by `libterminput_init`
+ * 
+ * `ctx` is no longer usable after this function returns
+ * 
+ * @param  ctx  Parser state
+ * 
+ * @since  1.1
+ */
+void libterminput_destroy(struct libterminput_state *ctx);
+
+/**
  * Get input from the terminal
  * 
  * @param   fd     The file descriptor to the terminal
diff --git a/libterminput_destroy.3 b/libterminput_destroy.3
new file mode 120000
index 0000000..81850ed
--- /dev/null
+++ b/libterminput_destroy.3
@@ -0,0 +1 @@
+libterminput_init.3
\ No newline at end of file
diff --git a/libterminput_destroy.c b/libterminput_destroy.c
new file mode 100644
index 0000000..628032f
--- /dev/null
+++ b/libterminput_destroy.c
@@ -0,0 +1,9 @@
+/* See LICENSE file for copyright and license details. */
+#include "common.h"
+
+
+void
+libterminput_destroy(struct libterminput_state *ctx)
+{
+	(void) ctx;
+}
diff --git a/libterminput_init.3 b/libterminput_init.3
new file mode 100644
index 0000000..fa739a0
--- /dev/null
+++ b/libterminput_init.3
@@ -0,0 +1,110 @@
+.TH LIBTERMINPUT_INIT 3 LIBTERMINPUT
+.SH NAME
+libterminput_init \- Configure library for terminal quirks
+.br
+libterminput_destory \- Deallocate library configuration resources
+
+.SH SYNOPSIS
+.nf
+#include <libterminput.h>
+
+int libterminput_init(struct libterminput_state *\fIctx\fP, int \fIfd\fP);
+void libterminput_destroy(struct libterminput_state *\fIctx\fP);
+.fi
+.PP
+Link with
+.IR \-lterminput .
+
+.SH DESCRIPTION
+The current version of the
+.BR libterminput_init ()
+function doesn't do anything. However, future versions
+may communicate with the terminal, inspect the process's
+environment variables, and read the filesystem to determine
+the quirks of the terminal.
+.PP
+Before calling this,
+.I *ctx
+must be initialised by running
+.IR "memset(ctx, 0, sizeof(*ctx))" .
+.PP
+.I fd
+shall be a file descriptor to the terminal with both
+read and write access.
+.PP
+Calling the
+.BR libterminput_init ()
+function will always be optional. However, if the
+function has failed the function must be called again
+(until successful completion), or
+.I *ctx
+must be destroyed using
+.BR libterminput_destroy ()
+and reset with
+.BR memset (3).
+.PP
+The
+.BR libterminput_destroy ()
+function deallocates resources in
+.I *ctx
+allocated by the
+.BR libterminput_init ()
+function.
+
+.SH RETURN VALUE
+The
+.BR libterminput_init ()
+function returns 0 upon successful completion.
+On failure, it returns
+.B -1
+and sets
+.I errno
+to indicate the error.
+.PP
+The
+.BR libterminput_destroy ()
+function does not have a return value.
+
+.SH ERRORS
+The
+.BR libterminput_init ()
+function may fail for any reason, although it should
+avoid failing for any reason other than:
+.TP
+.B EINTR
+Default.
+.TP
+.B AGAIN
+Default.
+.PP
+The
+.BR libterminput_destroy ()
+function cannot fail.
+
+.SH EXAMPLES
+None.
+
+.SH APPLICATION USAGE
+None.
+
+.SH RATIONALE
+None.
+
+.SH FUTURE DIRECTIONS
+None.
+
+.SH HISTORY
+The
+.BR libterminput_init ()
+and
+.BR libterminput_destroy ()
+functions were added in version 1.1 of libterminput.
+
+.SH NOTES
+None.
+
+.SH BUGS
+None.
+
+.SH SEE ALSO
+.BR libterminput_read (3)
diff --git a/libterminput_init.c b/libterminput_init.c
new file mode 100644
index 0000000..0e65d40
--- /dev/null
+++ b/libterminput_init.c
@@ -0,0 +1,14 @@
+/* See LICENSE file for copyright and license details. */
+#include "common.h"
+
+
+#if defined(__GNUC__)
+__attribute__((__const__))
+#endif
+int
+libterminput_init(struct libterminput_state *ctx, int fd)
+{
+	(void) ctx;
+	(void) fd;
+	return -1;
+}
diff --git a/libterminput_read.3 b/libterminput_read.3
index 742c95a..7a30072 100644
--- a/libterminput_read.3
+++ b/libterminput_read.3
@@ -158,7 +158,9 @@ returns the result in the
 .I ctx
 must have been zero-initialised, e.g. with
 .BR memset (3)
-function.
+function, and optionally with
+.BR libterminput_init (3)
+afterwards.
 .PP
 .I input
 shall be the same pointer every time the
@@ -439,7 +441,7 @@ function returns
 .B -1
 and set
 .I errno
-it indicate the error.
+to indicate the error.
 
 .SH ERRORS
 The
@@ -467,6 +469,7 @@ None.
 None.
 
 .SH SEE ALSO
+.BR libterminput_init (3),
 .BR libterminput_is_ready (3),
 .BR libterminput_set_flags (3),
 .BR libterminput_marshal_state (3)
diff --git a/libterminput_set_flags.3 b/libterminput_set_flags.3
index 30301bc..fd1df68 100644
--- a/libterminput_set_flags.3
+++ b/libterminput_set_flags.3
@@ -117,7 +117,7 @@ functions return
 .B -1
 and set
 .I errno
-it indicate the error.
+to indicate the error.
 
 .SH ERRORS
 Current versions of the