Richard Alpe | f043759 | 2015-05-07 15:07:36 +0200 | [diff] [blame] | 1 | DESIGN DECISIONS |
| 2 | ---------------- |
| 3 | |
| 4 | HELP |
| 5 | ~~~~ |
| 6 | --help or -h is used for help. We do not reserve the bare word "help", which |
| 7 | for example the ip command does. Reserving a bare word like help quickly |
| 8 | becomes cumbersome to handle in the code. It might be simple to handle |
| 9 | when it's passed early in the command chain like "ip addr help". But when |
| 10 | the user tries to pass "help" further down this requires manual checks and |
| 11 | special treatment. For example, at the time of writing this tool, it's |
| 12 | possible to create a vlan named "help" with the ip tool, but it's impossible |
| 13 | to remove it, the command just shows help. This is an effect of treating |
| 14 | bare words specially. |
| 15 | |
| 16 | Help texts are not dynamically generated. That is, we do not pass datastructures |
| 17 | like command list or option lists and print them dynamically. This is |
| 18 | intentional. There is always that exception and when it comes to help texts |
| 19 | these exceptions are normally neglected at the expence of usability. |
| 20 | |
| 21 | KEY-VALUE |
| 22 | ~~~~~~~~~ |
| 23 | All options are key-values. There are both drawbacks and benefits to this. |
| 24 | The main drawback is that it becomes more to write for the user and |
| 25 | information might seem redundant. The main benefits is scalability and code |
| 26 | simplification. Consistency is important. |
| 27 | |
| 28 | Consider this. |
| 29 | 1. tipc link set priority PRIO link LINK |
| 30 | 2. tipc link set LINK priority PRIO |
| 31 | |
| 32 | Link might seem redundant in (1). However, if the command should live for many |
| 33 | years and be able to evolve example (2) limits the set command to only work on a |
| 34 | single link with no ability to extend. As an example, lets say we introduce |
| 35 | grouping on the kernel side. |
| 36 | |
| 37 | 1. tipc link set priority PRIO group GROUP |
| 38 | 2. tipc link set ??? priority PRIO group GROUP |
| 39 | |
| 40 | 2. breaks, we can't extend the command to cover a group. |
| 41 | |
| 42 | PARSING |
| 43 | ~~~~~~~ |
| 44 | Commands are single words. As an example, all words in "tipc link list" are |
| 45 | commands. Options are key-values that can be given in any order. In |
| 46 | "tipc link set priority PRIO link LINK" "tipc link set" are commands while |
| 47 | priority and link are options. Meaning that they can be given like |
| 48 | "tipc link set link LINK priority PRIO". |
| 49 | |
| 50 | Abbreviation matching works for both command and options. Meaning that |
| 51 | "tipc link set priority PRIO link LINK" could be given as |
| 52 | "tipc l s p PRIO l LINK" and "tipc link list" as "tipc l l". |
| 53 | |
| 54 | MEMORY |
| 55 | ~~~~~~ |
| 56 | The tool strives to avoid allocating memory on the heap. Most (if not all) |
| 57 | memory allocations are on the stack. |
| 58 | |
| 59 | RETURNING |
| 60 | ~~~~~~~~~ |
| 61 | The tool could throw exit() deep down in functions but doing so always seems |
| 62 | to limit the program in the long run. So we output the error and return an |
| 63 | appropriate error code upon failure. |