libk  Check-in [c0e04b9015]

if test "$1" = "-C"; then
	say "precleaning repo"
	./clean.sh
fi

# TODO: make it possible for user to change
#       default set with environment vars
modules=(kcore kmem kstr kio kgraft kfile)

# compose an arch tuple. this is used in
# places, mostly to select the correct
# version of assembly files for a given
# platform (each has an arch tuple in its
# name, following the linkage specifier)
target=$arch.$os

if test "$1" = "-C"; then
	say "precleaning repo"
	./clean.sh
fi

# TODO: make it possible for user to change
#       default set with environment vars
modules=(kcore kmem kstr kio kgraft kfile kcli)

# compose an arch tuple. this is used in
# places, mostly to select the correct
# version of assembly files for a given
# platform (each has an arch tuple in its
# name, following the linkage specifier)
target=$arch.$os

	descline=$(echo "$dhead" | cut -d: -f1)
	offset=1
else
	descline=$(grep -m2 -n "^#" "$file" | tail -n1 | cut -d: -f1)
	offset=0
fi

tail -n+2 $file | head -n$(expr $descline - 2) | cmark -t man >>"$fmt"

echo >>"$fmt" ".SH DESCRIPTION"

tail -n+$(expr $descline + $offset) "$file"  | cmark -t man >> "$fmt"

test "$doc_html" = "yes" && {
	mkdir -p "$htmldest"
	groff -Thtml -Kutf8 -m man "$fmt" > "$html"
	test "$verbose" != "loud" ||
	say "wrote html page for $stem to $html"
}

	descline=$(echo "$dhead" | cut -d: -f1)
	offset=1
else
	descline=$(grep -m2 -n "^#" "$file" | tail -n1 | cut -d: -f1)
	offset=0
fi

tail -n+2 $file | head -n$(expr $descline - 2) | cmark --smart -t man >>"$fmt"

echo >>"$fmt" ".SH DESCRIPTION"

tail -n+$(expr $descline + $offset) "$file"  | cmark --smart --normalize -t man >> "$fmt"

test "$doc_html" = "yes" && {
	mkdir -p "$htmldest"
	groff -Thtml -Kutf8 -m man "$fmt" > "$html"
	test "$verbose" != "loud" ||
	say "wrote html page for $stem to $html"
}

#ifndef KIcli
#define KIcli

#include <k/core.h>
#include <k/io.h>
#include <k/type.h>
#include <k/internal.egroup.h>

/* input types */

typedef struct kcli_opt {
	codepoint id;
	const char* name;
	enum kcli_opt_kind {
		kcli_opt_none /* flag is disabled and hidden */,
		kcli_opt_string /* flag takes a string argument */,
		kcli_opt_flag /* on if present, off if absent */,
		kcli_opt_toggle /* off by default, value toggles
		                 * for each occurrence */,
		kcli_opt_accumulate /* u8, value increases for each
		                     * occurrence, saturates at 255 */,
		kcli_opt_enum /* matched against a table of string
		               * values to retrieve the corresponding
					   * integer ID */,

		kcli_opt_int = 0x40,
		/* kcli_opt_int takes a default base parameter.
		 * for instance, to take a decimal number, you
		 * might write `kcli_opt_int | 10.` if the
		 * argument takes a base prefix, the default
		 * base will be disregarded. */
			kcli_opt_oct = kcli_opt_int | 8,
			kcli_opt_dec = kcli_opt_int | 10,
			kcli_opt_hex = kcli_opt_int | 16,
	} kind;
	void* val;
	const char* desc;
} kcli_opt;

typedef struct kcli_param {
	const char* name;
	enum kcli_param_kind {
		kcli_param_none,
		kcli_param_string,
		kcli_param_enum,
		kcli_param_int = 0x40,
			kcli_param_oct = kcli_param_int | 8,
			kcli_param_dec = kcli_param_int | 10,
			kcli_param_hex = kcli_param_int | 16,
	} kind;
	enum kcli_rule {
		kcli_rule_forbidden,
		kcli_rule_optional,
		kcli_rule_required,
	} rule;
} kcli_param;

typedef struct kcli_set {
	const char*       name;
	const char*       version;
	const char**      args;   sz argc;
	const char*       desc;
	const kcli_param* params; sz paramc;
	const kcli_opt*   opts;   sz optc;
} kcli_set;

/* output types */

typedef enum kcli_cond {
	kcli_cond_ok = kcli_cond_id,
	kcli_cond_extra /* parse succeded, but arguments or
	                   flags were left over */,
	kcli_cond_fail /* unspecified error */,
	kcli_cond_parse /* bad syntax, parse failed */,
} kcli_cond;

typedef enum kcli_flag {
	kcli_flag_off = 0,
	kcli_flag_on = 1,
} kcli_flag;

/* functions */

kcond kcli_usage(kcli_set, kiochan);
kcli_cond kcli_parse(kcli_set);

/* macros */

#define Kcli_param(field,kind,rule,description) \
	{#field, kcli_param_##kind, kcli_rule_##rule, &field, description}
#define Kcli_opt(long,short,kind,description) \
	{short, #long, kcli_opt_##kind, &long, description}

#endif

## kcli_usage(kcli_set, kiochan)
kcli_usage() takes a `kcli_set` and prints a succinct usage summary to a [kiochan](../kio/kio.md).

# types

## struct kcli_set
`kcli_set` is a struct containing information about your program, such as its name, a synopsis of its function, a pointer to `argv`, and a list of `kcli_opt`s.

 * `const char* name` - program name (if null, will be determined from argv instead)


 * `size_t argc` - the number of arguments in the `argv` array.
 * `const char** argv` - the `argv` pointer passed to the `entry` function, representing the command-line arguments passed to the program.
 * `const char* desc` - program description
 * `const kcli_param* params` - a list of options expected by the program.
 * `size_t paramc` - the number of params in the list to process.
 * `const kcli_opt* opts` - a list of options expected by the program.
 * `size_t optc` - the number of options in the list to process.

a kcli_set might be used like so:
................................................................................
    stat entry(kenv e) {
    	kcli_flag aardvark;
    	kcli_flag zebra;
    	char* user;
    	char* password;
		long age;
		kcli_param params[] = {
    		{ "user", kcli_param_string, kcli_class_required,
    		  &user, "the user to log in as" }
			  // or Kcli_param(user,string,required,"the user to log in as"),

			{ "age", kcli_param_dec, kcli_class_optional,
    		  &age, "the age of the user" }
			  // or Kcli_param(age,dec,optional,"the age of the user"),
		};
    	kcli_opt options[] = {
    		{ 'a', "aardvark", kcli_opt_flag, &aardvark,
    		  "a nocturnal burrowing mammal" },
			  // or Kcli_opt(aardvark, 'a', flag, "a nocturnal burrowing mammal")
    		{ 'z', "zebra", kcli_opt_flag, &zebra,
    		  "a striped equine" },
    		{ 'p', "password", kcli_opt_string, &password,
    		  "the password to log in with" }
    	};
    	kcli_set argset = {
    		"demo", e.argc, e.argv,
    		"a demonstration of the kcli_set type",
			params, Kmsz(params),
			options, Kmsz(options)
    	},
		size_t args_parsed = kcli_parse(&argset);
		if (args_parsed == 0) { kcli_usage(&me, e.err); return 1; }

		return 0;
	}

### struct kcli_opt
a `kcli_opt` is a representation of a command-line flag and its function. each option must have a unique `id` and/or a unique `name`.

 * `char id` - the short single-character form of the flag (or NUL for no short form)
 * `const char* name` - the long string form of the flag (or NULL for no long form)
 * `kcli_opt_kind kind` - enum that describes how the flag will function
 * `void* val` - a pointer to an appropriate type to store the return value in.
 * `const char* desc` - a description of the flag's purpose and function (or NULL for no description)

#### enum kcli_opt_kind

 * `kcli_opt_none` - flag is disabled and will not be shown in usage
 * `kcli_opt_string` - flag tells kcli to add a string to the list of expected parameters; appropriate string will be returned

 * `kcli_opt_oct` - flag tells kcli to add an octal number to the list of expected parameters
 * `kcli_opt_dec` - flag tells kcli to add a decimal number to the list of expected parameters
 * `kcli_opt_hex` - flag tells kcli to add a hexdecimal number to the list of expected parameters
 * `kcli_opt_flag` - flag is an option: will return `kcli_flag_on` if entered at least once, `kcli_flag_off` otherwise.
 * `kcli_opt_toggle` - flag toggles value on and off: will return `kcli_flag_on` if entered an odd number of times, `kcli_flag_off` otherwise.
 * `kcli_opt_accumulate` - flag increments a value every time it is entered; often used to implement `-v (--verbose)`-style options (e.g. `-vvvv` would return a value of `4`).
 * `kcli_opt_enum` - flag is one of a series of enumerated values, which will be matched against a table to yield the associated integer.

### struct kcli_param
`kcli_param` describes a parameter that may be passed to the program whether or not any flags are passed.

 * `const char* name` - a short name for the parameter
 * `kcli_param_kind kind` - the kind of parameter passed
 * `kcli_class class` - whether or not the parameter is optional
 * `void* val` - a pointer to an appropriate type of variable to fill
 * `const char* desc` - a description of the parameter's function

#### enum kcli_param_kind
 * `kcli_param_none` - parameter is disabled and will not be expected or accepted
 * `kcli_param_string` - parameter will not be parsed; a raw string will be returned


 * `kcli_param_oct` - parameter will be parsed as an octal number
 * `kcli_param_dec` - parameter will be parsed as a decimal number
 * `kcli_param_hex` - parameter will be parsed as a hexadecimal number

### enum kcli_class
 * `kcli_class_forbidden` - parameter may not be passed
 * `kcli_class_optional` - parameter may or may not be passed
 * `kcli_class_required` - parameter must be passed

### enum kcli_flag
results that an option of kind `kcli_opt_flag` can return.

 * `kcli_flag_off = 0` - flag is off
 * `kcli_flag_on = 1` - flag is on
 
## macros

### Kcli_param(field, kind, class, description)
a convenience macro for filling out parameter lists.

`Kcli_param(field,a,b,"description")` is transformed into:

    { "field", kcli_param_a, kcli_class_b, &field, "description" }

### Kcli_opt(field, kind, class, description)
a convenience macro for filling out option lists.

`Kcli_opt(name,'n',string,"description")` is transformed into:

    { 'n', "name", kcli_opt_string, &name, "description" }

## kcli_usage(kcli_set, kiochan)
kcli_usage() takes a `kcli_set` and prints a succinct usage summary to a [kiochan](../kio/kio.md).

# types

## struct kcli_set
`kcli_set` is a struct containing information about your program, such as its name, a synopsis of its function, a pointer to an array of arguments, and a list of `kcli_opt`s.

 * `const char* name` - program name (if null, will be determined from argv instead)
 * `const char* version` - a string describing the program version (if null, version will not be printed)
 * `const char** args` - the `argv` pointer passed to the `entry` function, representing the command-line arguments passed to the program.
 * `size_t argc` - the number of arguments in the `argv` array.

 * `const char* desc` - program description
 * `const kcli_param* params` - a list of options expected by the program.
 * `size_t paramc` - the number of params in the list to process.
 * `const kcli_opt* opts` - a list of options expected by the program.
 * `size_t optc` - the number of options in the list to process.

a kcli_set might be used like so:
................................................................................
    stat entry(kenv e) {
    	kcli_flag aardvark;
    	kcli_flag zebra;
    	char* user;
    	char* password;
		long age;
		kcli_param params[] = {
    		{ "user", kcli_param_string, kcli_rule_required,
    		  &user, "the user to log in as" }
			  // or Kcli_param(user,string,required,"the user to log in as"),

			{ "age", kcli_param_dec, kcli_rule_optional,
    		  &age, "the age of the user" }
			  // or Kcli_param(age,dec,optional,"the age of the user"),
		};
    	kcli_opt options[] = {
    		{ 'a', "aardvark", kcli_opt_flag, &aardvark,
    		  "a nocturnal burrowing mammal" },
			  // or Kcli_opt(aardvark, 'a', flag, "a nocturnal burrowing mammal")
    		{ 'z', "zebra", kcli_opt_flag, &zebra,
    		  "a striped equine" },
    		{ 'p', "password", kcli_opt_string, &password,
    		  "the password to log in with" }
    	};
    	kcli_set argset = {
    		"demo", e.args, e.argc,
    		"a demonstration of the kcli_set type",
			params, Kmsz(params),
			options, Kmsz(options)
    	},
		size_t args_parsed = kcli_parse(argset);
		if (args_parsed == 0) { kcli_usage(me, e.err); return 1; }

		return 0;
	}

## struct kcli_opt
a `kcli_opt` is a representation of a command-line flag and its function. each option must have a unique `id` and/or a unique `name`.

 * `char id` - the short single-character form of the flag (or NUL for no short form)
 * `const char* name` - the long string form of the flag (or NULL for no long form)
 * `kcli_opt_kind kind` - enum that describes how the flag will function
 * `void* val` - a pointer to an appropriate type to store the return value in.
 * `const char* desc` - a description of the flag's purpose and function (or NULL for no description)

## enum kcli_opt_kind

 * `kcli_opt_none` - flag is disabled and will not be shown in usage
 * `kcli_opt_string` - flag tells kcli to add a string to the list of expected parameters; appropriate string will be returned
 * `kcli_opt_int` - flag tells kcli to add an integer to the last of expected parameters; must be bitwise-OR'd with default base
 * `kcli_opt_oct` - flag tells kcli to add an octal number to the list of expected parameters
 * `kcli_opt_dec` - flag tells kcli to add a decimal number to the list of expected parameters
 * `kcli_opt_hex` - flag tells kcli to add a hexdecimal number to the list of expected parameters
 * `kcli_opt_flag` - flag is an option: will return `kcli_flag_on` if entered at least once, `kcli_flag_off` otherwise.
 * `kcli_opt_toggle` - flag toggles value on and off: will return `kcli_flag_on` if entered an odd number of times, `kcli_flag_off` otherwise.
 * `kcli_opt_accumulate` - flag increments a value every time it is entered; often used to implement `-v (--verbose)`-style options (e.g. `-vvvv` would return a value of `4`).
 * `kcli_opt_enum` - flag is one of a series of enumerated values, which will be matched against a table to yield the associated integer.

## struct kcli_param
`kcli_param` describes a parameter that may be passed to the program whether or not any flags are passed.

 * `const char* name` - a short name for the parameter
 * `kcli_param_kind kind` - the kind of parameter passed
 * `kcli_rule rule` - whether or not the parameter is optional
 * `void* val` - a pointer to an appropriate type of variable to fill
 * `const char* desc` - a description of the parameter's function

### enum kcli_param_kind
 * `kcli_param_none` - parameter is disabled and will not be expected or accepted
 * `kcli_param_string` - parameter will not be parsed; a raw string will be returned
 * `kcli_param_enum` - parameter will be matched against an enumeration table
 * `kcli_param_int` - parameter will be parsed as an integer; must be bitwise-OR'd with default base
 * `kcli_param_oct` - parameter will be parsed as an octal number
 * `kcli_param_dec` - parameter will be parsed as a decimal number
 * `kcli_param_hex` - parameter will be parsed as a hexadecimal number

## enum kcli_rule
 * `kcli_rule_forbidden` - parameter may not be passed
 * `kcli_rule_optional` - parameter may or may not be passed
 * `kcli_rule_required` - parameter must be passed

## enum kcli_flag
results that an option of kind `kcli_opt_flag` can return.

 * `kcli_flag_off = 0` - flag is off
 * `kcli_flag_on = 1` - flag is on
 
# macros

## Kcli_param(field, kind, class, description)
a convenience macro for filling out parameter lists.

`Kcli_param(field,a,b,"description")` is transformed into:

    { "field", kcli_param_a, kcli_rule_b, &field, "description" }

## Kcli_opt(field, kind, class, description)
a convenience macro for filling out option lists.

`Kcli_opt(name,'n',string,"description")` is transformed into:

    { 'n', "name", kcli_opt_string, &name, "description" }

#include <k/cli.h>

kcli_cond
kcli_parse(kcli_set prg) {

}

#include <k/core.h>
#include <k/cli.h>

stat
entry (kenv e) {
	kcli_set testbin = {
		"testbin", "1.0.0", e.args, e.argc,
		"this is a test of the kcli module",
	};

	kcli_usage(testbin, e.err);

	return 0;
}

#include <k/cli.h>
#include <k/io.h>
#include <k/str.h>

typedef struct buffer {
	char* cur;
	kiochan channel;
	sz run;
	char buf [];
} buffer;

static buffer*
buffer_new(void* mem, kiochan channel, sz run) {
	buffer* r = mem;
	r -> cur = r -> buf;
	r -> channel = channel;
	r -> run = run;
	return r;
}

static kiocond
buffer_flush(buffer* b) {
	ksraw str = {b -> cur - b -> buf, b -> buf};
	b -> cur = b -> buf;
	return kiosend(b -> channel, str, null);
}

static kcond
buffer_send(buffer* b, const char* str) {
	ksmut buf = { b->run - (b->cur - b->buf), b->cur };
	ksraw src = { 0, str };
	kscond sc = kscp(src, buf, &src.size);
	if (sc != kscond_ok) return sc;

	b->cur += src.size;
	if (b->cur >= (b->buf + b->run)) {
		return buffer_flush(b);
	} else return kiocond_ok;
}

kcond
kcli_usage(kcli_set prg, kiochan ch) {
	ubyte buf_space [sizeof(buffer) + 256];
	buffer* out = buffer_new(buf_space, ch, 256);

	const char* msg [] = {
		prg.name, " v", prg.version, "\n\n",
		prg.desc, "\n\n",
	};
	for (sz i = 0; i != sizeof msg / sizeof msg[0]; ++ i) {
		kcond c = buffer_send(out, msg[i]);
		if (!kokay(c)) return c;
	}
	
	return buffer_flush(out);
}

#include <k/core.h>
#include <k/type.h>
extern stat entry(kenv);

unsigned long long
_boot(unsigned int argc, /* argument count */
		char** argv, /* arguments */
		char** envp /* environment */ ) {

	envp ++; /* envp seems to point at a leading null;
				this is probably a sign of breakage but
				i don't know what else to do about it for
				the moment. */

................................................................................

	kenv e = { 
		/* TODO: determine terminal class and set term vs ansi correctly! */
		{ {kiostream_term, 0}, {kiostream_term, 1} }, // chan std
		{ {kiostream_closed},  {kiostream_term, 2} }, // chan err
		argc, argv, ep - envp, variables
	};

	return entry(e);
}

#include <k/core.h>
#include <k/type.h>
extern stat entry(kenv);

unsigned long long
_boot(unsigned int argc, /* argument count */
		const char** argv, /* arguments */
		char** envp /* environment */ ) {

	envp ++; /* envp seems to point at a leading null;
				this is probably a sign of breakage but
				i don't know what else to do about it for
				the moment. */

................................................................................

	kenv e = { 
		/* TODO: determine terminal class and set term vs ansi correctly! */
		{ {kiostream_term, 0}, {kiostream_term, 1} }, // chan std
		{ {kiostream_closed},  {kiostream_term, 2} }, // chan err
		argc, argv, ep - envp, variables
	};

	return entry(e);
}

	ksraw val;
	char* platform;
} kvar;

typedef struct kenv {
	kiochan std;
	kiochan err;
	sz argc; char** args;
	sz varc; kvar* vars;
} kenv;

/* i'm really sorry okay */
typedef
#if (__STDC_VERSION__ >= 199901L)
	_Bool bool;

	ksraw val;
	char* platform;
} kvar;

typedef struct kenv {
	kiochan std;
	kiochan err;
	sz argc; const char** args;
	sz varc; kvar* vars;
} kenv;

/* i'm really sorry okay */
typedef
#if (__STDC_VERSION__ >= 199901L)
	_Bool bool;

”)dnl

// exit status integer types - pls use kbad in <k/magic.h> instead
ifelse(target_posix,“yes”,“
	/* by convention, posix return values are 8-bit,
	 * but note that many modern UNIXes do technically
	 * support higher-bit values. for this reason,
	 * longstat is defined differently under posix. */
	typedef u8 stat;
	typedef u32 stat_long;
”,“dnl
	ifelse(atom_target_os,“win”,“
		typedef u32 stat;
	”,“dnl
	ifelse(atom_target_os,“vms”,“
................................................................................
		/* we don't know a specific exit status type
		 * for your arch so we're going with a sane
		 * default. if this is wrong, help us fix it! */
	”)”)dnl
	typedef stat stat_long;
”)dnl








#endif

”)dnl

// exit status integer types - pls use kbad in <k/magic.h> instead
ifelse(target_posix,“yes”,“
	/* by convention, posix return values are 8-bit,
	 * but note that many modern UNIXes do technically
	 * support higher-bit values. for this reason,
	 * stat_long is defined differently under posix. */
	typedef u8 stat;
	typedef u32 stat_long;
”,“dnl
	ifelse(atom_target_os,“win”,“
		typedef u32 stat;
	”,“dnl
	ifelse(atom_target_os,“vms”,“
................................................................................
		/* we don't know a specific exit status type
		 * for your arch so we're going with a sane
		 * default. if this is wrong, help us fix it! */
	”)”)dnl
	typedef stat stat_long;
”)dnl

/* unicode types */

typedef u32 codepoint;
	/* a codepoint is a UTF-32 character */
typedef u8 rune [5];
	/* a rune is a valid UTF-8 character terminated with a nul. */

#endif

	kiocond_fail_over_quota,
	kiocond_fail_pfault,
	kiocond_fail_too_big,
	kiocond_fail_stream_mismatch,
} kiocond;

kiocond kiosend(kiochan, ksraw, sz*); // send data to a channel

kiocond kiorecv(kiochan, ksraw*); // receive data from a channel
kmptr kiorecvall(kiochan, kmcell*, kmkind); // automatically allocate a bufer for a channel
  // kmkind is only used if kmcell* is null
kiocond kiocon(kiochan, kiochan); // connect one channel to another

#ifdef __cplusplus
}
#endif

#endif

	kiocond_fail_over_quota,
	kiocond_fail_pfault,
	kiocond_fail_too_big,
	kiocond_fail_stream_mismatch,
} kiocond;

kiocond kiosend(kiochan, ksraw, sz*); // send data to a channel
kiocond kiosendall(kiochan, ksraw); // keep sending data to a channel until it's all sent
kiocond kiorecv(kiochan, ksraw*); // receive data from a channel
kmptr kiorecvall(kiochan, kmcell*, kmkind); // automatically allocate a bufer for a channel
  // kmkind is only used if kmcell* is null
kiocond kiocon(kiochan, kiochan); // connect one channel to another

#ifdef __cplusplus
}
#endif

#endif

#include <k/core.h>
#include <k/str.h>

kscond kscp(ksraw str, ksmut dest, sz* len) {
	if (str.size == 0) { /* calculate length on the fly */
		for(; str.ptr[str.size] != 0; ++ str.size) {
			if (str.size >= dest.size) return kscond_no_room;

			dest.ptr[str.size] = str.ptr[str.size];
		}
	} else {
		if (dest.size < str.size) return kscond_no_room;

		if (dest.ptr == null || str.ptr == null) return kscond_null;

		for(sz idx = 0; idx < str.size; ++ idx) {
			dest.ptr[idx] = str.ptr[idx];
		}
	}

	/* did we copy a nul? */
	if (str.ptr[str.size - 1] != 0)
		/* we didn't, can we? */
		if (dest.size > str.size)
			/* set a final nul */
			dest.ptr[str.size] = 0;

	if (len != null) *len = str.size;
	return kscond_ok;
}

#include <k/internal.egroup.h>
typedef enum kscond {
	kscond_ok = kscond_id,
	kscond_fail,
	kscond_unimplemented,
	kscond_nonnumeric,


} kscond;

enum ksconv {
	ksconv_default = 0,

	ksconv_raw = 1,
	ksconv_bin = 2,
................................................................................
kscond ks_to_int(ksraw str,
		enum ksconv mode,
		u8* dest, sz size);

kscond ks_of_int(u8* number, sz size,
		enum ksconv mode,
		char* bufstart, sz bufsize);



#ifdef __cplusplus
}
#endif

#endif

#include <k/internal.egroup.h>
typedef enum kscond {
	kscond_ok = kscond_id,
	kscond_fail,
	kscond_unimplemented,
	kscond_nonnumeric,
	kscond_no_room,
	kscond_null,
} kscond;

enum ksconv {
	ksconv_default = 0,

	ksconv_raw = 1,
	ksconv_bin = 2,
................................................................................
kscond ks_to_int(ksraw str,
		enum ksconv mode,
		u8* dest, sz size);

kscond ks_of_int(u8* number, sz size,
		enum ksconv mode,
		char* bufstart, sz bufsize);

kscond kscp(ksraw str, ksmut dest, sz* len);

#ifdef __cplusplus
}
#endif

#endif