Custom cli formatter

[mjcarroll]

Add a custom formatter to make standalone executables line up more closely with the previous ruby-style documentation.

Address #42

Example result with ign-transport-topic: (gazebosim/gz-transport#296)

With custom formatter

./bin/ign-transport-topic
Introspect Ignition topics
Usage: ./bin/ign-transport-topic [OPTIONS]

Options:
  -h [--help]                 Print this help message and exit
                              
  -v [--version]              
                              
  -t [--topic] TEXT           Name of a topic
                              Required by: --pub
                              Required by: --echo
                              Required by: --info
                              
  -m [--msgtype] TEXT         Type of message to publish
                              Required by: --pub
                              
  -d [--duration] FLOAT       Duration (seconds) to run
                              Excludes: --num
                              
  -n [--num] INT              Numer of messages to echo and then exit
                              Excludes: --duration
                              
[Option Group: command]
  Command to be executed
  Options:
    -l [--list]                 List all topics.
                                
    -i [--info]                 "Get info about a topic. E.g.:
                                  ign topic -i -i /foo
                                Requires: --topic
                                
    -e [--echo]                 Output data to screen. E.g.:
                                  ign topic -e -t /foo
                                Requires: --topic
                                
    -p [--pub] TEXT             Publish a message.
                                arg is the message data. The format expected is
                                the same used by Protobuf DebugString(). E.g.:
                                  ign topic -t /foo -m ignition.msgs.StringMsg \
                                    -p 'data:"Custom data"'
                                Requires: --msgtype
                                Requires: --topic
                                

Before with CLI11 (no custom formatter)

$ ign topic --force-version 11.0.0
Introspect Ignition topics
Usage: /usr/lib/x86_64-linux-gnu/ignition/transport11/ign-transport-topic [OPTIONS]

Options:
  -h,--help                   Print this help message and exit
  -v,--version                
  -t,--topic TEXT             Name of a topic
  -m,--msgtype TEXT           Type of message to publish
  -d,--duration FLOAT Excludes: --num
                              Duration (seconds) to run
  -n,--num INT Excludes: --duration
                              Numer of messages to echo and then exit
[Option Group: command]
  Command to be executed
  Options:
    -l,--list                   
    -i,--info Needs: --topic    
    -e,--echo                   
    -p,--pub TEXT Needs: --topic --msgtype

Ruby version

$ign topic --force-version 8.2.1
Print information about topics.

  ign topic [options]

Options:

  -i [ --info ]              Get info about a topic.
                             Requires the -t option.
                                                    
  -l [ --list ]              List all topics.
                                                    
  -t [ --topic ] arg         Name of a topic.
                             Required with -i, -p.
                                                    
  -m [ --msgtype ] arg       Type of message to publish.
                             Arg is a message type.
                             Required with -p.
                                                    
  -p [ --pub ] arg           Publish a message.
                             arg is the message data. The format expected is
                             the same used by Protobuf DebugString(). E.g.:

                               ign topic -t /foo -m   ignition.msgs.StringMsg
                               -p 'data:"Custom data"'

                             Requires -t and -m.
                                                    
  -e [ --echo ]              Output data to screen. E.g.:

                               ign topic -e -t /foo
                                                    
                             Requires -t.
                                                    
  -d [--duration] arg        Duration (seconds) to run. Applicable with 
                             echo. This will override -n.
                                                    
  -n [--num] arg             Number of messages to echo and then exit. A value 
                             <=0 implies infinite messages. Applicable with 
                             echo. This is overriden by -d.

  -h [ --help ]              Print this help message.
                                                    
  --force-version <VERSION>  Use a specific library version.
                                                    
  --versions                 Show the available versions.

[mjcarroll]

Note that "requires", "required by", and "excludes" are automatically computed from the CLI parser, this documentation is now auto-generated and should stay in sync with the actual code.

[codecov-commenter]

Codecov Report

Merging #42 (0b945ed) into ign-utils1 (959e8e1) will decrease coverage by 53.68%.
The diff coverage is 88.13%.

❗ Current head 0b945ed differs from pull request most recent head 098959f. Consider uploading reports for the commit 098959f to get more accurate results

@@               Coverage Diff               @@
##           ign-utils1      #42       +/-   ##
===============================================
- Coverage       94.87%   41.18%   -53.69%     
===============================================
  Files               5       17       +12     
  Lines              78     2326     +2248     
===============================================
+ Hits               74      958      +884     
- Misses              4     1368     +1364     

Impacted Files	Coverage Δ
...i/include/ignition/utils/cli/IgnitionFormatter.hpp	88.13% <88.13%> (ø)
...li/include/vendored-cli/ignition/utils/cli/App.hpp	36.43% <0.00%> (ø)
...lude/vendored-cli/ignition/utils/cli/Formatter.hpp	41.71% <0.00%> (ø)
...de/vendored-cli/ignition/utils/cli/StringTools.hpp	40.00% <0.00%> (ø)
...include/vendored-cli/ignition/utils/cli/Config.hpp	26.86% <0.00%> (ø)
...include/vendored-cli/ignition/utils/cli/Option.hpp	50.94% <0.00%> (ø)
...lude/vendored-cli/ignition/utils/cli/ConfigFwd.hpp	7.14% <0.00%> (ø)
.../include/vendored-cli/ignition/utils/cli/Split.hpp	47.36% <0.00%> (ø)
...lude/vendored-cli/ignition/utils/cli/TypeTools.hpp	54.80% <0.00%> (ø)
...e/vendored-cli/ignition/utils/cli/FormatterFwd.hpp	90.90% <0.00%> (ø)
... and 2 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 959e8e1...098959f. Read the comment docs.

[mjcarroll]

We should probably find a way to exclude the vendored cli code from codecov?

[mjcarroll]

This will also likely break if we ever update CLI11 versions, so I split the initial import from the ignition-specific modifications in 29b53bb and dc5be4e. We may want to avoid squash merging this one for that reason.

[azeey]

I have a few minor comments and codecheck is failing, otherwise LGTM!

[mjcarroll]

Squashed a few commits together here so that I can do a merge to keep the import and modifications separate.

[osrf-triage]

This pull request has been mentioned on Gazebo Community. There might be relevant details there:

https://community.gazebosim.org/t/new-ignition-releases-2022-04-13-fortress-edifice/1367/1