Overview
| Comment: | factor out write buffer code so any module and libk users can call it; update documentation to match; add kssz string length function |
|---|---|
| Downloads: | Tarball | ZIP archive | SQL archive |
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA3-256: |
8d6b36fcac4d6db018f6597f71ce140e |
| User & Date: | lexi on 2019-10-30 07:44:12 |
| Other Links: | manifest | tags |
Context
|
2019-10-31
| ||
| 03:44 | add usage display for parameters and command line switches for kcli_set, the structure used to define command line syntax for the parser; add more string & buffer functions check-in: 927371b674 user: lexi tags: trunk | |
|
2019-10-30
| ||
| 07:44 | factor out write buffer code so any module and libk users can call it; update documentation to match; add kssz string length function check-in: 8d6b36fcac user: lexi tags: trunk | |
| 03:34 | begin work on kcli module; continue to build out infra for error explanation function check-in: c0e04b9015 user: lexi tags: trunk | |
Changes
Modified mod/kcli/testbin.exe.c from [7d0c94d714] to [9c55c30fa9].
4 4 stat 5 5 entry (kenv e) { 6 6 kcli_set testbin = { 7 7 "testbin", "1.0.0", e.args, e.argc, 8 8 "this is a test of the kcli module", 9 9 }; 10 10 11 - kcli_usage(testbin, e.err); 11 + kcond c = kcli_usage(testbin, e.err); 12 12 13 - return 0; 13 + return c; 14 14 }
Modified mod/kcli/usage.fn.c from [2416d97ee0] to [09e6f94502].
1 1 #include <k/cli.h> 2 2 #include <k/io.h> 3 3 #include <k/str.h> 4 4 5 -typedef struct buffer { 6 - char* cur; 7 - kiochan channel; 8 - sz run; 9 - char buf []; 10 -} buffer; 11 - 12 -static buffer* 13 -buffer_new(void* mem, kiochan channel, sz run) { 14 - buffer* r = mem; 15 - r -> cur = r -> buf; 16 - r -> channel = channel; 17 - r -> run = run; 18 - return r; 19 -} 20 - 21 -static kiocond 22 -buffer_flush(buffer* b) { 23 - ksraw str = {b -> cur - b -> buf, b -> buf}; 24 - b -> cur = b -> buf; 25 - return kiosend(b -> channel, str, null); 26 -} 27 - 28 -static kcond 29 -buffer_send(buffer* b, const char* str) { 30 - ksmut buf = { b->run - (b->cur - b->buf), b->cur }; 31 - ksraw src = { 0, str }; 32 - kscond sc = kscp(src, buf, &src.size); 33 - if (sc != kscond_ok) return sc; 34 - 35 - b->cur += src.size; 36 - if (b->cur >= (b->buf + b->run)) { 37 - return buffer_flush(b); 38 - } else return kiocond_ok; 39 -} 40 - 41 5 kcond 42 6 kcli_usage(kcli_set prg, kiochan ch) { 43 - ubyte buf_space [sizeof(buffer) + 256]; 44 - buffer* out = buffer_new(buf_space, ch, 256); 7 + ubyte buf_space [sizeof(ksbuf) + 256]; 8 + ksbuf* out = ksbufmk(buf_space, ch, 256); 45 9 46 10 const char* msg [] = { 47 11 prg.name, " v", prg.version, "\n\n", 48 12 prg.desc, "\n\n", 49 13 }; 50 - for (sz i = 0; i != sizeof msg / sizeof msg[0]; ++ i) { 51 - kcond c = buffer_send(out, msg[i]); 52 - if (!kokay(c)) return c; 14 + for (sz i = 0; i != Kmsz(msg); ++ i) { 15 + ksraw str = { 0, msg[i] }; 16 + kcond c = ksbufput(out, str); 53 17 } 54 18 55 - return buffer_flush(out); 19 + return ksbufflush(out); 56 20 }
Modified mod/kcore/core.h from [4d5847ec2c] to [4054dd1b64].
1 1 #ifndef KIcore 2 2 #define KIcore 3 + 3 4 #include <k/type.h> 4 -#include <k/io.h> 5 -#include <k/str.h> 6 -#include <k/internal.egroup.h> 7 5 8 -#ifdef __cplusplus 9 -extern "C" { 10 -#endif 11 - 12 -typedef struct kvar { 13 - ksraw name; 14 - ksraw val; 15 - char* platform; 16 -} kvar; 17 - 18 -typedef struct kenv { 19 - kiochan std; 20 - kiochan err; 21 - sz argc; const char** args; 22 - sz varc; kvar* vars; 23 -} kenv; 6 +typedef u16 kcond; 7 +/* this will probably not need to be altered, 8 + * as libk sports a modest number of modules, 9 + * and there are few enough error conditions 10 + * in each that 16-bit address space should 11 + * be more than enough for the foreseeable 12 + * future. however if that changes, altering 13 + * the definition here will effect all the 14 + * necessary changes throughout the library */ 24 15 25 16 /* i'm really sorry okay */ 26 17 typedef 27 18 #if (__STDC_VERSION__ >= 199901L) 28 19 _Bool bool; 29 20 #endif 30 21 enum ................................................................................ 36 27 false = 0, no = 0, 37 28 true = 1, yes = 1 38 29 } 39 30 #if !(__STDC_VERSION__ >= 199901L) 40 31 bool /* } bool ; */ 41 32 #endif 42 33 ; 34 + 35 +bool kokay(kcond); 43 36 44 37 #ifndef KFclean 45 38 # include <k/internal.egroup.h> 46 39 # define Kokay(cond) (((cond) % kglobal_module_offset) == 0) 47 40 # if (__STDC_VERSION__ >= 199901L) ||\ 48 41 (__cplusplus >= 201103L) 49 42 # define KVvm_args __VA_ARGS__ ................................................................................ 146 139 [[noreturn]] void kstop(stat_long code); 147 140 #elif __STDC_VERSION__ >= 201103L 148 141 _Noreturn void kstop(stat_long code); 149 142 #else 150 143 void kstop(stat_long code); 151 144 #endif 152 145 153 -typedef u16 kcond; 154 -/* this will probably not need to be altered, 155 - * as libk sports a modest number of modules, 156 - * and there are few enough error conditions 157 - * in each that 16-bit address space should 158 - * be more than enough for the foreseeable 159 - * future. however if that changes, altering 160 - * the definition here will effect all the 161 - * necessary changes throughout the library */ 162 -bool kokay(kcond); 163 - 164 146 typedef struct kerror { 165 147 const char* module_name, 166 148 * module_desc, 167 149 * error_string; 168 150 kcond cond; 169 151 } kerror; 152 + 153 +#include <k/io.h> 154 +#include <k/str.h> 155 +#include <k/internal.egroup.h> 156 + 157 +#ifdef __cplusplus 158 +extern "C" { 159 +#endif 160 + 161 +typedef struct kvar { 162 + ksraw name; 163 + ksraw val; 164 + char* platform; 165 +} kvar; 166 + 167 +typedef struct kenv { 168 + kiochan std; 169 + kiochan err; 170 + sz argc; const char** args; 171 + sz varc; kvar* vars; 172 +} kenv; 170 173 171 174 kerror kexplain(kcond); 172 175 173 176 #ifdef __cplusplus 174 177 } 175 178 #endif 176 179 177 180 #endif
Modified mod/kio/io.h.m from [34396da060] to [03256457ff].
4 4 * ~ lexi hale <lexi@hale.su> 5 5 * this header declares IO primitive functions and 6 6 * structures. it is the same for all platforms. 7 7 * platform-specific code is found in the *.platform.h 8 8 * files. 9 9 */ 10 10 11 -#include <k/str.h> 12 11 #include <k/type.h> 13 12 #include <k/mem.h> 14 13 15 14 #ifdef __cplusplus 16 15 extern "C" { 17 16 #endif 18 17 ................................................................................ 72 71 kiocond_fail_no_space, 73 72 kiocond_fail_forbidden, 74 73 kiocond_fail_over_quota, 75 74 kiocond_fail_pfault, 76 75 kiocond_fail_too_big, 77 76 kiocond_fail_stream_mismatch, 78 77 } kiocond; 78 + 79 +#include <k/str.h> 79 80 80 81 kiocond kiosend(kiochan, ksraw, sz*); // send data to a channel 81 82 kiocond kiosendall(kiochan, ksraw); // keep sending data to a channel until it's all sent 82 83 kiocond kiorecv(kiochan, ksraw*); // receive data from a channel 83 84 kmptr kiorecvall(kiochan, kmcell*, kmkind); // automatically allocate a bufer for a channel 84 85 // kmkind is only used if kmcell* is null 85 86 kiocond kiocon(kiochan, kiochan); // connect one channel to another 86 87 87 88 #ifdef __cplusplus 88 89 } 89 90 #endif 90 91 91 92 #endif
Added mod/kstr/bufflush.fn.c version [45cb80b779].
1 +#include <k/type.h> 2 +#include <k/str.h> 3 +#include <k/io.h> 4 + 5 +kiocond 6 +ksbufflush(ksbuf* b) { 7 + ksraw str = {b -> cur - b -> buf, b -> buf}; 8 + b -> cur = b -> buf; 9 + return kiosend(b -> channel, str, null); 10 +}
Added mod/kstr/bufmk.fn.c version [25e9d731b6].
1 +#include <k/type.h> 2 +#include <k/str.h> 3 + 4 +ksbuf* 5 +ksbufmk (void* where, kiochan channel, sz run) { 6 + ksbuf* r = where; 7 + r -> cur = r -> buf; 8 + r -> channel = channel; 9 + r -> run = run; 10 + return r; 11 +}
Added mod/kstr/bufput.fn.c version [32dbad6423].
1 +#include <k/type.h> 2 +#include <k/io.h> 3 +#include <k/str.h> 4 + 5 +kcond 6 +ksbufput(ksbuf* b, ksraw src) { 7 + ksmut dest = { b->run - (b->cur - b->buf), b->cur }; 8 + /* there are a number of scenarios we need to account for: 9 + * 10 + * - the ksraw has an unknown size. in this case, we 11 + * determine the size with kssz and proceed according to 12 + * the following rules. we could also count the string 13 + * as we copy, taking advantage of kscp's behavior on 14 + * strings of unknown length, but this would drastically 15 + * complicate the code for an almost certainly negligible 16 + * gain in performance. 17 + * 18 + * - the ksraw has a known size that is shorter than the 19 + * remaining space in the buffer. in this case, we copy 20 + * it into the buffer and return the result of the copy. 21 + * 22 + * - the ksraw has a known size that is the same as the 23 + * remaining space in the buffer. in this case, we copy 24 + * it into the buffer and flush the buffer immediately. 25 + * 26 + * - the ksraw has a known size that is longer than the 27 + * remaining space in the buffer. in this case, we flush 28 + * the buffer immediately and then copy in the new string. 29 + * 30 + * - the ksraw has a known size that is greater than or 31 + * equal to the buffer's run. in this case, we flush the 32 + * buffer and print the ksraw directly, bypassing the 33 + * buffer as it would only be a performance impediment. 34 + */ 35 + 36 + if (src.size == 0) src.size = kssz(src.ptr, -1); 37 + 38 + if (src.size < dest.size) { 39 + kcond c = kscp(src, dest, null); 40 + if (!kokay(c)) return c; 41 + b -> cur += src.size; 42 + return kscond_ok; 43 + } else if (src.size == dest.size) { 44 + kcond c = kscp(src, dest, null); 45 + if (!kokay(c)) return c; 46 + b -> cur += src.size; 47 + return ksbufflush(b); 48 + } else if (src.size > b -> run) { 49 + kcond c = ksbufflush(b); 50 + if (!kokay(c)) return c; 51 + return kiosend(b -> channel, src, null); 52 + } else if (src.size > dest.size) { 53 + kcond c = ksbufflush(b); 54 + if (!kokay(c)) return c; 55 + dest.size = b -> run; 56 + dest.ptr = b -> cur; 57 + c = kscp(src, dest, null); 58 + if (!kokay(c)) return c; 59 + b -> cur += src.size; 60 + return kscond_ok; 61 + } else return kscond_fail; /* what in the sam heck */ 62 +}
Added mod/kstr/kssz.fn.c version [a254af4df5].
1 +#include <k/type.h> 2 +#include <k/str.h> 3 + 4 +sz kssz(const char* str, sz max) { 5 + const char* end; 6 + for (end = str; *end!=0; ++end); 7 + return end - str; 8 +}
Modified mod/kstr/kstr.md from [b3e2b4c4d7] to [7f4b99ca6c].
1 1 # kstr 2 2 3 3 **kstr** is the libk string library. it uses the **short** naming convention with the glyph `s`. **kstr** implies `#include <k/mem.h>`. 4 4 5 -## types 5 +# types 6 6 7 -### struct kstr 7 +## struct kstr 8 8 `struct kstr` is a structure for holding pascal strings (length-prefixed strings). it is the basic libk string type. **note:** if `ptr.ref` ≠ NULL and `sz` = 0, the string's length is unknown and should be calculated by any function that operates on a kstr, storing the result in the object if possible. 9 9 * `sz size` - length of string, excluding any null terminator 10 10 * `kmptr ptr` - pointer to string in memory 11 11 12 -### struct ksraw 12 +## struct ksraw 13 13 `struct ksraw` is like `kstr` except it uses raw `char` pointers instead of a `kmptr`. 14 14 * `sz size` - length of string, excluding any null terminator 15 15 * `char* ptr` - pointer to string in memory 16 16 17 -### struct ksbuf 18 -`struct ksbuf` is a structure used to hold buffers. 19 - * `sz size` - maximum size of buffer, including any null terminator 20 - * `char* buf` - region of memory to store buffer in 21 - * `ksalloc strat` - allocation strategy 22 - * `kmkind rule` - kind of allocator to use. only needs to be set if `where` is NULL. see [kmem](../kmem/kmem.md). 23 - * `kmcell* where` - where to allocate the object, in case of pool or tree allocation. 17 +## struct ksbuf 18 +`struct ksbuf` is a structure used for buffered IO. 19 + * `sz run` - maximum size of buffer, including any null terminator 20 + * `kiochan channel` - the channel that output will be written to when flushed 21 + * `char* cur` - a pointer that tracks the length of the buffer 22 + * `char buf []` - region of memory to store buffer in 24 23 25 -### struct kschain 24 +## struct kschain 26 25 `struct kschain` is a structure used for string accumulators that works by aggregating pointers to strings, instead of copying the strings themselves. 27 26 * `kschain_kind kind` - kind of chain 28 27 * `kmkind rule` - kind of allocation to use if `kind` ≠ `kschain_kind_linked` 29 28 * `pstr* ptrs` - pointer to pointer list 30 29 * `sz ptrc` - number of pointers 31 30 * `sz size` - total amount of space in `ptrs` 32 31 33 -#### enum kschain_kind 32 +### enum kschain_kind 34 33 * `kschain_kind_block` - occupies a single block of memory 35 34 * `kschain_kind_linked` - uses a linked list, allocated and deallocated as necessary 36 35 37 -### enum ksalloc 38 -`enum ksalloc` is an enumerator that tells libk what strategy to use when filling a `ksbuf` or `kschain` struct. 36 +## enum ksalloc 37 +`enum ksalloc` is an enumerator that tells libk what strategy to use when filling a `kschain` struct. 39 38 * `ksalloc_static` - do not allocate memory, fill an already-allocated, statically-sized array. 40 39 * `ksalloc_alloc` - allocate a string in memory using the specified kind of allocator. 41 40 * `ksalloc_dynamic` - fill an already-allocated array if possible, allocate a string in memory if the string length exceeds available space. 42 41 43 -## functions 42 +# functions 44 43 45 -### kssz 44 +## kssz 46 45 `size_t kssz(char* str, size_t max)` returns the number of characters in a C string, **including** the final null. will count at most `max` characters if `max` > 0. 47 46 48 -### kstr 47 +## kstr 49 48 `kstr kstr(char* str, size_t max)` takes a C string and returns a P-string, calculating the length of `str` and storing it in the return value. `max` works as in `kssz`. 50 49 51 -### kstoraw 50 +## kstoraw 52 51 `ksraw ksref(kstr)` is a simple convenience function that returns the `ksraw` form of a `kstr`. 53 52 54 -### kscomp 53 +## kscp 54 +`kscond kscp(ksraw src, ksmut dest, sz* len)` copies the string pointed to by `src` into `dest`. its behavior varies depending on the value of `src.size` — if the size is already known, attempts to copy a longer string on top of a shorter one will immediately fail with no changes made to either string. if the size is set to zero, `kscp()` will copy as many bytes as it can before it hits either a NUL terminator in the source string or reaches the end of the destination string. if `dest.src` is zero, kscp simply copies until it hits the first NUL, or reaches `src.ptr[src.size - 1]`. for safety reasons, kscp always terminates `dest` with a NUL when it has enough space to, even if neither string ended with a NUL. if a partial copy occurs, `kscp` will return a `kscond` of `kscond_partial`. 55 + 56 +## ksbufmk 57 +`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. 58 + 59 +## ksbufput 60 +`kcond ksbufput(ksbuf* b, ksraw str)` copies a string into a buffer with `kscp`. flushing it as necessary. 61 + 62 +# ksbufflush 63 +`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. 64 + 65 +## kscomp 55 66 `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`. 56 67 57 68 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. 58 69 59 70 char mem[512]; 60 71 kmptr text = <...>; 61 72 char* src = <...>; ................................................................................ 65 76 ksref(text), 66 77 Kstr("</a>") 67 78 }; 68 79 char* html = kscomp(Kmsz(chain), chain, &buf); 69 80 70 81 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. 71 82 72 -### macros 83 +## macros 73 84 if `KFclean` is not set when <k/str.h> is included, the following macros are defined. 74 85 75 86 * `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.
Modified mod/kstr/str.h from [43535adcf4] to [18dd12a221].
1 1 #ifndef KIstr 2 2 #define KIstr 3 3 4 -#include <k/mem.h> 4 +#include <k/type.h> 5 5 6 6 #ifdef __cplusplus 7 7 extern "C" { 8 8 #endif 9 9 10 -typedef struct kstr { 11 - sz size; 12 - kmptr ptr; 13 -} kstr; 14 - 15 10 typedef struct ksraw { 16 11 sz size; 17 12 const char* ptr; 18 13 } ksraw; 19 14 20 15 typedef struct ksmut { 21 16 sz size; 22 17 char* ptr; 23 18 } ksmut; 19 + 20 +sz kssz(const char* str, sz max); 21 + 22 +#include <k/mem.h> 23 + 24 +typedef struct kstr { 25 + sz size; 26 + kmptr ptr; 27 +} kstr; 28 + 29 +#include <k/io.h> 24 30 25 31 #include <k/internal.egroup.h> 26 32 typedef enum kscond { 27 33 kscond_ok = kscond_id, 34 + kscond_partial, 28 35 kscond_fail, 29 36 kscond_unimplemented, 30 37 kscond_nonnumeric, 31 38 kscond_no_room, 32 39 kscond_null, 33 40 } kscond; 34 41 ................................................................................ 44 51 45 52 ksconv_partial = 1 << 7, 46 53 ksconv_nopfx = 1 << 8, 47 54 ksconv_endh = 1 << 9, 48 55 ksconv_endl = 1 << 10, 49 56 }; 50 57 58 + 59 +typedef struct ksbuf { 60 + sz run; 61 + kiochan channel; 62 + char* cur; 63 + char buf []; 64 +} ksbuf; 65 + 66 +/* functions */ 67 + 51 68 kscond ks_to_int(ksraw str, 52 69 enum ksconv mode, 53 70 u8* dest, sz size); 54 71 55 72 kscond ks_of_int(u8* number, sz size, 56 73 enum ksconv mode, 57 74 char* bufstart, sz bufsize); 58 75 59 76 kscond kscp(ksraw str, ksmut dest, sz* len); 77 + 78 +ksbuf* ksbufmk(void* where, kiochan channel, sz run); 79 + 80 +#include <k/core.h> 81 + 82 +kcond ksbufput(ksbuf*, ksraw); 83 + 84 +kiocond ksbufflush(ksbuf*); 60 85 61 86 #ifdef __cplusplus 62 87 } 63 88 #endif 64 89 65 90 #endif