64 lines
2.6 KiB
Plaintext
64 lines
2.6 KiB
Plaintext
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.
|