gen

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package gen is "ypy gen": it reads the table of YPY names (src/attributes.json and one fragment per extension in src/attributes.d/) and generates the editor data from it: the VS Code HTML Custom Data, the JetBrains web-types and the JSON schema of ypy.config. It also checks that src/ypy.d.ts and the sources say the same as the table.

The table is the only place where a name, its value, its default and its owner are written down. Nothing in this package hard-codes an attribute, an event, a header or a config key.

Index

Constants

View Source
const (
	VSCodePath   = "editors/vscode/ypy.html-data.json"
	WebTypesPath = "src/editors/jetbrains/ypy.web-types.json"
	SchemaPath   = "src/editors/schema/ypy.config.schema.json"
)

Output paths, relative to the repository root.

View Source
const (
	CoreTable    = "src/attributes.json"
	FragmentsDir = "src/attributes.d"
	DTSPath      = "src/ypy.d.ts"
	ExtDir       = "src/ext"
	CSSDir       = "src/css"
	CoreSource   = "src/ypy.js"
)

Paths, relative to the repository root.

View Source
const DocBase = "https://ypy.dev/docs/"

DocBase is where the documentation lives: the pages are on the website, not in the repository, so a "doc" field is an address under it.

Variables

View Source
var Profiles = []string{"native", "v1", "v2", "v4"}

Profiles are the compatibility profiles a name can belong to.

View Source
var ValueTypes = []string{"none", "string", "url", "selector", "time", "boolean", "enum", "json", "expression", "text", "number"}

ValueTypes are the kinds of attribute values the table knows.

Functions

func CheckDTS

func CheckDTS(t *Table, root string) ([]string, error)

CheckDTS compares src/ypy.d.ts with the table and returns what differs.

func Command

func Command() cli.Command

Command is the "gen" subcommand.

func HasProfile

func HasProfile(list []string, p string) bool

HasProfile reports whether a list of profiles includes p; an empty list means every profile.

func InNative

func InNative(list []string) bool

InNative reports whether a name belongs to the native profile (the one new pages use).

func Render

func Render(t *Table) (map[string][]byte, error)

Render returns every generated file, keyed by its path relative to the repository root.

Types

type Attribute

type Attribute struct {
	Named
	Description string   `json:"description"`
	ValueType   string   `json:"valueType,omitempty"`
	Values      []Value  `json:"values,omitempty"`
	Syntax      string   `json:"syntax,omitempty"`
	Modifiers   []Value  `json:"modifiers,omitempty"`
	Inherited   bool     `json:"inherited,omitempty"`
	Profiles    []string `json:"profiles,omitempty"`
	Variants    []string `json:"variants,omitempty"`
	Pattern     string   `json:"pattern,omitempty"`
	// ExpandEvents offers one variant per event (ypy-on::<event>) in editors.
	ExpandEvents bool   `json:"expandEvents,omitempty"`
	Doc          string `json:"doc,omitempty"`
	Deprecated   string `json:"deprecated,omitempty"`
}

Attribute is an attribute (or a family of attributes) of the HTML.

type Class

type Class struct {
	Named
	Description string `json:"description"`
}

Class is a CSS class YPY adds.

type ConfigKey

type ConfigKey struct {
	Named
	Description string          `json:"description"`
	Schema      json.RawMessage `json:"schema"`
	Default     json.RawMessage `json:"default,omitempty"`
	Deprecated  string          `json:"deprecated,omitempty"`
	Profiles    []string        `json:"profiles,omitempty"`
}

ConfigKey is a key of ypy.config and of the ypy-config meta tag. Nested keys use a dotted path.

func (ConfigKey) SchemaMap

func (c ConfigKey) SchemaMap() (map[string]any, error)

SchemaMap decodes the JSON Schema fragment of a config key.

type DTS

type DTS struct {
	Interfaces map[string][]member
}

DTS is what the checks need to know about src/ypy.d.ts: its interfaces with every member of every merged declaration.

func ParseDTS

func ParseDTS(src string) *DTS

ParseDTS parses the interfaces of a declaration file. It understands what ypy.d.ts uses (interfaces, namespaces that hold interfaces, property and method signatures) and nothing more.

func (*DTS) ConfigPaths

func (d *DTS) ConfigPaths() []string

ConfigPaths returns every dotted config path that ypy.d.ts declares, starting at YpyConfig.

type Element

type Element struct {
	Named
	Description string   `json:"description"`
	Attributes  []string `json:"attributes,omitempty"`
}

Element is a custom element.

type Event

type Event struct {
	Named
	Description string            `json:"description"`
	Detail      map[string]string `json:"detail"`
	Cancelable  bool              `json:"cancelable,omitempty"`
	Target      string            `json:"target,omitempty"`
	// Listen is true when YPY listens to the event instead of firing it.
	Listen bool `json:"listen,omitempty"`
	// Legacy marks the old camelCase names that exist only in the compat profiles.
	Legacy bool `json:"legacy,omitempty"`
	// ExtensionOnly marks hooks delivered to extensions (ypy_<name>), never to the DOM.
	ExtensionOnly bool     `json:"extensionOnly,omitempty"`
	Profiles      []string `json:"profiles,omitempty"`
	Doc           string   `json:"doc,omitempty"`
}

Event is a ypy:* event, or an extension hook of the same name.

type Header struct {
	Named
	Direction   string   `json:"direction"`
	Description string   `json:"description"`
	Value       string   `json:"value,omitempty"`
	Profiles    []string `json:"profiles,omitempty"`
	Legacy      bool     `json:"legacy,omitempty"`
}

Header is a YPY-* HTTP header.

type Named

type Named struct {
	Name string `json:"name"`
	// Extension is the slug of the extension that owns the entry; empty for the core.
	// It is stamped by Load from the fragment, never written in the files.
	Extension string `json:"-"`
}

Named is something with a name and an owner.

type Scan

type Scan struct {
	// Problems are names the sources use that the table does not know, in a file that has a table
	// (the core, or an extension with a fragment).
	Problems []string
	// Warnings are extensions that have no fragment yet, and table entries no source mentions.
	Warnings []string
}

Scan is the result of reading the sources for names.

func ScanSources

func ScanSources(t *Table, root string) (*Scan, error)

ScanSources reads src/ypy.js and every src/ext/*.js and compares the names it finds with the table.

type Table

type Table struct {
	Version    string
	Elements   []Element
	Attributes []Attribute
	Events     []Event
	Headers    []Header
	Config     []ConfigKey
	Classes    []Class
	// Internal maps a name that appears in the sources but is not public to its owner.
	Internal map[string]string
	// Extensions lists the slugs that have a fragment, sorted.
	Extensions []string
}

Table is the merged table: the core and every extension fragment.

func Load

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

Load reads the core table and every fragment under root and checks the result.

func (*Table) Known

func (t *Table) Known(name string) bool

Known reports whether name is a public name of any kind: attribute, element, event, header or class.

func (*Table) Summary

func (t *Table) Summary() string

Summary counts the entries of the table.

func (*Table) Validate

func (t *Table) Validate() []string

Validate checks the table and returns every problem found.

type ValidationError

type ValidationError struct{ Problems []string }

ValidationError lists every problem of a table.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type Value

type Value struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

Value is one entry of an enumerated value or one modifier.

Jump to

Keyboard shortcuts

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