| 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 datastructures | |
| 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 expence 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. |