libk  Check-in [5c1200e1a8]

Overview
Comment:update kcli syntax
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 5c1200e1a8ba2c2d7c1e171cd3025ee10836744a8d6f55b0b6a0e0ce986c519f
User & Date: lexi on 2019-09-04 01:23:03
Other Links: manifest | tags
Context
2019-10-21
01:03
change testbin to pass appropriate string lengths to kiosend check-in: 3626b335f2 user: lexi tags: trunk
2019-09-04
01:23
update kcli syntax check-in: 5c1200e1a8 user: lexi tags: trunk
2019-08-29
06:41
arch: rewrite and merge mktbl scripts for Linux These now use the kernel’s own build system to generate headers and extract information from them. check-in: ceed477743 user: lachs0r tags: trunk
Changes

Modified mod/kcli/kcli.md from [09b7990027] to [fb0395874f].

     1      1   # kcli
     2      2   **kcli** is a module that implements common routines used by command-line utilities, such as option parsing, usage display, and more.
     3      3   
     4         -## functions
            4  +# syntax
            5  +kcli implements the unspoken standard for command line parsing that is adhered to by many UNIX programs. it operates on an array of tokens, whose role depends on their content and on preceeding flags. note that in flag names, dashes and underscores are equivalent. this is to prevent obnoxious behavior and enable the macros to define multi-word long flags.
     5      6   
     6         -### kcli_usage(kcli_set, kiochan)
            7  +1. if the argument `--` preceded the current argument, it is interpreted as a parameter.
            8  +2. if an argument begins with `-` and is followed by any symbol besides `-`, the remainder of the its characters are interpreted as short flags.
            9  +3. if an argument consists solely of `--`, it is ignored, and all further arguments are treated as parameters regardless of their form.
           10  +4. if an argument begins with `--` and is longer than two characters, it is interpreted as a long flag.
           11  +5. if a flag takes a parameter, the cursor is incremented and the field it points to is interpreted as its parameter. if there are not enough arguments, parse fails.
           12  +6. if an argument consists solely of `@`, it is treated as in step 7, except flags and parameters are read from standard in.
           13  +7. if an argument begins with `@`, the remainder is interpreted as a filename. this file is loaded and interpreted according to this same set of rules, where spaces separate each parameter, and double or single quote marks can be used to escape strings. newlines are ignored.
           14  +8. if an argument consists solely of `=@`, it is treated as in step 9, except flags and parameters are read from standard in.
           15  +9. if an argument begins with `=@`, the remainder is interpreted as a filename. this file is loaded and interpreted according to this same set of rules, where newlines separate each parameter.
           16  +8. if an argument consists solely of `:@`, lines will be read from stdin and interpreted as individual parameters, not as flags.
           17  +8. if an argument begins with `:@`, the remainder is interpreted as a filename. all of the file's lines will be interpreted as individual parameters, not as flags.
           18  +10. if no other rules apply, the argument is added to the parameter list.
           19  +
           20  +**note:** in the future, `kcore` will parse arguments at startup before passing them on to the application. all libk control arguments are prefixed with `-:`. these will not be passed onto the application, and so will not be available for kcli to parse.
           21  +
           22  +consider the following examples:
           23  +1. `--no-arg-flag --arg-flag --other-flag` will set the flag `no-arg-flag`, and set the field `arg-flag` to `"--other-flag"`.
           24  +2. if `-a` names a flag and `-b` and `-c` name string fields, `-abc b-field-value c-field-value parameter` sets the short flag `a`, set the field `b` to `"b-field-value"`, set `c` to `"c-field-value"`, and add the parameter `parameter`
           25  +3. `-s --long @args -- -s --long @args` sets the flags `s`, `long`, and parses the file `args` for further parameters, then adds the parameters `"-s"``"--long"``"@args"` to the parameter list.
           26  +
           27  +# functions
           28  +
           29  +## kcli_usage(kcli_set, kiochan)
     7     30   kcli_usage() takes a `kcli_set` and prints a succinct usage summary to a [kiochan](../kio/kio.md).
     8     31   
     9         -## types
           32  +# types
    10     33   
    11         -### struct kcli_set
           34  +## struct kcli_set
    12     35   `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.
    13     36   
    14     37    * `const char* name` - program name (if null, will be determined from argv instead)
    15     38    * `size_t argc` - the number of arguments in the `argv` array.
    16     39    * `const char** argv` - the `argv` pointer passed to the `entry` function, representing the command-line arguments passed to the program.
    17     40    * `const char* desc` - program description
    18     41    * `const kcli_param* params` - a list of options expected by the program.