soml-lang 0.0.1 → 0.0.3

package/distribution/tree.d.ts

@@ -0,0 +1,264 @@
+/**
+A position in the source: a 1-based line, and a 0-based column in UTF-16 code units, as in ESTree.
+*/
+export type Position = {
+    /**
+    The 1-based line.
+    */
+    readonly line: number;
+    /**
+    The 0-based column, in UTF-16 code units.
+    */
+    readonly column: number;
+};
+/**
+Where a node, token, or comment is in the source.
+*/
+export type SourceLocation = {
+    /**
+    The position of the first character.
+    */
+    readonly start: Position;
+    /**
+    The position after the last character.
+    */
+    readonly end: Position;
+};
+type Located<Type extends string> = {
+    readonly type: Type;
+    /**
+    The start and end, as UTF-16 offsets into the text.
+    */
+    readonly range: readonly [start: number, end: number];
+    /**
+    The start and end, as lines and columns.
+    */
+    readonly loc: SourceLocation;
+};
+/**
+A token. `value` is its source text.
+
+A `Punctuator` is one of `{`, `}`, `[`, `]`, `:`, `,`, and `.`. A `Keyword` is `true`, `false`, or `null`. `infinity` and `-infinity` are `Float` tokens, and a quoted key segment is a `String` token.
+*/
+export type Token = Located<'Punctuator' | 'BareKey' | 'String' | 'Integer' | 'Float' | 'Keyword' | 'Instant' | 'Duration'> & {
+    readonly value: string;
+};
+/**
+A comment. `value` is its text without its delimiters.
+*/
+export type Comment = Located<'Line' | 'Block'> & {
+    readonly value: string;
+};
+/**
+The root of a tree.
+*/
+export type DocumentNode = Located<'Document'> & {
+    /**
+    The document's collection, an object or an array.
+    */
+    readonly body: ObjectNode | ArrayNode;
+    /**
+    Every token, in source order, without comments.
+    */
+    readonly tokens: readonly Token[];
+    /**
+    Every comment, in source order.
+    */
+    readonly comments: readonly Comment[];
+};
+/**
+An object, written with braces or as a top-level object without them.
+*/
+export type ObjectNode = Located<'Object'> & {
+    /**
+    The members, in source order.
+    */
+    readonly members: readonly MemberNode[];
+    /**
+    `false` only for a top-level object written without braces.
+    */
+    readonly braced: boolean;
+};
+/**
+A `key: value` member of an object.
+*/
+export type MemberNode = Located<'Member'> & {
+    /**
+    The key, which can be dotted.
+    */
+    readonly key: KeyNode;
+    /**
+    The value after the `:`.
+    */
+    readonly value: ValueNode;
+};
+/**
+An array, with its items in `elements`.
+*/
+export type ArrayNode = Located<'Array'> & {
+    /**
+    The items, in source order.
+    */
+    readonly elements: readonly ValueNode[];
+};
+/**
+A key, with more than one segment when it is dotted.
+*/
+export type KeyNode = Located<'Key'> & {
+    /**
+    The segments between the dots, in source order.
+    */
+    readonly segments: readonly KeySegmentNode[];
+};
+/**
+One segment of a key, which is the whole key unless it is dotted.
+*/
+export type KeySegmentNode = Located<'KeySegment'> & {
+    /**
+    The decoded key.
+    */
+    readonly value: string;
+    /**
+    How the segment is written: bare, as `'...'`, or as `"..."`.
+    */
+    readonly style: 'bare' | 'literal' | 'escaped';
+};
+/**
+A string, written as `'...'`, `"..."`, or a block string.
+*/
+export type StringNode = Located<'String'> & {
+    /**
+    The decoded string.
+    */
+    readonly value: string;
+    /**
+    Whether the string is written with `'` (literal) or `"` (escaped).
+    */
+    readonly style: 'literal' | 'escaped';
+    /**
+    Whether it is a block string.
+    */
+    readonly block: boolean;
+};
+/**
+An int, in any radix.
+*/
+export type IntegerNode = Located<'Integer'> & {
+    /**
+    The value, which is always a `bigint`.
+    */
+    readonly value: bigint;
+    /**
+    The radix it is written in: `2` for `0b`, `8` for `0o`, `16` for `0x`, and otherwise `10`.
+    */
+    readonly radix: 2 | 8 | 10 | 16;
+};
+/**
+A float, including `infinity` and `-infinity`.
+*/
+export type FloatNode = Located<'Float'> & {
+    /**
+    The value, including `Infinity` and `-Infinity`.
+    */
+    readonly value: number;
+};
+/**
+`true` or `false`.
+*/
+export type BooleanNode = Located<'Boolean'> & {
+    /**
+    The value.
+    */
+    readonly value: boolean;
+};
+/**
+The `null` keyword, which has no fields of its own.
+*/
+export type NullNode = Located<'Null'>;
+/**
+An instant, such as `2026-09-19T14:00:00Z`.
+*/
+export type InstantNode = Located<'Instant'> & {
+    /**
+    Made when it is first read, so that only reading it needs `Temporal`. Spreading or serializing the node reads it too.
+    */
+    readonly value: Temporal.Instant;
+};
+/**
+One part of a duration, such as `30m` in `1h30m`.
+*/
+export type DurationPart = {
+    /**
+    The number as it is written, with any `_` and fraction, such as `1_000` or `1.5`.
+    */
+    readonly number: string;
+    /**
+    The unit.
+    */
+    readonly unit: 'h' | 'm' | 's' | 'ms' | 'us' | 'ns';
+};
+/**
+A duration, such as `1h30m`.
+*/
+export type DurationNode = Located<'Duration'> & {
+    /**
+    Made when it is first read, so that only reading it needs `Temporal`. Spreading or serializing the node reads it too.
+    */
+    readonly value: Temporal.Duration;
+    /**
+    Whether it is written with a `-`, which negates the whole duration.
+    */
+    readonly negative: boolean;
+    /**
+    The parts as they are written, in order. So `-1h30m` is `negative` with the parts `1` `h` and `30` `m`.
+    */
+    readonly parts: readonly DurationPart[];
+};
+/**
+A node that is a value.
+*/
+export type ValueNode = ObjectNode | ArrayNode | StringNode | IntegerNode | FloatNode | BooleanNode | NullNode | InstantNode | DurationNode;
+/**
+Any node in a tree.
+*/
+export type Node = DocumentNode | MemberNode | KeyNode | KeySegmentNode | ValueNode;
+/**
+The properties of each node type that hold its child nodes, in source order, for tools that walk the tree, such as an ESLint language plugin.
+
+@example
+```
+import {visitorKeys} from 'soml-lang';
+
+visitorKeys.Member;
+//=> ['key', 'value']
+
+visitorKeys.Integer;
+//=> []
+```
+*/
+export declare const visitorKeys: Readonly<Record<Node['type'], readonly string[]>>;
+/**
+Parse a document into a syntax tree, for tools such as linters and formatters. Returns a `Document` node, which also holds every token and comment.
+
+Every node, token, and comment has a `range`, which is `[start, end]` as UTF-16 offsets into `text`, and a `loc`, which is `{start: {line, column}, end: {line, column}}`, with a 1-based line and a 0-based column in UTF-16 code units, as in ESTree. A `ParseError` counts its column differently, for people to read, so use its `offset` to find the position in the tree. A scalar node or a key segment shares its `range` and `loc` with its token, and other nodes, except `Document`, share the positions in `loc` with their first and last token, so treat them as read-only.
+
+@param text - The document.
+@returns The root node, which also holds every token and comment.
+@throws {ParseError} When the document is not valid, the same as `parse()`.
+@throws {TypeError} When `text` is not a string.
+
+@example
+```
+import {parseTree} from 'soml-lang';
+
+const tree = parseTree('port: 8080 # The default');
+
+tree.body.members[0].value;
+//=> {type: 'Integer', value: 8080n, radix: 10, range: [6, 10], loc: {…}}
+
+tree.comments[0];
+//=> {type: 'Line', value: ' The default', range: [11, 24], loc: {…}}
+```
+*/
+export declare function parseTree(text: string): DocumentNode;
+export {};