Documentation
¶
Overview ¶
Package examples reads the fenced code blocks of the pages, runs them and checks their output (spec 07).
Index ¶
- Constants
- Variables
- func Clean(s string) string
- func Collect(file, src string, line0 int) ([]Case, []Issue)
- func LangID(name string) string
- func Normalize(s string, extra []string) string
- func NormalizeReport(lang, s string) string
- func NorunShare(src string) (norun, total int)
- func Stream(got lang.RunResult, stream string) string
- func Update(src string, results []Result) (string, int)
- type Block
- type Case
- type Issue
- type Result
- type Runner
Constants ¶
const TestFailure = "test-failure"
TestFailure is the failure signature of a test block with fails: at least one test fails (spec 07.11).
Variables ¶
var Expects = []string{"compile", "runtime", "exit", "exception", "error", "panic", "timeout", "sanitizer"}
Expects are the kinds of failure signature of spec 07.2.
var NorunReasons = []string{"network", "gui", "platform", "hardware", "ub", "vulnerable", "fragment", "pseudo", "long", "interactive"}
NorunReasons are the codes of spec 07.8.
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 ¶
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 ¶
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 Normalize ¶
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
NormalizeReport applies the normalizers of the test runner of a language to a report.
func NorunShare ¶ added in v0.0.3
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 Update ¶
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 ¶
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
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) Mode ¶
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.
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
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 ¶
Files gives the files of the program. The parts without file= go to the main file of the language, in order.
func (*Case) ID ¶
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
Label is the mode of the case as the result shows it. A test block with fails is "test fails".
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.