.editorconfig

+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+#
 # https://editorconfig.org/
 
 root = true
@@ -27,6 +30,14 @@ indent_size = 4
 indent_style = tab
 tab_size = 8
 
+[*.toml]
+indent_style = space
+indent_size = 2
+
+[*.yml]
+indent_style = space
+indent_size = 2
+
 [setup.cfg]
 indent_style = space
 indent_size = 4

.gitignore

+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+
+site/
+.mypy_cache/
+.tox/
+
+**/__pycache__/

.readthedocs.yaml

+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+
+version: 2
+
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3.12"
+
+mkdocs:
+    configuration: mkdocs.yml
+
+python:
+    install:
+        - requirements: requirements/docs.txt

CHANGELOG.md

-# Changelog
-
-All notable changes to the parse-stages project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [0.1.0] - 2023-01-25
-
-### Started
-
-- First public release.
-
-[0.1.0]: https://gitlab.com/ppentchev/parse-stages/-/tags/release%2F0.1.0

LICENSES/BSD-2-Clause.txt

+Copyright (c) <year> <owner> 
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

-include .editorconfig
-include CHANGELOG.md
-recursive-include nix *.nix *.sh
-recursive-include requirements *.txt
-include tox.ini
-recursive-include unit_tests *.py

README.md

+<!--
+SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+SPDX-License-Identifier: BSD-2-Clause
+-->
+
 # Parse a mini-language for selecting objects by tag or name
 
+\[[Home][ringlet-parse-stages] | [GitLab][gitlab] | [PyPI][pypi] | [ReadTheDocs][readthedocs]\]
+
 This library is mostly useful for command-line parsing by other tools like
 `tox-stages` and `nox-stages`. It may be used to parse e.g. a command-line
 specification like `@check and not pylint` or `@tests or ruff` and then
@@ -30,10 +37,9 @@ Thus, all of the following:
 - `pep8 or not @quick and @check`
 
 ...are valid expressions,
-with the "not", "and", and "or" keywords having their usual priorities
+with the "not", "and", and "or" keywords having their usual precedence
 (`pep8 or not @quick and @check` is parsed as
-`pep8 or ((@not quick) and @check)`, but the mini-language does not
-support parentheses yet).
+`pep8 or ((@not quick) and @check)`).
 
 ## Check whether an object matches a parsed specification
 
@@ -99,7 +105,11 @@ Select the test environments that match the specification:
 ## Contact
 
 The `parse-stages` library was written by [Peter Pentchev][roam].
-It is developed in [a GitLab repository][gitlab].
+It is developed in [a GitLab repository][gitlab]. This documentation is
+hosted at [Ringlet][ringlet-parse-stages] with a copy at [ReadTheDocs][readthedocs].
 
 [roam]: mailto:roam@ringlet.net "Peter Pentchev"
 [gitlab]: https://gitlab.com/ppentchev/parse-stages "The parse-stages GitLab repository"
+[pypi]: https://pypi.org/project/parse-stages/ "The parse-stages Python Package Index page"
+[readthedocs]: https://parse-stages.readthedocs.io/ "The parse-stages ReadTheDocs page"
+[ringlet-parse-stages]: https://devel.ringlet.net/devel/parse-stages/ "The Ringlet parse-stages homepage"

docs/api.md

+<!--
+SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+SPDX-License-Identifier: BSD-2-Clause
+-->
+
+# API Reference
+
+## The tagged object classes
+
+::: parse_stages.Tagged
+
+::: parse_stages.TaggedFrozen
+
+## The evaluated boolean expression
+
+::: parse_stages.BoolExpr
+
+::: parse_stages.OrExpr
+
+::: parse_stages.AndExpr
+
+::: parse_stages.NotExpr
+
+## The object's tags and keywords
+
+::: parse_stages.TagExpr
+
+::: parse_stages.KeywordExpr
+
+## The helper functions
+
+::: parse_stages.EMPTY_SET_SPECS
+
+::: parse_stages.parse_spec
+
+::: parse_stages.parse_stage_ids

docs/changes.md

+<!--
+SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+SPDX-License-Identifier: BSD-2-Clause
+-->
+
+# Changelog
+
+All notable changes to the parse-stages project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.9] - 2024-08-09
+
+### Semi-incompatible changes
+
+- Drop support for Python 3.8 and 3.9
+
+### Fixes
+
+- Fix the logic in a "this should never happen anyway" check for
+  the `pyparsing` parser returning invalid results
+- Nix expressions:
+    - run `python3.X`, not `python3`, so as to not accidentally invoke
+      a "more preferred" Python version that is also installed in
+      the Nix environment
+
+### Other changes
+
+- Let Ruff insist on trailing commas when formatting the source code
+- Use `list` instead of `typing.List` for the dataclass member fields
+- Simplify the expression parser by using structural pattern matching
+- Use `typeA | typeB | typeC` as a type parameter to `isinstance()`
+- Documentation:
+    - use mkdocstrings 0.25 with no changes
+- Test suite:
+    - Ruff:
+        - fold the "all" configuration into the `pyproject.toml` file and
+          move the "base" one to the `ruff-base.toml` file in the top-level directory
+        - use Ruff 0.5.7
+        - drop the override for the no longer emitted `ANN101`
+        - add global overrides for the new docstring-related `DOC201` and `DOC501`
+    - use Reuse 4.x with no changes
+    - vendor-import vetox 0.2.0 and use it with no changes
+- Nix expressions:
+    - drop Python 3.8 from the `run-*.sh` helpers, it was dropped form nixpkgs/unstable
+    - run pytest on Python 3.13, too
+    - run tox on Python 3.12 and 3.13, too
+    - update the vendored copy of vetox to version 0.1.3
+    - run vetox with support for [uv](https://github.com/astral-sh/uv) and
+      [tox-uv](https://github.com/tox-dev/tox-uv)
+    - when running `uv`, use `/etc/ssl/certs/ca-certificates.crt` as the path to
+      the system-wide certificates file; allow it to be overridden using
+      the `VETOX_CERT_FILE` environment variable
+    - only pass the minor version of Python, we only support Python 3.x
+    - pass the Python minor version as a string for easier interpolation
+
+## [0.1.8] - 2024-02-08
+
+### Additions
+
+- Support parentheses in stage specifications, e.g. `(@check or @docs) and not @manual`
+- Tentatively declare Python 3.13 as a supported version
+- Documentation:
+    - add a "Download" page
+- Test suite:
+    - vendor-import [the vetox testing tool](https://devel.ringlet.net/devel/vetox/)
+    - add a Nix expression to run `vetox`
+
+### Other changes
+
+- Completely switch to Ruff for source code formatting
+- Test suite:
+    - use Ruff 0.2.1:
+        - derive an abstract class directly from `abc.ABC`, no need for the metaclass
+        - sort the list of exported symbols (`__all__`)
+        - add an empty line to the end of the "Examples" docstring section
+        - push some Ruff configuration settings into the `ruff.lint.*` hierarchy
+    - use Pytest 8.x and also install Pygments for syntax highlighting
+    - push the unit tests' source from `unit_tests/` into `tests/unit/`
+    - also build the documentation in the second Tox stage
+    - put the Tox stage specifications in the `pyproject.toml` file on separate lines
+    - let `reuse` ignore the `.mypy_cache/` directory, too
+
+## [0.1.7] - 2023-11-08
+
+### Fixes
+
+- Documentation:
+    - fix the ReadTheDocs build by adding the `build` section to its configuration
+
+### Additions
+
+- Test suite:
+    - also run the Ruff formatter in the `format` Tox check environment
+    - add a "reformat-ruff" Tox environment that uses the Ruff formatter
+    - add the "reuse" environment to the list of Tox environments to run by
+      default and install Git in the Nix derivation since the `reuse` tool
+      uses it to figure out which files to check
+
+### Other changes
+
+- Documentation:
+    - use mkdocstrings 0.23 with no changes
+- Test suite:
+    - use Ruff 0.1.4:
+        - specify the copyright notice pattern for Ruff to look for
+    - let Ruff also reformat the docstrings in addition to the import blocks
+    - move the "reuse" Tox test environment to the first (quick) stage
+
+## [0.1.6] - 2023-09-28
+
+### Other changes
+
+- Test suite:
+    - use a pinned version of Ruff to avoid breakage with changes enabled in
+      future versions
+    - use Ruff 0.0.291, add a forgotten deferred annotations import
+    - move the "format" check to the first Tox stage
+    - use black 23.7 or later so it understands "py312" as a supported version
+    - use reuse 2.x with no changes
+
+## [0.1.5] - 2023-06-27
+
+### Fixes
+
+- Build infrastructure:
+    - relax the `hatch-requirements-txt` to >= 0.3, which is the version in
+      Debian testing/unstable
+    - specify a lower requirement for `hatchling` as >= 1.8, which is
+      the version in Ubuntu 22.10 (kinetic)
+    - specify an upper requirement for `hatchling`
+- Main source:
+    - do not disable all Flake8 / Ruff checks for three files!
+    - fix some formatting nits in the newly-checked source files
+- Test suite:
+    - drop the `pyupgrade` environment from Tox's default envlist;
+      there is (by design) no way to run it in a no-op, report-only mode
+    - do not pass the `python_version` option to `mypy`, let it check
+      the code with regard to the currently-running Python interpreter
+
+### Additions
+
+- Build infrastructure:
+    - specify the project license
+    - add some more PyPI trove classifiers
+- Test suite:
+    - introduce the `PY_MINVER_MIN` and `PY_MINVER_MAX` environment variables for
+      the `nix/run-pytest.sh` helper tool so that e.g. the current flakiness of
+      Python 3.12 in nixpkgs-unstable can be skipped
+    - add a Nix expression and the `nix/run-tox.sh` helper tool to run
+      all the Tox tests using a different Python version
+    - also include the `reuse` Tox environment in the ones run at the `@check`
+      stage using the `tox-stages` tool
+
+### Other changes
+
+- Main source:
+    - replace assertions in the parsing code with `if` statements that
+      raise our own exceptions
+- Documentation:
+    - refer to version 1.1.0 of the "Keep a Changelog" format specification
+    - use `mkdocstrings` 0.22, no changes
+- Test suite:
+    - drop the `flake8` / `pep8`, `pylint`, and `pydocstyle`
+      Tox test environments, Ruff handles most of these checks now
+    - use Ruff 0.0.275, activate all the new check areas, just in case
+    - use mypy 1.x, no changes
+
+## [0.1.4] - 2023-05-13
+
+### Additions
+
+- Documentation:
+    - add a [ReadTheDocs mirror](https://parse-stages.readthedocs.io/)
+- Main source:
+    - `parse_stage_ids()`: allow an empty set to be specified by the exact
+      strings "", "0", or "none"
+
+### Other changes
+
+- Build system:
+    - drop the obsolete `tool.setuptools.*` sections from the `pyproject.toml` file
+- Documentation:
+    - bump the version of `mkdocstrings-python` with no changes
+- Test suite:
+    - Ruff:
+        - use Ruff 0.0.267, enable the `FLY` checks area
+
+## [0.1.3] - 2023-05-07
+
+### Fixes
+
+- Add a blank line to a docstring section (ruff D214).
+- Drop the text in a `NotImplementedError` raised in an abstract method;
+  it should be obvious (ruff EM101)
+
+### Additions
+
+- Add a `.gitignore` file, mostly so that `reuse` can be run at any time
+- Add a "Home, GitLab, PyPI" navigational line to the documentation
+  index page and to the `README.md` file
+
+### Other changes
+
+- Main source:
+    - reformat the import sections using Ruff's `isort` implementation
+- Build system:
+    - switch to `hatch` / `hatchling` for the PEP517 build
+- Documentation:
+    - use the `default_handler` configuration option of `mkdocstrings`
+      instead of specifying `handler: python` for each class!
+    - bump the versions of `mkdocstrings` and `mkdocstrings-python` with
+      no changes
+- Test suite:
+    - specify 4.1 as the Tox minimum version and switch to the Tox 4.x
+      format for the multiline list of files
+    - rename the `black` Tox environment to `format` and
+      the `black-reformat` one to `reformat`, since they also run
+      Ruff's `isort` now
+    - Ruff:
+        - use Ruff 0.0.265, enable the `INT` checks area although
+          we do not use gettext
+        - enable all ruff check areas in `config/ruff-most/`, let
+          the `config/ruff-base/` files take care of the ignored ones
+        - no longer disable the "relative imports" check, it does not
+          complain about our source code
+    - Pylint:
+        - reenable the "empty comment" plugin; we should have no
+          trouble with it since switching to SPDX license tags
+    - Bump the versions of `flake8-implicit-str-concat`, `flake8-simplify`,
+      `pylint`, and `triceratops` with no code changes
+
+## [0.1.2] - 2023-03-10
+
+### Semi-incompatible changes
+
+- Drop Python 3.7 support.
+
+### Fixes
+
+- Fix the 0.1.1 release URL in the changelog file.
+- Do not run the `pyupgrade` Tox environment automatically.
+- Add a docstring to the unit test suite's `__init__.py` file instead of
+  overriding a linter check.
+
+### Additions
+
+- Start some MkDocs-based documentation.
+- Add the `reuse` Tox test environment to run the REUSE tool manually.
+
+### Other changes
+
+- Rework the Ruff invocation Tox targets a bit:
+    - drop the `ruff-all-unchained` test environment; at this point in
+      Ruff's development we are bound to specific versions anyway
+    - move the config files to a `config/` directory, not `.config/`
+    - move the "normal" Ruff invocation configuration to `config/ruff-most/`
+    - use Ruff 0.0.254 with no code changes
+    - activate all of Ruff 0.0.254's liners in the "normal" invocation
+- Switch to SPDX license tags.
+- Specify the supported Python version in the configuration of the pylint and
+  black tools.
+- Move the changelog file into the documentation directory.
+- In the packaging metadata, point to the Ringlet homepage generated from
+  the newly-added documentation.
+
+## [0.1.1] - 2023-02-05
+
+### Fixes
+
+- Use "precedence" instead of "priority" when discussing operators in
+  the README file.
+- Do not use the `list` generic type in the definition of the `TaggedFrozen` and
+  `Tagged` classes; library consumers may try to use `typing.get_type_hints()` on
+  them or on derived classes, and Python < 3.9 would have a problem with that.
+- Fill in the module docstring using the text of the README file.
+- Fix some problems reported by `ruff`:
+    - fix the order of some `import` statements
+    - fix the formatting of some docstrings
+
+### Other changes
+
+- Add the `ruff-all` test environment that enables all the checks of the `ruff`
+  tool for a certain locked version of `ruff`.
+- Add the `tool.test-stages` section in the `pyproject.toml` file to specify
+  the order that Tox environments should be run during development using
+  the `tox-stages` tool from the `test-stages` Python library.
+- Add a lot of `flake8` plugins to the Tox `pep8` test environment
+- Use ruff 0.0.241, pylint 2.16.x, and black 23.x.
+
+## [0.1.0] - 2023-01-25
+
+### Started
+
+- First public release.
+
+[Unreleased]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.9...main
+[0.1.9]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.8...release%2F0.1.9
+[0.1.8]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.7...release%2F0.1.8
+[0.1.7]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.6...release%2F0.1.7
+[0.1.6]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.5...release%2F0.1.6
+[0.1.5]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.4...release%2F0.1.5
+[0.1.4]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.3...release%2F0.1.4
+[0.1.3]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.2...release%2F0.1.3
+[0.1.2]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.1...release%2F0.1.2
+[0.1.1]: https://gitlab.com/ppentchev/parse-stages/-/compare/release%2F0.1.0...release%2F0.1.1
+[0.1.0]: https://gitlab.com/ppentchev/parse-stages/-/tags/release%2F0.1.0

docs/download.md

+<!--
+SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+SPDX-License-Identifier: BSD-2-Clause
+-->
+
+# Download
+
+These are the released versions of [parse-stages](index.md) available for download.
+
+## [0.1.9] - 2024-08-09
+
+### Source tarball
+
+- [parse_stages-0.1.9.tar.gz](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.9.tar.gz)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.9.tar.gz.asc))
+
+### Python wheel
+
+- [parse_stages-0.1.9-py3-none-any.whl](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.9-py3-none-any.whl)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.9-py3-none-any.whl.asc))
+
+## [0.1.8] - 2024-02-08
+
+### Source tarball
+
+- [parse_stages-0.1.8.tar.gz](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.8.tar.gz)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.8.tar.gz.asc))
+
+### Python wheel
+
+- [parse_stages-0.1.8-py3-none-any.whl](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.8-py3-none-any.whl)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.8-py3-none-any.whl.asc))
+
+## [0.1.7] - 2023-11-08
+
+### Source tarball
+
+- [parse_stages-0.1.7.tar.gz](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.7.tar.gz)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.7.tar.gz.asc))
+
+### Python wheel
+
+- [parse_stages-0.1.7-py3-none-any.whl](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.7-py3-none-any.whl)
+  (with [a PGP signature](https://devel.ringlet.net/files/devel/parse-stages/parse_stages-0.1.7-py3-none-any.whl.asc))
+
+[0.1.9]: https://gitlab.com/ppentchev/parse-stages/-/tags/release%2F0.1.9
+[0.1.8]: https://gitlab.com/ppentchev/parse-stages/-/tags/release%2F0.1.8
+[0.1.7]: https://gitlab.com/ppentchev/parse-stages/-/tags/release%2F0.1.7

docs/index.md

+<!--
+SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+SPDX-License-Identifier: BSD-2-Clause
+-->
+
+# Parse a mini-language for selecting objects by tag or name
+
+\[[Home][ringlet-parse-stages] | [GitLab][gitlab] | [PyPI][pypi] | [ReadTheDocs][readthedocs]\]
+
+## Overview
+
+The `parse-stages` Python library may be used by other tools to group
+objects (e.g. [Tox] or [Nox] test environments) for step-by-step processing
+(e.g. running some tests in parallel, then only running others if the first
+group passes).
+
+The language used by the library is described in the
+[_Grouping stages_](language.md#grouping-stages-for-step-by-step-execution)
+section.
+
+[tox]: https://tox.wiki/en/latest/ "The tox automation project"
+[nox]: https://nox.thea.codes/en/stable/ "The nox flexible automation tool"
+
+## Installation
+
+A program that uses the `parse-stages` library should specify it in
+its list of requirements, e.g. using [PEP508][pep508] syntax:
+
+    parse-stages >= 0.1.9, < 0.2
+
+[pep508]: https://peps.python.org/pep-0508/ "PEP 508 – Dependency specification for Python Software Packages"
+
+## Parsing a stage specification
+
+The `parse_spec()` function parses a string specification into
+a [BoolExpr][parse_stages.BoolExpr] object that may later be used to
+select matching objects (e.g. test environments).
+
+``` py
+    e_check = parse_stages.parse_spec("@check")
+    e_check_quick = parse_stages.parse_spec("@check and @quick")
+    e_check_no_ruff = parse_stages.parse_spec("@check and not ruff")
+    
+    specs = [(spec, parse_stages.parse_spec(spec)) for spec in args.stage_specs]
+```
+
+## Check whether an object matches a parsed specification
+
+The `parse-stages` library provides two base dataclasses for objects that
+may be matched against parsed expressions:
+[TaggedFrozen][parse_stages.TaggedFrozen] and [Tagged][parse_stages.Tagged].
+Both classes have the same members:
+
+- [name][parse_stages.TaggedFrozen.name]: a string
+- [tags][parse_stages.TaggedFrozen.tags]: a list of strings
+- [get_keyword_haystacks()][parse_stages.TaggedFrozen.get_keyword_haystacks]:
+  a method that returns a list of strings,
+  `self.name` unless overridden
+
+When a `BoolExpr` object's [evaluate()][parse_stages.BoolExpr.evaluate]
+method is called for a specific
+`TaggedFrozen` or `Tagged` object, it checks whether the specification
+matches the tags and keywords defined for this object. Tags are matched
+exactly, while a keyword is considered to match if it is contained in
+the checked string; e.g. `pep` would match both `pep8` and `exp_pep563`,
+while `@black` would not match a `black-reformat` tag.
+
+The `get_keyword_haystacks()` method returns the strings to look in for
+matching keywords. By default, it only returns the `name` field;
+however, it may be extended, e.g. for Nox sessions it may also return
+the name of the Python function that implements the session, for test
+classes with methods it may return the class name and the method name, etc.
+
+``` py
+    # Obtain a list (okay, a dictionary) of test environments in some way
+    tox_envs = get_tox_environments()  # {"ruff": {"tags": ["check", "quick"]}, ...}
+
+    # Convert them to objects that the parsed expressions can match
+    all_envs = [
+        parse_stages.TaggedFrozen(name, env["tags"])
+        for name, env in tox_envs.items()
+    ]
+
+    # Or define our own class that may hold additional information
+    @dataclasses.dataclass(frozen=True)
+    class TestEnv(parse_stages.TaggedFrozen):
+        """A single test environment: name, tags, etc."""
+        ...
+
+    all_envs = [TestEnv(name, env["tags"], ...) for name, env in tox_envs.items()]
+
+    # Select the ones that match the "@check" expression
+    matched = [env for env in all_envs if e_check.evaluate(env)]
+
+    # Or if we only care about the names...
+    quick_names = [env.name for env in all_envs if e_check_quick.evaluate(env)]
+```
+
+## Contact
+
+The `parse-stages` library was written by [Peter Pentchev][roam].
+It is developed in [a GitLab repository][gitlab]. This documentation is
+hosted at [Ringlet][ringlet-parse-stages] with a copy at [ReadTheDocs][readthedocs].
+
+[roam]: mailto:roam@ringlet.net "Peter Pentchev"
+[gitlab]: https://gitlab.com/ppentchev/parse-stages "The parse-stages GitLab repository"
+[pypi]: https://pypi.org/project/parse-stages/ "The parse-stages Python Package Index page"
+[readthedocs]: https://parse-stages.readthedocs.io/ "The parse-stages ReadTheDocs page"
+[ringlet-parse-stages]: https://devel.ringlet.net/devel/parse-stages/ "The Ringlet parse-stages homepage"

docs/language.md

+<!--
+SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+SPDX-License-Identifier: BSD-2-Clause
+-->
+
+# The Specification Mini-Language
+
+## Grouping stages for step-by-step execution
+
+The specification mini-language may roughly be described as:
+
+    expr ::= and_expr ["or" and_expr...]
+    and_expr ::= not_expr ["and" not_expr...]
+    not_expr ::= ["not"] atom
+    atom ::= tag | keyword | "(" expr ")"
+    tag ::= "@" characters
+    keyword ::= characters
+    characters ::= [A-Za-z0-9_-]+
+
+Thus, all of the following:
+
+- `@check`
+- `@check and @quick`
+- `@tests and not examples`
+- `not @tests`
+- `pep8 or not @quick and @check`
+- `not (@check or @tests) and @quick`
+
+...are valid expressions,
+with the "not", "and", and "or" keywords having their usual precedence
+(`pep8 or not @quick and @check` is parsed as
+`pep8 or ((@not quick) and @check)`).

mkdocs.yml

+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - toc.integrate
+    - toc.follow
+    - content.code.copy
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+site_name: parse-stages
+repo_url: https://gitlab.com/ppentchev/parse-stages
+repo_name: parse-stages
+site_author: ppentchev
+site_url: https://devel.ringlet.net/devel/parse-stages/
+site_dir: site/docs
+nav:
+  - 'index.md'
+  - 'Download': 'download.md'
+  - 'Changelog': 'changes.md'
+  - 'Language reference': 'language.md'
+  - 'API reference': 'api.md'
+markdown_extensions:
+  - toc:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite:
+  - pymdownx.superfences:
+plugins:
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [src]
+          options:
+            heading_level: 3
+            show_root_heading: true
+  - search
+watch:
+  - 'src/parse_stages'

nix/cleanpy.sh

+#!/bin/sh
+#
+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+
+set -e
+
+find . -mindepth 1 -maxdepth 1 -type d \( \
+	-name '.tox' \
+	-or -name '.mypy_cache' \
+	-or -name '.pytest_cache' \
+	-or -name '.nox' \
+	-or -name '.ruff_cache' \
+\) -exec rm -rf -- '{}' +
+find . -type d -name '__pycache__' -exec rm -rfv -- '{}' +
+find . -type f -name '*.pyc' -delete -print
+find . -mindepth 1 -maxdepth 2 -type d -name '*.egg-info' -exec rm -rfv -- '{}' +

nix/mkdocs.nix

+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+
+{ pkgs ? import <nixpkgs> { }
+, py-ver ? "11"
+}:
+let
+  python-name = "python3${py-ver}";
+  python = builtins.getAttr python-name pkgs;
+  python-pkgs = python.withPackages (p: with p;
+    [
+      mkdocs
+      mkdocs-material
+      mkdocstrings
+      mkdocstrings-python
+    ]
+  );
+in
+pkgs.mkShell {
+  buildInputs = [ python-pkgs ];
+  shellHook = ''
+    set -e
+    rm -rf site
+    python3.${py-ver} -m mkdocs build
+    exit
+  '';
+}

nix/python-pytest.nix

+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+
 { pkgs ? import <nixpkgs> { }
-, py-ver ? 311
+, py-ver ? "11"
 }:
 let
-  python-name = "python${toString py-ver}";
+  python-name = "python3${py-ver}";
   python = builtins.getAttr python-name pkgs;
   python-pkgs = python.withPackages (p: with p; [ pyparsing pytest ]);
 in
@@ -10,7 +13,7 @@ pkgs.mkShell {
   buildInputs = [ python-pkgs ];
   shellHook = ''
     set -e
-    PYTHONPATH="$(pwd)/src" python3 -m pytest -v unit_tests
+    PYTHONPATH="$(pwd)/src" python3.${py-ver} -m pytest -v tests/unit
     exit
   '';
 }

nix/python-tox.nix

+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+
+{ pkgs ? import <nixpkgs> { }
+, py-ver ? "11"
+}:
+let
+  python-name = "python3${py-ver}";
+  python = builtins.getAttr python-name pkgs;
+  python-pkgs = python.withPackages (p: with p; [ tox ]);
+in
+pkgs.mkShell {
+  buildInputs = [
+    pkgs.gitMinimal
+    python-pkgs
+  ];
+  shellHook = ''
+    set -e
+    python3.${py-ver} -m tox run-parallel
+    exit
+  '';
+}

nix/python-vetox.nix

+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
+
+{ pkgs ? import <nixpkgs> { }
+, py-ver ? "11"
+}:
+let
+  python-name = "python3${py-ver}";
+  python = builtins.getAttr python-name pkgs;
+in
+pkgs.mkShell {
+  buildInputs = [
+    pkgs.gitMinimal
+    pkgs.uv
+    python
+  ];
+  shellHook = ''
+    set -e
+    if [ -z "$VETOX_CERT_FILE" ]; then
+      VETOX_CERT_FILE='/etc/ssl/certs/ca-certificates.crt'
+    fi
+    env SSL_CERT_FILE="$VETOX_CERT_FILE" python3.${py-ver} tests/vetox.py run-parallel --tox-uv --uv
+    exit
+  '';
+}

nix/reformat.sh

 #!/bin/sh
 #
-# Copyright (c) Peter Pentchev <roam@ringlet.net>
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-# 1. Redistributions of source code must retain the above copyright
-#    notice, this list of conditions and the following disclaimer.
-# 2. Redistributions in binary form must reproduce the above copyright
-#    notice, this list of conditions and the following disclaimer in the
-#    documentation and/or other materials provided with the distribution.
-#
-# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-# SUCH DAMAGE.
+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
 
 set -e
 

nix/run-pytest.sh

 #!/bin/sh
 #
-# Copyright (c) Peter Pentchev <roam@ringlet.net>
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-# 1. Redistributions of source code must retain the above copyright
-#    notice, this list of conditions and the following disclaimer.
-# 2. Redistributions in binary form must reproduce the above copyright
-#    notice, this list of conditions and the following disclaimer in the
-#    documentation and/or other materials provided with the distribution.
-#
-# THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
-# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-# OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-# OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-# SUCH DAMAGE.
+# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
+# SPDX-License-Identifier: BSD-2-Clause
 
 set -e
 
-cleanpy()
-{
-	find . -mindepth 1 -maxdepth 1 -type d \( \
-		-name '.tox' \
-		-or -name '.mypy_cache' \
-		-or -name '.pytest_cache' \
-		-or -name '.nox' \
-		-or -name '.ruff_cache' \
-	\) -exec rm -rf -- '{}' +
-	find . -type d -name '__pycache__' -exec rm -rfv -- '{}' +
-	find . -type f -name '*.pyc' -delete -print
-	find . -mindepth 1 -maxdepth 2 -type d -name '*.egg-info' -exec rm -rfv -- '{}' +
-}
+: "${PY_MINVER_MIN:=10}"
+: "${PY_MINVER_MAX:=13}"
 
-for pyver in 38 39 310 311 312; do
-	cleanpy
-	printf -- '\n===== Running tests for %s\n\n\n' "$pyver"
-	nix-shell --pure --arg py-ver "$pyver" nix/python-pytest.nix
-	printf -- '\n===== Done with %s\n\n' "$pyver"
+for pyver in $(seq -- "$PY_MINVER_MIN" "$PY_MINVER_MAX"); do
+	nix/cleanpy.sh
+	printf -- '\n===== Running tests for 3.%s\n\n\n' "$pyver"
+	nix-shell --pure --argstr py-ver "$pyver" nix/python-pytest.nix
+	printf -- '\n===== Done with 3.%s\n\n' "$pyver"
 done