Documentation
¶
Overview ¶
Package compat reads the compat entries of a feature (spec 09.2), the probes that prove them (09.4), and the register of the implementations of each language.
Index ¶
- Constants
- func Edition(s, def string) string
- func Key(feature, impl, probe, added string) string
- func ProbeHash(dir, probe string, e Expect) (string, error)
- func ReadExpect(dir string) (map[string]Expect, error)
- type Entry
- type Expect
- type Impl
- type Prober
- type Register
- type Result
- type Results
- type Run
- type Statement
- type Task
Constants ¶
const ResultsFile = "manifests/probes.jsonl"
ResultsFile is the file of the content repository where prog compat probe records its results.
Variables ¶
This section is empty.
Functions ¶
func Edition ¶
Edition returns the first edition of a statement, such as 2018 for "2018+", and def when the statement has none.
func Key ¶
Key identifies the result of a probe of a feature for an implementation and a version_added.
Types ¶
type Entry ¶
type Entry struct {
Key string `json:"key"`
Description string `json:"description"`
Spec map[string]string `json:"spec,omitempty"`
Source map[string]string `json:"source,omitempty"`
// Support maps an implementation column to its statements. Most columns have one statement. A column has more than one when the answer differs by edition or by flag.
Support map[string][]Statement `json:"support"`
// Columns are the keys of Support in the order of the file.
Columns []string `json:"-"`
Status map[string]bool `json:"status,omitempty"`
Line int `json:"-"`
// Unknown are the keys of the entry that the schema does not have.
Unknown []string `json:"-"`
}
Entry is one compat entry. The key of the first entry is the slug of the feature. The keys of the other entries add a dot and a sub-feature, such as match-statement.class-patterns.
type Expect ¶
type Expect struct {
// Output is the standard output that the probe must give where it passes. When it is empty, exit status 0 is enough.
Output string `yaml:"output,omitempty" json:"output,omitempty"`
// FailsWith is a regular expression that the output of the probe must match on the release before version_added (rule K05).
FailsWith string `yaml:"fails_with,omitempty" json:"fails_with,omitempty"`
}
Expect is what a probe must do (spec 09.4). It comes from the file probes/probes.yaml of the feature, keyed by the name of the probe file.
type Impl ¶
type Impl struct {
ID string `yaml:"id" json:"id"`
Name string `yaml:"name" json:"name"`
// Standard is true for a column that is the language standard, such as c++20, not a program.
Standard bool `yaml:"standard,omitempty" json:"standard,omitempty"`
// Main is true for the implementations that the computed status counts (spec 09.5).
Main bool `yaml:"main,omitempty" json:"main,omitempty"`
// Image is the container image of a release, with {v} for the version, such as python:{v}-slim. Probe runs a probe in it.
Image string `yaml:"image,omitempty" json:"image,omitempty"`
// Run is the command that runs a probe, with {file} for the path of the probe in the container.
Run []string `yaml:"run,omitempty" json:"run,omitempty"`
// Releases are the releases of the implementation, oldest first. Rule K02 checks each version_added against this list, and probe takes the release before from it.
Releases []string `yaml:"releases,omitempty" json:"releases,omitempty"`
}
Impl is one implementation column of a language, from registers/implementations.yaml.
type Prober ¶
type Prober struct {
// Engine is the container command, such as docker or podman.
Engine string
// Timeout limits one run, including the compile step.
Timeout time.Duration
// Exec runs a command and returns its combined output and exit code. Tests replace it. The default runs the command with os/exec.
Exec func(ctx context.Context, name string, args ...string) (string, int, error)
// contains filtered or unexported fields
}
Prober runs probes in containers (spec 09.4). Each run gets a new container with no network, a read-only root and a small writable /tmp.
type Register ¶
Register maps a language id to its implementation columns, in the order of the file.
func ReadRegister ¶
ReadRegister reads registers/implementations.yaml under root. A missing file gives an empty register.
type Result ¶
type Result struct {
// Feature is the slug of the feature, and Probe is the path of the probe file in the node directory, such as probes/match_basic.py.
Feature string `json:"feature"`
Impl string `json:"impl"`
Probe string `json:"probe"`
Added string `json:"version_added"`
// Hash is the SHA-256 of the probe file and of its entry in probes.yaml. A result with an old hash does not count.
Hash string `json:"hash"`
Pass Run `json:"pass"`
// Fail is the run on the release before version_added. It is nil when the register has no release before.
Fail *Run `json:"fail,omitempty"`
Date string `json:"date"`
}
Result is the record of one probe for one implementation and one version_added (spec 09.4).
type Results ¶
Results maps Key to the result.
func ReadResults ¶
ReadResults reads manifests/probes.jsonl under root. A missing file gives no results.
type Run ¶
type Run struct {
Version string `json:"version"`
Image string `json:"image"`
// OK tells if the run did what the check needs: exit 0 and the output for the pass run, a failure that matches the signature for the fail run.
OK bool `json:"ok"`
Exit int `json:"exit"`
Output string `json:"output,omitempty"`
Error string `json:"error,omitempty"`
}
Run is one run of a probe.
type Statement ¶
type Statement struct {
// Added is the version_added: a version, "false" for not supported, or "preview". It is empty when the field is missing, and "true" or "null" when the file has these values, so that rule K01 can find them.
Added string `json:"version_added"`
Removed string `json:"version_removed,omitempty"`
Deprecated string `json:"version_deprecated,omitempty"`
Flags []string `json:"flags,omitempty"`
Partial bool `json:"partial_implementation,omitempty"`
AltName string `json:"alternative_name,omitempty"`
Edition string `json:"edition,omitempty"`
Std string `json:"std,omitempty"`
Note string `json:"notes,omitempty"`
Probe string `json:"probe,omitempty"`
Source string `json:"source,omitempty"`
Line int `json:"-"`
Unknown []string `json:"-"`
}
Statement is one support statement of an implementation (spec 09.2).
type Task ¶
type Task struct {
Feature string
// Dir is the node directory on the host.
Dir string
Impl Impl
Probe string
Added string
Expect Expect
// Edition is the edition of the statement, such as 2018 for "2018+". It fills {edition} in the run command.
Edition string
}
Task is one probe to prove: a statement of an entry for one implementation.