Field selection

[rgoldberg]

Field-Selection Options

--fields … & associated options allow commands that support --json to:

• Select fields
• Order fields
• Rename fields
• Format field values
• Sort rows

--fields … & associated options affect all output formats (currently: tabular
& JSON).

Remove --price from search after field addition implemented.

Custom EBNF Syntax Definition

This custom flavor of EBNF (Extended Backus-Naur Form) is later used to describe
the command-line syntax for field-selection options & their values.

Wildcard / EBNF Placeholder

*

Literal Text

"*"

"" is the escape for a literal ".

Value Description

{*}

* describes valid literal values, e.g., {non-negative integer}.

Value Placeholder (aka Non-Terminal Symbol)

<*>

* is the name of the value's type.

Standard-Escaping Text Placeholder

<text>

Non-empty string input that is literal except for \-escaped characters.

• \ escapes the following character to itself (e.g., \n results in a literal
  n).
• \ must be escaped unless it is the final character.
• Whitespace is significant.

Required-Escaping Text Placeholder

<text\*>
<text\\*>
<text\*\\*>

Extends <text> specifying additional characters that must be escaped:

• Characters in \* must be escaped when they are the first character.
• Characters in \\* must be escaped everywhere.

Example

<text\@+-\\:^,>

• @, + & - must be escaped if first.
• \, :, ^ & , must be escaped throughout.

Grouping

( * )

Optional Singleton (0 or 1)

[ * ]

Optional Repetition (0 or More)

*…

Choice

* | *

---

General Spec Information

All values are case-sensitive.

Headers Option Spec

Controls the visibility & format of the header row.

header-option ::= "--no-headers" | "--headers" [ "=" <header-format> ]

Standard: --no-headers

<header-format> is reserved for future implementation (e.g., csv, bold,
underline).

Fields Option Spec

Field Specs

Configure how a field is included in the output, containing:

• Required field name
• Optional output label (defaults to the field name)
• Optional value formatting
• Optional row sorting

Field Spec Sets

A field spec set is an ordered set of field specs.

Effective Set

The field spec set actually used for output for a command line.

Named Field Spec Sets

Field spec sets stored in a persistent configuration under a case-sensitive name
that is unique for a context.

mas provides Immutable Standard Named Field Spec
Sets.

Users can define named field spec sets in any context.

Contexts

A context exists for each command in a command stack:

Command Stack	Most Specific Context	Parent Context
mas config	mas.config	mas
mas list	mas.list	mas
mas lookup	mas.lookup	mas
mas outdated	mas.outdated	mas
mas search	mas.search	mas

The context stack for each command is ordered from most specific to least
specific context (e.g., the context stack for mas outdated is
[mas.outdated, mas]).

Named field specs are found by:

• Returning the first named field spec found with a given name while iterating
  through the context stack for the current command from most to least specific
  context.
• If no match is found, an error is reported.

Immutable Standard Named Field Spec Sets

Provided for each leaf command:

• standard: The command's default tabular output field specs.
• all: Field specs for all of the command's fields.

Provided for mas:

• none (alias empty): No field specs.

Base Set

The base named field spec set for computing the effective set.

The base set is set to:

• A named field spec set referenced in the command line.
• If no named field spec set is referenced in the command line: a
  user-configured per-output-format per-command default base set.
• If no default base set is configured by the user: standard for tabular
  output & all for JSON output.

Fields Option

fields-option ::= "--fields " ( <replacement-spec> | <modification-spec> | <empty> )
empty         ::= {a shell literal empty string}

The effective set is:

• If <fields-option> is omitted: the default base set.
• If --fields <replacement-spec> is supplied: sourced solely from
  <replacement-spec>; this is the equivalent of the base set being set to
  none.
• If --fields <modification-spec> is supplied: sourced from the base set as
  modified by the <modification-spec>.

<replacement-spec> & <modification-spec> are overlaid on top of the base set
for the current command line only; they do not persistently affect named field
spec sets.

Replacement Spec

replacement-spec             ::= <first-replacement-field-spec> [ "," <field-spec> ]…
first-replacement-field-spec ::= <first-replacement-field-name> [ <field-modifiers> ]
first-replacement-field-name ::= <text\@+-\\:^,>

field-spec                   ::= [ <addition-indicator> ] <field-name> [ <field-modifiers> ]
addition-indicator           ::= "+"
field-name                   ::= <text\+\\:^,>

field-modifiers              ::= [ <label-spec> ] [ <format-spec> ] [ <sort-spec> ]

A <replacement-spec>:

• Sets the base set to none.
• Is equivalent to @none+<replacement-spec>.

A <field-spec>:

• With an <addition-indicator> (+ prefix) creates an additional field output
  for the field (i.e., an additional column for tabular output & an additional
  key-value pair for JSON output).
• Without an <addition-indicator> overrides the rightmost previous field spec
  for the field.

A field has an effective given field modifier (i.e., <label-spec>,
<format-spec>, or <sort-spec>) if one has been defined (possibly in the base
set, possibly in the command line), but not subsequently cleared, for the field.

Labelling

label-spec ::= ">" [ <label> ]
label      ::= <text\\:^,>

• An empty label (>) clears any inherited label for the field.
• A field without an effective label spec uses <field-name> as its label.
• Labels are used as headers for tabular output.
• Labels are used as keys in JSON output.

Formatting

format-spec    ::= ":" [ <format> ]
format         ::= <format-type> [ ":" <format-pattern> ]
format-type    ::= <text\\:^,>
format-pattern ::= <text\\^,>

• An empty format (:) clears all inherited formatting for the field.
• A field without an effective format spec outputs verbatim field values.

Sorting

sort-spec       ::= "^" [ <sort> ]
sort            ::= [ <sort-direction> ] <sort-priority>
sort-direction  ::= <sort-ascending> | <sort-descending>
sort-ascending  ::= "+"
sort-descending ::= "-"
sort-priority   ::= {non-negative integer}

• An empty sort (^) clears inherited sorting for the field.
• A field without an effective sort spec does not affect row sorting.
• <sort-direction> defaults to <sort-ascending>.
• A field with an effective sort spec takes sort precedence over fields:
  • With a numerically higher <sort-priority>.
  • To its right with the same <sort-priority>.

Modification Spec

modification-spec ::= [ <base-set-spec> ] [ <augmentations-spec> [ "," <exclusions-spec> ] | <exclusions-spec> ]

• Computes the effective set from a resolved base set adjusted by modifications
  from the command line.
• If <base-set-spec> is omitted, the default base set is used.
• Exclusions take precedence over additions.

Base Set Selection

base-set-spec       ::= "@" [ <field-spec-set-name> ]
field-spec-set-name ::= <text\\+->

• If <field-spec-set-name> is omitted, the base set is all.
• If no field spec set is named <field-spec-set-name> in the context stack, an
  error is reported.

Additions / Overrides

augmentations-spec ::= "+" <field-spec> [ "," <field-spec> ]…

• Appends field specs to, or overrides field specs from, the base set.
• The rightmost field spec for the same field takes precedence.

Exclusions

exclusions-spec     ::= "-" excluded-field-name [ "," excluded-field-name ]…
excluded-field-name ::= <text\\,>

• Removes field specs for the specified fields from the effective set.