Add support for a more compact usage template

[codegangsta]

This PR adds support for a more compact usage template for top-level, sub commands and subcommand/known command errors.

To not break any current projects that use this package, I added and ErrorUsageTemplate method on Application to support customizing the usage template for subcommand related errors.

I also split up global vs local flags in this template to clean up the output a bit.

This is to support nats-io/natscli#523

Example - Top Level NATS command:

 nats
usage: nats [<flags>] <command> [<args> ...]

NATS Utility

NATS Server and JetStream administration.

See 'nats cheat' for a quick cheatsheet of commands

Commands:
  account    Account information and status
  backup     JetStream configuration backup utility
  bench      Benchmark utility
  consumer   JetStream Consumer management
  context    Manage nats configuration contexts
  errors     Error code documentation
  events     Show Advisories and Events
  governor   Controls the concurrency of distributed command executions
  kv         Interacts with a JetStream based Key-Value store
  latency    Perform latency tests between two NATS servers
  object     Interacts with a JetStream based Object store
  publish    Generic data publish utility
  request    Generic request-reply request utility
  reply      Generic service reply utility
  restore    Restores a backup of JetStream configuration
  rtt        Compute round-trip time to NATS server
  schema     Schema tools
  server     Server information
  stream     JetStream Stream management
  subscribe  Generic subscription client

Global Flags:
  -h, --help                    Show context-sensitive help
      --version                 Show application version.
  -s, --server=URL              NATS server urls ($NATS_URL)
      --user=USER               Username or Token ($NATS_USER)
      --password=PASSWORD       Password ($NATS_PASSWORD)
      --connection-name=NAME    Nickname to use for the underlying NATS Connection
      --creds=FILE              User credentials ($NATS_CREDS)
      --nkey=FILE               User NKEY ($NATS_NKEY)
      --tlscert=FILE            TLS public certificate ($NATS_CERT)
      --tlskey=FILE             TLS private key ($NATS_KEY)
      --tlsca=FILE              TLS certificate authority chain ($NATS_CA)
      --timeout=DURATION        Time to wait on responses from NATS ($NATS_TIMEOUT)
      --js-api-prefix=PREFIX    Subject prefix for access to JetStream API
      --js-event-prefix=PREFIX  Subject prefix for access to JetStream Advisories
      --js-domain=DOMAIN        JetStream domain to access
      --inbox-prefix=PREFIX     Custom inbox prefix to use for inboxes
      --context=NAME            Configuration context ($NATS_CONTEXT)
      --trace                   Trace API interactions

And a subcommand:

 nats stream
error: a subcommand from the list below is required, use --help for full help including flags and arguments

usage: nats stream [<flags>] <command> [<args> ...]

JetStream Stream management

Subcommands:
  stream ls        List all known Streams
  stream report    Reports on Stream statistics
  stream find      Finds streams matching certain criteria
  stream info      Stream information
  stream add       Create a new Stream
  stream edit      Edits an existing stream
  stream rm        Removes a Stream
  stream purge     Purge a Stream without deleting it
  stream copy      Creates a new Stream based on the configuration of another
  stream rmm       Securely removes an individual message from a Stream
  stream view      View messages in a stream
  stream get       Retrieves a specific message from a Stream
  stream backup    Creates a backup of a Stream over the NATS network
  stream restore   Restore a Stream over the NATS network
  stream seal      Seals a stream preventing further updates
  stream cluster   Manages a clustered Stream
  stream template  Manages Stream Templates

Flags:
  -a, --all  When listing or selecting streams show all streams including system ones

And a command with a lot of local flags:

 nats help stream add
usage: nats stream add [<flags>] [<stream>]

Create a new Stream

Args:
  [<stream>]  Stream name

Flags:
      --config=CONFIG            JSON file to read configuration from
      --validate                 Only validates the configuration against the official Schema
      --output=FILE              Save configuration instead of creating
      --subjects=SUBJECTS ...    Subjects that are consumed by the Stream
      --description=DESCRIPTION  Sets a contextual description for the stream
      --storage=STORAGE          Storage backend to use (file, memory)
      --replicas=REPLICAS        When clustered, how many replicas of the data to create
      --tag=TAG ...              Place the stream on servers that has specific tags (pass multiple times)
      --cluster=CLUSTER          Place the stream on a specific cluster
      --[no-]ack                 Acknowledge publishes
      --retention=RETENTION      Defines a retention policy (limits, interest, work)
      --discard=DISCARD          Defines the discard policy (new, old)
      --max-age=""               Maximum age of messages to keep
      --max-bytes=MAX-BYTES      Maximum bytes to keep
      --max-consumers=-1         Maximum number of consumers to allow
      --max-msg-size=MAX-MSG-SIZE  
                                 Maximum size any 1 message may be
      --max-msgs=0               Maximum amount of messages to keep
      --max-msgs-per-subject=0   Maximum amount of messages to keep per subject
      --dupe-window=""           Duration of the duplicate message tracking window
      --mirror=MIRROR            Completely mirror another stream
      --source=STREAM ...        Source data from other Streams, merging into this one
      --[no-]allow-rollup        Allows roll-ups to be done by publishing messages with special headers
      --[no-]deny-delete         Deny messages from being deleted via the API
      --[no-]deny-purge          Deny entire stream or subject purges via the API
      --[no-]allow-direct        Allows fast, direct, access to stream data via the direct get API
  -j, --json                     Produce JSON output
      --republish-source=REPUBLISH-SOURCE  
                                 Republish messages to --republish-destination
      --republish-destination=REPUBLISH-DESTINATION  
                                 Republish destination for messages in --republish-source
      --republish-headers        Republish only message headers, no bodies

[ripienaar]

very good, thank you