libk  Check-in [927371b674]

#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_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;
................................................................................

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;

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

/* input types */

typedef struct kcli_opt {
	rune 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_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_required,
		kcli_rule_optional,
		kcli_rule_overflow,
	} rule;
	void* val;
	const char* desc;
} kcli_param;

typedef struct kcli_set {
	const char*       name;
	const char*       version;
	const char**      args;   sz argc;
	const char*       desc;
................................................................................

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_overlong /* a string in the configuration structures is longer than allowed */,
} kcli_cond;

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

		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

		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`.

 * `rune id` - the short single-character form of the flag as a UTF-8 codepoint (or initial 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

#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",


	};

	kcond c = kcli_usage(testbin, e.err);

	return c;
}

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

stat
entry (kenv e) {
	kcli_flag verbose = false,
	          debug = false;
	
	kcli_opt options[] = {
		{ "v", "verbose", kcli_opt_flag, &verbose,
		  "induce information overload" },
		{ "d", "debug-mode", kcli_opt_flag, &debug,
		  "run the program in debug mode"},
	};

	const char* perp, * place, * weapon;

	kcli_param params[] = {
		{"perp", kcli_param_string, kcli_rule_required, &perp,
		 "the one who did the dastardly deed"},
		{"place", kcli_param_string, kcli_rule_required, &place,
		 "where the crime was committed"},
		{"murder weapon", kcli_param_string, kcli_rule_optional, &weapon,
		 "the implement used to murder the victim"},
	};

	kcli_set testbin = {
		"testbin", "1.0.0", e.args, e.argc,
		"this is a test of the kcli module",
		params, Kmsz(params),
		options, Kmsz(options),
	};

	kcond c = kcli_usage(testbin, e.err);

	return c;
}

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









kcond
kcli_usage(kcli_set prg, kiochan ch) {



	ubyte buf_space [sizeof(ksbuf) + 256];
	ksbuf* out = ksbufmk(buf_space, ch, 256);




	const char* msg [] = {
		prg.name, " v", prg.version, "\n\n",
		prg.desc, "\n\n",


	};





	for (sz i = 0; i != Kmsz(msg); ++ i) {
		ksraw str = { 0, msg[i] };







		kcond c = ksbufput(out, str);
	}
	
















































	return ksbufflush(out);
}

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

extern char* _k_internal_binary_name;

static const struct { const char* front, * back; } param_styles [] = {
	[kcli_rule_required] = { "<",">" },
	[kcli_rule_optional] = { "[","]" },
	[kcli_rule_overflow] = { "","..." },
};

kcond
kcli_usage(kcli_set prg, kiochan ch) {
	enum { max_name_len = 32 };

	kcond c;
	ubyte buf_space [sizeof(ksbuf) + 256];
	ksbuf* out = ksbufmk(buf_space, ch, 256);

	const char* name = prg.name != null ?
		prg.name : _k_internal_binary_name;

	const char* msg [] = {
		name, " v", prg.version, "\n\n",
		prg.desc, "\n\n",
		"usage: ", _k_internal_binary_name,
		prg.optc == 0 ? null : " [-",
	};

	if (!kokay(c = ksbufwrite(out, msg))) return c;

	u8 longest_opt = 0;
	u8 opt_lens [prg.optc];
	for (sz i = 0; i != prg.optc; ++ i) {

		if (prg.opts[i].id[0] == 0) continue;

		opt_lens[i] = kssz(prg.opts[i].name, max_name_len);
		if (opt_lens[i] > longest_opt)
			longest_opt = opt_lens[i];

		ksraw str = { kssz(prg.opts[i].id, 4), prg.opts[i].id };
		if (!kokay(c = ksbufput(out, str))) return c;
	}

	if (!kokay(c = ksbufput(out, Ksraw("]")))) return c;
	
	u8 longest_param = 0;
	u8 param_lens [prg.paramc];
	for (sz i = 0; i != prg.paramc; ++ i) {
		enum kcli_rule r = prg.params[i].rule;

		param_lens[i] = kssz(prg.params[i].name, max_name_len);
		if (param_lens[i] > longest_param)
			longest_param = param_lens[i];

		const char* param[] = {
			" ", param_styles[r].front, prg.params[i].name,
			param_styles[r].back, null
		};

		if (!kokay(c = ksbufwrite(out,param))) return c;
	}

	if (!kokay(c = ksbufput(out, Ksraw("\n")))) return c;

	const char spacing [] = "                                ";
	Kassert(sizeof spacing - 1 == max_name_len,
			"spacing string not equal in length to max_name_len");
	/* yes, yes, i know */

	for (sz i = 0; i != prg.paramc; ++ i) {
		u8 pad = (longest_param - param_lens[i]) + 1;
		const char* tpl [] = {
			"\n    ", spacing + (sizeof spacing - pad),
			prg.params[i].name, ": ", prg.params[i].desc, null
		};

		if (!kokay(c = ksbufwrite(out, tpl))) return c;
	}

	if (!kokay(c = ksbufput(out, (ksraw){1, "\n"}))) return c;

	for (sz i = 0; i != prg.optc; ++ i) {
		u8 pad = (longest_opt - opt_lens[i]) + 1;
		const char* tpl [] = {
			"\n    -", prg.opts[i].id, ", --", prg.opts[i].name,
			spacing + (sizeof spacing - pad), ": ", prg.opts[i].desc, null
		};

		if (!kokay(c = ksbufwrite(out, tpl))) return c;
	}

	return ksbufflush(out);
}

#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. */

	char** ep;

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

const char* _k_internal_binary_name;

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

	_k_internal_binary_name = argv[0];

	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. */

	char** ep;

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

kcond
ksbufwrite(ksbuf* out, const char** array) {
	for (sz i=0; array[i] != null; ++ i) {
		ksraw str = { 0, array[i] };
		kcond c = ksbufput(out, str);
		if (!kokay(c)) return c;
	}

	return kscond_ok;
}

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

kcond
ksemitc(const char** array, sz bufsz, kiochan channel) {
	ubyte cache [sizeof(ksbuf) + bufsz];
	ksbuf* out = ksbufmk(cache, channel, bufsz);

	kcond c = ksbufwrite(out, array);
	if (!kokay(c)) return c;

	return ksbufflush(out);
}

## ksbufmk
`ksbuf* ksbufmk(void* where, kiochan channel, sz run)` initializes a new buffer at the specified address. `run` should be equivalent to the full length of the memory region minus `sizeof(struct ksbuf)` - in other words, the size of the string the `ksbuf` can hold. memory should be allocated by the user, either by creating an array on the stack or with `kmem` allocation functions. `ksbufmk()` returns a pointer to the new structure. the return value will always point to the same point in memory as `where`, but will be of the appropriate type to pass to buffer functions.

## ksbufput
`kcond ksbufput(ksbuf* b, ksraw str)` copies a string into a buffer with `kscp`. flushing it as necessary.

# ksbufflush
`kcond ksbufflush(ksbuf* b)` flushes a buffer to its assigned channel, emptying it and readying it for another write cycle. a buffer should almost always be flushed before it goes out of scope or is deallocated.

## kscomp
`char* kscomp(size_t ct, ksraw struct[], kmbuf* buf)` is a **string composition** function. it serves as an efficient, generalized replacement for functions like `strcat` and `strdup`.

to use kscomp, create an array of `kstr` and fill it with the strings you wish to concatenate. for example, to programmatically generate an HTML link tag, you might use the following code.

................................................................................
			ksref(text),
		Kstr("</a>")
	};
	char* html = kscomp(Kmsz(chain), chain, &buf);

kscomp will only calculate the length of individual strings if they are not already known. when it needs to calculate the length of a string, it will store that length in the original array so repeated calls can be made without needing to repeatedly calculate the lengths. this is not always desirable, so the variant `kscompc` exists, which is exactly the same as `kscomp` in every respect except that `chain` is not altered in any way.







## macros
if `KFclean` is not set when <k/str.h> is included, the following macros are defined.

 * `Kstr(string)` - the compile-time equivalent to `kstr()`. `Kstr` takes a literal string and inserts the text `{ sizeof (string), string }` into the document, suitable for initializing a kstr.

## ksbufmk
`ksbuf* ksbufmk(void* where, kiochan channel, sz run)` initializes a new buffer at the specified address. `run` should be equivalent to the full length of the memory region minus `sizeof(struct ksbuf)` - in other words, the size of the string the `ksbuf` can hold. memory should be allocated by the user, either by creating an array on the stack or with `kmem` allocation functions. `ksbufmk()` returns a pointer to the new structure. the return value will always point to the same point in memory as `where`, but will be of the appropriate type to pass to buffer functions.

## ksbufput
`kcond ksbufput(ksbuf* b, ksraw str)` copies a string into a buffer with `kscp`. flushing it as necessary.

## ksbufflush
`kcond ksbufflush(ksbuf* b)` flushes a buffer to its assigned channel, emptying it and readying it for another write cycle. a buffer should almost always be flushed before it goes out of scope or is deallocated.

## kscomp
`char* kscomp(size_t ct, ksraw struct[], kmbuf* buf)` is a **string composition** function. it serves as an efficient, generalized replacement for functions like `strcat` and `strdup`.

to use kscomp, create an array of `kstr` and fill it with the strings you wish to concatenate. for example, to programmatically generate an HTML link tag, you might use the following code.

................................................................................
			ksref(text),
		Kstr("</a>")
	};
	char* html = kscomp(Kmsz(chain), chain, &buf);

kscomp will only calculate the length of individual strings if they are not already known. when it needs to calculate the length of a string, it will store that length in the original array so repeated calls can be made without needing to repeatedly calculate the lengths. this is not always desirable, so the variant `kscompc` exists, which is exactly the same as `kscomp` in every respect except that `chain` is not altered in any way.

## ksemit
`ksemit(sz len, ksraw* array, kiochan channel)` takes a `len`-length `array` of `ksraw`s and prints them to a channel. a buffer will be allocated based on the total length of the strings to avoid unnecessary write calls.

## ksemitc
`ksemitc(const char** array, sz bufsz, kiochan channel)` takes a null-terminated `array` of NUL-terminated strings and buffer-prints them to a channel. `bufsz` controls the size of the buffer used, and should be as close as possible to the size of the strings emitted. the buffer will be kept on the stack, so no memory management or cleanup is necessary.

# macros
if `KFclean` is not set when <k/str.h> is included, the following macros are defined.

 * `Kstr(string)` - the compile-time equivalent to `kstr()`. `Kstr` takes a literal string and inserts the text `{ sizeof (string) - 1, string }` into the document, suitable for initializing a kstr.

#endif

typedef struct ksraw {
	sz size;
	const char* ptr;
} ksraw;



typedef struct ksmut {
	sz size;
	char* ptr;
} ksmut;

sz kssz(const char* str, sz max);

#include <k/mem.h>

typedef struct kstr {
	sz size;
	kmptr ptr;
} kstr;


#include <k/io.h>

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

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

ksbuf* ksbufmk(void* where, kiochan channel, sz run);

#include <k/core.h>

kcond ksbufput(ksbuf*, ksraw);

kiocond ksbufflush(ksbuf*);



#ifdef __cplusplus
}
#endif

#endif

#endif

typedef struct ksraw {
	sz size;
	const char* ptr;
} ksraw;

#define Ksraw(str) ((ksraw){sizeof(str),str})

typedef struct ksmut {
	sz size;
	char* ptr;
} ksmut;

sz kssz(const char* str, sz max);

#include <k/mem.h>

typedef struct kstr {
	sz size;
	kmptr ptr;
} kstr;


#include <k/io.h>

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

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

ksbuf* ksbufmk(void* where, kiochan channel, sz run);

#include <k/core.h>

kcond   ksbufput(ksbuf*, ksraw);

kiocond ksbufflush(ksbuf*);
kcond   ksbufwrite(ksbuf*, const char** array);
kcond   ksemitc(const char** array, sz bufsz, kiochan channel);

#ifdef __cplusplus
}
#endif

#endif