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