tipc/README

   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.