@glimmer/syntax

@glimmer/syntax

Version 0.94.3
Published 2 days ago
789 kB
5 dependencies
MIT license

Install

npm i @glimmer/syntax

yarn add @glimmer/syntax

pnpm add @glimmer/syntax

Overview

Overview not available.

Index

Variables

variable builders

const builders: {
    mustache: typeof buildMustache;
    block: typeof buildBlock;
    comment: typeof buildComment;
    mustacheComment: typeof buildMustacheComment;
    element: typeof buildElement;
    elementModifier: typeof buildElementModifier;
    attr: typeof buildAttr;
    text: typeof buildText;
    sexpr: typeof buildSexpr;
    concat: typeof buildConcat;
    hash: typeof buildHash;
    pair: typeof buildPair;
    literal: typeof buildLiteral;
    program: typeof buildProgram;
    blockItself: typeof buildBlockItself;
    template: typeof buildTemplate;
    loc: typeof buildLoc;
    pos: typeof buildPosition;
    path: typeof buildPath;
    fullPath: typeof buildCleanPath;
    head: typeof buildHeadFromString;
    at: typeof buildAtName;
    var: typeof buildVar;
    this: typeof buildThis;
    string: (value: string) => ASTv1.StringLiteral;
    boolean: (value: boolean) => ASTv1.BooleanLiteral;
    number: (value: number) => ASTv1.NumberLiteral;
    undefined(): ASTv1.UndefinedLiteral;
    null(): ASTv1.NullLiteral;
};

variable KEYWORDS_TYPES

const KEYWORDS_TYPES: {
    action: ('Call' | 'Modifier')[];
    component: ('Block' | 'Call' | 'Append')[];
    debugger: 'Append'[];
    'each-in': 'Block'[];
    each: 'Block'[];
    'has-block-params': ('Call' | 'Append')[];
    'has-block': ('Call' | 'Append')[];
    helper: ('Call' | 'Append')[];
    if: ('Block' | 'Call' | 'Append')[];
    'in-element': 'Block'[];
    let: 'Block'[];
    log: ('Call' | 'Append')[];
    modifier: ('Call' | 'Modifier')[];
    mount: 'Append'[];
    mut: ('Call' | 'Append')[];
    outlet: 'Append'[];
    readonly: ('Call' | 'Append')[];
    unbound: ('Call' | 'Append')[];
    unless: ('Block' | 'Call' | 'Append')[];
    yield: 'Append'[];
};

This includes the full list of keywords currently in use in the template language, and where their valid usages are.

variable visitorKeys

const visitorKeys: {
    readonly Template: readonly ['body'];
    readonly Block: readonly ['body'];
    readonly MustacheStatement: readonly ['path', 'params', 'hash'];
    readonly BlockStatement: readonly [
        'path',
        'params',
        'hash',
        'program',
        'inverse'
    ];
    readonly ElementModifierStatement: readonly ['path', 'params', 'hash'];
    readonly CommentStatement: readonly [];
    readonly MustacheCommentStatement: readonly [];
    readonly ElementNode: readonly [
        'attributes',
        'modifiers',
        'children',
        'comments'
    ];
    readonly AttrNode: readonly ['value'];
    readonly TextNode: readonly [];
    readonly ConcatStatement: readonly ['parts'];
    readonly SubExpression: readonly ['path', 'params', 'hash'];
    readonly PathExpression: readonly [];
    readonly StringLiteral: readonly [];
    readonly BooleanLiteral: readonly [];
    readonly NumberLiteral: readonly [];
    readonly NullLiteral: readonly [];
    readonly UndefinedLiteral: readonly [];
    readonly Hash: readonly ['pairs'];
    readonly HashPair: readonly ['value'];
};

Functions

function cannotRemoveNode

cannotRemoveNode: (
    node: ASTv1.Node,
    parent: ASTv1.Node,
    key: string
) => TraversalError;

function cannotReplaceNode

cannotReplaceNode: (
    node: ASTv1.Node,
    parent: ASTv1.Node,
    key: string
) => TraversalError;

function generateSyntaxError

generateSyntaxError: (
    message: string,
    location: src.SourceSpan
) => GlimmerSyntaxError;

function getTemplateLocals

getTemplateLocals: (
    html: string,
    options?: GetTemplateLocalsOptions
) => string[];

Parses and traverses a given handlebars html template to extract all template locals referenced that could possible come from the parent scope. Can exclude known keywords optionally.

function getVoidTags

getVoidTags: () => string[];

function hasSpan

hasSpan: (span: MaybeHasSourceSpan) => span is HasSourceSpan;

function isKeyword

isKeyword: {
    (word: string): word is
        | 'action'
        | 'component'
        | 'debugger'
        | 'each-in'
        | 'each'
        | 'has-block-params'
        | 'has-block'
        | 'helper'
        | 'if'
        | 'in-element'
        | 'let'
        | 'log'
        | 'modifier'
        | 'mount'
        | 'mut'
        | 'outlet'
        | 'readonly'
        | 'unbound'
        | 'unless'
        | 'yield';
    (word: string, type: KeywordType): boolean;
};

function isVoidTag

isVoidTag: (tag: string) => boolean;

Examples when true: - link - liNK
Examples when false: - Link (component)

function loc

loc: (span: HasSourceSpan) => SourceSpan;

function maybeLoc

maybeLoc: (location: MaybeHasSourceSpan, fallback: SourceSpan) => SourceSpan;

function node

node: {
    (): {
        fields<Fields extends object>(): NodeConstructor<Fields & BaseNodeFields>;
    };
    <T extends string>(name: T): {
        fields<Fields extends object>(): TypedNodeConstructor<
            T,
            Fields & BaseNodeFields
        >;
    };
};

This is a convenience function for creating ASTv2 nodes, with an optional name and the node's options.
export class HtmlText extends node('HtmlText').fields<{ chars: string }>() {}
This creates a new ASTv2 node with the name 'HtmlText' and one field chars: string (in addition to a loc: SourceOffsets field, which all nodes have).
export class Args extends node().fields<{ positional: PositionalArguments; named: NamedArguments }>() {}
This creates a new un-named ASTv2 node with two fields (positional: Positional and `named: Named, in addition to the generic loc: SourceOffsets` field).
Once you create a node using node, it is instantiated with all of its fields (including loc):
new HtmlText({ loc: offsets, chars: someString });

function normalize

normalize: (
    source: Source,
    options?: PrecompileOptionsWithLexicalScope
) => [ast: ASTv2.Template, locals: string[]];

function preprocess

preprocess: (
    input: string | src.Source | HBS.Program,
    options?: PreprocessOptions
) => ASTv1.Template;

function print

print: (ast: ASTv1.Node, options?: PrinterOptions) => string;

function sortByLoc

sortByLoc: (a: ASTv1.Node, b: ASTv1.Node) => -1 | 0 | 1;

function traverse

traverse: (node: ASTv1.Node, visitor: NodeVisitor) => void;

Classes

class BlockSymbolTable

class BlockSymbolTable extends SymbolTable {}

constructor

constructor(parent: SymbolTable, symbols: string[], slots: number[]);

property locals

readonly locals: string[];

property slots

slots: number[];

property symbols

symbols: string[];

method allocate

allocate: (identifier: string) => number;

method allocateBlock

allocateBlock: (name: string) => number;

method allocateFree

allocateFree: (name: string, resolution: ASTv2.FreeVarResolution) => number;

method allocateNamed

allocateNamed: (name: string) => number;

method get

get: (name: string) => [number, boolean];

method getDebugInfo

getDebugInfo: () => [
    locals: Record<string, number>,
    upvars: Record<string, number>
];

method getKeyword

getKeyword: (name: string) => number;

method getLocalsMap

getLocalsMap: () => Dict<number>;

method has

has: (name: string) => boolean;

method hasKeyword

hasKeyword: (name: string) => boolean;

method hasLexical

hasLexical: (name: string) => boolean;

method root

root: () => ProgramSymbolTable;

class Path

class Walker {}

constructor

constructor(order?: {});

property order

order?: {};

property stack

stack: unknown[];

method children

children: <N extends ASTv1.Node>(
    node: N & ASTv1.Node,
    callback: NodeCallback<N & ASTv1.Node>
) => void;

method visit

visit: <N extends ASTv1.Node>(
    node: Nullable<N>,
    visitor: NodeCallback<N>
) => void;

class ProgramSymbolTable

class ProgramSymbolTable extends SymbolTable {}

constructor

constructor(
    templateLocals: readonly string[],
    keywords: readonly string[],
    options: SymbolTableOptions
);

property blocks

readonly blocks: Dict<number>;

property named

readonly named: Dict<number>;

property symbols

readonly symbols: string[];

property upvars

readonly upvars: string[];

property usedTemplateLocals

readonly usedTemplateLocals: string[];

method allocate

allocate: (identifier: string) => number;

method allocateBlock

allocateBlock: (name: string) => number;

method allocateFree

allocateFree: (name: string, resolution: ASTv2.FreeVarResolution) => number;

method allocateNamed

allocateNamed: (name: string) => number;

method get

get: (name: string) => [number, boolean];

method getDebugInfo

getDebugInfo: () => Core.DebugSymbols;

method getKeyword

getKeyword: (name: string) => number;

method getLocalsMap

getLocalsMap: () => Dict<number>;

method getUsedTemplateLocals

getUsedTemplateLocals: () => string[];

method has

has: (name: string) => boolean;

method hasKeyword

hasKeyword: (name: string) => boolean;

method hasLexical

hasLexical: (name: string) => boolean;

method root

root: () => this;

class SourceSlice

class SourceSlice<Chars extends string = string> {}

constructor

constructor(options: { loc: src.SourceSpan; chars: Chars });

property chars

readonly chars: string;

property loc

readonly loc: src.SourceSpan;

method getString

getString: () => string;

method load

static load: (
    source: src.Source,
    slice: SerializedSourceSlice<string>
) => SourceSlice;

method serialize

serialize: () => SerializedSourceSlice<Chars>;

method synthetic

static synthetic: <S extends string>(chars: S) => SourceSlice<S>;

class SpanList

class SpanList {}

constructor

constructor(span?: SourceSpan[]);

method add

add: (offset: SourceSpan) => void;

method getRangeOffset

getRangeOffset: (fallback: SourceSpan) => SourceSpan;

method range

static range: {
    (span: PresentArray<HasSourceSpan>): SourceSpan;
    (span: HasSourceSpan[], fallback: SourceSpan): SourceSpan;
};

class SymbolTable

abstract class SymbolTable {}

method allocate

abstract allocate: (identifier: string) => number;

method allocateBlock

abstract allocateBlock: (name: string) => number;

method allocateFree

abstract allocateFree: (
    name: string,
    resolution: ASTv2.FreeVarResolution
) => number;

method allocateNamed

abstract allocateNamed: (name: string) => number;

method child

child: (locals: string[]) => BlockSymbolTable;

method get

abstract get: (name: string) => [symbol: number, isRoot: boolean];

method getDebugInfo

abstract getDebugInfo: () => Core.DebugSymbols;

method getKeyword

abstract getKeyword: (name: string) => number;

method getLocalsMap

abstract getLocalsMap: () => Dict<number>;

method has

abstract has: (name: string) => boolean;

method hasKeyword

abstract hasKeyword: (name: string) => boolean;

method hasLexical

abstract hasLexical: (name: string) => boolean;

method root

abstract root: () => ProgramSymbolTable;

method top

static top: (
    locals: readonly string[],
    keywords: readonly string[],
    options: SymbolTableOptions
) => ProgramSymbolTable;

class Walker

class Walker {}

constructor

constructor(order?: {});

property order

order?: {};

property stack

stack: unknown[];

method children

children: <N extends ASTv1.Node>(
    node: N & ASTv1.Node,
    callback: NodeCallback<N & ASTv1.Node>
) => void;

method visit

visit: <N extends ASTv1.Node>(
    node: Nullable<N>,
    visitor: NodeCallback<N>
) => void;

class WalkerPath

class WalkerPath<N extends ASTv1.Node> {}

constructor

constructor(
    node: ASTv1.Node,
    parent?: WalkerPath<ASTv1.Node>,
    parentKey?: string
);

property node

node: ASTv1.Node;

property parent

parent: WalkerPath<ASTv1.Node>;

property parentKey

parentKey: string;

property parentNode

readonly parentNode: ASTv1.Node;

method parents

parents: () => Iterable<WalkerPath<ASTv1.Node> | null>;

Interfaces

interface ASTPlugin

interface ASTPlugin {}

property name

name: string;

property visitor

visitor: NodeVisitor;

interface ASTPluginBuilder

interface ASTPluginBuilder<
    TEnv extends ASTPluginEnvironment = ASTPluginEnvironment
> {}

ASTPlugins can make changes to the Glimmer template AST before compilation begins.

call signature

(env: TEnv): ASTPlugin;

interface ASTPluginEnvironment

interface ASTPluginEnvironment {}

property meta

meta?: object | undefined;

property syntax

syntax: Syntax;

interface GlimmerSyntaxError

interface GlimmerSyntaxError extends Error {}

property code

code: string | null;

property location

location: src.SourceSpan | null;

interface PrecompileOptions

interface PrecompileOptions extends PreprocessOptions {}

property customizeComponentName

customizeComponentName?: ((input: string) => string) | undefined;

In loose mode, this hook allows embedding environments to customize the name of an angle-bracket component. In practice, this means that <HelloWorld /> in Ember is compiled by Glimmer as an invocation of a component named hello-world.
It's a little weird that this is needed in addition to the resolver, but it's a classic-only feature and it seems fine to leave it alone for classic consumers.

property id

id?: TemplateIdFn;

property keywords

keywords?: readonly string[];

Additional non-native keywords.
Local variables (block params or lexical scope) always takes precedence, but otherwise, suitable free variable candidates (e.g. those are not part of a path) are matched against this list and turned into keywords.
In strict mode compilation, keywords suppresses the undefined reference error and will be resolved by the runtime environment.
In loose mode, keywords are currently ignored and since all free variables are already resolved by the runtime environment.

interface PrecompileOptionsWithLexicalScope

interface PrecompileOptionsWithLexicalScope extends PrecompileOptions {}

property emit

emit?:
    | {
          debugSymbols?: boolean;
      }
    | undefined;

If emit.debugSymbols is set to true, the name of lexical local variables will be included in the wire format.

property lexicalScope

lexicalScope: (variable: string) => boolean;

interface PreprocessOptions

interface PreprocessOptions {}

property customizeComponentName

customizeComponentName?: ((input: string) => string) | undefined;

property locals

locals?: string[] | undefined;

property meta

meta?:
    | {
          moduleName?: string | undefined;
      }
    | undefined;

property mode

mode?: 'codemod' | 'precompile' | undefined;

Useful for specifying a group of options together.
When 'codemod' we disable all whitespace control in handlebars (to preserve as much as possible) and we also avoid any escaping/unescaping of HTML entity codes.

property parseOptions

parseOptions?: HandlebarsParseOptions | undefined;

property plugins

plugins?:
    | {
          ast?: ASTPluginBuilder[] | undefined;
      }
    | undefined;

property strictMode

strictMode?: boolean | undefined;

interface Syntax

interface Syntax {}

property builders

builders: typeof publicBuilder;

property parse

parse: typeof preprocess;

property print

print: typeof print;

property traverse

traverse: typeof traverse;

property Walker

Walker: typeof Walker;

interface TemplateIdFn

interface TemplateIdFn {}

call signature

(src: string): Nullable<string>;

Type Aliases

type HasSourceSpan

type HasSourceSpan =
    | {
          loc: SourceSpan;
      }
    | SourceSpan
    | [HasSourceSpan, ...HasSourceSpan[]];

type KeywordType

type KeywordType = 'Call' | 'Modifier' | 'Append' | 'Block';

type MaybeHasSourceSpan

type MaybeHasSourceSpan =
    | {
          loc: SourceSpan;
      }
    | SourceSpan
    | MaybeHasSourceSpan[];

type NodeVisitor

type NodeVisitor = {
    [P in keyof ASTv1.Nodes]?: NodeTraversal<ASTv1.Nodes[P]>;
} & {
    All?: NodeTraversal<ASTv1.Node>;
    /**
     * @deprecated use Template or Block instead
     */
    Program?: NodeTraversal<ASTv1.Template | ASTv1.Block>;
};

Namespaces

namespace AST

module 'dist/dev/lib/v1/api.d.ts' {}

interface AtHead

interface AtHead {}

property loc

loc: src.SourceSpan;

property name

name: string;

property original

original: string;

alias for name

property type

type: 'AtHead';

interface AttrNode

interface AttrNode extends BaseNode {}

property name

name: string;

property type

type: 'AttrNode';

property value

value: AttrValue;

interface BaseNode

interface BaseNode {}

property loc

loc: src.SourceSpan;

property type

type: NodeType;

interface Block

interface Block extends CommonProgram {}

property blockParams

blockParams: string[];

string accessor for params.name

property chained

chained?: boolean;

property params

params: VarHead[];

property type

type: 'Block';

interface BlockStatement

interface BlockStatement extends BaseNode {}

property chained

chained?: boolean;

property closeStrip

closeStrip: StripFlags;

property hash

hash: Hash;

property inverse

inverse?: Nullable<Block>;

property inverseStrip

inverseStrip: StripFlags;

property openStrip

openStrip: StripFlags;

property params

params: Expression[];

property path

path: CallableExpression;

property program

program: Block;

property type

type: 'BlockStatement';

interface BooleanLiteral

interface BooleanLiteral extends BaseNode {}

property original

original: boolean;

Deprecated
use value instead

property type

type: 'BooleanLiteral';

property value

value: boolean;

interface CallParts

interface CallParts {}

property hash

hash: Hash;

property loc

loc: src.SourceSpan;

property params

params: Expression[];

property path

path: CallableExpression;

interface CommentStatement

interface CommentStatement extends BaseNode {}

property type

type: 'CommentStatement';

property value

value: string;

interface CommonProgram

interface CommonProgram extends BaseNode {}

property body

body: Statement[];

interface ConcatStatement

interface ConcatStatement extends BaseNode {}

property parts

parts: PresentArray<TextNode | MustacheStatement>;

property type

type: 'ConcatStatement';

interface ElementModifierStatement

interface ElementModifierStatement extends BaseNode {}

property hash

hash: Hash;

property params

params: Expression[];

property path

path: CallableExpression;

property type

type: 'ElementModifierStatement';

interface ElementNode

interface ElementNode extends BaseNode {}

property attributes

attributes: AttrNode[];

property blockParams

blockParams: string[];

string accessor for params.name

property children

children: Statement[];

property closeTag

closeTag: Nullable<src.SourceSpan>;

span for the close tag, null for void or self-closing tags

property comments

comments: MustacheCommentStatement[];

property modifiers

modifiers: ElementModifierStatement[];

property openTag

openTag: src.SourceSpan;

span for the open tag

property params

params: VarHead[];

property path

path: PathExpression;

property selfClosing

selfClosing: boolean;

property tag

tag: string;

string accessor for path.original

property type

type: 'ElementNode';

interface Hash

interface Hash extends BaseNode {}

property pairs

pairs: HashPair[];

property type

type: 'Hash';

interface HashPair

interface HashPair extends BaseNode {}

property key

key: string;

property type

type: 'HashPair';

property value

value: Expression;

interface MinimalPathExpression

interface MinimalPathExpression extends BaseNode {}

property head

head: PathHead;

property tail

tail: string[];

property type

type: 'PathExpression';

interface MustacheCommentStatement

interface MustacheCommentStatement extends BaseNode {}

property type

type: 'MustacheCommentStatement';

property value

value: string;

interface MustacheStatement

interface MustacheStatement extends BaseNode {}

property escaped

escaped: boolean;

Deprecated
use trusting instead

property hash

hash: Hash;

property params

params: Expression[];

property path

path: Expression;

property strip

strip: StripFlags;

property trusting

trusting: boolean;

property type

type: 'MustacheStatement';

interface NullLiteral

interface NullLiteral extends BaseNode {}

property original

original: null;

Deprecated
use value instead

property type

type: 'NullLiteral';

property value

value: null;

interface NumberLiteral

interface NumberLiteral extends BaseNode {}

property original

original: number;

Deprecated
use value instead

property type

type: 'NumberLiteral';

property value

value: number;

interface PathExpression

interface PathExpression extends MinimalPathExpression {}

property data

readonly data: boolean;

Deprecated
use `head.type' instead

property head

head: PathHead;

property original

original: string;

property parts

parts: readonly string[];

Deprecated
use head and tail instead

property tail

tail: string[];

property this

readonly this: boolean;

Deprecated
use head.type instead

property type

type: 'PathExpression';

interface Position

interface SourcePosition {}

property column

column: number;

>= 0

property line

line: number;

>= 1

interface SourceLocation

interface SourceLocation {}

property end

end: SourcePosition;

property start

start: SourcePosition;

interface SourcePosition

interface SourcePosition {}

property column

column: number;

>= 0

property line

line: number;

>= 1

interface StringLiteral

interface StringLiteral extends BaseNode {}

property original

original: string;

Deprecated
use value instead

property type

type: 'StringLiteral';

property value

value: string;

interface StripFlags

interface StripFlags {}

property close

close: boolean;

property open

open: boolean;

interface SubExpression

interface SubExpression extends BaseNode {}

property hash

hash: Hash;

property params

params: Expression[];

property path

path: CallableExpression;

property type

type: 'SubExpression';

interface Template

interface Template extends CommonProgram {}

property blockParams

blockParams: string[];

property type

type: 'Template';

interface TextNode

interface TextNode extends BaseNode {}

property chars

chars: string;

property type

type: 'TextNode';

interface ThisHead

interface ThisHead {}

property loc

loc: src.SourceSpan;

property original

original: 'this';

property type

type: 'ThisHead';

interface UndefinedLiteral

interface UndefinedLiteral extends BaseNode {}

property original

original: undefined;

Deprecated
use value instead

property type

type: 'UndefinedLiteral';

property value

value: undefined;

interface VarHead

interface VarHead {}

property loc

loc: src.SourceSpan;

property name

name: string;

property original

original: string;

alias for name

property type

type: 'VarHead';

type AttrPart

type AttrPart = TextNode | MustacheStatement;

type AttrValue

type AttrValue = TextNode | MustacheStatement | ConcatStatement;

type CallableExpression

type CallableExpression = SubExpression | PathExpression;

type CallNode

type CallNode =
    | MustacheStatement
    | BlockStatement
    | ElementModifierStatement
    | SubExpression;

type EntityEncodingState

type EntityEncodingState = 'transformed' | 'raw';

type Expression

type Expression = Nodes[ExpressionName];

type ExpressionName

type ExpressionName = 'SubExpression' | 'PathExpression' | LiteralName;

type Expressions

type Expressions = Pick<Nodes, ExpressionName>;

type Literal

type Literal = Nodes[LiteralName];

type LiteralName

type LiteralName =
    | 'StringLiteral'
    | 'BooleanLiteral'
    | 'NumberLiteral'
    | 'UndefinedLiteral'
    | 'NullLiteral';

type Node

type Node = Nodes[NodeType];

type Nodes

type Nodes = {
    Template: Template;
    Block: Block;
    MustacheStatement: MustacheStatement;
    BlockStatement: BlockStatement;
    ElementModifierStatement: ElementModifierStatement;
    CommentStatement: CommentStatement;
    MustacheCommentStatement: MustacheCommentStatement;
    ElementNode: ElementNode;
    AttrNode: AttrNode;
    TextNode: TextNode;
    ConcatStatement: ConcatStatement;
    SubExpression: SubExpression;
    PathExpression: PathExpression;
    StringLiteral: StringLiteral;
    BooleanLiteral: BooleanLiteral;
    NumberLiteral: NumberLiteral;
    NullLiteral: NullLiteral;
    UndefinedLiteral: UndefinedLiteral;
    Hash: Hash;
    HashPair: HashPair;
};

type NodeType

type NodeType = keyof Nodes;

type ParentNode

type ParentNode = Template | Block | ElementNode;

type PathHead

type PathHead = ThisHead | AtHead | VarHead;

type Program

type Program = Template | Block;

Deprecated
use Template or Block instead

type Statement

type Statement = Nodes[StatementName];

type StatementName

type StatementName =
    | 'MustacheStatement'
    | 'CommentStatement'
    | 'BlockStatement'
    | 'MustacheCommentStatement'
    | 'TextNode'
    | 'ElementNode';

type Statements

type Statements = Pick<Nodes, StatementName>;

type SubNode

type SubNode = SubNodes[SubNodeType];

type SubNodes

type SubNodes = {
    ThisHead: ThisHead;
    AtHead: AtHead;
    VarHead: VarHead;
};

type SubNodeType

type SubNodeType = keyof SubNodes;

type TopLevelStatement

type TopLevelStatement = Statement | Nodes['Block'];

namespace ASTv1

module 'dist/dev/lib/v1/api.d.ts' {}

interface AtHead

interface AtHead {}

property loc

loc: src.SourceSpan;

property name

name: string;

property original

original: string;

alias for name

property type

type: 'AtHead';

interface AttrNode

interface AttrNode extends BaseNode {}

property name

name: string;

property type

type: 'AttrNode';

property value

value: AttrValue;

interface BaseNode

interface BaseNode {}

property loc

loc: src.SourceSpan;

property type

type: NodeType;

interface Block

interface Block extends CommonProgram {}

property blockParams

blockParams: string[];

string accessor for params.name

property chained

chained?: boolean;

property params

params: VarHead[];

property type

type: 'Block';

interface BlockStatement

interface BlockStatement extends BaseNode {}

property chained

chained?: boolean;

property closeStrip

closeStrip: StripFlags;

property hash

hash: Hash;

property inverse

inverse?: Nullable<Block>;

property inverseStrip

inverseStrip: StripFlags;

property openStrip

openStrip: StripFlags;

property params

params: Expression[];

property path

path: CallableExpression;

property program

program: Block;

property type

type: 'BlockStatement';

interface BooleanLiteral

interface BooleanLiteral extends BaseNode {}

property original

original: boolean;

Deprecated
use value instead

property type

type: 'BooleanLiteral';

property value

value: boolean;

interface CallParts

interface CallParts {}

property hash

hash: Hash;

property loc

loc: src.SourceSpan;

property params

params: Expression[];

property path

path: CallableExpression;

interface CommentStatement

interface CommentStatement extends BaseNode {}

property type

type: 'CommentStatement';

property value

value: string;

interface CommonProgram

interface CommonProgram extends BaseNode {}

property body

body: Statement[];

interface ConcatStatement

interface ConcatStatement extends BaseNode {}

property parts

parts: PresentArray<TextNode | MustacheStatement>;

property type

type: 'ConcatStatement';

interface ElementModifierStatement

interface ElementModifierStatement extends BaseNode {}

property hash

hash: Hash;

property params

params: Expression[];

property path

path: CallableExpression;

property type

type: 'ElementModifierStatement';

interface ElementNode

interface ElementNode extends BaseNode {}

property attributes

attributes: AttrNode[];

property blockParams

blockParams: string[];

string accessor for params.name

property children

children: Statement[];

property closeTag

closeTag: Nullable<src.SourceSpan>;

span for the close tag, null for void or self-closing tags

property comments

comments: MustacheCommentStatement[];

property modifiers

modifiers: ElementModifierStatement[];

property openTag

openTag: src.SourceSpan;

span for the open tag

property params

params: VarHead[];

property path

path: PathExpression;

property selfClosing

selfClosing: boolean;

property tag

tag: string;

string accessor for path.original

property type

type: 'ElementNode';

interface Hash

interface Hash extends BaseNode {}

property pairs

pairs: HashPair[];

property type

type: 'Hash';

interface HashPair

interface HashPair extends BaseNode {}

property key

key: string;

property type

type: 'HashPair';

property value

value: Expression;

interface MinimalPathExpression

interface MinimalPathExpression extends BaseNode {}

property head

head: PathHead;

property tail

tail: string[];

property type

type: 'PathExpression';

interface MustacheCommentStatement

interface MustacheCommentStatement extends BaseNode {}

property type

type: 'MustacheCommentStatement';

property value

value: string;

interface MustacheStatement

interface MustacheStatement extends BaseNode {}

property escaped

escaped: boolean;

Deprecated
use trusting instead

property hash

hash: Hash;

property params

params: Expression[];

property path

path: Expression;

property strip

strip: StripFlags;

property trusting

trusting: boolean;

property type

type: 'MustacheStatement';

interface NullLiteral

interface NullLiteral extends BaseNode {}

property original

original: null;

Deprecated
use value instead

property type

type: 'NullLiteral';

property value

value: null;

interface NumberLiteral

interface NumberLiteral extends BaseNode {}

property original

original: number;

Deprecated
use value instead

property type

type: 'NumberLiteral';

property value

value: number;

interface PathExpression

interface PathExpression extends MinimalPathExpression {}

property data

readonly data: boolean;

Deprecated
use `head.type' instead

property head

head: PathHead;

property original

original: string;

property parts

parts: readonly string[];

Deprecated
use head and tail instead

property tail

tail: string[];

property this

readonly this: boolean;

Deprecated
use head.type instead

property type

type: 'PathExpression';

interface Position

interface SourcePosition {}

property column

column: number;

>= 0

property line

line: number;

>= 1

interface SourceLocation

interface SourceLocation {}

property end

end: SourcePosition;

property start

start: SourcePosition;

interface SourcePosition

interface SourcePosition {}

property column

column: number;

>= 0

property line

line: number;

>= 1

interface StringLiteral

interface StringLiteral extends BaseNode {}

property original

original: string;

Deprecated
use value instead

property type

type: 'StringLiteral';

property value

value: string;

interface StripFlags

interface StripFlags {}

property close

close: boolean;

property open

open: boolean;

interface SubExpression

interface SubExpression extends BaseNode {}

property hash

hash: Hash;

property params

params: Expression[];

property path

path: CallableExpression;

property type

type: 'SubExpression';

interface Template

interface Template extends CommonProgram {}

property blockParams

blockParams: string[];

property type

type: 'Template';

interface TextNode

interface TextNode extends BaseNode {}

property chars

chars: string;

property type

type: 'TextNode';

interface ThisHead

interface ThisHead {}

property loc

loc: src.SourceSpan;

property original

original: 'this';

property type

type: 'ThisHead';

interface UndefinedLiteral

interface UndefinedLiteral extends BaseNode {}

property original

original: undefined;

Deprecated
use value instead

property type

type: 'UndefinedLiteral';

property value

value: undefined;

interface VarHead

interface VarHead {}

property loc

loc: src.SourceSpan;

property name

name: string;

property original

original: string;

alias for name

property type

type: 'VarHead';

type AttrPart

type AttrPart = TextNode | MustacheStatement;

type AttrValue

type AttrValue = TextNode | MustacheStatement | ConcatStatement;

type CallableExpression

type CallableExpression = SubExpression | PathExpression;

type CallNode

type CallNode =
    | MustacheStatement
    | BlockStatement
    | ElementModifierStatement
    | SubExpression;

type EntityEncodingState

type EntityEncodingState = 'transformed' | 'raw';

type Expression

type Expression = Nodes[ExpressionName];

type ExpressionName

type ExpressionName = 'SubExpression' | 'PathExpression' | LiteralName;

type Expressions

type Expressions = Pick<Nodes, ExpressionName>;

type Literal

type Literal = Nodes[LiteralName];

type LiteralName

type LiteralName =
    | 'StringLiteral'
    | 'BooleanLiteral'
    | 'NumberLiteral'
    | 'UndefinedLiteral'
    | 'NullLiteral';

type Node

type Node = Nodes[NodeType];

type Nodes

type Nodes = {
    Template: Template;
    Block: Block;
    MustacheStatement: MustacheStatement;
    BlockStatement: BlockStatement;
    ElementModifierStatement: ElementModifierStatement;
    CommentStatement: CommentStatement;
    MustacheCommentStatement: MustacheCommentStatement;
    ElementNode: ElementNode;
    AttrNode: AttrNode;
    TextNode: TextNode;
    ConcatStatement: ConcatStatement;
    SubExpression: SubExpression;
    PathExpression: PathExpression;
    StringLiteral: StringLiteral;
    BooleanLiteral: BooleanLiteral;
    NumberLiteral: NumberLiteral;
    NullLiteral: NullLiteral;
    UndefinedLiteral: UndefinedLiteral;
    Hash: Hash;
    HashPair: HashPair;
};

type NodeType

type NodeType = keyof Nodes;

type ParentNode

type ParentNode = Template | Block | ElementNode;

type PathHead

type PathHead = ThisHead | AtHead | VarHead;

type Program

type Program = Template | Block;

Deprecated
use Template or Block instead

type Statement

type Statement = Nodes[StatementName];

type StatementName

type StatementName =
    | 'MustacheStatement'
    | 'CommentStatement'
    | 'BlockStatement'
    | 'MustacheCommentStatement'
    | 'TextNode'
    | 'ElementNode';

type Statements

type Statements = Pick<Nodes, StatementName>;

type SubNode

type SubNode = SubNodes[SubNodeType];

type SubNodes

type SubNodes = {
    ThisHead: ThisHead;
    AtHead: AtHead;
    VarHead: VarHead;
};

type SubNodeType

type SubNodeType = keyof SubNodes;

type TopLevelStatement

type TopLevelStatement = Statement | Nodes['Block'];

namespace ASTv2

module 'dist/dev/lib/v2/api.d.ts' {}

variable COMPONENT_NAMESPACE

const COMPONENT_NAMESPACE: string;

variable HELPER_NAMESPACE

const HELPER_NAMESPACE: string;

variable HTML_RESOLUTION

const HTML_RESOLUTION: {
    isAngleBracket: true;
    resolution: () => GetContextualFreeOpcode;
    serialize: () => SerializedResolution;
};

variable MODIFIER_NAMESPACE

const MODIFIER_NAMESPACE: string;

variable STRICT_RESOLUTION

const STRICT_RESOLUTION: {
    resolution: () => GetContextualFreeOpcode;
    serialize: () => SerializedResolution;
    isAngleBracket: false;
};

Strict resolution is used:
1. in a strict mode template 2. in an local variable invocation with dot paths

function isLiteral

isLiteral: <K extends keyof LiteralTypes = keyof LiteralTypes>(
    node: ExpressionNode,
    kind?: K
) => node is StringLiteral;

Returns true if an input is a literal.

function isStrictResolution

isStrictResolution: (
    value: unknown
) => value is {
    resolution: () => GetContextualFreeOpcode;
    serialize: () => SerializedResolution;
    isAngleBracket: false;
};

function loadResolution

loadResolution: (resolution: SerializedResolution) => FreeVarResolution;

function node

node: {
    (): {
        fields<Fields extends object>(): NodeConstructor<Fields & BaseNodeFields>;
    };
    <T extends string>(name: T): {
        fields<Fields extends object>(): TypedNodeConstructor<
            T,
            Fields & BaseNodeFields
        >;
    };
};

This is a convenience function for creating ASTv2 nodes, with an optional name and the node's options.
export class HtmlText extends node('HtmlText').fields<{ chars: string }>() {}
This creates a new ASTv2 node with the name 'HtmlText' and one field chars: string (in addition to a loc: SourceOffsets field, which all nodes have).
export class Args extends node().fields<{ positional: PositionalArguments; named: NamedArguments }>() {}
This creates a new un-named ASTv2 node with two fields (positional: Positional and `named: Named, in addition to the generic loc: SourceOffsets` field).
Once you create a node using node, it is instantiated with all of its fields (including loc):
new HtmlText({ loc: offsets, chars: someString });

class AppendContent

class AppendContent extends AppendContent_base {}

property args

readonly args: Args;

property callee

readonly callee: ExpressionNode;

class ArgReference

class ArgReference extends ArgReference_base {}

Corresponds to @<ident> at the beginning of an expression.

class Args

class Args extends Args_base {}

Corresponds to syntaxes with positional and named arguments:
- SubExpression - Invoking Append - Invoking attributes - InvokeBlock
If Args is empty, the SourceOffsets for this node should be the collapsed position immediately after the parent call node's callee.

method empty

static empty: (loc: SourceSpan) => Args;

method get

get: (name: string) => ExpressionNode | null;

method isEmpty

isEmpty: () => boolean;

method named

static named: (named: NamedArguments) => Args;

method nth

nth: (offset: number) => ExpressionNode | null;

class Block

class Block extends Block_base {}

Represents a block. In principle this could be merged with NamedBlock, because all cases involving blocks have at least a notional name.

class CallExpression

class CallExpression extends CallExpression_base {}

Corresponds to a parenthesized call expression.
(x) (x.y) (x y) (x.y z)

class ComponentArg

class ComponentArg extends ComponentArg_base {}

Corresponds to an argument passed by a component (@x=<value>)

method toNamedArgument

toNamedArgument: () => NamedArgument;

Convert the component argument into a named argument node

class ElementModifier

class ElementModifier extends ElementModifier_base {}

An ElementModifier is just a normal call node in modifier position.

class FreeVarReference

class FreeVarReference extends FreeVarReference_base {}

Corresponds to <ident> at the beginning of an expression, when <ident> is *not* in the current block's scope.
The resolution: FreeVarResolution field describes how to resolve the free variable.
Note: In strict mode, it must always be a variable that is in a concrete JavaScript scope that the template will be installed into.

class GlimmerComment

class GlimmerComment extends GlimmerComment_base {}

class HtmlAttr

class HtmlAttr extends HtmlAttr_base {}

HtmlAttr nodes are valid HTML attributes, with or without a value.
Exceptions:
- ...attributes is SplatAttr - @x=<value> is ComponentArg

class HtmlComment

class HtmlComment extends HtmlComment_base {}

class HtmlText

class HtmlText extends HtmlText_base {}

class InterpolateExpression

class InterpolateExpression extends InterpolateExpression_base {}

Corresponds to an interpolation in attribute value position.
<a href="{{url}}.html"

class InvokeBlock

class InvokeBlock extends InvokeBlock_base {}

class InvokeComponent

class InvokeComponent extends InvokeComponent_base {}

Corresponds to a component invocation. When the content of a component invocation contains no named blocks, blocks contains a single named block named "default". When a component invocation is self-closing, blocks is empty.

property args

readonly args: Args;

class KeywordExpression

class KeywordExpression extends KeywordExpression_base {}

Corresponds to a known strict-mode keyword. It behaves similarly to a PathExpression with a FreeVarReference, but implies StrictResolution and is guaranteed to not have a tail, since {{outlet.foo}} would have been illegal.

class LiteralExpression

class LiteralExpression extends LiteralExpression_base {}

Corresponds to a Handlebars literal.
See Also
- {LiteralValue}

method toSlice

toSlice: (this: StringLiteral) => SourceSlice;

class LocalVarReference

class LocalVarReference extends LocalVarReference_base {}

Corresponds to <ident> at the beginning of an expression, when <ident> is in the current block's scope.

class LooseModeResolution

class LooseModeResolution {}

A LooseModeResolution includes one or more namespaces to resolve the variable in
In practice, there are a limited number of possible combinations of these degrees of freedom, and they are captured by the Namespaces union below.

constructor

constructor(namespaces: Namespaces, isAngleBracket?: boolean);

property isAngleBracket

readonly isAngleBracket: boolean;

property namespaces

readonly namespaces: Namespaces;

method append

static append: () => LooseModeResolution;

Append resolution is used when the variable should be resolved in both the component and helper namespaces.
{{x}}
{{x y}}
^ In either case, x should be resolved in the component and helper namespaces.

method namespaced

static namespaced: (
    namespace: FreeVarNamespace,
    isAngleBracket?: boolean
) => LooseModeResolution;

Namespaced resolution is used in an unambiguous syntax position:
1. (sexp) (namespace: Helper) 2. {{#block}} (namespace: Component) 3. <a {{modifier}}> (namespace: Modifier) 4. <Component /> (namespace: Component)

method resolution

resolution: () => GetContextualFreeOpcode;

method serialize

serialize: () => SerializedResolution;

method trustingAppend

static trustingAppend: () => LooseModeResolution;

Trusting append resolution is used when the variable should be resolved only in the helper namespaces.
{{{x}}}
{{{x y}}}
^ In either case, x should be resolved in the helper namespace.

class NamedArgument

class NamedArgument {}

Corresponds to a single named argument.
x=<expr>

constructor

constructor(options: { name: SourceSlice; value: ExpressionNode });

property loc

readonly loc: SourceSpan;

property name

readonly name: SourceSlice<string>;

property value

readonly value: ExpressionNode;

class NamedArguments

class NamedArguments extends NamedArguments_base {}

Corresponds to named arguments.
If PositionalArguments and NamedArguments are empty, the SourceOffsets for this node should be the same as the Args node that contains this node.
If PositionalArguments is not empty but NamedArguments is empty, the SourceOffsets for this node should be the collapsed position immediately after the last positional argument.

property size

readonly size: number;

method empty

static empty: (loc: SourceSpan) => NamedArguments;

method get

get: (name: string) => ExpressionNode | null;

method isEmpty

isEmpty: () => boolean;

class NamedBlock

class NamedBlock extends NamedBlock_base {}

Corresponds to a single named block. This is used for anonymous named blocks (default and else).

property args

readonly args: Args;

class NamedBlocks

class NamedBlocks extends NamedBlocks_base {}

Corresponds to a collection of named blocks.

method get

get: { (name: 'default'): NamedBlock; (name: string): NamedBlock };

Get the NamedBlock for a given name.

class PathExpression

class PathExpression extends PathExpression_base {}

Corresponds to a path in expression position.
this this.x @x @x.y x x.y

class PositionalArguments

class PositionalArguments extends PositionalArguments_base {}

Corresponds to positional arguments.
If PositionalArguments is empty, the SourceOffsets for this node should be the collapsed position immediately after the parent call node's callee.

property size

readonly size: number;

method empty

static empty: (loc: SourceSpan) => PositionalArguments;

method isEmpty

isEmpty: () => boolean;

method nth

nth: (offset: number) => ExpressionNode | null;

class SimpleElement

class SimpleElement extends SimpleElement_base {}

Corresponds to a simple HTML element. The AST allows component arguments and modifiers to support future extensions.

property args

readonly args: Args;

class SplatAttr

class SplatAttr extends SplatAttr_base {}

class Template

class Template extends Template_base {}

Corresponds to an entire template.

class ThisReference

class ThisReference extends ThisReference_base {}

Corresponds to this at the head of an expression.

interface AttrNodeOptions

interface AttrNodeOptions {}

property name

name: SourceSlice;

property trusting

trusting: boolean;

property value

value: ExpressionNode;

interface BaseNodeFields

interface BaseNodeFields {}

property loc

loc: SourceSpan;

interface CallFields

interface CallFields extends BaseNodeFields {}

property args

args: Args;

property callee

callee: CalleeNode;

interface GlimmerParentNodeOptions

interface GlimmerParentNodeOptions extends BaseNodeFields {}

property body

body: readonly ContentNode[];

interface LiteralTypes

interface LiteralTypes {}

property boolean

boolean: boolean;

property null

null: null;

property number

number: number;

property string

string: string;

property undefined

undefined: undefined;

interface NamedBlockFields

interface NamedBlockFields extends BaseNodeFields {}

property attrs

attrs: readonly HtmlOrSplatAttr[];

property block

block: Block;

property componentArgs

componentArgs: readonly ComponentArg[];

property modifiers

modifiers: readonly ElementModifier[];

property name

name: SourceSlice;

interface NodeConstructor

interface NodeConstructor<Fields> {}

construct signature

new (fields: Fields): Readonly<Fields>;

interface SerializedBaseNode

interface SerializedBaseNode {}

property loc

loc: SerializedSourceSpan;

interface TypedNodeConstructor

interface TypedNodeConstructor<T extends string, Fields> {}

construct signature

new (options: Fields): TypedNode<T, Fields>;

type AttrBlockNode

type AttrBlockNode = AttrNode | ElementModifier;

"Attr Block" nodes are allowed inside an open element tag in templates. They interact with the element (or component).

type AttrNode

type AttrNode = HtmlAttr | SplatAttr | ComponentArg;

Attr nodes look like HTML attributes, but are classified as:
1. HtmlAttr, which means a regular HTML attribute in Glimmer 2. SplatAttr, which means ...attributes 3. ComponentArg, which means an attribute whose name begins with @, and it is therefore a component argument.

type CalleeNode

type CalleeNode = KeywordExpression | PathExpression | CallExpression;

type CallNode

type CallNode =
    | CallExpression
    | InvokeBlock
    | AppendContent
    | InvokeComponent
    | ElementModifier;

type ContentNode

type ContentNode =
    | HtmlText
    | HtmlComment
    | AppendContent
    | InvokeBlock
    | InvokeComponent
    | SimpleElement
    | GlimmerComment;

Content Nodes are allowed in content positions in templates. They correspond to behavior in the [Data][data] tokenization state in HTML.
[data]: https://html.spec.whatwg.org/multipage/parsing.html#data-state

type ElementNode

type ElementNode = NamedBlock | InvokeComponent | SimpleElement;

type ExpressionNode

type ExpressionNode =
    | LiteralExpression
    | PathExpression
    | KeywordExpression
    | CallExpression
    | InterpolateExpression;

type FreeVarResolution

type FreeVarResolution = StrictResolution | HtmlResolution | LooseModeResolution;

type HtmlOrSplatAttr

type HtmlOrSplatAttr = HtmlAttr | SplatAttr;

HtmlAttr and SplatAttr are grouped together because the order of the SplatAttr node, relative to other attributes, matters.

type HtmlResolution

type HtmlResolution = typeof HTML_RESOLUTION;

type LiteralValue

type LiteralValue = string | boolean | number | undefined | null;

A Handlebars literal.
https://handlebarsjs.com/guide/expressions.html#literal-segments

type SerializedResolution

type SerializedResolution =
    | 'Strict'
    | 'Helper'
    | 'Modifier'
    | 'Component'
    | 'ComponentOrHelper';

type StrictResolution

type StrictResolution = typeof STRICT_RESOLUTION;

type StringLiteral

type StringLiteral = LiteralExpression & {
    value: string;
};

type VariableReference

type VariableReference =
    | ThisReference
    | ArgReference
    | LocalVarReference
    | FreeVarReference;

namespace src

module 'dist/dev/lib/source/api.d.ts' {}

variable NON_EXISTENT_LOCATION

const NON_EXISTENT_LOCATION: Readonly<{
    readonly source: '(nonexistent)';
    readonly start: Readonly<{ readonly line: 1; readonly column: 0 }>;
    readonly end: Readonly<{ readonly line: 1; readonly column: 0 }>;
}>;

variable SYNTHETIC_LOCATION

const SYNTHETIC_LOCATION: Readonly<{
    readonly source: '(synthetic)';
    readonly start: Readonly<{ readonly line: 1; readonly column: 0 }>;
    readonly end: Readonly<{ readonly line: 1; readonly column: 0 }>;
}>;

variable UNKNOWN_POSITION

const UNKNOWN_POSITION: Readonly<{ readonly line: 1; readonly column: 0 }>;

function hasSpan

hasSpan: (span: MaybeHasSourceSpan) => span is HasSourceSpan;

function loc

loc: (span: HasSourceSpan) => SourceSpan;

function maybeLoc

maybeLoc: (location: MaybeHasSourceSpan, fallback: SourceSpan) => SourceSpan;

class Source

class Source {}

constructor

constructor(source: string, module?: string);

property module

readonly module: string;

property source

readonly source: string;

method charPosFor

charPosFor: (position: SourcePosition) => number | null;

method from

static from: (source: string, options?: PrecompileOptions) => Source;

method hbsPosFor

hbsPosFor: (offset: number) => Nullable<SourcePosition>;

method offsetFor

offsetFor: (line: number, column: number) => SourceOffset;

method slice

slice: (start: number, end: number) => string;

method spanFor

spanFor: ({ start, end }: Readonly<SourceLocation>) => SourceSpan;

method validate

validate: (offset: number) => boolean;

Validate that the character offset represents a position in the source string.

class SourceOffset

class SourceOffset {}

A SourceOffset represents a single position in the source.
There are three kinds of backing data for SourceOffset objects:
- CharPosition, which contains a character offset into the raw source string - HbsPosition, which contains a SourcePosition from the Handlebars AST, which can be converted to a CharPosition on demand. - InvisiblePosition, which represents a position not in source (@see {InvisiblePosition})

constructor

constructor(data: PositionData & AnyPosition);

property data

readonly data: PositionData & AnyPosition;

property offset

readonly offset: number;

Get the character offset for this SourceOffset, if possible.

method broken

static broken: (pos?: SourcePosition) => SourceOffset;

Create a SourceOffset that corresponds to a broken SourcePosition. This means that the calling code determined (or knows) that the SourceLocation doesn't correspond correctly to any part of the source.

method collapsed

collapsed: () => SourceSpan;

Create a new SourceSpan that represents a collapsed range at this source offset. Avoid computing the character offset if it has not already been computed.

method eql

eql: (right: SourceOffset) => boolean;

Compare this offset with another one.
If both offsets are HbsPositions, they're equivalent as long as their lines and columns are the same. This avoids computing offsets unnecessarily.
Otherwise, two SourceOffsets are equivalent if their successfully computed character offsets are the same.

method forHbsPos

static forHbsPos: (source: Source, pos: SourcePosition) => SourceOffset;

Create a SourceOffset from a Handlebars SourcePosition. It's stored as-is, and converted into a character offset on demand, which avoids unnecessarily computing the offset of every SourceLocation, but also means that broken SourcePositions are not always detected.

method move

move: (by: number) => SourceOffset;

Create a SourceOffset by moving the character position represented by this source offset forward or backward (if by is negative), if possible.
If this SourceOffset can't compute a valid character offset, move returns a broken offset.
If the resulting character offset is less than 0 or greater than the size of the source, move returns a broken offset.