add WIP clarg subproject

clarg/.clang-format

@@ -0,0 +1 @@
+../common/share/clang-format

clarg/.gitattributes

@@ -0,0 +1 @@
+../common/share/gitattributes

clarg/.gitignore

@@ -0,0 +1 @@
+../common/share/gitignore

clarg/Makefile

@@ -0,0 +1,56 @@
+##############################################################################
+##                       neopolitan command line args                       ##
+##                                                                          ##
+##                      Copyright © 2019-2021 Aquefir.                      ##
+##                       Released under BSD-2-Clause.                       ##
+##############################################################################
+
+ifeq ($(strip $(AQ)),)
+$(error "AQ was not found in your environment. You need to install the Slick Makefiles from github.com/aquefir/slick to continue.")
+endif
+
+include $(AQ)/lib/slick/base.mk
+
+PROJECT := uni_clarg
+
+# put a ‘1’ for the desired target types to compile
+SOFILE :=
+AFILE  := 1
+
+# space-separated path list for #includes
+# <system> includes
+INCLUDES := include ../arr/include ../decl/include ../himem/include
+# "local" includes
+INCLUDEL := src
+
+# space-separated library name list
+LIBS    :=
+LIBDIRS :=
+
+# frameworks (macOS target only)
+FWORKS :=
+
+# ‘3P’ are in-tree 3rd-party dependencies
+# 3PLIBDIR is the base directory
+# 3PLIBS is the folder names in the base directory for each library
+3PLIBDIR := 3rdparty
+3PLIBS   :=
+
+# sources
+SFILES    :=
+CFILES    := \
+	src/clarg.c
+CPPFILES  :=
+PUBHFILES := \
+	include/uni/clarg.h
+PRVHFILES := \
+	src/clarg.h
+
+# test suite sources
+TES_CFILES    :=
+TES_CPPFILES  :=
+TES_PUBHFILES :=
+TES_PRVHFILES :=
+
+# this defines all our usual targets
+include $(AQ)/lib/slick/targets.mk

clarg/etc/BOILERPLATE

@@ -0,0 +1,19 @@
+This file contains the project’s copypastable boilerplate comment headers.
+
+Boilerplate for C-like languages:
+
+/****************************************************************************\
+ *                       neopolitan command line args                       *
+ *                                                                          *
+ *                      Copyright © 2019-2021 Aquefir.                      *
+ *                       Released under BSD-2-Clause.                       *
+\****************************************************************************/
+
+Hash-based boilerplate (Python, POSIX shell, Makefile):
+
+##############################################################################
+##                       neopolitan command line args                       ##
+##                                                                          ##
+##                      Copyright © 2019-2021 Aquefir.                      ##
+##                       Released under BSD-2-Clause.                       ##
+##############################################################################

clarg/etc/DEPENDS

@@ -0,0 +1,3 @@
+github.com/aquefir/neopolitan/arr
+github.com/aquefir/neopolitan/decl
+github.com/aquefir/neopolitan/himem

clarg/include/uni/clarg.h

@@ -0,0 +1,48 @@
+/****************************************************************************\
+ *                       neopolitan command line args                       *
+ *                                                                          *
+ *                      Copyright © 2019-2021 Aquefir.                      *
+ *                       Released under BSD-2-Clause.                       *
+\****************************************************************************/
+
+#ifndef INC_API__UNI_CLARG_H
+#define INC_API__UNI_CLARG_H
+
+#include <uni/types/int.h>
+#include <uni/types/mathprim.h>
+
+enum /* uni_clarg_tmpl_flags */
+{
+	UNI_CLARG_TMPL_FLAG_TAKESVAL,
+	UNI_CLARG_TMPL_FLAG_VALREQD
+};
+
+enum /* uni_clarg_tmpl_masks */
+{
+	UNI_CLARG_TMPL_MASK_TAKESVAL = 1 << UNI_CLARG_TMPL_FLAG_TAKESVAL,
+	UNI_CLARG_TMPL_MASK_VALREQD = 1 << UNI_CLARG_TMPL_FLAG_VALREQD
+};
+
+struct uni_clarg_tmpl;
+
+struct uni_clarg_out;
+
+struct uni_clarg_tmpl * uni_clarg_tmpl_init(
+	const char *, const char *, const char *, struct range, const char * );
+void uni_clarg_tmpl_fini( struct uni_clarg_tmpl * );
+
+void uni_clarg_tmpl_add(
+	struct uni_clarg_tmpl *, char, const char *, u32, const char * );
+
+struct uni_clarg_out * uni_clarg_tmpl_parse(
+	s32, char **, struct uni_clarg_tmpl * );
+
+const char * uni_clarg_out_readc( struct uni_clarg_out *, char );
+const char * uni_clarg_out_reads( struct uni_clarg_out *, const char * );
+int uni_clarg_out_checkc( struct uni_clarg_out *, char );
+int uni_clarg_out_checks( struct uni_clarg_out *, const char * );
+
+const char ** uni_clarg_out_getpargs( struct uni_clarg_out * );
+const char * uni_clarg_out_print( struct uni_clarg_out * );
+
+#endif /* INC_API__UNI_CLARG_H */

clarg/src/clarg.c

@@ -0,0 +1,6 @@
+/****************************************************************************\
+ *                       neopolitan command line args                       *
+ *                                                                          *
+ *                      Copyright © 2019-2021 Aquefir.                      *
+ *                       Released under BSD-2-Clause.                       *
+\****************************************************************************/

clarg/src/clarg.h

@@ -0,0 +1,43 @@
+/****************************************************************************\
+ *                       neopolitan command line args                       *
+ *                                                                          *
+ *                      Copyright © 2019-2021 Aquefir.                      *
+ *                       Released under BSD-2-Clause.                       *
+\****************************************************************************/
+
+#ifndef INC__UNI_CLARG_H
+#define INC__UNI_CLARG_H
+
+#include <uni/arr.h>
+#include <uni/types/mathprim.h>
+
+struct uni_clarg_tmpl
+{
+	/* these are all indexed together.
+	 * push ‘\0’ if no short name is given, NULL if no long name is given.
+	 */
+	struct uni_arr * snames;
+	struct uni_arr * lnames;
+	struct uni_arr * opts;
+	struct uni_arr * descs;
+	const char * title;
+	const char * briefdesc;
+	struct range copy_year;
+	const char * copy_name;
+	const char * usage;
+};
+
+struct uni_clarg_outarg
+{
+	/* index in the uni_clarg_tmpl struct */
+	u32 tmpl_i;
+	const char * val;
+};
+
+struct uni_clarg_out
+{
+	struct uni_arr * outargs;
+	const char ** pargs;
+};
+
+#endif /* INC__UNI_CLARG_H */

common/doc/clarg.sli

@@ -0,0 +1,47 @@
+uni/clarg/uni_clarg_tmpl_flags.enum
+	Argument template flags. Currently there are two flags: one to note that an
+	argument takes a value parameter, and another to note if a value parameter
+	is required. Whether or not a parameter is required is not evaluated by
+	this library.
+uni/clarg/uni_clarg_tmpl_masks.enum
+	Bitmasks for the uni_clarg_tmpl_flags enum. These are the constants to be
+	used usually in function calls to the library.
+uni/clarg/uni_clarg_tmpl.struct
+	Forward declaration of the command-line arg template. The user adds to this
+	with the provided functions all the options their program supports, then
+	finalises it into a uni_clarg_out struct.
+uni/clarg/uni_clarg_out.struct
+	Forward declaration of the command-line arg final structure. The user
+	provides argc, argv and an instance of a uni_clarg_tmpl struct, and the
+	argv is validated against the template and output values are stored.
+uni/clarg/uni_clarg_tmpl_init.sub
+	Initialise a uni_clarg_tmpl object.
+uni/clarg/uni_clarg_tmpl_init.sub:$1
+	The program title. Usually the same as its command invocation name.
+uni/clarg/uni_clarg_tmpl_init.sub:$1*
+	Must either be NULL or a valid pointer to a NUL-terminated UTF-8 char
+	array. If it is NULL, $2 is not used either.
+uni/clarg/uni_clarg_tmpl_init.sub:$2
+	Brief description of the program. Describe its purpose, ideally in less
+	than 72 characters.
+uni/clarg/uni_clarg_tmpl_init.sub:$2*
+	Must either be NULL or a valid pointer to a NUL-terminated UTF-8 char
+	array.
+uni/clarg/uni_clarg_tmpl_init.sub:$3
+	A less-than-brief description of the program. This is not the same as the
+	flags description, which is procedurally generated.
+uni/clarg/uni_clarg_tmpl_init.sub:$3*
+	Must either be NULL or a valid pointer to a NUL-terminated UTF-8 char
+	array.
+uni/clarg/uni_clarg_tmpl_init.sub:$4
+	A range of years in which publication copyright is claimed to apply.
+uni/clarg/uni_clarg_tmpl_init.sub:$5
+	A name under which publication copyright is claimed to apply.
+uni/clarg/uni_clarg_tmpl_init.sub:$5*
+	Must either be NULL or a valid pointer to a NUL-terminated UTF-8 char
+	array. If it is NULL, $4 is not used either.
+uni/clarg/uni_clarg_tmpl_init.sub:#
+	A newly-allocated uni_clarg_tmpl object.
+uni/clarg/uni_clarg_tmpl_fini.sub
+	Finalise and deallocate the memory of a uni_clarg_tmpl object.
+uni/clarg/uni_clarg_tmpl_fini.sub:$1