mathspec 0.2.0__tar.gz → 0.3.0__tar.gz

{mathspec-0.2.0 → mathspec-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mathspec
-Version: 0.2.0
+Version: 0.3.0
 Summary: Write the specification (spec) of an optimisation model as a YAML file. Check it and print it as math, with no data and no solver.
 Project-URL: Documentation, https://mathspec.readthedocs.io
 Project-URL: Repository, https://github.com/energy-models/mathspec
@@ -43,20 +43,11 @@ SPDX-License-Identifier: CC-BY-4.0
 **Write the specification (spec) of an optimisation model as a YAML file. Check it and print it
 as math, with no data and no solver.**
 
-A mathspec file states a specification, or spec. A spec declares four things: the axes it runs
-over, such as `snapshot` and `generator`; the data it expects, such as `load`
-and `cost`; the decisions the solver makes, such as `dispatch`; and the rules
-those decisions obey, such as `sum(dispatch, over=generator) == load`. The file
-[below](#example) is a complete spec.
-
-<!--- --8<-- [start:engines] -->
-
-mathspec builds nothing and solves nothing itself.
-[specsolve](https://github.com/fluxopt/specsolve) and
-[linopy](https://github.com/PyPSA/linopy) build a model from a spec and its
-data, and solve it. Support in both is work in progress.
-
-<!--- --8<-- [end:engines] -->
+A spec declares four things: the dimensions it runs over, such as `snapshot`
+and `generator`; the data it expects, such as `load` and `cost`; the decisions
+the solver makes, such as `dispatch`; and the rules those decisions obey, such
+as `sum(dispatch, over=generator) == load`. The file [below](#example) is a
+complete spec.
 
 <!--- --8<-- [start:benefits] -->
 
@@ -123,6 +114,14 @@ Markdown is one of three formats, and GitHub renders it here.
 
 Least-cost dispatch of a generator fleet against an hourly load.
 
+#### Variable domains
+
+**`dispatch`**
+
+```math
+0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0
+```
+
 #### Objective
 
 ```math
@@ -137,14 +136,6 @@ Least-cost dispatch of a generator fleet against an hourly load.
 \sum_{g \in \mathcal{G}} \mathit{dispatch}_{t,g} = \mathrm{load}_{t} \qquad \forall\, t \in \mathcal{T}
 ```
 
-#### Variable domains
-
-**`dispatch`**
-
-```math
-0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0
-```
-
 <details>
 <summary>The whole document: a symbol table, and the legend it prints</summary>
 
@@ -171,6 +162,12 @@ Least-cost dispatch of a generator fleet against an hourly load.
 |---|---|
 | $`\mathit{dispatch}`$ | `dispatch` over $`\mathcal{S} \times \mathcal{G}`$ — output of a generator in a snapshot |
 
+#### Variable domains
+
+**`dispatch`**
+
+$`0 \le \mathit{dispatch}_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0`$
+
 #### Objective
 
 $`\min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} \mathit{dispatch}_{s,g} \cdot c_{g}`$
@@ -181,12 +178,6 @@ $`\min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} \mathit{dispatch}_{s,g} \cdo
 
 $`\sum_{g \in \mathcal{G}} \mathit{dispatch}_{s,g} = \ell_{s} \qquad \forall\, s \in \mathcal{S}`$
 
-#### Variable domains
-
-**`dispatch`**
-
-$`0 \le \mathit{dispatch}_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0`$
-
 </details>
 
 <!-- readme-math:end -->
@@ -208,6 +199,35 @@ A [symbol table](https://mathspec.readthedocs.io/en/latest/reference/typeset/#sy
 conventional spelling, as in the folded block.
 [Print a spec as math](https://mathspec.readthedocs.io/en/latest/howto/print/) does the same from a shell.
 
+## Engines and other tools
+
+<!--- --8<-- [start:engines] -->
+
+mathspec builds nothing and solves nothing itself. Instead,
+[specsolve](https://github.com/fluxopt/specsolve) and
+[linopy](https://github.com/PyPSA/linopy) build a model from a spec and its
+data, and solve it. Support in both is work in progress. Any other tool can
+read the same spec through the
+[Program API](https://mathspec.readthedocs.io/en/latest/reference/program/).
+The solid boxes are mathspec; the dashed boxes are outside it.
+
+```mermaid
+flowchart LR
+    accTitle: What mathspec does, and what other tools do with a spec
+    accDescr: A YAML file loads into a Spec and the Program it lowers to. mathspec checks the spec and prints it as math, with no data. Outside mathspec, drawn dashed, an engine such as specsolve or linopy reads the same spec, takes your data and returns your answers, and any other tool, such as a renderer or an analyser, reads the same spec through the Program API.
+    Y(["your spec<br/>one YAML file"]) --> SPEC["<b>Spec</b> and the <b>Program</b> it lowers to<br/><i>checked before any data exists</i>"]
+    SPEC --> CHECK["<b>check it</b><br/>python -m mathspec check"]
+    SPEC --> SHOW["<b>print it as math</b><br/>LaTeX · Typst · Markdown"]
+    SPEC -.-> OTHER["<b>your own tool</b><br/>a renderer · an analyser · …<br/>reads the Program API"]
+    SPEC -.-> ENGINE["<b>an engine</b><br/>specsolve · linopy<br/>builds and solves the model"]
+    DATA[("your data")] -.-> ENGINE
+    ENGINE -.-> ANS(["your answers"])
+    classDef outside stroke-dasharray:5 4
+    class ENGINE,DATA,ANS,OTHER outside
+```
+
+<!--- --8<-- [end:engines] -->
+
 ## Documentation
 
 The documentation is at <https://mathspec.readthedocs.io>.
@@ -220,11 +240,10 @@ See [installation](https://mathspec.readthedocs.io/en/latest/howto/installation/
 ## Prior art
 
 Every file under `src/` was written in [specsolve](https://github.com/fluxopt/specsolve)
-and extracted here. The keys themselves,
-which are YAML math, a block per component, `dims:` and a `where:` string,
-come from [Calliope](https://github.com/calliope-project/calliope).
-[linopy](https://github.com/PyPSA/linopy) supplies the vocabulary that
-`sum(over=)` and the dimension rules are named against.
+and extracted here. The keys come from
+[Calliope](https://github.com/calliope-project/calliope): math in YAML, one
+block per component, `dims:` and a `where:` string. `sum(over=)` and the
+dimension rules take their names from [linopy](https://github.com/PyPSA/linopy).
 
 ## Status
 
@@ -235,9 +254,9 @@ Alpha, pre-1.0.
 **Breaking changes land without a deprecation cycle.** Pin an exact version if
 you depend on this, and read the
 [changelog](https://github.com/energy-models/mathspec/blob/main/CHANGELOG.md)
-before upgrading. Every construct round-trips through the schema, the parsers
-and all three typeset formats, and the LaTeX is compiled. The accepted YAML is
-not yet frozen.
+before upgrading. The test suite passes every construct through the schema,
+the parsers and all three typeset formats, and compiles the LaTeX. The YAML that
+mathspec accepts can still change.
 
 <!--- --8<-- [end:status] -->
 

{mathspec-0.2.0 → mathspec-0.3.0}/README.md

@@ -18,20 +18,11 @@ SPDX-License-Identifier: CC-BY-4.0
 **Write the specification (spec) of an optimisation model as a YAML file. Check it and print it
 as math, with no data and no solver.**
 
-A mathspec file states a specification, or spec. A spec declares four things: the axes it runs
-over, such as `snapshot` and `generator`; the data it expects, such as `load`
-and `cost`; the decisions the solver makes, such as `dispatch`; and the rules
-those decisions obey, such as `sum(dispatch, over=generator) == load`. The file
-[below](#example) is a complete spec.
-
-<!--- --8<-- [start:engines] -->
-
-mathspec builds nothing and solves nothing itself.
-[specsolve](https://github.com/fluxopt/specsolve) and
-[linopy](https://github.com/PyPSA/linopy) build a model from a spec and its
-data, and solve it. Support in both is work in progress.
-
-<!--- --8<-- [end:engines] -->
+A spec declares four things: the dimensions it runs over, such as `snapshot`
+and `generator`; the data it expects, such as `load` and `cost`; the decisions
+the solver makes, such as `dispatch`; and the rules those decisions obey, such
+as `sum(dispatch, over=generator) == load`. The file [below](#example) is a
+complete spec.
 
 <!--- --8<-- [start:benefits] -->
 
@@ -98,6 +89,14 @@ Markdown is one of three formats, and GitHub renders it here.
 
 Least-cost dispatch of a generator fleet against an hourly load.
 
+#### Variable domains
+
+**`dispatch`**
+
+```math
+0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0
+```
+
 #### Objective
 
 ```math
@@ -112,14 +111,6 @@ Least-cost dispatch of a generator fleet against an hourly load.
 \sum_{g \in \mathcal{G}} \mathit{dispatch}_{t,g} = \mathrm{load}_{t} \qquad \forall\, t \in \mathcal{T}
 ```
 
-#### Variable domains
-
-**`dispatch`**
-
-```math
-0 \le \mathit{dispatch}_{t,g} \le \mathrm{capacity}_{g} \qquad \forall\, t \in \mathcal{T},\ g \in \mathcal{G} \,:\, \mathrm{capacity}_{g} > 0
-```
-
 <details>
 <summary>The whole document: a symbol table, and the legend it prints</summary>
 
@@ -146,6 +137,12 @@ Least-cost dispatch of a generator fleet against an hourly load.
 |---|---|
 | $`\mathit{dispatch}`$ | `dispatch` over $`\mathcal{S} \times \mathcal{G}`$ — output of a generator in a snapshot |
 
+#### Variable domains
+
+**`dispatch`**
+
+$`0 \le \mathit{dispatch}_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0`$
+
 #### Objective
 
 $`\min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} \mathit{dispatch}_{s,g} \cdot c_{g}`$
@@ -156,12 +153,6 @@ $`\min \sum_{s \in \mathcal{S},\ g \in \mathcal{G}} \mathit{dispatch}_{s,g} \cdo
 
 $`\sum_{g \in \mathcal{G}} \mathit{dispatch}_{s,g} = \ell_{s} \qquad \forall\, s \in \mathcal{S}`$
 
-#### Variable domains
-
-**`dispatch`**
-
-$`0 \le \mathit{dispatch}_{s,g} \le \bar p_{g} \qquad \forall\, s \in \mathcal{S},\ g \in \mathcal{G} \,:\, \bar p_{g} > 0`$
-
 </details>
 
 <!-- readme-math:end -->
@@ -183,6 +174,35 @@ A [symbol table](https://mathspec.readthedocs.io/en/latest/reference/typeset/#sy
 conventional spelling, as in the folded block.
 [Print a spec as math](https://mathspec.readthedocs.io/en/latest/howto/print/) does the same from a shell.
 
+## Engines and other tools
+
+<!--- --8<-- [start:engines] -->
+
+mathspec builds nothing and solves nothing itself. Instead,
+[specsolve](https://github.com/fluxopt/specsolve) and
+[linopy](https://github.com/PyPSA/linopy) build a model from a spec and its
+data, and solve it. Support in both is work in progress. Any other tool can
+read the same spec through the
+[Program API](https://mathspec.readthedocs.io/en/latest/reference/program/).
+The solid boxes are mathspec; the dashed boxes are outside it.
+
+```mermaid
+flowchart LR
+    accTitle: What mathspec does, and what other tools do with a spec
+    accDescr: A YAML file loads into a Spec and the Program it lowers to. mathspec checks the spec and prints it as math, with no data. Outside mathspec, drawn dashed, an engine such as specsolve or linopy reads the same spec, takes your data and returns your answers, and any other tool, such as a renderer or an analyser, reads the same spec through the Program API.
+    Y(["your spec<br/>one YAML file"]) --> SPEC["<b>Spec</b> and the <b>Program</b> it lowers to<br/><i>checked before any data exists</i>"]
+    SPEC --> CHECK["<b>check it</b><br/>python -m mathspec check"]
+    SPEC --> SHOW["<b>print it as math</b><br/>LaTeX · Typst · Markdown"]
+    SPEC -.-> OTHER["<b>your own tool</b><br/>a renderer · an analyser · …<br/>reads the Program API"]
+    SPEC -.-> ENGINE["<b>an engine</b><br/>specsolve · linopy<br/>builds and solves the model"]
+    DATA[("your data")] -.-> ENGINE
+    ENGINE -.-> ANS(["your answers"])
+    classDef outside stroke-dasharray:5 4
+    class ENGINE,DATA,ANS,OTHER outside
+```
+
+<!--- --8<-- [end:engines] -->
+
 ## Documentation
 
 The documentation is at <https://mathspec.readthedocs.io>.
@@ -195,11 +215,10 @@ See [installation](https://mathspec.readthedocs.io/en/latest/howto/installation/
 ## Prior art
 
 Every file under `src/` was written in [specsolve](https://github.com/fluxopt/specsolve)
-and extracted here. The keys themselves,
-which are YAML math, a block per component, `dims:` and a `where:` string,
-come from [Calliope](https://github.com/calliope-project/calliope).
-[linopy](https://github.com/PyPSA/linopy) supplies the vocabulary that
-`sum(over=)` and the dimension rules are named against.
+and extracted here. The keys come from
+[Calliope](https://github.com/calliope-project/calliope): math in YAML, one
+block per component, `dims:` and a `where:` string. `sum(over=)` and the
+dimension rules take their names from [linopy](https://github.com/PyPSA/linopy).
 
 ## Status
 
@@ -210,9 +229,9 @@ Alpha, pre-1.0.
 **Breaking changes land without a deprecation cycle.** Pin an exact version if
 you depend on this, and read the
 [changelog](https://github.com/energy-models/mathspec/blob/main/CHANGELOG.md)
-before upgrading. Every construct round-trips through the schema, the parsers
-and all three typeset formats, and the LaTeX is compiled. The accepted YAML is
-not yet frozen.
+before upgrading. The test suite passes every construct through the schema,
+the parsers and all three typeset formats, and compiles the LaTeX. The YAML that
+mathspec accepts can still change.
 
 <!--- --8<-- [end:status] -->
 

{mathspec-0.2.0 → mathspec-0.3.0}/pyproject.toml

@@ -211,12 +211,13 @@ extend-exclude = ["CHANGELOG.md"]
 [tool.typos.default.extend-words]
 # Each of these is deliberate, and none is reachable by fixing a spelling.
 #
-# `wher` and `generatr` are misspellings *on purpose*: they are the input to the
-# did-you-mean suggester, so correcting them deletes the case. `missable` is the
+# `wher`, `generatr` and `balnce` are misspellings *on purpose*: they are the
+# input to the did-you-mean suggester, so correcting them deletes the case. `missable` is the
 # word the sentence wants — a coordinate that can go missing — and is not
 # "miscible". `unparseable` is the accepted variant and is the name of a test.
 wher = "wher"
 generatr = "generatr"
+balnce = "balnce"
 missable = "missable"
 unparseable = "unparseable"
 # `fom` is PyPSA's `fom_cost` — fixed operation and maintenance — quoted by name

mathspec-0.3.0/src/mathspec/__init__.py

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: mathspec Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""The language: what a YAML file may say, and what it means.
+
+The top level is what a consumer calls: [`to_spec`][], the one door to a
+file, and the verbs over what it returns. The rest of the surface is three
+modules, each with one rule:
+
+- [`mathspec.spec`][] is what the file *says*: [`Spec`][mathspec.spec.Spec]
+  and the blocks it holds.
+- [`mathspec.program`][] is what the file *means*: the
+  [`Program`][mathspec.program.Program] a spec lowers to, its nodes, and the
+  [`Advice`][mathspec.program.Advice] the language gives about it.
+- [`mathspec.errors`][] is what a consumer catches.
+
+Everything between them — both grammars and the tree they build — is
+package-private, because a consumer reads a program instead.
+"""
+
+from mathspec import errors, program, spec
+from mathspec.advising import advice
+from mathspec.composition import merge, override
+from mathspec.typesetting import (
+    FormatName,
+    SymbolTable,
+    to_latex,
+    to_markdown,
+    to_typst,
+    typeset,
+    typeset_declaration,
+)
+from mathspec.validation import to_spec
+
+__all__ = [
+    'FormatName',
+    'SymbolTable',
+    'advice',
+    'errors',
+    'merge',
+    'override',
+    'program',
+    'spec',
+    'to_latex',
+    'to_markdown',
+    'to_spec',
+    'to_typst',
+    'typeset',
+    'typeset_declaration',
+]
+
+import warnings as _warnings
+from importlib import metadata as _metadata
+
+try:
+    __version__ = _metadata.version(__name__)
+except _metadata.PackageNotFoundError as e:  # pragma: no cover
+    _warnings.warn(f'Could not determine version of {__name__}\n{e!s}', stacklevel=2)
+    __version__ = 'unknown'

{mathspec-0.2.0 → mathspec-0.3.0}/src/mathspec/__main__.py

@@ -4,9 +4,11 @@
 
 """``python -m mathspec <verb> spec.yaml`` — the shell front.
 
-``check`` loads the file and prints the language's advice; one further verb
-per typeset format, read off [`mathspec.typesetting.FORMATS`][]. Every verb
-reads the file as written, and nothing here writes a formulation out unasked.
+``check`` loads the file and prints the language's advice; ``canonical``
+writes the spec in the form two files that state the same spec share, or with
+``--check`` asks whether the file is already in that form; one further verb per
+typeset format, read off [`mathspec.typesetting.FORMATS`][]. Every verb reads
+the file as written, and nothing here writes a formulation out unasked.
 The typeset verbs take ``--expand``, because a shell cannot compose
 [`expand`][mathspec.spec.Spec.expand] the way a caller does and the rows are a
 different document; ``check`` has no such flag, because advice reads a block
@@ -33,6 +35,13 @@ def parser() -> argparse.ArgumentParser:
     check = verbs.add_parser('check', help='load a spec, and print what the language advises')
     check.add_argument('spec', help='path to a mathspec YAML file')
 
+    canonical = verbs.add_parser('canonical', help='write a spec in the form two files that state it share')
+    canonical.add_argument('spec', help='path to a mathspec YAML file')
+    target = canonical.add_mutually_exclusive_group()
+    target.add_argument('-o', '--out', help='write here instead of stdout')
+    target.add_argument('--write', action='store_true', help='rewrite the file in the form, dropping its comments')
+    target.add_argument('--check', action='store_true', help='exit 1 if the file is not in the form, writing nothing')
+
     for name in FORMATS:
         verb = verbs.add_parser(name, help=f'render a spec as {name}')
         verb.add_argument('spec', help='path to a mathspec YAML file')
@@ -52,10 +61,26 @@ def parser() -> argparse.ArgumentParser:
     return front
 
 
+def _checked(path: str, text: str) -> int:
+    """Exit status 0 if the file at *path* already holds *text*, the form, and 1 with the rewrite on stderr if not.
+
+    A CI job runs this, so it compares bytes and writes nothing: the job fails,
+    and the author runs the rewrite the message names.
+    """
+    if Path(path).read_text(encoding='utf-8') == text:
+        return 0
+    sys.stderr.write(
+        f'{path} is not in the canonical form. Run `python -m mathspec canonical --write {path}` to rewrite it.\n'
+    )
+    return 1
+
+
 def main(argv: list[str] | None = None) -> int:
     """Run one verb; a refused file is its message on stderr and exit status 1.
 
-    Advice is not a refusal: ``check`` prints it and exits 0.
+    Advice is not a refusal: ``check`` prints it and exits 0. A file that
+    ``canonical --check`` finds out of the form exits 1, with the rewrite on
+    stderr.
     """
     args = parser().parse_args(argv)
     if args.verb == 'check':
@@ -66,16 +91,28 @@ def main(argv: list[str] | None = None) -> int:
             return 1
         sys.stdout.write(''.join(f'{note}\n' for note in notes))
         return 0
-    spec = to_spec(args.spec).expand() if args.expand else args.spec
-    text = typeset(
-        spec,
-        args.verb,
-        symbols=args.symbols,
-        standalone=args.standalone,
-        legend=not args.no_legend,
-        numbered=not args.no_numbers,
-        inline_expressions=args.inline_expressions,
-    )
+    if args.verb == 'canonical':
+        try:
+            text = to_spec(args.spec).to_yaml(canonical=True)
+        except MathSpecError as e:
+            sys.stderr.write(f'{e}\n')
+            return 1
+        if args.check:
+            return _checked(args.spec, text)
+        if args.write:
+            Path(args.spec).write_text(text, encoding='utf-8')
+            return 0
+    else:
+        spec = to_spec(args.spec).expand() if args.expand else args.spec
+        text = typeset(
+            spec,
+            args.verb,
+            symbols=args.symbols,
+            standalone=args.standalone,
+            legend=not args.no_legend,
+            numbered=not args.no_numbers,
+            inline_expressions=args.inline_expressions,
+        )
     if args.out:
         Path(args.out).write_text(text, encoding='utf-8')
     else:

{mathspec-0.2.0 → mathspec-0.3.0}/src/mathspec/_expression_parser.py

@@ -23,23 +23,23 @@ from mathspec.errors import SchemaError
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Mapping
 
-#: The relation a comparison may carry — the three an expression may be
-#: written with, which is what a constraint's sense is read off.
+#: The three comparison operators an expression may use. A constraint reads
+#: its sense from this operator.
 ComparisonOperator = Literal['<=', '>=', '==']
 
 #: The sign a unary operator applies to its operand.
 UnaryOperator = Literal['+', '-']
 
-#: The arithmetic a binary operator may spell. Closed by the grammar, and the
-#: vocabulary a renderer dispatching on [`BinaryOperatorNode.op`][]
-#: switches over — it keeps no list of its own.
+#: The arithmetic a binary operator may spell. The grammar closes the set, and
+#: a renderer that dispatches on [`BinaryOperatorNode.op`][] switches over it
+#: and keeps no list of its own.
 BinaryOperator = Literal['+', '-', '*', '/', '**']
 
 #: What an expression writes to refer to a declaration, and so what a
 #: declaration may be named.
 NAME = r'[a-zA-Z_][a-zA-Z0-9_]*'
 
-#: A float — a fractional part or an exponent. A sign is the unary operator's.
+#: A float has a fractional part or an exponent. The unary operator carries the sign.
 REAL = r'\d+\.\d*([eE][+-]?\d+)?|\d+[eE][+-]?\d+'
 
 # ---------------------------------------------------------------------------
@@ -79,6 +79,22 @@ class NameListNode:
         return shown(self.names)
 
 
+@dataclass(frozen=True)
+class ColumnsNode:
+    """Columns of one relation in a kwarg value — ``sum(x, over=g, by=gen_bus[bus])``.
+
+    The relation is written once and its columns after it, so one call cannot
+    name columns of two tables. Unresolved: which columns the kwarg admits is
+    the operator's business.
+    """
+
+    relation: str
+    columns: tuple[str, ...]
+
+    def __str__(self) -> str:
+        return f'{self.relation}[{", ".join(self.columns)}]'
+
+
 @dataclass(frozen=True)
 class KeywordNode:
     """A quoted closed keyword in a kwarg value — ``shift(..., edge='wrap')``.
@@ -131,10 +147,18 @@ class FunctionCallNode:
         return f'{self.name}({", ".join(passed)})'
 
 
-#: Every arithmetic node the grammar builds. A name, a name list and a quoted
-#: keyword are what resolution reads for their kind; the rest is structure.
+#: Every arithmetic node the grammar builds. A name, a name list, a column
+#: selection and a quoted keyword are what resolution reads for their kind; the
+#: rest is structure.
 ArithmeticNode = (
-    NumberNode | NameNode | NameListNode | KeywordNode | UnaryOperatorNode | BinaryOperatorNode | FunctionCallNode
+    NumberNode
+    | NameNode
+    | NameListNode
+    | ColumnsNode
+    | KeywordNode
+    | UnaryOperatorNode
+    | BinaryOperatorNode
+    | FunctionCallNode
 )
 
 
@@ -200,7 +224,7 @@ def nodes(*roots: ParsedNode) -> Iterator[ParsedNode]:
 
 def with_children(node: ArithmeticNode, recurse: Callable[[ArithmeticNode], ArithmeticNode]) -> ArithmeticNode:
     """*node* rebuilt with *recurse* applied to each of its [`children`][]; a leaf comes back as is."""
-    if isinstance(node, NumberNode | NameNode | NameListNode | KeywordNode):
+    if isinstance(node, NumberNode | NameNode | NameListNode | ColumnsNode | KeywordNode):
         return node
     if isinstance(node, UnaryOperatorNode):
         return UnaryOperatorNode(node.op, recurse(node.operand))
@@ -220,8 +244,15 @@ def with_children(node: ArithmeticNode, recurse: Callable[[ArithmeticNode], Arit
 # ---------------------------------------------------------------------------
 
 
-def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement]:
-    """The arithmetic grammar, and the expression grammar that puts one comparison over it.
+#: A bracketed list of names as a kwarg value, in an expression and in a where
+#: string alike.
+NAME_LIST = (pp.Suppress('[') + pp.DelimitedList(pp.Regex(NAME)) + pp.Suppress(']')).set_parse_action(
+    lambda t: NameListNode(tuple(str(x) for x in t))
+)
+
+
+def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement, pp.ParserElement]:
+    """The arithmetic grammar, the expression grammar that puts one comparison over it, and a column selection.
 
     ``inf`` is a ``pp.Keyword`` rather than a ``pp.Literal``, which would
     match the prefix of ``inflow``.
@@ -235,10 +266,10 @@ def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement]:
     name = pp.Regex(NAME)
 
     quoted = (pp.QuotedString("'") | pp.QuotedString('"')).set_parse_action(lambda t: KeywordNode(str(t[0])))
-    name_list = (pp.Suppress('[') + pp.DelimitedList(name) + pp.Suppress(']')).set_parse_action(
-        lambda t: NameListNode(tuple(str(x) for x in t))
+    columns = (name + pp.Suppress('[') + pp.DelimitedList(name) + pp.Suppress(']')).set_parse_action(
+        lambda t: ColumnsNode(str(t[0]), tuple(str(x) for x in t[1:]))
     )
-    kwarg = (name + pp.Suppress('=') + (quoted | name_list | arith)).set_parse_action(lambda t: (t[0], t[1]))
+    kwarg = (name + pp.Suppress('=') + (quoted | columns | NAME_LIST | arith)).set_parse_action(lambda t: (t[0], t[1]))
     pos_arg = arith
     arg_list = pp.Optional(pp.DelimitedList(kwarg | pos_arg))
     func_call = (name + pp.Suppress('(') + arg_list + pp.Suppress(')')).set_parse_action(_make_func_call)
@@ -264,7 +295,7 @@ def _build_grammar() -> tuple[pp.ParserElement, pp.ParserElement]:
     expression = (arith + pp.Optional(comparator + arith)).set_parse_action(
         lambda t: ComparisonNode(t[1], t[0], t[2]) if len(t) == 3 else t[0]
     )
-    return arith, expression
+    return arith, expression, columns
 
 
 def _make_func_call(tokens: pp.ParseResults) -> FunctionCallNode:
@@ -282,7 +313,7 @@ def keywords[V](name: str, pairs: Iterable[tuple[str, V]]) -> dict[str, V]:
     kwargs: dict[str, V] = {}
     for key, value in pairs:
         if key in kwargs:
-            msg = f'{name}({key}=) is given twice. A keyword names one value; drop one of them.'
+            msg = f'{name}({key}=) is given twice. Delete one of them.'
             raise SchemaError(msg)
         kwargs[key] = value
     return kwargs
@@ -304,7 +335,9 @@ def _make_power(tokens: pp.ParseResults) -> ArithmeticNode:
 
 #: The arithmetic half on its own, for the where grammar to put a predicate's
 #: comparator over: one grammar for what a side may say, wherever it stands.
-ARITHMETIC, _GRAMMAR = _build_grammar()
+#: The column selection is shared too, so a kwarg reads one the same way in
+#: both grammars.
+ARITHMETIC, _GRAMMAR, COLUMNS = _build_grammar()
 
 
 #: How deep a tree the language admits. Every pass over an expression recurses,
@@ -359,7 +392,7 @@ def parse_text[T](
         result = grammar.parse_string(text, parse_all=True)
     except pp.ParseException as e:
         hint = rewrite(text, e.loc)
-        msg = f'Failed to parse {what}: {text!r}\n{f"{hint}\n" if hint is not None else ""}{e}'
+        msg = f'Cannot parse the {what} {text!r}.\n{f"{hint}\n" if hint is not None else ""}{e}'
         raise SchemaError(msg) from e
     except RecursionError:
         raise SchemaError(_too_deep(what, text, None, deep_rewrite)) from None
@@ -377,22 +410,13 @@ def _named_rewrite(text: str, loc: int) -> str | None:
     """
     rest = text[loc:].lstrip()
     if rest.startswith(get_args(ComparisonOperator)):
-        return (
-            f"'{rest[:2]}' follows a complete comparison, and an expression carries "
-            f'one comparison, at the top. Split the chain into two constraints.'
-        )
+        return f"'{rest[:2]}' follows a complete comparison. Split the chain into two constraints."
     if rest.startswith('!='):
-        return (
-            "'!=' is not a constraint sense — the senses are <=, >= and ==. "
-            'Holding rows apart is a where matter: write the test in where:, where != is legal.'
-        )
+        return "'!=' is not a constraint sense. Write <=, >= or ==, or move the != test to where:."
     if rest.startswith(('<', '>')):
-        return f"'{rest[0]}' is not a constraint sense — the senses are <=, >= and ==. Write the bound inclusive."
+        return f"'{rest[0]}' is not a constraint sense. Write '{rest[0]}=' instead."
     if rest.startswith('='):
-        return (
-            "'=' on its own is how a kwarg is written inside a call, like sum(x, over=d). "
-            'Equality between two sides is written ==.'
-        )
+        return "A single '=' passes a keyword argument, as in sum(x, over=d). Write == for equality."
     if rest.startswith('^'):
         return "power is written '**', not '^'."
     return None