"Fossies" - the Fresh Open Source Software Archive
Member "brlcad-7.32.4/doc/notes/bu_opt_design_notes.txt" (29 Jul 2021, 4493 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:
As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
1 Thoughts on expansion of bu_opt capability to include subcommands, other misc
4 Check over POSIX.1-2008 Utility Conventions - should guide (but not define) our
5 option handling. (In particular, we want long opts. On the other hand,
6 probably explicitly don't want the full GNU 'opts anywhere' convention as that
7 precludes structured subcommand parsing.)
11 * Define separate structure for subcommands, have as an optional pointer in
12 bu_opt structure.
14 * Explore + and -+ as opt/longopt specifiers for subcommands, directly mapping to
15 - and -- for options. Use +- to denote the end of a subcommand, like -- denotes
16 end of options.
18 Rule - options with optional arguments (e.g. --help JSON vs --help - both are
19 legal) will require that arguments needing to start with a "+" character (e.g.
20 --help "+arg1") be quoted. (For that matter, is the same true of normal "-"
21 option parsing?)
23 Can we allow "lazy" subcommand specification without +/-+ if we disqualify any
24 string in quotes from being a subcommand? (e.g. 'cmd arg1 arg2' treats arg1 as
25 a subcommand but 'cmd "arg1" arg2' treats arg1 as an arg? Do we need to worry
26 about this at all?
28 Can "leftover" operands from a subcommand be handed back up to parent commands?
30 Convention thoughts:
32 - or -- - option/long-option handling per POSIX and GNU convention.
34 + or -+ - explicit specifier of subcommand.
36 -- - explicit 'exit option parsing' mode - remainder is operands (per POSIX)
37 except that a -+ option will indicate another subcommand or a +- will elevate
38 the parsing environment back to the parent level.
40 +- "exit subcommand" - returns parsing to the parent level command evaluation
41 environment: brep -a1 -+plot -p1 +- -o out.pl results in brep handling -o
42 out.pl, not plot.
44 Scope of "next arg" other than +- is current command/subcommand: e.g. brep -a1
45 -+plot -p1 will pass p1 to plot's option handling, not brep's
47 If subsequent -+ are specified, first check if the current command has the
48 specified subcommand. If not, return parsing to the parent level to see if it
49 has the specified subcommand, and so on until a command table claims the
50 subcommand. Allows for both a subcommand of a subcommand:
52 brep obj_csg.c -+bool_eval -+plot curve S1_S2
54 and subsequent subcommands:
55 brep obj_csg.c -+facetize -+simplify
57 to be specified without requiring +- unless a command and a subcommand both
58 have a matching subcommand.
60 With that feature present, +- is necessary to specify a parent command's version of
61 the subcommand unambiguously (i.e. requires explicit exiting of subcommand state with
62 a matching subcommand):
64 cmd arg1 +c +d -> runs d subcommand defined by c
65 cmd arg1 +c +- +d -> runs d subcommand defined by cmd
68 TODOs for bu_opt help routines:
70 Maybe have help as a default subcommand rather than a default option, to allow for fancy
71 stuff without bastardizing the help option?
73 * define a built-in bu_help to support docbook, json, etc. specification which
74 can be used by commands not wanting to define their own, more complex options.
76 * need a routine to generate a POSIX compliant one-line description of the
77 command's syntax
79 * need built-in help (option or subcommand, maybe both?) that is available for
80 commands not wanting to define their own help, but can be over-ridden by an
81 explicit specification of help in the options. We will need some "smart" help
82 options for JSON, DocBook, etc as well as subcommand listing (--help cmds
83 maybe?) so a calling script can systematically and automatically generate
84 documentation for all commands.
86 * explore the possibility of adding to the help system a generator of some sort
87 that can produce a JSON structure describing the structure of the commands and
88 options in such a way that a libbu routine could accept that structure as a
89 validation template and validate a command line string against it. Would
90 (potentially) allow for things like smart tab completion, valid/invalid syntax
91 highlighting, etc. without having to either explicitly duplicate the command
92 syntax in code or back such validation logic into each command. With this
93 setup we would run the "generate syntax" help option for every command/subcommand
94 in all of BRL-CAD (which just coincidentally would make the function of the
95 help system for every command in the code a build time requirement/check)
96 and supply a pre-built validation database in a data_dir location for libbu
97 to check.