pygments-pss

A Pygments lexer for the Accellera Portable Test and Stimulus Standard (PSS), packaged as a plugin. Installing it is the entire configuration step:

pip install pygments-pss

After that, pss is a language Pygments knows about everywhere it looks — no conf.py entry, no mkdocs.yml entry, no registration call:

pygmentize -l pss my_test.pss

```pss
component pss_top {
    action entry {
        activity {
            do mem_write;
        }
    }
}
```

Targets PSS 3.1 (Draft 19), including annotations, monitors, behavioral coverage and triple-quoted target templates, and lexes earlier revisions unchanged.

Why

Pygments ships no PSS lexer, so every documentation pipeline that shows PSS either renders it as plain text or hand-rolls a lexer. This is that lexer, once, with tests.

Usage

Sphinx — nothing to configure; the entry point is enough.

.. code-block:: pss

   component pss_top { }

MyST/Markdown fences (```pss) work the same way. Options go through highlight_options:

highlight_options = {"pss": {"builtins": False}}

MkDocs — install the package; pymdownx.highlight picks it up. No mkdocs.yml change is needed beyond whatever highlighting extension you already use.

Command line

pygmentize -l pss -f html -O full,style=friendly -o out.html my_test.pss
pygmentize -S friendly -f html > pygments.css     # stylesheet for fragments
pygmentize -l pss -f terminal256 my_test.pss      # 256-colour terminal

Python

from pygments import highlight
from pygments.formatters import HtmlFormatter
from pygments.lexers import get_lexer_by_name

print(highlight(source, get_lexer_by_name("pss"), HtmlFormatter()))

Options

Two further options — dialect (standard versus pssparser extensions) and target_lexers (lex a exec body C = """…""" body as C/C++/SystemVerilog) — are designed but not implemented in this release.

What gets highlighted

Known deviations and false positives

Kept short and honest rather than absent:

• Whitespace-separated based literals are not supported. The LRM permits 8'h FF; supporting it costs a lookahead and risks mis-lexing 8'h followed by an unrelated identifier. 8'hFF is the supported form.
• An escaped identifier runs to whitespace, so \net1; includes the semicolon. That is Clause 4.3's rule, not a defect — the terminator is white space and nothing else. Write \net1 ; if you want the semicolon back.
• A user-defined name that shadows a core-library name is highlighted as a builtin. A RegexLexer has no scope information. Turn it off with builtins=False.
• numeric is not treated as a keyword. It appears in pssparser's token list and in a damaged cell of the LRM's keyword table, but nowhere in the Annex B grammar. Highlighting a non-keyword is a visible error; missing one is mild.
• Tool extensions are not keywords: pyimport, pyobj, from, init, option are pssparser reservations, not PSS.
• Template parameter brackets are not special. < and > stay Operator; distinguishing them from comparison needs a parser. One consequence: a templated declaration's base type (struct s<type T> : base_s) is not highlighted as a class.
• A typedef's declared name is an ordinary Name, because in typedef bit[3:0] nibble_t; the name comes after an arbitrary type expression.

Requirements

Python 3.9+ and Pygments 2.14+. No other runtime dependency: no parser, no ANTLR, no compiler.

License

Apache-2.0. See LICENSE.