"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:

    1 Thoughts on expansion of bu_opt capability to include subcommands, other misc
    2 notes...
    3 
    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.)
    8 
    9 http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
   10 
   11 * Define separate structure for subcommands, have as an optional pointer in
   12   bu_opt structure.
   13 
   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.
   17 
   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?)
   22 
   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?
   27 
   28 Can "leftover" operands from a subcommand be handed back up to parent commands?
   29 
   30 Convention thoughts:
   31 
   32 - or -- - option/long-option handling per POSIX and GNU convention.
   33 
   34 + or -+ - explicit specifier of subcommand.
   35 
   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.
   39 
   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.
   43 
   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
   46 
   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:
   51 
   52 brep obj_csg.c -+bool_eval -+plot curve S1_S2
   53 
   54 and subsequent subcommands:
   55 brep obj_csg.c -+facetize -+simplify
   56 
   57 to be specified without requiring +- unless a command and a subcommand both
   58 have a matching subcommand.
   59 
   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):
   63 
   64 cmd arg1 +c +d    -> runs d subcommand defined by c
   65 cmd arg1 +c +- +d -> runs d subcommand defined by cmd
   66 
   67 
   68 TODOs for bu_opt help routines:
   69 
   70 Maybe have help as a default subcommand rather than a default option, to allow for fancy
   71 stuff without bastardizing the help option?
   72 
   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.
   75 
   76 * need a routine to generate a POSIX compliant one-line description of the
   77   command's syntax
   78 
   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.
   85 
   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.