node

package
v0.0.7 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 15 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 CardKinds = map[string]string{"diagnostic": "code", "proposal": "id", "api": "path", "exercise": "id"}

CardKinds are the kinds that are cards by default (spec 04.1), with the field that holds the local slug.

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.

View Source
var Verdicts = []string{"native", "stdlib", "library", "idiom", "absent", "n/a"}

Verdicts are the values of a cell of the concept and language matrix (spec 04.8), in order from the strongest support to none.

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, binary_search.bats, BinarySearch.Tests.ps1.

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 ShardOf added in v0.0.2

func ShardOf(c *Card) string

ShardOf is the path of the shard that must hold the card: cards/<kind>/<owner>/<pp>.jsonl, where <owner> is _ for a card with no owner and <pp> is the first two characters of the local slug in lower case (spec 20.3).

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 Card added in v0.0.2

type Card struct {
	Tag      string   `json:"tag"`
	Kind     string   `json:"kind"`
	Owner    string   `json:"owner"`
	Title    string   `json:"title,omitempty"`
	Name     string   `json:"name,omitempty"`
	Summary  string   `json:"summary,omitempty"`
	URL      string   `json:"url,omitempty"`
	Licence  string   `json:"licence,omitempty"`
	Since    string   `json:"since,omitempty"`
	Removed  string   `json:"removed,omitempty"`
	Features []string `json:"features,omitempty"`
	Concepts []string `json:"concepts,omitempty"`
	Tasks    []string `json:"tasks,omitempty"`

	// diagnostic
	Code             string   `json:"code,omitempty"`
	Severity         string   `json:"severity,omitempty"`
	MessageTemplates []string `json:"message_templates,omitempty"`
	// Type is the type of a proposal, such as standards-track, or lint for a diagnostic that is a lint rule.
	Type string `json:"type,omitempty"`

	// proposal
	ID      string   `json:"id,omitempty"`
	Status  string   `json:"status,omitempty"`
	Created string   `json:"created,omitempty"`
	Release string   `json:"release,omitempty"`
	Authors []string `json:"authors,omitempty"`

	// api
	Path       string `json:"path,omitempty"`
	Entity     string `json:"entity,omitempty"`
	Signature  string `json:"signature,omitempty"`
	Module     string `json:"module,omitempty"`
	Deprecated string `json:"deprecated,omitempty"`
	Doc        struct {
		URL string `json:"url,omitempty"`
	} `json:"doc,omitzero"`

	Source struct {
		URL     string `json:"url,omitempty"`
		Licence string `json:"licence,omitempty"`
	} `json:"source,omitzero"`

	// Raw is the row as it is in the file. The site writes it as the JSON record of the card.
	Raw map[string]any `json:"-"`
	// File is the path of the shard, relative to the root, and Line is the line of the row, from 1.
	File string `json:"-"`
	Line int    `json:"-"`
}

Card is one row of a card register, cards/<kind>/<owner>/<pp>.jsonl (spec 04.1 and 20.3). A card is a set of checked facts with sources. It has no page of its own: the site shows it on the collection page of its kind and owner.

func ReadCards added in v0.0.2

func ReadCards(root string) ([]*Card, []error)

ReadCards reads each shard under cards/. A missing directory gives no cards. A row that does not parse is an error of the list, and the reading goes on.

func (*Card) Anchor added in v0.0.2

func (c *Card) Anchor() string

Anchor is the id of the card on its collection page.

func (*Card) Collection added in v0.0.2

func (c *Card) Collection() string

Collection is the URL of the collection page that shows the card.

func (*Card) Group added in v0.0.2

func (c *Card) Group() string

Group is the part of the collection that holds the card. An api card is in the group of its module, class or package: str for str.split, os.path for os.path.join, std::vec::Vec for std::vec::Vec::push. A card of another kind is in one group, "".

func (*Card) Heading added in v0.0.2

func (c *Card) Heading() string

Heading is the text that names the card: the title, or the name, or the local slug.

func (*Card) Local added in v0.0.2

func (c *Card) Local() string

Local is the slug of the card inside its owner: the code of a diagnostic, the id of a proposal or an exercise, the path of an api entry.

func (*Card) Slug added in v0.0.2

func (c *Card) Slug() string

Slug is the full slug of the card, as a node of the same kind would have it: rust/errors/E0382.

type CardError added in v0.0.2

type CardError struct {
	File string
	Line int
	Err  error
}

CardError is a row of a shard that could not be read.

func (*CardError) Error added in v0.0.2

func (e *CardError) Error() string

type Cell added in v0.0.2

type Cell struct {
	Status      string `yaml:"status" json:"status"`
	Reason      string `yaml:"reason,omitempty" json:"reason,omitempty"`
	Alternative string `yaml:"alternative,omitempty" json:"alternative,omitempty"`
	Library     string `yaml:"library,omitempty" json:"library,omitempty"`
	Source      string `yaml:"source,omitempty" json:"source,omitempty"`
	// From tells where the cell comes from: a file path, "example" or "feature".
	From string `yaml:"-" json:"from,omitempty"`
	// Feature is the slug of the feature node that realizes the concept, for a cell that comes from a feature.
	Feature string `yaml:"-" json:"feature,omitempty"`
	// Line is the line of the cell in its file, for the checks.
	Line int `yaml:"-" json:"-"`
}

Cell is one cell of the matrix: how a language does a concept. Written cells come from the matrix.yaml file of a concept or the concepts.yaml file of a language. Other cells come from the example files and the features.

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()
	// AreaDocs holds the README of each top area that has one, keyed by the area id. The README says what the area holds and what it does not hold (spec 05.2).
	AreaDocs map[string]string
	// 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
	// Cards are the rows of the card registers under cards/, sorted by slug (spec 04.1).
	Cards []*Card
	// CardBySlug holds the first card of each slug.
	CardBySlug map[string]*Card
	// CardErrors are the card rows that could not be read. Package check reports them as C01.
	CardErrors []error
	// Impls is registers/implementations.yaml: the compat columns of each language (spec 09.2). Probes are the results of prog compat probe, from manifests/probes.jsonl.
	Impls  compat.Register
	Probes compat.Results
	// contains filtered or unexported fields
}

Corpus is the content tree.

func Load

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

Load reads the whole content tree at root.

func (*Corpus) Cell added in v0.0.2

func (c *Corpus) Cell(concept *Node, lang string) (*Cell, bool)

Cell gives the cell of a concept for a language, and false when nothing decides it. The order is: the matrix.yaml of the concept, the concepts.yaml of the language, the example file of the language, then a feature of the language that realizes the concept.

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
	// Verdict is the matrix cell that the file states, in a line such as "- Verdict: native." (spec 04.8).
	Verdict string `json:"verdict,omitempty"`
}

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"`
	// Signature is the signature of an api entry. ProposalStatus, ProposalType, Created and Release are the facts of a proposal; the key is not status, because a status is computed (rule T05).
	Signature      string `yaml:"signature,omitempty" json:"signature,omitempty"`
	ProposalStatus string `yaml:"proposal_status,omitempty" json:"proposal_status,omitempty"`
	ProposalType   string `yaml:"proposal_type,omitempty" json:"proposal_type,omitempty"`
	Created        string `yaml:"created,omitempty" json:"created,omitempty"`
	Release        string `yaml:"release,omitempty" json:"release,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"`
	// Cells are the written cells of the matrix: by language for a concept (matrix.yaml), by concept for a language (concepts.yaml).
	Cells     map[string]*Cell `json:"cells,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"`
	// CompatEntries are the entries of the compat file of the node (spec 09.2), and CompatErr is the error when the file could not be read. Probes holds probes/probes.yaml.
	CompatEntries []compat.Entry           `yaml:"-" json:"-"`
	CompatErr     error                    `yaml:"-" json:"-"`
	Probes        map[string]compat.Expect `yaml:"-" json:"-"`
	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