brbzull0 commented on code in PR #13570:
URL: https://github.com/apache/trafficserver/pull/13570#discussion_r3880163952
##########
doc/appendices/command-line/traffic_ctl.en.rst:
##########
@@ -563,6 +569,28 @@ Display the current value of a configuration record.
Specifying the file name is not needed as `traffic_ctl` will try to use the
build(or the runroot if used) information to figure
out the path to the `records.yaml`.
+ ``-c`` accepts at most one file name, so it may be written before or after
the record
+ names:
+
+ .. code-block:: bash
+
+ $ traffic_ctl config get -c records.yaml proxy.config.diags.debug.enabled
+ $ traffic_ctl config get proxy.config.diags.debug.enabled -c records.yaml
+ $ traffic_ctl config get --cold=records.yaml
proxy.config.diags.debug.enabled
+
+ When no file name is given, write ``-c`` last, or use the ``--cold=`` form
for the
+ explicit file. A bare ``-c`` followed by a record name takes the record as
the file name,
+ which leaves the command with no records of its own and is reported as a
usage error:
+
+ .. code-block:: bash
+
+ $ traffic_ctl config get proxy.config.diags.debug.enabled -c #
default records.yaml
+ $ traffic_ctl config get -c proxy.config.diags.debug.enabled
+ Error: at least one argument expected by get
+
+ ``-c`` is also given at most once, so repeating it is a usage error rather
than the last
+ file name silently winning.
Review Comment:
Right, and it was worse than the space-separated form alone: `check_map`
only counted the `--option=value` spelling, so `-c a -c b` kept the last name
silently, and mixing the two spellings (`-c a --cold=b`) put two values into an
option that permits one.
Fixed in 73d26466c5 by counting the space-separated form against the same
limit, so all three shapes now exit 64 with `at most one argument expected by
--cold`. Gold tests added for the repeated and mixed forms. Fixed-arity options
such as `-t a -t b` keep their existing last-one-wins behaviour; that is a
separate concern and not something this PR changes.
##########
doc/appendices/command-line/traffic_ctl.en.rst:
##########
@@ -456,11 +456,17 @@ Display the current value of a configuration record.
.. note::
- ``-D`` uses variable-argument parsing and must appear as the **last
option**
- on the command line. Any flags placed after ``-D`` will be consumed
as directive
- values. ``-D`` and ``-d`` cannot be combined in the same invocation
due to this
- same constraint. Use ``-d`` with full YAML when you need both
directives and
- inline content in a single reload request.
+ ``-D`` accepts values until the next option or the end of the command
line, so it
+ may appear anywhere among the options and can be combined with ``-d``
— directives
+ and inline content merge under the same config key:
+
+ .. code-block:: bash
+
+ $ traffic_ctl config reload -D myconfig.id=foo --monitor
+ $ traffic_ctl config reload -D myconfig.id=foo -d 'myconfig:
{rules: [a]}'
+
+ To pass a directive value that begins with ``-``, place ``--`` before
it; every
+ token after ``--`` is taken as a value rather than an option.
Review Comment:
Agreed, the wording hid the consequence. `--` turns option recognition off
for the rest of that collection, so a variable-arity option swallows every
remaining token and any later option is lost.
Reworded in 68e57089ac to say so directly, and it now points at
`--directive=-value` with an example for the case where options still have to
follow.
##########
doc/developer-guide/internal-libraries/ArgParser.en.rst:
##########
@@ -104,6 +104,33 @@ To add options to the parser or current command:
This function call returns the new :class:`Option` instance. (0 is also number
of arguments expected)
+.. Note::
+
+ For options, the number of arguments may also be one of the following,
which mirror the
+ ``nargs`` values of Python's ``argparse``:
+
+ ================================
=======================================================
+ Value Meaning
+ ================================
=======================================================
+ ``AT_MOST_ONE_ARG_N`` Zero or one value (``argparse``
``nargs='?'``)
+ ``MORE_THAN_ZERO_ARG_N`` Zero or more values (``argparse``
``nargs='*'``)
+ ``MORE_THAN_ONE_ARG_N`` One or more values (``argparse``
``nargs='+'``)
+ ================================
=======================================================
+
+ An option taking a variable number of values stops collecting when it
reaches a token
+ naming another option of the same command, so options written afterwards
keep their own
+ arguments. Use ``AT_MOST_ONE_ARG_N`` rather than ``MORE_THAN_ZERO_ARG_N``
for an option
+ whose value is optional, otherwise it also consumes the positional
arguments of its
+ command.
+
+ A token naming another option is not a value for a fixed number of
arguments either. An
+ option written where a value is expected leaves the value missing, which is
reported as a
+ usage error rather than the option being consumed and applied as the value.
+
+ A ``--`` token stops option recognition for the values being collected,
which is how a
+ value beginning with ``-`` is passed. Note this differs from the POSIX
``--``: it does
+ not end the value list nor force the remainder to be positional arguments.
Review Comment:
Added in 68e57089ac. The paragraph now states that option recognition stays
off for the remainder of the value list, so every later token becomes a value
and no subsequent option is recognized, and recommends the `--option=value`
form when options still have to follow a dash-prefixed value.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
