diff options
Diffstat (limited to '')
| -rw-r--r-- | tipc/README | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/tipc/README b/tipc/README new file mode 100644 index 0000000..529d781 --- /dev/null +++ b/tipc/README @@ -0,0 +1,63 @@ +DESIGN DECISIONS +---------------- + +HELP +~~~~ +--help or -h is used for help. We do not reserve the bare word "help", which +for example the ip command does. Reserving a bare word like help quickly +becomes cumbersome to handle in the code. It might be simple to handle +when it's passed early in the command chain like "ip addr help". But when +the user tries to pass "help" further down this requires manual checks and +special treatment. For example, at the time of writing this tool, it's +possible to create a vlan named "help" with the ip tool, but it's impossible +to remove it, the command just shows help. This is an effect of treating +bare words specially. + +Help texts are not dynamically generated. That is, we do not pass data structures +like command list or option lists and print them dynamically. This is +intentional. There is always that exception and when it comes to help texts +these exceptions are normally neglected at the expense of usability. + +KEY-VALUE +~~~~~~~~~ +All options are key-values. There are both drawbacks and benefits to this. +The main drawback is that it becomes more to write for the user and +information might seem redundant. The main benefits is scalability and code +simplification. Consistency is important. + +Consider this. +1. tipc link set priority PRIO link LINK +2. tipc link set LINK priority PRIO + +Link might seem redundant in (1). However, if the command should live for many +years and be able to evolve example (2) limits the set command to only work on a +single link with no ability to extend. As an example, lets say we introduce +grouping on the kernel side. + +1. tipc link set priority PRIO group GROUP +2. tipc link set ??? priority PRIO group GROUP + +2. breaks, we can't extend the command to cover a group. + +PARSING +~~~~~~~ +Commands are single words. As an example, all words in "tipc link list" are +commands. Options are key-values that can be given in any order. In +"tipc link set priority PRIO link LINK" "tipc link set" are commands while +priority and link are options. Meaning that they can be given like +"tipc link set link LINK priority PRIO". + +Abbreviation matching works for both command and options. Meaning that +"tipc link set priority PRIO link LINK" could be given as +"tipc l s p PRIO l LINK" and "tipc link list" as "tipc l l". + +MEMORY +~~~~~~ +The tool strives to avoid allocating memory on the heap. Most (if not all) +memory allocations are on the stack. + +RETURNING +~~~~~~~~~ +The tool could throw exit() deep down in functions but doing so always seems +to limit the program in the long run. So we output the error and return an +appropriate error code upon failure. |