examples

package
v0.0.16 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package examples reads the fenced code blocks of the pages, runs them and checks their output (spec 07).

Index

Constants

View Source
const TestFailure = "test-failure"

TestFailure is the failure signature of a test block with fails: at least one test fails (spec 07.11).

Variables

View Source
var Expects = []string{"compile", "runtime", "exit", "exception", "error", "panic", "timeout", "sanitizer"}

Expects are the kinds of failure signature of spec 07.2.

View Source
var NorunReasons = []string{"network", "gui", "platform", "hardware", "ub", "vulnerable", "fragment", "pseudo", "long", "interactive"}

NorunReasons are the codes of spec 07.8.

View Source
var TestTimeout = time.Minute

TestTimeout is the default limit of a test block. It is longer than the limit of a run block, because it includes the build of the tests.

Functions

func Clean

func Clean(s string) string

Clean gives the text that -update writes in an output block: the run output with the line ends, the colour codes and the trailing spaces made the same as Normalize makes them.

func Collect

func Collect(file, src string, line0 int) ([]Case, []Issue)

Collect gives the cases of one Markdown file, and the issues of the rules X01 and X02. The blocks of the languages that prog run can run need a mode; the other blocks, such as text or json, do not.

func LangID

func LangID(name string) string

LangID gives the language id of a name in an info string.

func Normalize

func Normalize(s string, extra []string) string

Normalize applies the default normalizers of spec 07.6 and the extra ones that are named: addr, time, tmp, hash and float:<digits>.

func NormalizeReport added in v0.0.3

func NormalizeReport(lang, s string) string

NormalizeReport applies the normalizers of the test runner of a language to a report.

func NorunShare added in v0.0.3

func NorunShare(src string) (norun, total int)

NorunShare counts the blocks of a Markdown file for rule X08 (spec 07.8). total is the number of code blocks with a run mode, and norun is the number of them that are norun. A norun block of a group that runs is a part of a program that runs, so it does not count as norun.

func Stream

func Stream(got lang.RunResult, stream string) string

Stream gives the text of a stream of the run: stdout, stderr or both.

func Update

func Update(src string, results []Result) (string, int)

Update writes the output of the runs into the output blocks of a file (prog run -update). It replaces the text of an output block that differs from the run, and adds an output block after a run, wrong or test block that has none. The output of a test block is the report of the test runner with its normalizers (spec 07.11). It does not change an output block with match=regex or match=any, because a person wrote the pattern. The results must be of the cases of src. It returns the new text and the number of blocks that changed, and it sets Updated on each result whose blocks now match the run.

Types

type Block

type Block struct {
	// Lang is the language id after the aliases, such as python or cpp. It is "output" or "input" for those blocks.
	Lang  string
	Info  string
	Attrs map[string]string
	// Words are the attributes without a value, such as run or fails.
	Words []string
	Code  string
	// Line is the line of the opening fence, from 1.
	Line int
	// Start and End are the byte offsets of the code in the file. Start is the first byte after the opening fence line and End is the first byte of the closing fence line.
	Start, End int
	// Closed is false when the file ends before the closing fence.
	Closed bool
	// After is the byte offset just after the closing fence line.
	After int
}

Block is one fenced code block of a Markdown file.

func Parse

func Parse(src string, line0 int) []Block

Parse finds the fenced code blocks of a Markdown file, as CommonMark defines them: a fence of three or more backticks or tildes, indented by at most three spaces, closed by a fence of the same character that is at least as long. line0 is the line of the file where src starts, from 1.

func (*Block) Deps added in v0.0.3

func (b *Block) Deps() string

Deps is the value of deps=: the path of a lock file, relative to the node directory (spec 07.7). It is "" when the block has no deps=.

func (*Block) Has

func (b *Block) Has(w string) bool

Has tells if the block has a word attribute.

func (*Block) Mode

func (b *Block) Mode() string

Mode is the run mode of the block: run, fails, wrong, test or norun. It is "" when the block has none, and "many" when it has more than one. A test block with fails is a test block that must fail (spec 07.11), so its mode is test.

func (*Block) Runs added in v0.0.3

func (b *Block) Runs() bool

Runs tells if prog run runs the block: its mode is run, fails, wrong or test.

func (*Block) TestFails added in v0.0.3

func (b *Block) TestFails() bool

TestFails tells if the block is a test block with fails, which shows a test that fails on purpose (spec 07.11).

type Case

type Case struct {
	File string
	// Block is the block that owns the run: the block itself, or the last runnable block of a group.
	Block *Block
	// Parts are the blocks of the program in the order of the page. A block without file= adds its code to the main file of the language.
	Parts   []*Block
	Outputs []*Block
	// Stdin is the text of the input block that stdin= names.
	Stdin string
	// Dir is the directory of the node. The path of deps= is relative to it.
	Dir string
}

Case is one program to run: a block, or the blocks of a group, with its output blocks.

func (*Case) Deps added in v0.0.3

func (c *Case) Deps() string

Deps is the lock file that deps= names, as a path relative to the node directory (spec 07.7). It is the deps= of the block that owns the run, or of another block of the group. It is "" when the program uses the standard library only.

func (*Case) Files

func (c *Case) Files(p lang.Program) map[string]string

Files gives the files of the program. The parts without file= go to the main file of the language, in order.

func (*Case) ID

func (c *Case) ID() string

ID is the id of the case: the id= of the block, or ex<n> from the order of the blocks.

func (*Case) Label added in v0.0.3

func (c *Case) Label() string

Label is the mode of the case as the result shows it. A test block with fails is "test fails".

func (*Case) LockPath added in v0.0.3

func (c *Case) LockPath() string

LockPath is the path of the lock file of deps= on this machine, or "".

func (*Case) Mode

func (c *Case) Mode() string

Mode is run, fails, wrong or test.

func (*Case) TestFile added in v0.0.3

func (c *Case) TestFile(p lang.Program) string

TestFile is the name of the test file of a test block in the work directory: the file= of the block next to the main file, or the main file.

type Issue

type Issue struct {
	File string
	Line int
	Rule string
	Msg  string
}

Issue is a broken rule of spec 07.2.

func (Issue) String

func (i Issue) String() string

type Result

type Result struct {
	File   string `json:"file"`
	Line   int    `json:"line"`
	ID     string `json:"id"`
	Lang   string `json:"lang"`
	Mode   string `json:"mode"`
	Status string `json:"status"` // pass, fail or skip
	Why    string `json:"why,omitempty"`
	// Reason is a short code for the cause of a skip, such as deps when prog run cannot get the packages of the block here (spec 07.7).
	Reason string `json:"reason,omitempty"`
	Tool   string `json:"tool,omitempty"`
	Ms     int64  `json:"ms"`
	// Updated is set by Update when the output blocks of the case were written from this run.
	Updated bool `json:"updated,omitempty"`
	// Got is the output of the run, for -update.
	Got lang.RunResult `json:"-"`
	// Case is the case of the result.
	Case *Case `json:"-"`
}

Result is the result of one case.

type Runner

type Runner struct {
	R *lang.Runner
	// contains filtered or unexported fields
}

Runner runs the cases. It keeps the version of each toolchain.

func (*Runner) Run

func (x *Runner) Run(c *Case) Result

Run runs one case and checks it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL