node

package
v0.0.1 Latest Latest
Warning

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

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

Documentation

Overview

Package node reads the node directories of tamnd/programming (spec 04.3 and 04.4).

Index

Constants

This section is empty.

Variables

View Source
var (
	KebabRE   = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
	VersionRE = regexp.MustCompile(`^[0-9][0-9a-z]*(?:[.-][0-9a-z]+)*$`)
	CodeRE    = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]*$`)
	APIRE     = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*(?:[.:/][A-Za-z_][A-Za-z0-9_]*)*$`)
)

The forms of a local slug. A feature slug is kebab-case. A release slug is a version. A diagnostic slug is a code. An api slug is a path in the library.

View Source
var BuildFiles = []string{
	"go.mod", "go.sum", "go.work", "Cargo.toml", "Cargo.lock", "package.json", "package-lock.json", "tsconfig.json",
	"pyproject.toml", "setup.py", "setup.cfg", "conftest.py", "pom.xml", "build.gradle", "build.gradle.kts",
	"settings.gradle", "settings.gradle.kts", "CMakeLists.txt", "Makefile", "Directory.Build.props",
}

BuildFiles are the names of the files that the generator writes (spec 08.5). Rule I15 refuses them in the content repo.

View Source
var EdgeKeys = []string{
	"solves", "implements", "techniques", "uses", "variant_of", "generalizes",
	"model", "complexity_in", "prereqs", "see_also", "exercises",
	"realizes", "related", "alternative_to", "refactorings", "prevents", "concepts", "features",
}

EdgeKeys are the front matter keys whose values name other nodes by slug (spec 04.6).

View Source
var KeyOrder = []string{}/* 104 elements not displayed */

KeyOrder is the order of the front matter keys (spec 04.4). Keys that are not in the list go after it, in the order of the file.

View Source
var KindList = []Kind{
	{ID: "area", One: "area", Many: "areas", Weight: 5},
	{ID: "concept", One: "concept", Many: "concepts", Weight: 50,
		Blurb:    "A concept is an idea of programming that does not depend on one language. Each page shows the idea in each language where it exists.",
		Sections: cat(s2("Idea", "How it works", "In languages"), s3("Variations and related ideas", "Pitfalls", "Cost", "History"), s0("Theory", "Exercises"), s2("References"))},
	{ID: "definition", One: "definition", Many: "definitions", Weight: 30,
		Blurb:    "A definition gives the exact meaning of a term.",
		Sections: cat(s2("Definition"), s3("Examples and non-examples"), s0("Related definitions"), s2("References"))},
	{ID: "language", One: "language", Many: "languages", Weight: 48,
		Blurb:    "A language page is the front page of the guide to that language.",
		Sections: cat(s2("Overview", "A first program", "The language at a glance", "The guide"), s3("Versions and support", "Implementations", "Ecosystem", "History and influence"), s0("Coming from another language"), s2("References"))},
	{ID: "feature", One: "feature", Many: "features", Owned: true, Weight: 46,
		Blurb:    "A feature is a construct, a rule or a facility of one language. Each page gives the syntax, the rules and the versions.",
		Sections: cat(s2("Synopsis", "Semantics", "Examples"), s3("Versions", "Pitfalls", "Comparison"), s0("Implementation notes"), s2("References"))},
	{ID: "release", One: "release", Many: "releases", Owned: true, Weight: 40,
		Blurb:    "A release is a version of a language, a standard or a tool.",
		Sections: cat(s2("What is new", "Removed and deprecated"), s3("Migration", "Support dates"), s2("References"))},
	{ID: "task", One: "task", Many: "tasks", Weight: 44,
		Blurb:    "A task is a common job of a programmer. Each page has a contract and a solution in many languages, and each solution passes the same tests.",
		Sections: cat(s2("Task", "Solutions"), s3("Edge cases", "Pitfalls"), s0("Related tasks"), s2("References"))},
	{ID: "pattern", One: "pattern", Many: "patterns", Weight: 42,
		Blurb:    "A pattern is a named design that people use again and again. Anti-patterns and code smells are patterns too.",
		Sections: cat(s2("Intent", "Problem", "Solution", "Example"), s3("Consequences", "When not to use it", "How to fix it", "Variants and related patterns"), s0("Known uses"), s2("References"))},
	{ID: "technique", One: "technique", Many: "techniques", Weight: 41,
		Blurb:    "A technique is a named method with steps, such as a refactoring or a way to debug.",
		Sections: cat(s2("Purpose", "Steps", "Example"), s3("When to use", "Pitfalls", "Tools that do it"), s2("References"))},
	{ID: "practice", One: "practice", Many: "practices", Weight: 40,
		Blurb:    "A practice is a principle, a law, a guideline or a method of work.",
		Sections: cat(s2("Statement", "Meaning"), s3("Examples", "Criticism and limits", "History"), s2("References"))},
	{ID: "tool", One: "tool", Many: "tools", Weight: 39,
		Blurb:    "A tool is software that programmers use to make software, such as a compiler, a build tool or a debugger.",
		Sections: cat(s2("What it is", "Install and first use"), s3("Concepts of the tool", "Common tasks", "Configuration", "Alternatives", "History and versions"), s2("References"))},
	{ID: "library", One: "library", Many: "libraries", Weight: 38,
		Blurb:    "A library is code that a program uses, from a standard library to a framework.",
		Sections: cat(s2("What it is", "Install and first use"), s3("Concepts of the tool", "Common tasks", "Configuration", "Alternatives", "History and versions"), s2("References"))},
	{ID: "format", One: "format", Many: "formats", Weight: 37,
		Blurb:    "A format is a way to write data, such as JSON or UTF-8.",
		Sections: cat(s2("What it is", "Syntax or structure", "Examples"), s3("Versions", "Pitfalls", "Tools and libraries"), s2("References"))},
	{ID: "standard", One: "standard", Many: "standards", Weight: 36,
		Blurb:    "A standard is a specification document, such as ISO C or ECMA-262.",
		Sections: cat(s2("What it is", "Syntax or structure", "Examples"), s3("Versions", "Pitfalls", "Tools and libraries"), s2("References"))},
	{ID: "weakness", One: "weakness", Many: "weaknesses", Weight: 35,
		Blurb:    "A weakness is a class of defect, such as a security weakness of CWE or a common bug.",
		Sections: cat(s2("Description", "Vulnerable code", "Fixed code"), s3("How to detect it", "How to prevent it", "Real cases"), s2("References"))},
	{ID: "diagnostic", One: "diagnostic", Many: "diagnostics", Owned: true, Infix: "errors", Weight: 34,
		Blurb:    "A diagnostic is an error, a warning or a lint rule of a language or a tool.",
		Sections: cat(s2("Message", "Cause", "Example", "Fix"), s3("Related diagnostics"), s2("References"))},
	{ID: "proposal", One: "proposal", Many: "proposals", Owned: true, Infix: "proposals", Weight: 33,
		Blurb:    "A proposal is a change request of a language or a tool, such as a PEP or a JEP.",
		Sections: cat(s2("Summary"), s3("Motivation", "What changed", "History"), s2("References"))},
	{ID: "api", One: "API entry", Many: "API entries", Owned: true, Infix: "api", Weight: 32,
		Blurb:    "An API entry is a module, a type, a function or a constant of a standard library or a platform.",
		Sections: cat(s2("Signature", "Semantics", "Examples"), s3("Versions", "Pitfalls"), s2("References"))},
	{ID: "work", One: "work", Many: "works", Weight: 20,
		Blurb:    "A work is a book, a paper, an essay or a talk that is part of the canon of programming.",
		Sections: cat(s2("Summary"), s3("Contents", "Influence"), s2("References"))},
	{ID: "person", One: "person", Many: "people", Weight: 15,
		Blurb:    "A person made or named items of programming.",
		Sections: cat(s2("Biography"), s3("Work"), s2("References"))},
	{ID: "organization", One: "organization", Many: "organizations", Weight: 14,
		Blurb:    "An organization is a company, a foundation, a committee or a standards body.",
		Sections: cat(s2("About"), s3("Work"), s2("References"))},
	{ID: "exercise", One: "exercise", Many: "exercises", Owned: true, Weight: 10,
		Blurb: "An exercise is a practice problem on a public site."},
}

KindList is the list of the 22 kinds, in the order of spec 04.2.

View Source
var Kinds = func() []string {
	out := make([]string, len(KindList))
	for i, k := range KindList {
		out[i] = k.ID
	}
	return out
}()

Kinds are the ids of the 22 kinds of spec 04.2.

View Source
var Levels = []string{"intro", "core", "advanced", "research"}

Levels are the editorial levels of spec 05.5.

Functions

func FormatNode

func FormatNode(b []byte) ([]byte, error)

FormatNode returns node.md in canonical form: LF line ends, no trailing spaces, the front matter keys in the order of KeyOrder, at most one blank line in a row outside code blocks, and one newline at the end. It returns an error when the new front matter does not parse to the same value as the old one, so it never changes what a node says.

func FormatText

func FormatText(b []byte) []byte

FormatText returns a text file with LF line ends, no trailing spaces and one newline at the end. prog fmt uses it for YAML, registers and proofs.

func FullSlug

func FullSlug(kind, owner, local string) string

FullSlug joins the owner, the infix of the kind and the local slug. The result is the path of the URL without the slashes at the ends.

func IsBuildFile

func IsBuildFile(name string) bool

IsBuildFile tells if a file name is a build file of a language, such as go.mod or a .csproj file.

func IsKind

func IsKind(k string) bool

IsKind tells if k is one of the 22 kinds.

func IsOwned

func IsOwned(k string) bool

IsOwned tells if the URL of a kind has the owner first.

func IsTestFile

func IsTestFile(name string) bool

IsTestFile tells if a file name is a native test, by the conventions of spec 08.3. Examples: test_binary_search.py, binary_search_test.go, binarySearch.test.js, BinarySearchTest.java, binary_search_tests.rs.

func LocalOK

func LocalOK(kind, local string) bool

LocalOK tells if a local slug has the form of its kind.

func ReadAliases

func ReadAliases(path string) (map[string]string, error)

readTags reads registers/tags.reg. Each line is "TAG slug". A line that starts with # is a comment. ReadAliases reads registers/aliases.reg. Each line is an old slug and the slug it moved to.

func RenameRefs

func RenameRefs(b []byte, old, new string) []byte

RenameRefs changes each reference to the slug old into new: the values of the edge keys in the front matter, and the links "](/old/" and "](/old#" in the text. It changes nothing else, so a word in a summary or a URL in a source stays as it is.

func SetSlugArea

func SetSlugArea(b []byte, slug, area string) []byte

SetSlugArea sets the slug line and, when area is not empty, the area line of the front matter.

func SplitFront

func SplitFront(b []byte) (front, body []byte, bodyLine int, err error)

SplitFront splits a Markdown file into its YAML front matter and its body. It returns the line number where the body starts.

Types

type Area

type Area struct {
	ID       string `yaml:"id" json:"id"`
	Name     string `yaml:"name" json:"name"`
	Summary  string `yaml:"summary,omitempty" json:"summary,omitempty"`
	Children []Area `yaml:"children,omitempty" json:"children,omitempty"`
	Parent   string `yaml:"-" json:"parent,omitempty"`
}

Area is one entry of topics/areas.yaml (spec 05.2).

func (Area) InLanguage

func (a Area) InLanguage() bool

InLanguage tells if the area is a language tree or a part of one.

func (Area) Path

func (a Area) Path() string

Path is "top/sub" for a sub-area and "top" for a top area. A sub-area of a language tree has three parts, such as languages/python/control-flow.

func (Area) URL

func (a Area) URL() string

URL is the path of the area page. A topic area is at /<id>/. A language tree is at /<lang>/ and its sub-areas are at /<lang>/<sub>/ (spec 16.2).

type Complexity

type Complexity struct {
	Vars  map[string]string            `yaml:"vars,omitempty" json:"vars,omitempty"`
	Time  map[string]string            `yaml:"time,omitempty" json:"time,omitempty"`
	Space map[string]string            `yaml:"space,omitempty" json:"space,omitempty"`
	Other map[string]map[string]string `yaml:",inline" json:"other,omitempty"`
}

Complexity holds the claims of a node (spec 04.4 and 06.6).

type Corpus

type Corpus struct {
	Root     string
	Nodes    []*Node
	BySlug   map[string]*Node
	ByTag    map[string]*Node
	Areas    []Area
	AreaByID map[string]*Area // keyed by Area.Path()
	// Template is the list of sub-areas of a language tree, from topics/languages.yaml (spec 05.3).
	Template []Area
	Langs    []Lang
	LangByID map[string]*Lang
	Reserved map[string]bool
	Tags     []Tag
	// OldSlugs maps each old slug of registers/aliases.reg to the slug it moved to.
	OldSlugs map[string]string
	// Errors are the node directories that could not be read. Package check reports them as T01.
	Errors []error
}

Corpus is the content tree.

func Load

func Load(root string) (*Corpus, error)

Load reads the whole content tree at root.

func (*Corpus) InArea

func (c *Corpus) InArea(path string) []*Node

InArea returns the nodes whose primary area is path or is under path.

func (*Corpus) Kind

func (c *Corpus) Kind(kind string) []*Node

Kind returns the nodes of one kind.

func (*Corpus) Leads

func (c *Corpus) Leads(slug string) []*Node

Leads returns the nodes that list slug in prereqs or uses.

func (*Corpus) Solvers

func (c *Corpus) Solvers(problem string) []*Node

Solvers returns the nodes that solve a task. A task holds its own solutions (spec 10.1), so the task is first. The nodes with a `solves` edge to the task come after it.

type Example

type Example struct {
	Lang string `json:"lang"`
	Path string `json:"path"`
	Body string `json:"-"`
	Line int    `json:"-"` // the line of the file where the body starts
}

Example is one file of examples/: the section of a concept or a feature for one language (spec 04.4).

type File

type File struct {
	Name    string `json:"name"`
	Path    string `json:"path"`
	Content string `json:"-"`
	Test    bool   `json:"test"`
}

File is one file of an implementation.

type Front

type Front struct {
	Tag         string            `yaml:"tag" json:"tag"`
	Kind        string            `yaml:"kind" json:"kind"`
	Slug        string            `yaml:"slug" json:"slug"`
	Name        string            `yaml:"name" json:"name"`
	Aliases     []string          `yaml:"aliases,omitempty" json:"aliases,omitempty"`
	Area        string            `yaml:"area" json:"area"`
	Areas       []string          `yaml:"areas,omitempty" json:"areas,omitempty"`
	Level       string            `yaml:"level" json:"level"`
	Summary     string            `yaml:"summary" json:"summary"`
	Solves      []Solve           `yaml:"solves,omitempty" json:"solves,omitempty"`
	Implements  []string          `yaml:"implements,omitempty" json:"implements,omitempty"`
	Techniques  []string          `yaml:"techniques,omitempty" json:"techniques,omitempty"`
	Uses        []string          `yaml:"uses,omitempty" json:"uses,omitempty"`
	VariantOf   string            `yaml:"variant_of,omitempty" json:"variant_of,omitempty"`
	Generalizes []string          `yaml:"generalizes,omitempty" json:"generalizes,omitempty"`
	Model       string            `yaml:"model,omitempty" json:"model,omitempty"`
	Complexity  *Complexity       `yaml:"complexity,omitempty" json:"complexity,omitempty"`
	Properties  map[string]any    `yaml:"properties,omitempty" json:"properties,omitempty"`
	Constraints map[string]any    `yaml:"constraints,omitempty" json:"constraints,omitempty"`
	History     *History          `yaml:"history,omitempty" json:"history,omitempty"`
	Prereqs     []string          `yaml:"prereqs,omitempty" json:"prereqs,omitempty"`
	SameAs      map[string]any    `yaml:"same_as,omitempty" json:"same_as,omitempty"`
	Lean        map[string]string `yaml:"lean,omitempty" json:"lean,omitempty"`
	Sources     []Source          `yaml:"sources,omitempty" json:"sources,omitempty"`
	Exercises   []string          `yaml:"exercises,omitempty" json:"exercises,omitempty"`
	People      []string          `yaml:"people,omitempty" json:"people,omitempty"`
	SeeAlso     []string          `yaml:"see_also,omitempty" json:"see_also,omitempty"`

	// Owner is the language, tool or library that owns a feature, release, diagnostic, proposal or api node (spec 04.3).
	Owner string `yaml:"owner,omitempty" json:"owner,omitempty"`

	// concept
	AppliesTo string `yaml:"applies_to,omitempty" json:"applies_to,omitempty"`
	Viz       string `yaml:"viz,omitempty" json:"viz,omitempty"`
	Formal    string `yaml:"formal,omitempty" json:"formal,omitempty"`

	// language
	Class          string         `yaml:"class,omitempty" json:"class,omitempty"`
	Tier           int            `yaml:"tier,omitempty" json:"tier,omitempty"`
	Paradigms      []string       `yaml:"paradigms,omitempty" json:"paradigms,omitempty"`
	Typing         map[string]any `yaml:"typing,omitempty" json:"typing,omitempty"`
	Memory         string         `yaml:"memory,omitempty" json:"memory,omitempty"`
	Execution      []string       `yaml:"execution,omitempty" json:"execution,omitempty"`
	Appeared       int            `yaml:"appeared,omitempty" json:"appeared,omitempty"`
	Designers      []string       `yaml:"designers,omitempty" json:"designers,omitempty"`
	InfluencedBy   []string       `yaml:"influenced_by,omitempty" json:"influenced_by,omitempty"`
	Standard       string         `yaml:"standard,omitempty" json:"standard,omitempty"`
	Reference      map[string]any `yaml:"reference,omitempty" json:"reference,omitempty"`
	ReferenceImpl  string         `yaml:"licence_of_reference_impl,omitempty" json:"licence_of_reference_impl,omitempty"`
	FileExtensions []string       `yaml:"file_extensions,omitempty" json:"file_extensions,omitempty"`
	HelloWorld     string         `yaml:"hello_world,omitempty" json:"hello_world,omitempty"`

	// feature
	Realizes  []string       `yaml:"realizes,omitempty" json:"realizes,omitempty"`
	Grammar   string         `yaml:"grammar,omitempty" json:"grammar,omitempty"`
	Spec      map[string]any `yaml:"spec,omitempty" json:"spec,omitempty"`
	Proposals []string       `yaml:"proposals,omitempty" json:"proposals,omitempty"`
	Compat    string         `yaml:"compat,omitempty" json:"compat,omitempty"`
	Since     string         `yaml:"since,omitempty" json:"since,omitempty"`

	// release
	Version    string           `yaml:"version,omitempty" json:"version,omitempty"`
	Released   string           `yaml:"released,omitempty" json:"released,omitempty"`
	EOL        string           `yaml:"eol,omitempty" json:"eol,omitempty"`
	Patches    []map[string]any `yaml:"patches,omitempty" json:"patches,omitempty"`
	Adds       []string         `yaml:"adds,omitempty" json:"adds,omitempty"`
	Removes    []string         `yaml:"removes,omitempty" json:"removes,omitempty"`
	Deprecates []string         `yaml:"deprecates,omitempty" json:"deprecates,omitempty"`
	Notes      map[string]any   `yaml:"notes,omitempty" json:"notes,omitempty"`

	// task
	Contract       string              `yaml:"contract,omitempty" json:"contract,omitempty"`
	Category       string              `yaml:"category,omitempty" json:"category,omitempty"`
	Languages      Lit                 `yaml:"languages,omitempty" json:"languages,omitempty"`
	UsesFeatures   map[string][]string `yaml:"uses_features,omitempty" json:"uses_features,omitempty"`
	UsesAlgorithms []string            `yaml:"uses_algorithms,omitempty" json:"uses_algorithms,omitempty"`

	// pattern, technique and practice
	Family       string            `yaml:"family,omitempty" json:"family,omitempty"`
	Polarity     string            `yaml:"polarity,omitempty" json:"polarity,omitempty"`
	Intent       string            `yaml:"intent,omitempty" json:"intent,omitempty"`
	AlsoKnownAs  []string          `yaml:"also_known_as,omitempty" json:"also_known_as,omitempty"`
	Related      []string          `yaml:"related,omitempty" json:"related,omitempty"`
	BuiltIn      map[string]string `yaml:"languages_where_built_in,omitempty" json:"languages_where_built_in,omitempty"`
	Refactorings []string          `yaml:"refactorings,omitempty" json:"refactorings,omitempty"`

	// tool and library
	Role               Lit            `yaml:"role,omitempty" json:"role,omitempty"`
	ImplementsLanguage string         `yaml:"implements_language,omitempty" json:"implements_language,omitempty"`
	Licence            string         `yaml:"licence,omitempty" json:"licence,omitempty"`
	Repo               string         `yaml:"repo,omitempty" json:"repo,omitempty"`
	Homepage           string         `yaml:"homepage,omitempty" json:"homepage,omitempty"`
	FirstRelease       string         `yaml:"first_release,omitempty" json:"first_release,omitempty"`
	AlternativeTo      []string       `yaml:"alternative_to,omitempty" json:"alternative_to,omitempty"`
	Latest             map[string]any `yaml:"latest,omitempty" json:"latest,omitempty"`

	// format and standard
	MediaType  string   `yaml:"media_type,omitempty" json:"media_type,omitempty"`
	Extensions []string `yaml:"extensions,omitempty" json:"extensions,omitempty"`
	Specs      []string `yaml:"specs,omitempty" json:"specs,omitempty"`
	Publisher  string   `yaml:"publisher,omitempty" json:"publisher,omitempty"`

	// weakness
	CWE               int      `yaml:"cwe,omitempty" json:"cwe,omitempty"`
	Abstraction       string   `yaml:"abstraction,omitempty" json:"abstraction,omitempty"`
	LanguagesAffected []string `yaml:"languages_affected,omitempty" json:"languages_affected,omitempty"`
	OWASPTop10        string   `yaml:"owasp_top10_2025,omitempty" json:"owasp_top10_2025,omitempty"`
	CWETop25          int      `yaml:"cwe_top25_2025,omitempty" json:"cwe_top25_2025,omitempty"`
	DetectedBy        []string `yaml:"detected_by,omitempty" json:"detected_by,omitempty"`
	Prevents          []string `yaml:"prevents,omitempty" json:"prevents,omitempty"`

	// diagnostic, proposal and api, when they are promoted to nodes
	Code     string   `yaml:"code,omitempty" json:"code,omitempty"`
	Severity string   `yaml:"severity,omitempty" json:"severity,omitempty"`
	Messages []string `yaml:"message_templates,omitempty" json:"message_templates,omitempty"`
	Concepts []string `yaml:"concepts,omitempty" json:"concepts,omitempty"`
	Features []string `yaml:"features,omitempty" json:"features,omitempty"`
	Path     string   `yaml:"path,omitempty" json:"api_path,omitempty"`
	Entity   string   `yaml:"entity,omitempty" json:"entity,omitempty"`
	Module   string   `yaml:"module,omitempty" json:"module,omitempty"`

	// work, person and organization
	Authors []string `yaml:"authors,omitempty" json:"authors,omitempty"`
	Year    int      `yaml:"year,omitempty" json:"year,omitempty"`
	Born    string   `yaml:"born,omitempty" json:"born,omitempty"`
	Died    string   `yaml:"died,omitempty" json:"died,omitempty"`
	Founded string   `yaml:"founded,omitempty" json:"founded,omitempty"`
	URL     string   `yaml:"url,omitempty" json:"url,omitempty"`
}

Front is the front matter of node.md (spec 04.5). The schema is schema/node.v1.json in tamnd/programming. A field that does not apply to a kind is absent.

type History

type History struct {
	Year   int            `yaml:"year,omitempty" json:"year,omitempty"`
	People []string       `yaml:"people,omitempty" json:"people,omitempty"`
	First  map[string]any `yaml:"first,omitempty" json:"first,omitempty"`
	Note   string         `yaml:"note,omitempty" json:"note,omitempty"`
}

History says where a node comes from.

type Impl

type Impl struct {
	Lang  string `json:"lang"`
	Files []File `json:"files"`
}

Impl is the implementation of a node in one language (spec 08.1).

func (Impl) HasTests

func (im Impl) HasTests() bool

HasTests tells if the implementation has native tests.

func (Impl) Main

func (im Impl) Main() *File

Main is the first file that is not a test.

type Kind

type Kind struct {
	ID     string
	One    string // the name of one item, such as "design pattern"
	Many   string // the plural, such as "design patterns"
	Owned  bool   // the URL has the owner first (spec 04.3)
	Infix  string // the path between the owner and the local slug, such as "errors" for a diagnostic
	Blurb  string // one sentence for the index page of the kind
	Weight int    // the order of the kind in lists, high first
	// Sections are the headings of the body in their order. Need is 2 for a section that W2 needs, 3 for W3 and 0 for an optional section.
	Sections []Section
}

Kind describes one node kind of spec 04.2: its names, the slug form and the sections of spec 06.3.

func KindOf

func KindOf(id string) *Kind

KindOf returns the description of a kind, or nil.

type Lang

type Lang struct {
	ID        string   `yaml:"id" json:"id"`
	Name      string   `yaml:"name" json:"name"`
	Tier      int      `yaml:"tier" json:"tier"`
	Ext       []string `yaml:"ext" json:"ext"`
	FileCase  string   `yaml:"file_case" json:"file_case,omitempty"`
	Test      LangTool `yaml:"test" json:"test"`
	Format    LangTool `yaml:"format" json:"format"`
	Lint      LangTool `yaml:"lint" json:"lint"`
	Toolchain string   `yaml:"toolchain" json:"toolchain,omitempty"` // the pinned version, for the language page
	Run       string   `yaml:"run" json:"run,omitempty"`             // how a reader runs the tests without prog
	Comment   string   `yaml:"comment" json:"comment,omitempty"`
	Highlight string   `yaml:"highlight" json:"highlight"` // the Chroma lexer
	Int       string   `yaml:"int" json:"int,omitempty"`
	List      string   `yaml:"list" json:"list,omitempty"`
	Since     string   `yaml:"since" json:"since,omitempty"`
}

Lang is one entry of registers/languages.yaml (spec 08.2).

type LangTool

type LangTool struct {
	Tool      string   `yaml:"tool,omitempty" json:"tool,omitempty"`
	Framework string   `yaml:"framework,omitempty" json:"framework,omitempty"`
	File      string   `yaml:"file,omitempty" json:"file,omitempty"`
	Args      []string `yaml:"args,omitempty" json:"args,omitempty"`
}

LangTool is a tool of a language: the test framework, the formatter or the linter.

type Lit

type Lit []string

Lit is a list of strings that also accepts one string, such as `languages: tier-1+2`.

func (*Lit) UnmarshalYAML

func (l *Lit) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML accepts a scalar or a sequence.

type Node

type Node struct {
	Front
	// Local is the slug as the front matter writes it. For an owned kind, Slug is the full slug, such as python/match-statement, and Local is match-statement.
	Local     string    `json:"local,omitempty"`
	Examples  []Example `json:"examples,omitempty"`
	Body      string    `json:"-"`
	BodyLine  int       `json:"-"` // the line of node.md where the body starts
	Dir       string    `json:"-"`
	Rel       string    `json:"path"` // the directory, relative to the root
	RawFront  []byte    `json:"-"`
	Forbidden []string  `json:"-"` // front matter keys that rule T05 rejects
	Impls     []Impl    `json:"impls,omitempty"`
	Proofs    []Proof   `json:"proofs,omitempty"`
	Scene     string    `json:"scene,omitempty"` // path of viz/scene.ts, relative to the root
	Presets   []Preset  `json:"presets,omitempty"`
}

Node is one node directory.

func Read

func Read(root, dir string) (*Node, error)

Read reads one node directory. It does not check the node; package check does that.

func (*Node) Example

func (n *Node) Example(lang string) *Example

Example returns the example file of a language, or nil.

func (*Node) Lang

func (n *Node) Lang(id string) *Impl

Lang returns the implementation in a language, or nil.

type Preset

type Preset struct {
	Name  string         `yaml:"name" json:"name"`
	Input map[string]any `yaml:"input" json:"input"`
	Note  string         `yaml:"note,omitempty" json:"note,omitempty"`
}

Preset is a named input of a scene (spec 10.4).

type Proof

type Proof struct {
	ID    string     `json:"id"`
	Path  string     `json:"path"`
	Front ProofFront `json:"front"`
	Body  string     `json:"-"`
}

Proof is one file of proofs/.

type ProofFront

type ProofFront struct {
	Title  string   `yaml:"title" json:"title"`
	Proves []string `yaml:"proves" json:"proves"`
	Status string   `yaml:"status" json:"status"` // full or sketch
	Lean   string   `yaml:"lean,omitempty" json:"lean,omitempty"`
}

ProofFront is the front matter of a proof file (spec 06.5).

type Section

type Section struct {
	Name string
	Need int
}

Section is one heading of a kind.

type Solve

type Solve struct {
	Problem  string         `yaml:"problem" json:"problem"`
	Requires map[string]any `yaml:"requires,omitempty" json:"requires,omitempty"`
	Time     string         `yaml:"time,omitempty" json:"time,omitempty"`
	Note     string         `yaml:"note,omitempty" json:"note,omitempty"`
}

Solve is one `solves` edge. The short form is a problem slug. The long form has conditions (spec 04.4).

func (*Solve) UnmarshalYAML

func (s *Solve) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML accepts a slug or a mapping.

type Source

type Source struct {
	Work     string `yaml:"work,omitempty" json:"work,omitempty"`
	Book     string `yaml:"book,omitempty" json:"book,omitempty"`
	URL      string `yaml:"url,omitempty" json:"url,omitempty"`
	Paper    string `yaml:"paper,omitempty" json:"paper,omitempty"`
	Title    string `yaml:"title,omitempty" json:"title,omitempty"`
	Locator  string `yaml:"locator,omitempty" json:"locator,omitempty"`
	Accessed string `yaml:"accessed,omitempty" json:"accessed,omitempty"`
	Note     string `yaml:"note,omitempty" json:"note,omitempty"`
}

Source is one entry of `sources`. A source names a work of registers/works.yaml, a book, a paper or a URL, and a locator inside it (spec 04.5).

type Tag

type Tag struct {
	Tag  string
	Slug string
	Line int
}

Tag is one line of registers/tags.reg.

Jump to

Keyboard shortcuts

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