model

type Array ¶

type Array struct {
	// contains filtered or unexported fields
}

Array is PHP's ordered hash map. It preserves insertion order and allows both integer and string keys, so it doubles as list and dictionary.

It has two internal representations and switches between them by itself:

list mode  values live in `list`, the key of element i is int64(i).
           `keys` and `values` are nil, so the array costs one slice.
map mode   `values` holds key->value and `keys` holds insertion order.

A new array starts in list mode, which is what `$a[] = v` (Append) and a PHP list literal produce, and stays there for as long as every key so far is the dense sequence 0,1,...,n-1. The first key that breaks the invariant (a string key, a negative or sparse integer, an int that is not an int64) promotes the array to map mode, permanently. See promote.

Nothing about the observable behaviour differs between the two modes; list mode exists only so that the common case does not allocate a map[any]any, a key slice, and an interface box per key. Keys are still treated as opaque: an Array never normalises "1" to 1 (its callers do, see runner.normalizeKey), and only an int64 key advances the append index.

func CopyArray(a *Array) *Array

func NewArray() *Array

func NewArraySize(n int) *Array

func ToArray(v any) *Array

func (a *Array) Append(val any)

func (a *Array) Clear()

func (a *Array) Delete(key any)

func (a *Array) Get(key any) (any, bool)

func (a *Array) Int64List() ([]int64, bool)

func (a *Array) Keys() []any

func (a *Array) Len() int

func (a *Array) Map() map[string]any

func (a *Array) Pop() (any, any, bool)

func (a *Array) Range(fn func(key, val any) bool)

func (a *Array) ReplaceInt64List(vals []int64)

func (a *Array) Set(key, val any)

type ArrayItem ¶

type ArrayItem struct {
	Key Expr
	Val Expr
}

ArrayItem is one entry of an ArrayLit. Key is nil for list-style entries.

type ArrayItemValue ¶

type ArrayItemValue struct {
	Key any
	Val any
}

ArrayItemValue is a runtime (already-evaluated) array entry, the value-level counterpart of the ArrayItem AST node. The transpiled __array/__pair helpers produce these. Key is nil for list-style appends.

type ArrayLit ¶

type ArrayLit struct {
	Items []ArrayItem
}

ArrayLit is `array(...)`, `[...]` or `{...}` (map/list literal).

type Assign ¶

type Assign struct {
	Target Expr // Var, PropAccess or Index
	Op     string
	Value  Expr
}

Assign is `Target = Value`. Op may be "=", ".=", "+=", "[]=" (append). expr-lang cannot mutate, so assignment is handled entirely by the runner.

type AssignExpr ¶

type AssignExpr struct {
	Target Expr
	Op     string
	Value  Expr
	Line   int
}

AssignExpr is assignment used as an expression, e.g. the PHP idiom `if (($x = f()) !== false)`. The README forbids assignment in conditions, but minitpl relies on it, so it is supported with Var/Index/Prop targets. As a statement it is lowered to *Assign by the parser.

type Binary ¶

type Binary struct {
	Op    string
	Left  Expr
	Right Expr
}

Binary is an infix operator. Op covers arithmetic (+ - * / % **), string concat ("."), comparison (== != === !== < <= > >=), logical (&& ||) and bitwise (& | ^ << >>).

type Break ¶

type Break struct {
	Line int
}

Break exits the nearest loop or switch. Line is the source line it was written on, which also gives the node an address of its own: Go hands every zero-sized allocation the same one, and the formatter keys source spans by node.

type Call ¶

type Call struct {
	Name     string
	Fallback string
	Args     []Expr
	Bare     bool // exit/die used without parentheses
}

Call is a free-function call: `name(args...)`.

Name is the primary (possibly namespace-qualified) function name. Fallback is the global-namespace name to try if Name is undefined. PHP resolves an unqualified call inside a namespace by first looking in the current namespace and then falling back to the global function of the same short name. Fallback is "" for calls that need no fallback (the common, non-namespaced case), in which case the call resolves as a bare env identifier exactly as before.

type Cast ¶

type Cast struct {
	Type string
	X    Expr
}

Cast is a type cast like `(bool)$x`, `(int)$x`, `(string)$x`, `(array)$x`.

type Catch ¶

type Catch struct {
	Type string
	Var  string
	Body []Stmt
	Line int // source line of the `catch` keyword, for comment placement
}

Catch is one `catch (...) { ... }` clause. Var is the bound variable name (without `$`); the caught error is assigned to it so `echo $e` prints it. Type is the declared filter, `Exception` or the union form `A|B`, which decides whether this clause handles the error. PHP requires it: a catch clause printed without it is a syntax error.

type Class ¶

type Class struct {
	Name string
	// Implements is every interface name the declaration listed, plus the names
	// those interfaces extend, lower-cased. It records which contracts the
	// class was checked against, and is what `instanceof` answers an interface
	// name from. No member arrives through it; see docs/design.md.
	Implements []string
	Fields     []Field
	Statics    []Field // static property declarations (Name + default Expr)
	Consts     []Field // class constants (Name + value Expr)
	Methods    map[string]*FuncDecl
}

Class is the resolved, runnable form of a ClassDecl: field defaults plus a method table keyed by method name.

Statics are the declarations of `static $name = expr` properties; their values live in the runtime (one bag per class, created on first access) so that every instance and every static call observes the same storage.

type ClassConst ¶

type ClassConst struct {
	Class string
	Name  string
}

ClassConst is `Class::NAME` / `self::NAME` class-constant access. The pseudo-constant `Class::class` is spelled with Name "class" and resolves to the fully-qualified class name as a string.

type ClassDecl ¶

type ClassDecl struct {
	Name       string
	Parent     string   // `extends Name`, recorded for printing, never inherited from
	Implements []string // `implements A, B`, a contract this class must declare
	Abstract   bool
	Final      bool
	Readonly   bool
	Fields     []Field
	Statics    []Field // `static $name = expr` properties, referenced as Class::$name
	Consts     []Field // class constants (Name + value Expr), referenced as Class::NAME
	Methods    []*FuncDecl
}

ClassDecl is a trimmed-down class: fields + methods + class constants, no inheritance. The `abstract`, `final` and `readonly` modifiers are tolerated (parsed) but not enforced (README omits abstract classes; minitpl's Hook is abstract only to declare constants).

Parent is recorded so a file the formatter rewrites prints back what it read: a name the AST cannot hold is a name the formatter deletes. Nothing in runner may read it. phpscript has no inheritance, a catch clause filters on a class name and `instanceof` is name equality. See docs/design.md.

Implements is recorded for the same reason and is also checked, by CheckInterfaces: every method the listed interfaces name must be declared by this class. The check confers nothing; it only reports what is missing.

type Closure ¶

type Closure struct {
	Params     []Param
	Uses       []ClosureUse
	Body       []Stmt
	ReturnType string // declared `: Type`, kept for printing only
	Static     bool
}

Closure is an anonymous function expression `function($a,$b) use ($c){ ... }`. minitpl uses one as the usort() comparator; composer's generated autoloader uses the `use (...)` capture form, so Uses records the captured names. Static marks `static function(){}`, which PHP declares to have no `$this`.

type ClosureUse ¶ added in v0.3.0

type ClosureUse struct {
	Name  string
	ByRef bool
}

ClosureUse is one entry of a closure's `use (...)` capture list. ByRef marks `&$name`; the runtime has no reference values, so a by-reference capture binds the same value a by-value one does.

type Continue ¶

type Continue struct {
	Line int
}

Continue restarts the nearest loop. Line is the source line, for the reason given on Break.

type DatabaseProvider ¶ added in v0.3.1

type DatabaseProvider interface {
	// Open returns a client for the first name that is configured.
	Open(ctx context.Context, names ...string) (*sqlx.DB, error)

	// Connect is Open plus a ping, so the caller knows the storage is
	// reachable before it is handed a client.
	Connect(ctx context.Context, names ...string) (*sqlx.DB, error)
}

DatabaseProvider resolves the named connections a script opens.

The interface lives here so a runtime can name it in its options without depending on the package that implements it, which is stdlib/database and which imports the runtime to register its bindings. A runtime knows only that something answers to a connection name; which connections exist is the host's business, and a virtual host answers differently from the process it shares.

type Declare ¶ added in v0.3.0

type Declare struct {
	Directives []DeclareDirective
	Body       []Stmt
	Block      bool // the `declare(...) { ... }` spelling, even with an empty body
}

Declare is `declare(strict_types=1);` or `declare(ticks=1) { ... }`. The runtime has one set of semantics and no directive varies it, so the directives are recorded for printing and otherwise ignored; a block form still runs its body.

type DeclareDirective ¶ added in v0.3.0

type DeclareDirective struct {
	Name  string
	Value Expr
}

DeclareDirective is one `name=value` pair of a Declare.

type Echo ¶

type Echo struct {
	Args []Expr
}

Echo writes the evaluated arguments to the output buffer.

type Expr ¶

type Expr interface {
	Node
	// contains filtered or unexported methods
}

Expr is an expression: something that evaluates to a value. Expressions are the unit the runner transpiles into go-expr (expr-lang) source and evaluates through the embedded VM.

func UnwrapParenthesized(e Expr) Expr

type ExprStmt ¶

type ExprStmt struct {
	X Expr
}

ExprStmt is an expression evaluated for its side effects (e.g. a method call).

type ExtendedDatabaseProvider ¶ added in v0.2.1

type ExtendedDatabaseProvider interface {
	List() []string
	Register(string, string)
}

ExtendedDatabaseProvider extends database providers with listing and registration.

type Field ¶

type Field struct {
	Name       string
	Default    Expr   // nil if none
	Visibility string // "public", "protected", "private", or ""
	Type       string // declared type hint, kept for printing only
	// Span is the source-line range of the declaration when Field came from
	// the parser. The formatter uses it to keep the blank lines an author put
	// between groups of properties.
	Span SourceSpan
}

Field is a class property declaration (also reused for class constants).

type For ¶

type For struct {
	Init Stmt
	Cond Expr
	Post Stmt
	Body []Stmt
}

For is `for (Init; Cond; Post) { Body }`. `while` is parsed into a For with nil Init/Post.

type Foreach ¶

type Foreach struct {
	Source    Expr
	KeyTarget Expr // nil if not captured
	ValTarget Expr
	ByRef     bool   // `as &$v`: the target writes back into Source
	KeyVar    string // deprecated: use KeyTarget
	ValVar    string // deprecated: use ValTarget
	Body      []Stmt
}

Foreach is `foreach (Source as [KeyTarget =>] ValTarget) { Body }`.

ByRef records the `as &$v` spelling. It selects between PHP's two loop semantics: by value the target holds a copy of the element, so writing to it leaves the source alone; by reference the target is the element, so writing to it edits the source.

type Func ¶

type Func struct {
	Decl *FuncDecl
	Go   any // an arbitrary Go func, invoked via reflection by the runtime
}

Func is a callable value: either a user-defined PHP function (Decl set) or a host Go function (Go set). Registered host functions use Go.

type FuncDecl ¶

type FuncDecl struct {
	Class      string // "" for free functions
	Name       string
	Filename   string
	Params     []Param
	Body       []Stmt
	Visibility string // "public", "protected", "private", or ""
	ReturnType string // declared `: Type`, kept for printing only
	Static     bool
	Abstract   bool // declaration only; Body is empty
}

FuncDecl is a free function or a class method declared with the `function Class::method()` syntax described in the README.

type If ¶

type If struct {
	Cond Expr
	Then []Stmt
	Else []Stmt // may itself contain a single nested *If for elseif chains
	// ElseLine is the source line of the `else` or `elseif` keyword, which is
	// not a statement of its own. It marks where the then arm ends, so the
	// formatter can tell a comment written above the keyword from one written
	// below it.
	ElseLine int
}

If is `if (Cond) { Then } elseif... else { Else }`.

type Include ¶

type Include struct {
	Path          Expr
	Keyword       string // include, include_once, require, or require_once
	Once          bool
	Parenthesized bool
}

Include pulls in another file (include / include_once / require). PHP allows include constructs both as standalone statements and as value-producing expressions.

type Index ¶

type Index struct {
	Base  Expr
	Index Expr
}

Index is `Base[Index]` element access.

type InlineHTML ¶

type InlineHTML struct {
	Text string
}

InlineHTML is raw text outside of <?php ... ?> tags. It is emitted verbatim.

type InterfaceContractError ¶ added in v0.3.4

type InterfaceContractError struct {
	Violations []InterfaceViolation
}

InterfaceContractError is the failure both backends raise for a violated contract. It reaches a script as a RuntimeException, so a `catch (RuntimeException $e)` written around an include takes it.

func (e *InterfaceContractError) Error() string

type InterfaceDecl ¶ added in v0.3.4

type InterfaceDecl struct {
	Name string
	// Extends is `extends A, B`. The extended interfaces widen the contract:
	// the names a class is checked against are the union of what every listed
	// interface declares. Nothing is inherited, because there is no member to
	// inherit; an interface declares no body and holds no storage.
	Extends []string
	Consts  []Field
	// Methods are signatures: the parameters, the return type and the modifiers
	// are recorded so the formatter prints the declaration back, and Body is
	// always nil. None of them is ever called; they are only names to check a
	// class against.
	Methods []*FuncDecl
}

InterfaceDecl is `interface Name extends A, B { ... }`.

An interface is a declaration contract and nothing else. It names method signatures and constants, and a class that says `implements` must declare every one of those methods itself. No member is ever acquired from it, no method body comes from it, and `instanceof` does not consult it, so `$a instanceof SomeInterface` stays false. See docs/design.md.

type InterfaceViolation ¶ added in v0.3.4

type InterfaceViolation struct {
	Decl      *ClassDecl
	Class     string
	Interface string
	Method    string
}

InterfaceViolation is one method an interface names and a class declaring `implements` did not declare.

Decl is the class declaration it was found on, so a caller holding the program's source spans can report the line the class was written on.

func CheckInterfaces(stmts []Stmt) []InterfaceViolation

func (v InterfaceViolation) String() string

type Interp ¶ added in v0.3.4

type Interp struct {
	Parts []Expr
	Raw   string
}

Interp is a double-quoted string literal that embeds expressions, such as `"hello $name"` or `"{$row['id']}: $count"`.

Parts alternates literal runs, held as *Lit strings with their escapes already decoded, and the expressions written between them. Evaluating one converts every part to a string and joins them, which is what `.` concatenation does, so an Interp and the equivalent concatenation produce the same value.

Raw holds the source spelling, quotes included, for the same reason Lit does: the formatter rewrites files in place and prints the literal the way it was written rather than re-encoding it.

type Invoke ¶ added in v0.3.0

type Invoke struct {
	Callee Expr
	Args   []Expr
}

Invoke calls a callable held in a value rather than named at the call site: `$fn($x)`, `$this->handlers[0]($x)`, `(self::$includeFile)($file)`. The callee is resolved through Runtime.Callable, so every PHP callable spelling (closure, "func", array($obj, "method")) works.

type ListExpr ¶

type ListExpr struct {
	Elems []Expr
}

ListExpr is `list($a, $b, ...)`, valid only as an assignment target. Elements may be nil for skipped positions (`list(, $b)`).

type Lit ¶

type Lit struct {
	Value any
	Raw   string
}

Lit is a literal scalar: nil, bool, int64, float64 or string.

Raw holds the source spelling, quotes included, for a string literal that came from a parsed file. Decoding a string is lossy (`'$a'` and `"\$a"` decode to the same value, and only one of them can be re-encoded from it), so the formatter prints from Raw and falls back to encoding Value for nodes that were built rather than parsed.

type MethodCall ¶

type MethodCall struct {
	Base   Expr
	Method string
	Args   []Expr
}

MethodCall is `Base->method(args...)` or `Base.method(args...)`.

type New ¶

type New struct {
	Class string
	Args  []Expr
}

New is `new ClassName` / `new ClassName(args...)`.

type Node ¶

type Node interface {
	// contains filtered or unexported methods
}

Node is the root interface for every AST element.

type Object ¶

type Object struct {
	Class *Class
	Props map[string]any
	ID    string
}

Object is a class instance: a property bag plus a pointer back to its class. Because methods live on the Class (resolved by the runtime), an Object passed into expr-lang exposes its Props for `$obj->field` style access.

func NewObject(c *Class) *Object

func (o *Object) SetID(id string)

type Param ¶

type Param struct {
	Name      string
	Default   Expr // nil if required
	Modifiers string
	Type      string
	ByRef     bool
	Variadic  bool
}

Param is a single function parameter with an optional default value.

The runtime binds a parameter by name and ignores everything declared around it, but the formatter rewrites files in place, so the declaration is kept: Modifiers holds the `public readonly` of a promoted constructor property, Type the type hint, and ByRef and Variadic the `&` and `...` markers.

type Parenthesized ¶ added in v0.2.0

type Parenthesized struct {
	X Expr
}

Parenthesized preserves explicit grouping from the source expression.

type Program ¶

type Program struct {
	Stmts     []Stmt
	Namespace string // set when the file declares `namespace Name;`
	// NamespaceLine is the source line of the namespace declaration, which is
	// not a statement of its own. The formatter needs it to place the comments
	// written above it.
	NamespaceLine int
	// SourceSpans records original statement lines when Program came from the
	// parser. Consumers may ignore it; the formatter uses it to retain a single
	// intentional blank line between statements.
	SourceSpans map[Stmt]SourceSpan
}

Program is the top-level result of parsing a single PHP file.

type PropAccess ¶

type PropAccess struct {
	Base Expr
	Name string
}

PropAccess is field access. The README allows both `$obj->field` and the new `obj.field` notation; both parse to this node.

type Return ¶

type Return struct {
	Value Expr // may be nil
}

Return exits the current function with an optional value.

type RouteAnnotation ¶ added in v0.2.0

type RouteAnnotation struct {
	Method string
	Path   string
}

RouteAnnotation is one // @route declaration found in a PHP source file.

type SourceSpan ¶ added in v0.2.0

type SourceSpan struct {
	Start int
	End   int
}

SourceSpan is the inclusive source-line range occupied by a statement.

type StaticCall ¶ added in v0.3.0

type StaticCall struct {
	Class  string
	Method string
	Args   []Expr
}

StaticCall is `Class::method(args...)`, including the `self::` and `static::` spellings. It carries no receiver: the runtime runs the declaration against a class rather than an instance.

type StaticProp ¶ added in v0.3.0

type StaticProp struct {
	Class string
	Name  string
}

StaticProp is `Class::$name` / `self::$name` static-property access. Unlike a PropAccess it names storage owned by the class, shared by every instance, so it is both read and assigned through the runtime's per-class static table.

type Stmt ¶

type Stmt interface {
	Node
	// contains filtered or unexported methods
}

Stmt is a statement: something executed for its side effects (echo, control flow, assignment, declarations). Statements are interpreted directly by the runner because expr-lang has no concept of statements, loops or mutation.

type Switch ¶

type Switch struct {
	Cond    Expr
	Cases   []SwitchCase
	Default []Stmt
}

Switch is `switch (Cond) { case V: ...; default: ... }`. Case bodies fall through unless they break (PHP semantics); the runner handles break/return.

type SwitchCase ¶

type SwitchCase struct {
	Value Expr
	Body  []Stmt
	Line  int
}

SwitchCase is one `case Value:` arm of a Switch. Line is the source line of the `case` keyword, which the formatter uses to place comments.

type Ternary ¶

type Ternary struct {
	Cond Expr
	Then Expr
	Else Expr
}

Ternary is `Cond ? Then : Else`.

type Throw ¶

type Throw struct {
	X Expr
}

Throw raises an exception. The VM has no exception model; it surfaces as a runtime error (sufficient for minitpl's error-path `throw`s, which the happy compile path never hits).

type Try ¶

type Try struct {
	Body        []Stmt
	Catches     []Catch
	Finally     []Stmt
	FinallyLine int // source line of the `finally` keyword, for comment placement
}

Try is `try { Body } catch (Type $var) { ... } finally { ... }`. The first clause whose declared type matches the error raised in Body (a throw or a runtime error from a forwarded Go call) handles it; an error no clause matches keeps propagating. Finally always runs either way. Matching is by Go error type rather than a PHP class hierarchy, so two throwable names backed by the same type cannot be told apart.

type Unary ¶

type Unary struct {
	Op      string
	X       Expr
	Postfix bool
}

Unary is a prefix/postfix operator: "!", "-", "+", "~", "++", "--".

type Unset ¶ added in v0.3.0

type Unset struct {
	Targets []Expr
}

Unset is `unset($a, $b[$k], $o->p, C::$s)`. Each target is removed from the scope, array or property bag holding it.

type Use ¶ added in v0.3.0

type Use struct {
	Kind    string // "", "function" or "const"
	Imports []UseImport
}

Use is `use A\B\C;`, `use A\B\C as D;` or `use function f;`. The parser resolves an import to a fully-qualified name while parsing, so the statement has no effect at runtime. It is still kept in the AST: the formatter rewrites files in place, and a node the printer cannot see is a node it deletes.

type UseImport ¶ added in v0.3.0

type UseImport struct {
	Path  string
	Alias string
}

UseImport is one name of a `use` statement. Alias is set only for the `as` spelling; the short name of Path is implied otherwise.

type Var ¶

type Var struct {
	Name  string
	Const bool
}

Var is a `$name` reference (the `$` is stripped during parsing).

A bare identifier, a constant such as `PHP_EOL` or a magic constant such as `__DIR__`, is also a Var, because both resolve the same way at runtime: the current scope first (which is where the magic constants live), then the constant table. Const records which spelling the source used, so that printing the node back out does not turn `PHP_EOL` into `$PHP_EOL`.