]>
Commit | Line | Data |
---|---|---|
f043759d RA |
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. |