libk  Check-in [623e0fdd96]

Modified mod/kconf/kconf.md from [b260f2842a] to [6e72a9b762].

     1      1   # kconf
     2      2   
     3         -while there are a number of existing configuration parser libraries out there, they all have their problems, and all depend on libc. since configuration string parsing is a fairly core functionality that would force many programs to either write their own code or drag libc back into their dependencies, supplying a basic parser with libk makes sense.
            3  +while there are a number of existing configuration parser libraries out there, they all have their problems, and all depend on libc. since configuration string parsing is a fairly core functionality that would force many programs to either write their own code or drag libc back into their dependencies, supplying a basic parser with libk makes sense. it may also make sense at some point to add support for a simple binary configuration format, to make it easier to marshal out complex runtime data structures.
     4      4   
     5         -## basic principles
            5  +# basic principles
     6      6   
     7      7   kconf is intended to be fast, lightweight, transparent, and low-overhead.
     8      8   
     9      9   to initialize a kconf structure, we begin by supplying a list of *atoms.* like in Xlib, an atom is a performant way to reference a known string of text from a compiled program. we can do this in two different ways, either by generating the values ourselves at compile time with an enum, or by generating them at runtime using the appropriate kconf interface. note that if you supply your own with an enum, because zero is used for in-band error signalling, the first atom should always be an error token. alternately, it may be explicitly set to a non-zero number and a return value of zero can be checked for implicitly or against a literal 0.
    10     10   
    11         -note that, in a recurring libk pattern, if an element count of zero (or `null`) is passed to a function that takes an array of nullables, that function will treat its array argument as a null-terminated array to be counted at runtime.
           11  +note that, in a recurring libk pattern, if an element count of zero (or `null`) is passed to a function that takes an array of nullables, that function will treat its array argument as a null-terminated array to be counted at runtime. to actually pass an empty array, the pointer to the array itself should be `null`.
    12     12   
    13         -kconf is initialized by filling out the struct `kconf` with the parameters of operations and then passing it to the appropriate function.
           13  +kconf has two modes: key-value mode, a very lightweight mode suited for simple applications that only require a few parameters to be specialized, and record mode, which is heavier-weight but allows retrieving and working with complex datastructures.
    14     14   
    15         -    enum atoms { parse_error, user, pw, email, atomct };
    16         -    kconf kc = {
           15  +in key-value mode, kconf is initialized by filling out the appropriate `kconf` struct with the parameters required and then passing it to the appropriate function.
           16  +
           17  +    enum atoms { parse_error, user, pw, email, atoms_count };
           18  +    kconf_kv kc = {
    17     19       	.decl = { atomct, {
    18         -    		{ user,  {4, "user"    } },
    19         -    		{ pw,    {8, "password"} },
    20         -    		{ email, {5, "email"   } }
           20  +    		{ user,     {4, "user"    }, kconf_string },
           21  +    		{ password, {8, "password"}, kconf_string },
           22  +    		{ age,      {5, "age"     }, kconf_u8 }
    21     23       	}}
    22     24       };
    23     25   
    24     26   	/* with runtime counts:
    25     27        * enum atoms { parse_error, user, pw, email };
    26         -     * kconf kc = {
           28  +     * kconf_kv kc = {
    27     29        * 	.decl = { null, {
    28         -     * 		{ user,  {0, "user"    } },
    29         -     * 		{ pw,    {0, "password"} },
    30         -     * 		{ email, {0, "email"   } },
           30  +     * 		{ user,     {0, "user"    }, kconf_string },
           31  +     * 		{ password, {0, "password"}, kconf_string },
           32  +     * 		{ age,      {0, "age"     }, kconf_u8 },
    31     33   	 *		{ null }
    32     34        * 	}}
    33     35        * }; */
    34     36   
    35     37   	/* with macros:
    36     38        * enum atoms { parse_error, user, password, email };
    37         -     * kconf kc = {
           39  +     * kconf_kv kc = {
    38     40        * 	.decl = {Kmpsa(kconf_decl, {
    39         -	 * 		Kconf_atom(user),
    40         -	 * 		Kconf_atom(password),
    41         -	 * 		Kconf_atom(email)
           41  +	 * 		Kconf_atom(user, string),
           42  +	 * 		Kconf_atom(password, string),
           43  +	 * 		Kconf_atom(age, u8)
    42     44   	 * 	})};
    43     45   	 * }; */
    44     46   
    45         -## types
           47  +when invoked, `kconf_kv_read` populates an array with values read from the config file, and returns a structure containing a status report. kconf can be invoked on a kfile handle (with `kconf_kv_parse_file()`) or a string in memory (with `kconf_kv_parse_string()`), but in the normal course of usage, you'll simply use the `kconf_kv_read()` function, which automatically loads a configuration file from the appropriate location for the system (such as `$XDG_CONFIG_HOME/app` on linux or `~/Library/app preferences` on Mac OS X, where 'app' is the name the binary was invoked with. conveniently, this enables the user to have different 'profiles' simply by creating symbolic links to the binary).
           48  +
           49  +    kconf_val conf[atoms_count];
           50  +    kconf_result kr = kconf_read(kc, conf);
           51  +    struct { ksraw username, pw; u8 age; } user;
           52  +    user.username = conf[user].string;
           53  +    user.pw = conf[password].string;
           54  +    user.age = conf[age].u8;
           55  +
           56  +kconf record mode works somewhat differently. rather than access the values directly, you'll call the `kconf_rec_read()` function (or `kconf_rec_parse_file()` / `kconf_rec_parse_string()`) to retrieve a struct of type `kconf_digest,` which can then be queried with the `kconf_query()` function. kconf_query takes two arguments, a `struct kconf_digest*` and a `kconf_path.`
           57  +
           58  +    kconf_digest db = kconf_rec_read();
           59  +    ksraw user_six_name = kconf_query(&db, (kconf_path){"user", 6, "name", 0} ).val.string;
           60  +    /* or with macros:
           61  +     * ksraw user_six_name = kconf_query(&db, Kconf_path("user", 6, "name")).val.string;
           62  +     */
           63  +
           64  +# types
           65  + * `typedef kconf_path kconf_path_elt[]` - a `kconf_path` is used to unambiguously identify a single field in a `kconf_digest`. it consists of a zero-terminated array of names and machine word-size integers. for instance, the path `(kconf_path){"user", 6, "name", 0}` can be used to identify the name of the sixth member of the "user" array. note that lists are **1-indexed**, to prevent collision with the list terminator.
           66  +
           67  +## struct kconf_kv
           68  +
           69  +## struct kconf_rec
    46     70   
    47         -### struct kconf
    48         -	* `union { kconf_decl decl; kconf_gen gen; };`
           71  +## struct kconf_digest
    49     72   
    50         -### struct kconf_atom
    51         -
           73  +## enum kconf_type
           74  +  * `string`- a string, represented as a ksraw
           75  +  * `bool` - a boolean value, either true or false
           76  +  * `file` - a file, represented by a filename in system-local format. the file will be opened and a reference to it will be returned in a `kfile` object.
           77  +  * additionally, kconf_type will have a member for every kind of machine integer the architecture supports. these members will be named according to libk integer types, so if the value a signed 16-bit integer, you would name its type as `s16`.
           78  + 
           79  +## struct kconf_atom
    52     80    * `sz key`
    53     81    * `ksraw string`
           82  + * `kconf_type type`
           83  +
           84  +## struct kconf_result
           85  +  * `enum kconf_cond cond`
           86  +  
           87  +## struct kconf_answer
           88  + * `enum kconf_cond cond`
           89  + * `union kconf_val val`
           90  +  
           91  +## union kconf_val
           92  +  * kconf_val is a union containing fields that match the enumerations in `kconf_type` - for instance, `ksraw string,` `bool bool,` `kfile file,` or `s16`.
           93  +
           94  +## union kconf_path\_elt
           95  + * `const char* name`
           96  + * `sz index`
           97  +
           98  +# functions
           99  + * `struct kconf_result kconf_kv_read()`
          100  + * `struct kconf_result kconf_kv_parse_file()`
          101  + * `struct kconf_result kconf_kv_parse_string()`
          102  + * `struct kconf_digest kconf_rec_read()`
          103  + * `struct kconf_digest kconf_rec_parse_file()`
          104  + * `struct kconf_digest kconf_rec_parse_string()`
          105  + * `struct kconf_answer kconf_query()`
    54    106   
    55         -### struct kconf_pair
          107  +# macros
    56    108   
    57         - * `kconf_atom atom`
    58         - * `ksraw* dest`
          109  + * `Kconf_atom(id, atom, type)` - a convenience macro for definining an atom structure (`kconf_atom`). inserts the text `{id, {sizeof(#atom), #atom}, kconf_##type}`
          110  + * `Kconf_atomi(atom, type)`- equivalent to `Kconf_atom(atom,atom,type)`
          111  + * `Kconf_atomp(atom,type)` - a convenience macro for definining an pre-defined atom structure (`kconf_atom`), under the assumption that the C enumerator name is the string used to name the field in the configuration file with a prefix attached. define the prefix with `#define KVconf_prefix` before use. inserts the text `{KVconf_prefix##atom, {sizeof(#atom), #atom}, kconf_##type}`
          112  + * `Kconf_path(path...)` - provides a slightly nicer path syntax than a zero-terminated compound literal (but still requires compound literal support). inserts the text `((kconf_path) {path, 0})`
    59    113   
    60         -
    61         -## macros
    62         -
    63         - * `Kconf_atom(atom)` - a convenience macro for definining an pre-defined atom structure (`kconf_atom`), under the assumption that the C enumerator name is the same as the string used to name the field in the configuration file. inserts the text `{atom, {sizeof(#atom), #atom}}`
    64         - * `Kconf_atom_pfx(pfx,atom)` - a convenience macro for definining an pre-defined atom structure (`kconf_atom`), under the assumption that the C enumerator name is the string used to name the field in the configuration file with a prefix attached. inserts the text `{pfx##atom, {sizeof(#atom), #atom}}`
          114  +# file format