From 13dcceeeb9c837aa72ecea0eecb0b8c1434a0e57 Mon Sep 17 00:00:00 2001 From: Ilya Lakhin Date: Wed, 4 Sep 2024 04:31:15 +0600 Subject: [PATCH] Release 2.1.0 Semantic Analysis Framework: - #22: Introduced the new `Slot` object. This object is similar to `Attr`, except that its value is edited directly by the API user, and it does not have an associated computable function. This allows users to inject external metadata into the semantic model. - #22: Implemented the common semantic feature. This feature enables the user to specify Analyzer-wide semantic graph nodes (attributes and slots) that are shared across all compilation units. These enhancements address the lack of global state within the Analyzer's semantic analysis framework and introduce a conventional method to organize cross-document relationships. Lexer: - #16: Introduced new `$xid_start` and `$xid_continue` Lexer Regex classes. - #16: Added support for classes with combined Unicode properties: `${alpha | num}`. - #16: Adjusted the `$alpha` class in accordance with UCD specifications. - #16: Introduced the `lexis::Char` and `lexis::CharProperties` types in the main crate, enabling users to test characters for Unicode properties. - #20: Added a new Token operator `i("abc")` that expands to case-insensitive matching. - Fixed an edge-case bug in the Document (MutableUnit). The Mutable Document's lexer sometimes misinterpreted trailing token bounds when the user rewrote the end of the text. - Fixed a minor bug in the `#[constructor]` attribute of the Token macro. Syntax Parser: - #19: Fixed a minor bug in the conflict resolutions of the Node macro's root rule. Breaking Changes: - #22: The `analysis::Feature` and `analysis::AbstractFeature` traits have received new members. --- .../src/code-formatters/code-formatters.md | 4 +-- .../src/code-formatters/pretty-printer.md | 22 +++++++------- work/book/src/documents.md | 26 ++++++++-------- work/book/src/lexis/code-inspection.md | 28 ++++++++--------- work/book/src/lexis/lexical-grammar.md | 4 +-- work/book/src/lexis/site-references.md | 12 ++++---- work/book/src/lexis/source-code.md | 8 ++--- work/book/src/lexis/token-buffer.md | 4 +-- work/book/src/lexis/token-references.md | 12 ++++---- work/book/src/overview.md | 18 +++++------ work/book/src/semantics/code-diagnostics.md | 6 ++-- .../src/semantics/configuration-issues.md | 18 +++++------ work/book/src/semantics/grammar-setup.md | 18 +++++------ work/book/src/semantics/granularity.md | 6 ++-- .../book/src/semantics/multi-file-analysis.md | 14 ++++----- work/book/src/semantics/scope-access.md | 2 +- work/book/src/semantics/semantic-graph.md | 8 ++--- work/book/src/semantics/side-effects.md | 8 ++--- work/book/src/semantics/tasks-management.md | 18 +++++------ work/book/src/semantics/the-analyzer.md | 28 ++++++++--------- work/book/src/semantics/tree-index.md | 12 ++++---- work/book/src/snippets.md | 12 ++++---- work/book/src/syntax/debugging.md | 6 ++-- work/book/src/syntax/node-references.md | 12 ++++---- work/book/src/syntax/overriding-a-parser.md | 4 +-- work/book/src/syntax/syntax-grammar.md | 10 +++---- work/book/src/syntax/syntax-session.md | 30 +++++++++---------- work/book/src/syntax/syntax-tree.md | 10 +++---- work/book/src/syntax/tree-inspection.md | 8 ++--- work/crates/derive/Cargo.toml | 2 +- work/crates/derive/src/token/mod.rs | 1 - work/crates/derive/src/token/ucd.rs | 1 + work/crates/main/Cargo.toml | 4 +-- 33 files changed, 188 insertions(+), 188 deletions(-) create mode 120000 work/crates/derive/src/token/ucd.rs diff --git a/work/book/src/code-formatters/code-formatters.md b/work/book/src/code-formatters/code-formatters.md index 06956dc..6191641 100644 --- a/work/book/src/code-formatters/code-formatters.md +++ b/work/book/src/code-formatters/code-formatters.md @@ -47,11 +47,11 @@ their respective lines. Lady Deirdre offers two tools to aid in implementing the code formatter: 1. The - [ParseTree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.ParseTree.html) + [ParseTree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.ParseTree.html) builder constructs a concrete parsing tree. Unlike abstract syntax trees, it intentionally preserves all original source code whitespaces and comments. 2. The - [PrettyPrinter](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html) + [PrettyPrinter](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html) tool automatically decides on splitting the text into lines and determines line indentation to ensure that the final lines are aligned according to the predefined maximum line length. diff --git a/work/book/src/code-formatters/pretty-printer.md b/work/book/src/code-formatters/pretty-printer.md index a1236e4..e0ab334 100644 --- a/work/book/src/code-formatters/pretty-printer.md +++ b/work/book/src/code-formatters/pretty-printer.md @@ -47,7 +47,7 @@ following lines in accordance with the nesting of the groups. ## Printing Words -The [PrettyPrinter::word](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.word) +The [PrettyPrinter::word](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.word) function inputs a string word token into the printer, which will be printed on the current line of the output, thus increasing the line length. @@ -66,19 +66,19 @@ forcibly break lines. In such cases, you should use the *hardbreak* function. To separate the words in the output of the printer, you utilize one of the pretty printer's "blank" token functions: -- [PrettyPrinter::blank](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.blank) +- [PrettyPrinter::blank](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.blank) is the default blank token, interpreted either as a single whitespace or a line break. You call this function when the next word should be separated from the previous one, possibly with a line break, depending on the printing algorithm's decision. -- [PrettyPrinter::hardbreak](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.hardbreak) +- [PrettyPrinter::hardbreak](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.hardbreak) is a blank token that enforces the printer to always interpret it as a line break. You call this function, for instance, when printing the inner content of multi-line comments, as the structure of the comment's text typically needs to be preserved. -- [PrettyPrinter::softbreak](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.softbreak) +- [PrettyPrinter::softbreak](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.softbreak) is similar to the *blank* function, but if the printer's algorithm decides to preserve the next token on the line, it does not insert whitespace. This function is useful, for example, to delimit the `.` dot tokens in a @@ -115,13 +115,13 @@ more suitable. ``` Content breaking occurs within word groups. To initiate a new group, you use -either [PrettyPrinter::cbox](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.cbox) -or [PrettyPrinter::ibox](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.ibox). +either [PrettyPrinter::cbox](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.cbox) +or [PrettyPrinter::ibox](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.ibox). The former begins a consistent word group, while the latter starts an inconsistent group. Each group must be closed by -calling [PrettyPrinter::end](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.end). +calling [PrettyPrinter::end](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.end). Both *cbox* and *ibox* functions accept indentation level shifting for the group, represented by a signed integer. Positive values increase the inner @@ -132,7 +132,7 @@ with whitespace according to the current indentation level. ## Overriding Indentations You can manually adjust line indentation by calling -the [PrettyPrinter::indent](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.indent) +the [PrettyPrinter::indent](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.indent) function **immediately after** submitting any of the blank tokens. If the algorithm interprets the submitted token as a line break, the next line, as well as all subsequent lines, will be shifted accordingly. @@ -153,7 +153,7 @@ are situations where it's preferable to keep the parental content aligned in line and splitting of the nested groups instead. In such cases, you can utilize -the [PrettyPrinter::neverbreak](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.neverbreak) +the [PrettyPrinter::neverbreak](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.neverbreak) function, which instructs the printer to reset the current line length counter to zero. Consequently, the algorithm assumes that the previously submitted text fits on the line, and begins splitting from the subsequent nested submissions. @@ -173,8 +173,8 @@ single line. This formatting rule depends on whether the algorithm decides to insert a line break at the blank token. To address this, you can use -the [PrettyPrinter::pre_break](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.pre_break) -and [PrettyPrinter::pre_space](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.PrettyPrinter.html#method.pre_space) +the [PrettyPrinter::pre_break](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.pre_break) +and [PrettyPrinter::pre_space](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.PrettyPrinter.html#method.pre_space) functions to configure the preceding blank token. Both functions must be called **immediately after** submitting the blank token. diff --git a/work/book/src/documents.md b/work/book/src/documents.md index 5c2b263..3258bba 100644 --- a/work/book/src/documents.md +++ b/work/book/src/documents.md @@ -39,8 +39,8 @@ compilation unit, along with its lexical and syntax structures. It ensures all three components remain synchronized. This object has two -constructors: [Document::new_mutable](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html#method.new_mutable) -and [Document::new_immutable](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html#method.new_immutable). +constructors: [Document::new_mutable](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html#method.new_mutable) +and [Document::new_immutable](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html#method.new_immutable). Both constructors take the source code text as the initial input for the Document. The first constructor creates a Document that supports write @@ -49,7 +49,7 @@ document's text. The second constructor creates a Document that does not support write operations but is slightly faster during the document's creation. To edit a mutable Document, you use -the [Document::write](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html#method.write) +the [Document::write](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html#method.write) function. Thisfunction takes an arbitrary span of the source code text that you wish to rewrite and the text you want to insert in place of the specified span. It rescans the tokens of the affected source code fragment (localized to the @@ -79,7 +79,7 @@ documents depending on the current mode of the program. When the content of a file is being transferred in parts, for example, through a network or by loading the file from disk in chunks, you can create -a [TokenBuffer](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenBuffer.html) +a [TokenBuffer](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenBuffer.html) and continuously append these chunks into the buffer. Once the file loading is complete, you can use this token buffer as input for @@ -116,7 +116,7 @@ example, a mutable Document can be used as a simple storage of strings with random read/write access. In this case, you can use -the [VoidSyntax](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.VoidSyntax.html) +the [VoidSyntax](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.VoidSyntax.html) helper object to enforce the Document to bypass syntax analysis. ```rust,noplayground @@ -130,9 +130,9 @@ assert_eq!(doc.substring(..), r#"{ "foo": 456 }"#); ``` The above document has full capabilities of -the [SourceCode](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.SourceCode.html) +the [SourceCode](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.SourceCode.html) trait, but -the [SyntaxTree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxTree.html) +the [SyntaxTree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxTree.html) implementation represents a dummy syntax tree with just a single root node that covers empty text. @@ -141,15 +141,15 @@ covers empty text. Each instance of the Document (and similar source code storage objects such as the TokenBuffer) has a globally unique identifier within the current process. -The [Document::id](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html#method.id) +The [Document::id](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html#method.id) function returns an object of -type [Id](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/arena/struct.Id.html). +type [Id](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/arena/struct.Id.html). This object is Copy, Eq, and Hash, ensuring that two distinct instances of documents have distinct identifiers. Related objects of a Document, such -as [NodeRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.NodeRef.html), -[TokenRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenRef.html), +as [NodeRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.NodeRef.html), +[TokenRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenRef.html), and others, store the identifier of the document to which they belong. For example, from a NodeRef referential object, you can determine the identifier @@ -176,8 +176,8 @@ You can assign a possibly non-unique string name to the document to simplify document identification during debugging. For instance, you can use a file name as a document's name. -The [Id::set_name](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/arena/struct.Id.html#method.set_name) -and [Id::name](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/arena/struct.Id.html#method.name) +The [Id::set_name](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/arena/struct.Id.html#method.set_name) +and [Id::name](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/arena/struct.Id.html#method.name) functions set and retrieve the current document name, respectively. Additionally, the crate API uses the document's name in various debugging functions. For example, the Display implementation of the Document object prints diff --git a/work/book/src/lexis/code-inspection.md b/work/book/src/lexis/code-inspection.md index 60092fa..bd6df56 100644 --- a/work/book/src/lexis/code-inspection.md +++ b/work/book/src/lexis/code-inspection.md @@ -39,23 +39,23 @@ In Lady Deirdre, the minimal unit for indexing the source code text is the Unicode character. -A [Site](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/type.Site.html) +A [Site](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/type.Site.html) is a numeric type (an alias of `usize`) representing the absolute Unicode character index in a string. -[SiteSpan](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/type.SiteSpan.html) +[SiteSpan](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/type.SiteSpan.html) is an alias type of `Range` that denotes a fragment (or *span*) of the source code. Most API functions within the crate conveniently -accept [impl ToSite](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.ToSite.html) -or [impl ToSpan](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.ToSpan.html) +accept [impl ToSite](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.ToSite.html) +or [impl ToSpan](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.ToSpan.html) objects when users need to address specific source code characters or spans of characters. These traits facilitate automatic conversion between different representations of source code indices. One example of a source code index type is -the [Position](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.Position.html) +the [Position](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.Position.html) object, which references code in terms of the line and column within the line[^position]. It implements the *ToSite* trait. @@ -69,13 +69,13 @@ However, a particular span instance could be invalid; for instance, `20..10` is invalid because its lower bound is greater than its upper bound. Certain API functions in the crate (e.g., -[Document::write](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html#method.write)) +[Document::write](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html#method.write)) require that the specified span must be valid; otherwise, the function would panic. This behavior aligns with Rust's behavior when indexing arrays with invalid ranges. You can check the validity of a range upfront using -the [ToSpan::is_valid_span](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.ToSpan.html#tymethod.is_valid_span) +the [ToSpan::is_valid_span](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.ToSpan.html#tymethod.is_valid_span) function. The RangeFull `..` object always represents the entire content and is always @@ -94,14 +94,14 @@ assert!((Position::new(1, 2)..Position::new(3, 1)).is_valid_span(&buf)); ``` [^position]: Please note that the line and column numbers in -the [Position](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.Position.html) +the [Position](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.Position.html) object are one-based: 1 denotes the first line, 2 denotes the second line, and so forth. ## Text Inspection The -following [SourceCode](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.SourceCode.html)' +following [SourceCode](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.SourceCode.html)' s functions enable you to query various metadata of the compilation unit's text. ```rust,noplayground @@ -131,16 +131,16 @@ assert_eq!(buf.lines().lines_count(), 1); ``` From `buf.lines()`, you receive -a [LineIndex](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.LineIndex.html) +a [LineIndex](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.LineIndex.html) object that provides additional functions for querying metadata about the source code lines. For example, you can fetch the length of a particular line using this object. ## Tokens Iteration -The [SourceCode::cursor](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.SourceCode.html#tymethod.cursor) +The [SourceCode::cursor](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.SourceCode.html#tymethod.cursor) and its simplified -version [chunks](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.SourceCode.html#method.chunks) +version [chunks](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.SourceCode.html#method.chunks) allow you to iterate through the tokens of the source code. Both functions accept a span of the source code text and yield tokens that @@ -158,7 +158,7 @@ are in any way related to the specified span. The *chunks* function simply returns a standard iterator over the token metadata. Each -[Chunk](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.Chunk.html) +[Chunk](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.Chunk.html) object contains the token instance, a reference to its string, the absolute Site of the beginning of the token, and the substring length in Unicode characters[^chunk]. @@ -184,7 +184,7 @@ for Chunk { ``` The *cursor* function returns a more -complex [TokenCursor](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.TokenCursor.html) +complex [TokenCursor](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.TokenCursor.html) object that implements a cursor-like API with built-in lookahead capabilities and manual control over the iteration process. This object is particularly useful for syntax parsing and will be discussed in more detail in the subsequent diff --git a/work/book/src/lexis/lexical-grammar.md b/work/book/src/lexis/lexical-grammar.md index d4d70ca..e757ac5 100644 --- a/work/book/src/lexis/lexical-grammar.md +++ b/work/book/src/lexis/lexical-grammar.md @@ -35,7 +35,7 @@ # Lexical Grammar The lexical grammar is defined using -the [Token derive macro](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/derive.Token.html) +the [Token derive macro](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/derive.Token.html) on an arbitrary enum type, which represents the type of the token. Each enum variant represents a token variant. To specify the scanning rule for @@ -90,7 +90,7 @@ The type must be Copy, Eq, and `#[repr(u8)]` enum type with variants without a body. The macro will implement -the [Token](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.Token.html) +the [Token](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.Token.html) trait on the applicable object, providing not only the scan function itself but also additional metadata about the lexical grammar. diff --git a/work/book/src/lexis/site-references.md b/work/book/src/lexis/site-references.md index e90cb02..dc31f3f 100644 --- a/work/book/src/lexis/site-references.md +++ b/work/book/src/lexis/site-references.md @@ -34,14 +34,14 @@ # Site References -The [Site](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/type.Site.html) +The [Site](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/type.Site.html) index, which represents the absolute offset of a Unicode character in the source code text, cannot reliably address a token's absolute offset after source code edits. This is because the token could be shifted left or right, or it could disappear during incremental rescanning, depending on the bounds of the edit. In contrast, -[TokenRef::site](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenRef.html#method.site) +[TokenRef::site](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenRef.html#method.site) returns the absolute offset of the beginning of the token's string fragment at the time of the call. In other words, this function returns an updated absolute offset of the token after an edit operation, provided the incremental rescanner @@ -50,12 +50,12 @@ did not remove the token during rescanning. This allows for addressing a token's character bounds relative to changes in the source code. -The [SiteRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.SiteRef.html) +The [SiteRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.SiteRef.html) helper object (backed by the TokenRef under the hood) addresses token bounds. Specifically, this object addresses either the beginning of the token or the end of the source code. -[ToSite](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.ToSite.html) +[ToSite](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.ToSite.html) implements the ToSite trait, so it can be used as a valid bound of a range span. ```rust,noplayground @@ -79,7 +79,7 @@ assert_eq!(doc.substring(brackets_start..brackets_end), "[12345]"); ``` Similar to TokenRef, the SiteRef interface has a -special [nil](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.SiteRef.html#method.nil) +special [nil](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.SiteRef.html#method.nil) value and -the [is_nil](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.SiteRef.html#method.is_nil) +the [is_nil](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.SiteRef.html#method.is_nil) test function. diff --git a/work/book/src/lexis/source-code.md b/work/book/src/lexis/source-code.md index c873402..2044c43 100644 --- a/work/book/src/lexis/source-code.md +++ b/work/book/src/lexis/source-code.md @@ -35,18 +35,18 @@ # Source Code Lady Deirdre distinguishes between the scanner's implementation, carried out by -the [Token](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.Token.html) +the [Token](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.Token.html) type, and the source code manager, responsible for actual code storage and lexical scanning through interaction with the scanner's implementation. Each source code manager implements -a [SourceCode](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.SourceCode.html) +a [SourceCode](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.SourceCode.html) trait, providing a minimal set of features enabling inspection of its content, including the source code text and its lexical structure. The crate offers specialized source code managers with distinct API options and performance characteristics. For instance, while -the [TokenBuffer](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenBuffer.html) +the [TokenBuffer](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenBuffer.html) lacks general incremental rescanning capabilities, it offers slightly better performance than the -mutable [Document](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html). +mutable [Document](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html). diff --git a/work/book/src/lexis/token-buffer.md b/work/book/src/lexis/token-buffer.md index c033ac6..f214ca2 100644 --- a/work/book/src/lexis/token-buffer.md +++ b/work/book/src/lexis/token-buffer.md @@ -35,7 +35,7 @@ # Token Buffer The simplest data structure for storing the token stream is -the [TokenBuffer](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenBuffer.html). +the [TokenBuffer](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenBuffer.html). It holds both the source code text and the token stream but has limited incremental rescanning capabilities, only allowing appending to the end of the @@ -46,7 +46,7 @@ You are encouraged to use token buffer if you don't need general incremental rescanning capabilities and if you want to store only the source code with tokens, or if you plan to initially load the source code and later reupload it to a general-purpose compilation unit storage -like [Document](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html). +like [Document](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html). Token buffer offers the fastest scanning implementation among other Lady Deirdre compilation unit storages, providing high performance when iterating through diff --git a/work/book/src/lexis/token-references.md b/work/book/src/lexis/token-references.md index 685cf4d..7070a64 100644 --- a/work/book/src/lexis/token-references.md +++ b/work/book/src/lexis/token-references.md @@ -38,7 +38,7 @@ Lexical structures (tokens) are owned by the source code managers, such as TokenBuffers and Documents, which implement the SourceCode trait through which you can access the tokens. -The [TokenRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenRef.html) +The [TokenRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenRef.html) is a convenient interface containing a composite numeric index that uniquely addresses a token in the source code. As a numeric index, it is a Copy and lifetime-independent object that you can freely use throughout your program. @@ -48,7 +48,7 @@ code manager and may return None if the corresponding token does not exist in the manager. For example, -the [TokenRef::deref](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenRef.html#method.deref) +the [TokenRef::deref](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenRef.html#method.deref) function "dereferences" the token and returns Some if the token exists in the specified compilation unit, or None otherwise. @@ -91,12 +91,12 @@ The TokenRef reference is unique in the following ways: 2. It uniquely addresses a particular token within this unit. If the incremental source code manager (such -as [Document](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html)) +as [Document](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html)) rescans the source code fragment to which the token belongs, its TokenRef reference would effectively become obsolete. Every new token in the Document would receive a new unique instance of the TokenRef object. -The [TokenRef::is_valid_ref](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenRef.html#method.is_valid_ref) +The [TokenRef::is_valid_ref](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenRef.html#method.is_valid_ref) function tests the validity of the reference for a specified compilation unit. ## Nil TokenRef @@ -106,9 +106,9 @@ references that intentionally do not address any tokens within any compilation unit. These TokenRefs are created with -the [TokenRef::nil](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenRef.html#method.nil) +the [TokenRef::nil](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenRef.html#method.nil) function and can be tested using -the [is_nil](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.PolyRef.html#tymethod.is_nil) +the [is_nil](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.PolyRef.html#tymethod.is_nil) function. The *is_nil* function returns true only for token references created this way; otherwise, it returns false, even if the TokenRef is obsolete. diff --git a/work/book/src/overview.md b/work/book/src/overview.md index 9947668..2bc5b9a 100644 --- a/work/book/src/overview.md +++ b/work/book/src/overview.md @@ -98,7 +98,7 @@ compilation units. ### Compilation Units -The [Document](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html) +The [Document](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html) object represents the source code text, token stream, and syntax tree of an individual compilation unit. @@ -147,7 +147,7 @@ syntax tree's node type. First, you need to specify the type of the lexis. Typically, you can do this using -the [derive macro](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/derive.Token.html) +the [derive macro](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/derive.Token.html) on your enum type, where the enum variants denote individual token types. The token's lexical scanning rules are described in terms of regular expressions. @@ -180,7 +180,7 @@ during the syntax parsing stage. ### Syntax The syntax grammar is described similarly using enum types and -the [derive macro](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/derive.Node.html). +the [derive macro](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/derive.Node.html). The node's parsing rules are described in terms of LL(1) grammars, but you can also implement your own custom parsers for individual node types, allowing for @@ -221,7 +221,7 @@ hand-written recursive-descent parsers. The syntax trees created by Lady Deirdre are, informally speaking, abstract syntax trees where all trivial elements such as whitespaces and comments are intentionally omitted. However, it is worth noting that you can also build a -full [ParseTree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.ParseTree.html) +full [ParseTree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.ParseTree.html) based on the same grammar, which has a different structure useful for implementing code formatters. @@ -235,10 +235,10 @@ rules for fine-tuning. ### Ownership In Lady Deirdre, the source code tokens and syntax tree nodes are owned by the -[Document](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html). +[Document](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html). -The [NodeRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.NodeRef.html) -and [TokenRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenRef.html) +The [NodeRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.NodeRef.html) +and [TokenRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenRef.html) objects are globally unique (composite) numerical indices that point to a specific node or token inside the Document. They are unique in the sense that whenever the incremental reparser removes a node or token, the corresponding @@ -307,7 +307,7 @@ impl Visitor for MyVisitor { ### Semantics The semantic graph of the compilation project consists -of [attributes](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html). +of [attributes](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html). An attribute represents a value of arbitrary user-defined type, along with the function that computes this value based on the values of other attributes read @@ -380,7 +380,7 @@ project in a multi-threaded environment, handling concurrent requests to the semantic attributes. Specifically, the language server can manage parallel requests from the language client (code editor) in dedicated worker threads. -The [Analyzer](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Analyzer.html) +The [Analyzer](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Analyzer.html) object manages a collection of documents of the compilation project and the semantic graph of the project. diff --git a/work/book/src/semantics/code-diagnostics.md b/work/book/src/semantics/code-diagnostics.md index 9b3c21c..2f02cb2 100644 --- a/work/book/src/semantics/code-diagnostics.md +++ b/work/book/src/semantics/code-diagnostics.md @@ -47,7 +47,7 @@ attribute. Subsequently, in the root node's global diagnostics attribute, you can iterate through all local diagnostic attributes of scopes and aggregate their values into a single set, wrapping it into -a [Shared](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/sync/struct.Shared.html) +a [Shared](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/sync/struct.Shared.html) structure for efficient cloning. Furthermore, you can enhance the final diagnostics set with syntax errors from the normal compilation unit by directly reading them from the document[^syntaxerror]. @@ -59,11 +59,11 @@ intensive in edge cases. To mitigate this, the language server could periodically examine this attribute with a low-priority analysis task. Moreover, when utilizing -the [Attr::snapshot](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html#method.snapshot) +the [Attr::snapshot](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html#method.snapshot) function to retrieve a copy of the current diagnostics sets, you can leverage the version number of the attribute value to determine whether this set needs to be republished to the client. -[^syntaxerror]: The [Document::errors](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxTree.html#method.errors) +[^syntaxerror]: The [Document::errors](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxTree.html#method.errors) function would provide you with an iterator over all syntax errors within the compilation unit. diff --git a/work/book/src/semantics/configuration-issues.md b/work/book/src/semantics/configuration-issues.md index d70785d..c4e8b13 100644 --- a/work/book/src/semantics/configuration-issues.md +++ b/work/book/src/semantics/configuration-issues.md @@ -35,16 +35,16 @@ # Configuration Issues Many functions in the semantic analysis framework API can return -an [AnalysisError](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/enum.AnalysisError.html), +an [AnalysisError](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/enum.AnalysisError.html), representing either a normal result (e.g., -an [Interrupted](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/enum.AnalysisError.html#variant.Interrupted) +an [Interrupted](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/enum.AnalysisError.html#variant.Interrupted) error) or an abnormal error indicating a configuration or usage issue with the framework. For example, -the [write_to_doc](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.MutationAccess.html#method.write_to_doc) +the [write_to_doc](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.MutationAccess.html#method.write_to_doc) function of the mutation task can return -a [MissingDocument](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/enum.AnalysisError.html#variant.MissingDocument) +a [MissingDocument](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/enum.AnalysisError.html#variant.MissingDocument) error if you specify a document ID that does not exist in the Analyzer (e.g., if the document was previously removed from the Analyzer). @@ -52,7 +52,7 @@ The API documentation for framework functions typically describes the types of errors that a function can return. Depending on the situation, you may handle certain errors manually. However, as a fallback, it is recommended to return normal errors from functions that -return [AnalysisResult](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/type.AnalysisResult.html) +return [AnalysisResult](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/type.AnalysisResult.html) and to panic immediately if an abnormal error occurs. This convention helps identify configuration or usage issues more quickly. @@ -63,7 +63,7 @@ likely indicates a bug in your program's code that needs to be fixed. In particular, the computable functions of the [Chain Analysis](https://github.com/Eliah-Lakhin/lady-deirdre/blob/f350aaed30373a67694c3aba4d2cfd9874c2a656/work/crates/examples/src/chain_analysis/semantics.rs#L337) example use -the [unwrap_abnormal](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/type.AnalysisResult.html#method.unwrap_abnormal) +the [unwrap_abnormal](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/type.AnalysisResult.html#method.unwrap_abnormal) helper function to filter out normal errors from abnormal ones, panicking if an abnormal error is encountered. @@ -140,9 +140,9 @@ execution within a few milliseconds, even on low-end CPUs. By default, the Analyzer sets the timeout limit to a few seconds[^timeoutlimit]. If a computable function exceeds this limit, it indicates a potential issue in the semantics design, and the corresponding analysis function ( -e.g., [Attr::snapshot](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html#method.snapshot)) +e.g., [Attr::snapshot](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html#method.snapshot)) yields -a [Timeout](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/enum.AnalysisError.html#variant.Timeout) +a [Timeout](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/enum.AnalysisError.html#variant.Timeout) error. This mechanism is also useful for detecting cycles. When the semantic graph @@ -158,7 +158,7 @@ treated as normal errors, assumed to be caused by edge cases in the project's source code compilation, and thus handled without panic[^timoutpanic]. [^timeoutlimit]: You can configure this limit via -the [AnalyzerConfig](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.AnalyzerConfig.html) +the [AnalyzerConfig](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.AnalyzerConfig.html) object, which you pass to the Analyzer's constructor. [^timoutpanic]: The user of the code editor's extension would prefer the diff --git a/work/book/src/semantics/grammar-setup.md b/work/book/src/semantics/grammar-setup.md index 9417aaf..d076cea 100644 --- a/work/book/src/semantics/grammar-setup.md +++ b/work/book/src/semantics/grammar-setup.md @@ -35,7 +35,7 @@ # Grammar Setup The central component of your compiler is -the [Analyzer](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Analyzer.html) +the [Analyzer](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Analyzer.html) object. This object is responsible to manage the set of documents within the compilation project and their semantic graph. Further details regarding the Analyzer's API will be discussed in subsequent chapters. For now, our focus in @@ -114,7 +114,7 @@ pub enum ChainNode { Each variant in the Node enum must contain a semantics field annotated with the `#[semantics]` attribute and of -type [Semantics](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Semantics.html). +type [Semantics](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Semantics.html). This field will be automatically initialized[^handwritten] and managed by the macro-generated code. @@ -129,14 +129,14 @@ parameterized by the `BlockSemantics` type. If a node variant doesn't have any attributes, you can parameterize its Semantics object with -the [VoidFeature](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.VoidFeature.html) +the [VoidFeature](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.VoidFeature.html) type, as seen in the `Root` and `Assignment` node variants. [^handwritten]: To initialize this field manually in the hand-written parser, use -the [Semantics::new](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Semantics.html#method.new) +the [Semantics::new](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Semantics.html#method.new) function, passing the current NodeRef obtained from -the [SyntaxSession::node_ref](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.node_ref) +the [SyntaxSession::node_ref](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.node_ref) function. ## Feature Objects @@ -145,7 +145,7 @@ The type you use as a parameter of the Semantics object is called a *feature*. Typically, the semantic feature is a user-defined struct type derived from the Feature trait using -the [Feature derive macro](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/derive.Feature.html). +the [Feature derive macro](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/derive.Feature.html). This structure consists of fields that are either attributes or other feature objects. @@ -162,7 +162,7 @@ pub struct BlockSemantics { ``` In the above code, all fields are semantic -attributes ([Attr](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html) +attributes ([Attr](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html) types), but you are free to use other features as field types whenever you want to create more complex nested structures. You can also reuse the same feature type and attribute types in multiple places, as long as the feature or attribute @@ -183,7 +183,7 @@ a `#[scope]`). We will discuss attributes in more detail in the next chapters, but to give you a brief overview, the generic parameter -of [Attr](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html) +of [Attr](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html) specifies the type of the attribute value. This value is part of the semantic model and can be any user-defined type (e.g., a struct or an enum) equipped with a function that computes this value based on the syntax tree values and other @@ -210,5 +210,5 @@ impl Computable for BlockAnalysis { The general requirements imposed on this type are that it should implement the Clone, Eq, -and [Computable](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.Computable.html) +and [Computable](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.Computable.html) traits. diff --git a/work/book/src/semantics/granularity.md b/work/book/src/semantics/granularity.md index b091358..e0e3da4 100644 --- a/work/book/src/semantics/granularity.md +++ b/work/book/src/semantics/granularity.md @@ -88,7 +88,7 @@ comprise many more potentially independent fields. ## Shared Object -The [Shared](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/sync/struct.Shared.html) +The [Shared](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/sync/struct.Shared.html) helper object is Lady Deirdre's reference-counting thread-safe container, akin to Rust's standard Arc, with two notable distinctions: @@ -96,7 +96,7 @@ to Rust's standard Arc, with two notable distinctions: required, Shared's computation and memory performance are slightly better than Arc's. 2. The - [Shared::get_mut](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/sync/struct.Shared.html#method.get_mut) + [Shared::get_mut](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/sync/struct.Shared.html#method.get_mut) function accepts `&mut self`. This makes it more convenient to use when constructing Shared in place. @@ -124,7 +124,7 @@ assert_eq!(*shared_b.as_ref(), 120); ## Shared Computable -The [SharedComputable](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.SharedComputable.html) +The [SharedComputable](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.SharedComputable.html) is a specialized helper trait that automatically implements the Computable trait on the type `Shared` if *SharedComputable* is implemented on `T`. diff --git a/work/book/src/semantics/multi-file-analysis.md b/work/book/src/semantics/multi-file-analysis.md index 1224d16..4e86f6b 100644 --- a/work/book/src/semantics/multi-file-analysis.md +++ b/work/book/src/semantics/multi-file-analysis.md @@ -80,15 +80,15 @@ Common semantic features typically include: - Analyzer-wide reducing attributes, such as an attribute that collects all syntax and semantic issues detected across all managed documents. - External configuration metadata specified via the system of - [Slots](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Slot.html). + [Slots](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Slot.html). For instance, a map between file names and their document IDs within the Analyzer (as in the example above). You can access common semantics both inside and outside of computable functions. Inside a computable function, you can access common semantics -using the [AttrContext::common](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.AttrContext.html#method.common) +using the [AttrContext::common](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.AttrContext.html#method.common) method. To access the semantics outside, you would use the -[AbstractTask::common](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.AbstractTask.html#method.common) +[AbstractTask::common](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.AbstractTask.html#method.common) method. ```rust,noplayground @@ -133,7 +133,7 @@ task.common() ## Slots -The primary purpose of a [Slot](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Slot.html) +The primary purpose of a [Slot](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Slot.html) is to provide a convenient mechanism for injecting configuration metadata external to the Analyzer into the semantic graph. For instance, mapping between file system names and the Analyzer's document IDs can be injected through a @@ -144,15 +144,15 @@ attributes, except that a Slot does not have an associated computable function. Instead, Slots have associated values of a specified type (the second generic argument of the `Slot` signature). -You can [snapshot](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Slot.html#method.snapshot) +You can [snapshot](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Slot.html#method.snapshot) the current Slot value outside of computable functions, and you can -[read](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Slot.html#method.read) +[read](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Slot.html#method.read) Slot values within the computable functions of attributes, thereby subscribing those attributes to changes in the Slot, much like with normal attributes. By default, Slot values are set to the `Default` of the value type. You can modify the content of the Slot value using the -[Slot::mutate](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Slot.html#method.mutate) +[Slot::mutate](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Slot.html#method.mutate) method with a mutable (or exclusive) task. ```rust,noplayground diff --git a/work/book/src/semantics/scope-access.md b/work/book/src/semantics/scope-access.md index 9e93a4a..4707873 100644 --- a/work/book/src/semantics/scope-access.md +++ b/work/book/src/semantics/scope-access.md @@ -37,7 +37,7 @@ For any syntax tree node with semantics, you can obtain a NodeRef reference to the top node of the scope in which this node is nested. -The [Semantics::scope_attr](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Semantics.html#method.scope_attr) +The [Semantics::scope_attr](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Semantics.html#method.scope_attr) function returns a special built-in attribute that contains a NodeRef of the top node within the node's scope. The Analyzer is responsible for maintaining the accuracy of this attribute's value, and you can utilize it within any computable diff --git a/work/book/src/semantics/semantic-graph.md b/work/book/src/semantics/semantic-graph.md index 8cdaab7..342a218 100644 --- a/work/book/src/semantics/semantic-graph.md +++ b/work/book/src/semantics/semantic-graph.md @@ -35,17 +35,17 @@ # Semantic Graph A semantic -attribute ([Attr](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html) +attribute ([Attr](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html) object) consists of a cache for a value of an arbitrary user-defined type and a function that computes this value when invoked by the Analyzer's inner algorithm. Inside -the [Computable](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.Computable.html) +the [Computable](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.Computable.html) function that computes the value, you can access other attribute values, the syntax and lexical content of the compilation units, and other Analyzer-related elements from the `context` argument of -the [AttrContext](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.AttrContext.html) +the [AttrContext](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.AttrContext.html) type. This argument is the source of the inputs to the function, allowing you to infer and return the resulting attribute value. @@ -212,7 +212,7 @@ impl SharedComputable for LocalResolution { In this snippet, particularly on the line `block_semantics.assignments.read(context)`, we are reading the value of another attribute. -The [Attr::read](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html#method.read) +The [Attr::read](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html#method.read) function takes the current `context` reference and returns a RAII read-guard of the attribute's value. diff --git a/work/book/src/semantics/side-effects.md b/work/book/src/semantics/side-effects.md index c56fa2e..d6ac27d 100644 --- a/work/book/src/semantics/side-effects.md +++ b/work/book/src/semantics/side-effects.md @@ -35,7 +35,7 @@ # Side Effects Typically, implementations of -attribute's [Computable](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.Computable.html) +attribute's [Computable](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.Computable.html) functions should be free of side effects: their results should not rely on the external environment state, and non-input attributes should be independent from changes in the syntax and lexical structure of the compilation units. @@ -44,11 +44,11 @@ If the implementation has side effects that cannot be avoided, you have two ways to overcome the limitations of the validation procedure: 1. You can invalidate any attribute manually using - the [Attr::invalidate](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html#method.invalidate) + the [Attr::invalidate](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html#method.invalidate) function if you are aware that the external environment state has changed. 2. Inside the computable function implementation, you can use - the [Context::subscribe](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.AttrContext.html#method.subscribe) + the [Context::subscribe](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.AttrContext.html#method.subscribe) function to subscribe this attribute to the Analyzer-wide event that could be triggered independently for bulk invalidation of the semantic graph attributes subscribed to a specific event. The event object that you would @@ -65,7 +65,7 @@ the state of one Analyzer could be propagated to some attributes of another Analyzer's setup. [^builtinevenets]: There are a couple of built-in events as well, such as -the [DOC_UPDATED_EVENT](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/constant.DOC_UPDATED_EVENT.html), +the [DOC_UPDATED_EVENT](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/constant.DOC_UPDATED_EVENT.html), which denotes document-wide edits within the specified document regardless of the scopes. However, the majority of the value range is available for user-defined events. diff --git a/work/book/src/semantics/tasks-management.md b/work/book/src/semantics/tasks-management.md index 2a357c7..b826da3 100644 --- a/work/book/src/semantics/tasks-management.md +++ b/work/book/src/semantics/tasks-management.md @@ -69,10 +69,10 @@ assert!(handle.is_triggered()); assert!(task.handle().is_triggered()); ``` -The [TriggerHandle](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.TriggerHandle.html) +The [TriggerHandle](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.TriggerHandle.html) is the default implementation of the handle[^customhandle]. This object is thread-safe and cheap to clone. Once the handle is triggered (via -the [trigger](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.TaskHandle.html#tymethod.trigger) +the [trigger](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.TaskHandle.html#tymethod.trigger) function), all copies of the instance become triggered, which serves as a marker for the job thread to gracefully finish its job. @@ -94,10 +94,10 @@ handles of these active tasks. [^customhandle]: Note that Lady Deirdre allows you to create your own task handle types with more complex triggering logic by implementing -the [TaskHandle](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.TaskHandle.html) +the [TaskHandle](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.TaskHandle.html) trait on the user-defined type. In this case, you would use this type as the second generic parameter of -the [Analyzer](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Analyzer.html) +the [Analyzer](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Analyzer.html) object. ## Tasks Interruption @@ -107,13 +107,13 @@ between the attribute validation bounds. If the validation procedure determines that the handle was triggered in the middle of the analysis, the validator will leave the semantic graph in a not-yet-completed state (without breaking its integrity), and it will start returning -the [Interrupted](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/enum.AnalysisError.html#variant.Interrupted) +the [Interrupted](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/enum.AnalysisError.html#variant.Interrupted) error from all corresponding functions. For example, -the [Attr::read](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html#method.read) +the [Attr::read](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html#method.read) function used inside the computable functions and -the [Attr::snapshot](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html#method.snapshot) +the [Attr::snapshot](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html#method.snapshot) function used to get a copy of the attribute value from outside both would start returning the Interrupted error. @@ -210,7 +210,7 @@ queue. You can specify the minimum tasks priority level allowed in the Analyzer by calling -the [Analyzer::set_access_level](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Analyzer.html#method.set_access_level) +the [Analyzer::set_access_level](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Analyzer.html#method.set_access_level) function and specifying the priority threshold. Calling this function will interrupt all currently active tasks with a priority @@ -219,7 +219,7 @@ lower than the threshold. Non-active pending tasks with a priority lower than the threshold will be removed from the task queue, and the corresponding requester threads will be unblocked, immediately -receiving [Interrupted](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/enum.AnalysisError.html#variant.Interrupted) +receiving [Interrupted](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/enum.AnalysisError.html#variant.Interrupted) errors. All future task requests with a lower priority than the current threshold will diff --git a/work/book/src/semantics/the-analyzer.md b/work/book/src/semantics/the-analyzer.md index 8531779..22abc36 100644 --- a/work/book/src/semantics/the-analyzer.md +++ b/work/book/src/semantics/the-analyzer.md @@ -35,7 +35,7 @@ # The Analyzer To recap, -the [Analyzer](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Analyzer.html) +the [Analyzer](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Analyzer.html) serves as the central object of the compiler, managing the compilation project's set of documents and the semantic graph. @@ -61,22 +61,22 @@ gain access to specific operations on the Analyzer's data[^tasks]. The Analyzer offers three types of task objects: - The - [AnalysisTask](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.AnalysisTask.html): + [AnalysisTask](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.AnalysisTask.html): This task allows you to query semantic graph attributes. You can have as many simultaneous task objects of this type as you need. - The - [MutationTask](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.MutationTask.html): + [MutationTask](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.MutationTask.html): With this task, you can create, edit, or remove documents, and you can trigger analyzer-wide events. Similar to AnalysisTask, you can have multiple simultaneous task objects of this type. - The - [ExclusiveTask](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.ExclusiveTask.html): + [ExclusiveTask](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.ExclusiveTask.html): This task enables you to sequentially perform analysis and mutation operations within a single thread. However, you cannot have more than one task of this type simultaneously. You obtain the task objects by requesting them from the Analyzer. For instance, -the [Analyzer::analyze](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Analyzer.html#method.analyze) +the [Analyzer::analyze](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Analyzer.html#method.analyze) function returns an *AnalysisTask* instance. Each of these request functions could block the current thread if the Analyzer @@ -136,9 +136,9 @@ assert!(!task.contains_doc(doc_id)); ``` In the above code, the `add_mutable_doc` function -resembles [Document::new_mutable](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html#method.new_mutable), +resembles [Document::new_mutable](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html#method.new_mutable), and the `write_to_doc` function -resembles [Document::write](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html#method.write), +resembles [Document::write](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html#method.write), except that the Document instance is managed by the Analyzer. ## Analysis Task @@ -185,7 +185,7 @@ assert_eq!(resolution, GlobalResolution::Resolved(100)); ``` Note -the [snapshot](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html#method.snapshot) +the [snapshot](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html#method.snapshot) function in the above code that we're calling on the `global_resolution` attribute of the node's semantics. @@ -202,19 +202,19 @@ number is useful for quickly checking if the attribute has a new value by comparing it with the version number received from this function previously. The second object of the pair is a copy of the attribute's value. Unlike -the [Attr::read](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Attr.html#method.read) +the [Attr::read](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Attr.html#method.read) function used within computable functions, which returns a reference to the value, the *snapshot* function used externally copies the value (by cloning it). For this reason, it's recommended to make the attribute's value type cheap to copy if the attribute is intended to be observed from outside of computable functions. Otherwise, you can wrap the value type -into [Shared](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/sync/struct.Shared.html). +into [Shared](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/sync/struct.Shared.html). ## Exclusive Task You obtain the exclusive task using -the [Analyzer::exclusive](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.Analyzer.html#method.exclusive) +the [Analyzer::exclusive](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.Analyzer.html#method.exclusive) function. The Analyzer grants only one instance of this type of task at a time, but this @@ -239,7 +239,7 @@ from reading or changing the probed text in between. From any kind of task, you can read the content of the document (both lexical and syntactical). -The [read_doc](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.AbstractTask.html#method.read_doc) +The [read_doc](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.AbstractTask.html#method.read_doc) function returns a *DocumentReadGuard* RAII guard, through which you access the Document object immutably. While this guard is held, attempts to mutate this specific document (edit or remove) will be blocked. However, semantic analysis @@ -250,9 +250,9 @@ mutation of compilation units. As the Analyzer is going to be a central object of the compiler, it's recommended to either place it in a -[Shared](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/sync/struct.Shared.html) +[Shared](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/sync/struct.Shared.html) or a -[Lazy](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/sync/struct.Lazy.html) +[Lazy](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/sync/struct.Lazy.html) static for easy access from multiple threads. This is somewhat analogous to placing a Mutex or RwLock with the program-wide state into an Arc to share it across threads. diff --git a/work/book/src/semantics/tree-index.md b/work/book/src/semantics/tree-index.md index e8fa3d0..e5dce18 100644 --- a/work/book/src/semantics/tree-index.md +++ b/work/book/src/semantics/tree-index.md @@ -74,7 +74,7 @@ code that relate to a single variable: one discovered in step 2. [^traverse]: You can utilize depth-first traversal using -the [Document::traverse_tree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxTree.html#method.traverse_tree) +the [Document::traverse_tree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxTree.html#method.traverse_tree) function. By skipping the descent into child nodes with spans that don't cover the targeted site, the traversal complexity averages to `O(ln(N))`, where N is the number of nodes in the tree. In other words, traversing will typically be @@ -94,7 +94,7 @@ pub enum ChainNode { ``` The parameter of this macro attribute is an arbitrary type that implements -the [Classifier](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.Classifier.html) +the [Classifier](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.Classifier.html) trait. It denotes classes of nodes, essentially serving as indices, and the function that partitions requested nodes between these classes. @@ -164,7 +164,7 @@ above function on each syntax tree node, associating each class with the set of nodes of this class. When you edit the document (using -the [write_to_doc](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.MutationAccess.html#method.write_to_doc) +the [write_to_doc](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.MutationAccess.html#method.write_to_doc) function), the Analyzer incrementally updates this partition based on the changes in the structure of the syntax tree. @@ -172,13 +172,13 @@ changes in the structure of the syntax tree. You can query a set of nodes of the document that belong to a specified class both inside the computable functions of the attributes using -the [read_class](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/struct.AttrContext.html#method.read_class) +the [read_class](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/struct.AttrContext.html#method.read_class) function of the `context` variable, and outside using the -[snapshot_class](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/analysis/trait.AbstractTask.html#method.snapshot_class) +[snapshot_class](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/analysis/trait.AbstractTask.html#method.snapshot_class) function of the task object. Both functions return -a [Shared](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/sync/struct.Shared.html) +a [Shared](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/sync/struct.Shared.html) set of the NodeRefs that point to the nodes in the document's syntax tree belonging to the class. diff --git a/work/book/src/snippets.md b/work/book/src/snippets.md index 2d47be1..132b99c 100644 --- a/work/book/src/snippets.md +++ b/work/book/src/snippets.md @@ -41,7 +41,7 @@ fragments where the issues occur. While there are several similar tools in the Rust ecosystem that you can use with this crate, Lady Deirdre provides its own solution as well. -The [Snippet](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.Snippet.html) +The [Snippet](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.Snippet.html) is a configurable builder object that prints the source code text of a compilation unit, or a part of it, with emphasized fragments annotated with custom messages. @@ -122,7 +122,7 @@ impl<'a> Display for JsonSnippet<'a> { ``` The Snippet has several drawing configuration options that you can specify using -the [Snippet::set_config](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.Snippet.html#method.set_config) +the [Snippet::set_config](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.Snippet.html#method.set_config) function. Here are a few: - You can show or hide line numbers, header and footer, and the outer frame. @@ -135,16 +135,16 @@ alternated (`format!("{}")`). Otherwise, all drawing options are enabled (`format!("{:#}")`). In the example above, we specify the JSON syntax highlighter using -the [Snippet::set_highlighter](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.Snippet.html#method.set_highlighter) +the [Snippet::set_highlighter](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.Snippet.html#method.set_highlighter) function. The highlighter is a stateful object that implements -the [Highlighter](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/trait.Highlighter.html) +the [Highlighter](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/trait.Highlighter.html) trait and instructs the Snippet on how to stylize the source code tokens. The Snippet builder -calls [Highlighter::token_style](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/trait.Highlighter.html#tymethod.token_style) +calls [Highlighter::token_style](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/trait.Highlighter.html#tymethod.token_style) for each token in the source code sequentially, and the function returns -the [Style](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/format/struct.Style.html) +the [Style](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/format/struct.Style.html) of the token. ```rust,noplayground diff --git a/work/book/src/syntax/debugging.md b/work/book/src/syntax/debugging.md index f51a48d..c77f84b 100644 --- a/work/book/src/syntax/debugging.md +++ b/work/book/src/syntax/debugging.md @@ -38,7 +38,7 @@ When designing a syntax parser, it can be useful to perform quick and straightforward observations of the parser's step-by-step actions. The built-in -[Node::debug](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.Node.html#method.debug) +[Node::debug](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.Node.html#method.debug) function accepts a string of the source code text and prints to the terminal the hierarchical structure that shows how the parser descends into the node variant parsing procedures and what tokens these procedures consumed. Additionally, it @@ -105,7 +105,7 @@ Note that in the above example, the parser encountered a syntax error when parsing the JSON array (missing a comma between `123` and `"baz"`). You can generically iterate and print syntax errors using -the [SyntaxError::display](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.SyntaxError.html#method.display) +the [SyntaxError::display](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.SyntaxError.html#method.display) function. ```rust,noplayground @@ -141,7 +141,7 @@ messages. ## Syntax Tree Printing Finally, using -the [CompilationUnit::display](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/trait.CompilationUnit.html#method.display)[^treedisplay] +the [CompilationUnit::display](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/trait.CompilationUnit.html#method.display)[^treedisplay] method, you can print the output syntax tree to the terminal. ```rust,noplayground diff --git a/work/book/src/syntax/node-references.md b/work/book/src/syntax/node-references.md index 4540dda..b4ccf0b 100644 --- a/work/book/src/syntax/node-references.md +++ b/work/book/src/syntax/node-references.md @@ -39,7 +39,7 @@ Instances of nodes in the syntax tree are owned by the syntax tree manager Similar to the TokenRef reference used to access individual tokens in the source code, -the [NodeRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.NodeRef.html) +the [NodeRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.NodeRef.html) referential object is used to obtain access to instances of syntax tree nodes. NodeRefs are cheap to copy and are lifetime-independent objects representing @@ -81,17 +81,17 @@ assert!(NodeRef::nil().deref(&doc).is_none()); Since both NodeRef and TokenRef can serve as types for the children of syntax tree nodes, they both implement a generic -trait [PolyRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.PolyRef.html) +trait [PolyRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.PolyRef.html) that provides common functions for both. For example, -[PolyRef::span](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.PolyRef.html#tymethod.span) +[PolyRef::span](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.PolyRef.html#tymethod.span) returns the site span of the referred object's bounds. The PolyRef trait is an object-safe trait, useful for handling tree children without breaking the call chain. For instance, if you are confident that a particular instance of a PolyRef type is a NodeRef, you can use -the [PolyRef::as_node_ref](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.PolyRef.html#tymethod.as_node_ref) +the [PolyRef::as_node_ref](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.PolyRef.html#tymethod.as_node_ref) function to cast the instance to a NodeRef; otherwise, it returns a nil NodeRef without causing a panic if the instance is not a NodeRef. @@ -119,10 +119,10 @@ assert_eq!(root_span, Position::new(1, 1)..Position::new(4, 2)); ``` Finally, Lady Deirdre provides an owned version of the PolyRef trait, known -as [PolyVariant](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/enum.PolyVariant.html). +as [PolyVariant](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/enum.PolyVariant.html). PolyVariant is a simple enum with NodeRef and TokenRef variants. You can convert either of these referential objects into a PolyVariant using -the [PolyRef::as_variant](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.PolyRef.html#tymethod.as_variant) +the [PolyRef::as_variant](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.PolyRef.html#tymethod.as_variant) function whenever you need a generic owned referential object for the compilation unit's content. diff --git a/work/book/src/syntax/overriding-a-parser.md b/work/book/src/syntax/overriding-a-parser.md index 64bef88..4969444 100644 --- a/work/book/src/syntax/overriding-a-parser.md +++ b/work/book/src/syntax/overriding-a-parser.md @@ -35,7 +35,7 @@ # Overriding a Parser To recap, -the [Node derive macro](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/derive.Node.html) +the [Node derive macro](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/derive.Node.html) automatically implements parse procedures for each enum variant annotated with the `#[rule(...)]` macro attribute. Inside the rule, you write a regex-like parse expression in terms of the LL(1) grammars used by the macro to generate @@ -49,7 +49,7 @@ written Rust function using the `#[parser(...)]` macro attribute. This attribute accepts a Rust expression that must return an instance of the enum that represents the parsing result product. As an input, you would use the `session` variable, which is a mutable reference to -the [SyntaxSession](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html) +the [SyntaxSession](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html) that represents the current state of the parsing environment. Usually, inside this expression, you would call your parsing function passing diff --git a/work/book/src/syntax/syntax-grammar.md b/work/book/src/syntax/syntax-grammar.md index d9571b3..e06bdb0 100644 --- a/work/book/src/syntax/syntax-grammar.md +++ b/work/book/src/syntax/syntax-grammar.md @@ -35,7 +35,7 @@ # Syntax Grammar You define the syntax grammar using -the [Node derive macro](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/derive.Node.html) +the [Node derive macro](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/derive.Node.html) on an arbitrary enum type that serves as the type for the syntax tree nodes. Unlike the token enum, the node enum variants are required to have bodies with @@ -139,7 +139,7 @@ this guide. ## Macro API In this chapter, I will intentionally omit some details, referring you to -the [macro documentation](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/derive.Node.html) +the [macro documentation](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/derive.Node.html) for a more verbose description of the available features, and to the [JSON example](https://github.com/Eliah-Lakhin/lady-deirdre/blob/f350aaed30373a67694c3aba4d2cfd9874c2a656/work/crates/examples/src/json_grammar/syntax.rs) as an example of a node implementation that utilizes most of the macro's @@ -237,7 +237,7 @@ Examples: - In `foo: $Bar?`, the "foo" field would have the type TokenRef because "Bar" can be matched no more than one time. If the parser never matches "Bar", the "foo" field receives the - value [TokenRef::nil](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/struct.TokenRef.html#method.nil). + value [TokenRef::nil](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/struct.TokenRef.html#method.nil). ## Guidelines @@ -256,7 +256,7 @@ Examples: indirectly by capturing the starting and ending nodes of this node, these captures would help Lady Deirdre properly understand the starting and ending sites of the node. This is especially important for functions such as - the [NodeRef::span](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.NodeRef.html#method.span) + the [NodeRef::span](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.NodeRef.html#method.span) function. In particular, for this reason, in @@ -271,7 +271,7 @@ Examples: child is a token. For instance, - the [traverse_tree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxTree.html#method.traverse_tree) + the [traverse_tree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxTree.html#method.traverse_tree) function relies on this metadata when performing the syntax tree depth-first traversal. diff --git a/work/book/src/syntax/syntax-session.md b/work/book/src/syntax/syntax-session.md index c8e503a..bbaecc9 100644 --- a/work/book/src/syntax/syntax-session.md +++ b/work/book/src/syntax/syntax-session.md @@ -38,7 +38,7 @@ Inside the hand-written parse function, you will use the `session` variable provided by the macro-generated code when it invokes this function. The variable is of -type [SyntaxSession](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html), +type [SyntaxSession](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html), which provides an interface to read input tokens and manage the output syntax tree. @@ -49,7 +49,7 @@ instance of the syntax tree node as a result of the parsing procedure. ## Input Tokens Stream The SyntaxSession trait is at first place a supertrait -of [TokenCursor](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.TokenCursor.html), +of [TokenCursor](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.TokenCursor.html), representing an input stream for the parser. From this interface, you can read tokens' metadata ahead of the current stream @@ -63,10 +63,10 @@ state[^lookahead]. None of these lookahead functions move the input stream forward. Once your parse algorithm has observed a few tokens ahead, analyzed them, and made a decision to actually "consume" these tokens, the algorithm calls -the [TokenCursor::advance](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.TokenCursor.html#tymethod.advance) +the [TokenCursor::advance](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.TokenCursor.html#tymethod.advance) function, which consumes one token and moves the stream position to the next token, -or [TokenCursor::skip](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/lexis/trait.TokenCursor.html#tymethod.skip), +or [TokenCursor::skip](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/lexis/trait.TokenCursor.html#tymethod.skip), which allows you to consume several tokens. For instance, in @@ -117,15 +117,15 @@ would use the [panic recovery](error-recovering.md#panic-recovery) procedure. To avoid manually reimplementing the panic recovery algorithm and to be consistent with the auto-generated parsers, Lady Deirdre exposes -the [Recovery](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.Recovery.html) +the [Recovery](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.Recovery.html) configurable object that implements this algorithm, which is also used inside the macro-generated code. The Recovery object has the same configuration options that you would use inside the `#[recovery(...)]` macro attribute: -the [Recovery::unexpected](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.Recovery.html#method.unexpected) +the [Recovery::unexpected](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.Recovery.html#method.unexpected) function adds a halting token, and -the [Recovery::group](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.Recovery.html#method.group) +the [Recovery::group](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.Recovery.html#method.group) function adds a group of tokens that should be treated as a whole. It is assumed that this object will be constructed upfront in the const context @@ -154,7 +154,7 @@ static OPERAND_RECOVERY: Recovery = ``` To apply the panic recovery procedure, you call -the [Recovery::recover](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.Recovery.html#method.recover) +the [Recovery::recover](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.Recovery.html#method.recover) function, passing it the `session` variable and the set of tokens the recoverer should look for. The function will consume as many tokens as needed according to the configured rules and will return an object describing whether the procedure @@ -162,7 +162,7 @@ managed to find the required token or failed to do so due to a specific reason (e.g., a halting token has been reached). Regardless of the recovery result, you should report the error using -the [SyntaxSession::failure](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.failure) +the [SyntaxSession::failure](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.failure) function. ```rust,noplayground @@ -228,11 +228,11 @@ Whenever your parser needs to descend into other rules, you basically have two options: 1. Call - the [SyntaxSession::descend](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.descend) + the [SyntaxSession::descend](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.descend) function, which gives control flow back to the parsing environment. 2. Create and parse the node manually using a pair of - functions: [SyntaxSession::enter](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.enter) - and [SyntaxSession::leave](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.leave). + functions: [SyntaxSession::enter](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.enter) + and [SyntaxSession::leave](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.leave). The result of the *descend* function would be similar to if the parsing environment parsed the requested node: it will advance the token cursor of @@ -340,7 +340,7 @@ operand to the current operator's context, then parses the second operand and finishes the operator parser. You can repeat this procedure iteratively to create a left-rotated binary tree. -The [SyntaxSession::lift](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.lift) +The [SyntaxSession::lift](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.lift) function "transplants" the syntax tree branch created just before we enter the new node subparser to the context of this subparser. In particular, this function automatically changes the parent NodeRef of the former sibling to the @@ -398,11 +398,11 @@ you return the final result from the overall parse procedure, and when you finish the inner subparsers via the *leave* function. To set up the node-to-parent relation, you can use -the [SyntaxSession::parent_ref](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.parent_ref) +the [SyntaxSession::parent_ref](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.parent_ref) function that returns a NodeRef reference to the parent node in the syntax tree of the currently parsed node. -The [SyntaxSession::node_ref](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.node_ref) +The [SyntaxSession::node_ref](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxSession.html#tymethod.node_ref) returns a NodeRef reference of the currently parsed node that will be deployed into the syntax tree when the parser finishes parsing (or subparsing) process. diff --git a/work/book/src/syntax/syntax-tree.md b/work/book/src/syntax/syntax-tree.md index c5ea827..6036e24 100644 --- a/work/book/src/syntax/syntax-tree.md +++ b/work/book/src/syntax/syntax-tree.md @@ -37,21 +37,21 @@ The syntax API shares many similarities with the lexis API architecture: 1. The syntax grammar, implemented by - the [Node](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.Node.html) + the [Node](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.Node.html) type, is distinct from the syntax tree manager responsible for actual parsing and storage of the syntax tree. 2. The syntax tree manager implements - the [SyntaxTree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxTree.html) + the [SyntaxTree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxTree.html) trait, providing access to the parsed syntax tree through its functions. 3. There are several syntax manager implementations with distinct sets of features and performance characteristics. 4. Individual nodes within the syntax tree are addressed using - the [NodeRef](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.NodeRef.html) + the [NodeRef](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.NodeRef.html) referential object, which points to concrete node instances owned by the syntax tree manager. The simplest implementation of the syntax tree manager is -the [ImmutableSyntaxTree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.ImmutableSyntaxTree.html), +the [ImmutableSyntaxTree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.ImmutableSyntaxTree.html), which performs one-time parsing without incremental reparsing capabilities but has the fastest computation performance. @@ -81,7 +81,7 @@ The above code is verbose because it requires manual setup of the TokenBuffer and its token cursor. More commonly, we can utilize the -immutable [Document](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/units/enum.Document.html), +immutable [Document](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/units/enum.Document.html), which is backed by the TokenBuffer and ImmutableSyntaxTree under the hood. Through this object, we can directly scan and parse the source code text. This object implements both the SourceCode and SyntaxTree traits, allowing us to diff --git a/work/book/src/syntax/tree-inspection.md b/work/book/src/syntax/tree-inspection.md index 89c999a..0ce31fb 100644 --- a/work/book/src/syntax/tree-inspection.md +++ b/work/book/src/syntax/tree-inspection.md @@ -102,7 +102,7 @@ assert_eq!(string, "123"); ``` Each of these functions is infallible; they will return -a [nil](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/struct.NodeRef.html#method.nil) +a [nil](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/struct.NodeRef.html#method.nil) NodeRef if they cannot fulfill the request. Therefore, we should be confident about the node configuration we are trying to query. @@ -110,13 +110,13 @@ about the node configuration we are trying to query. You can perform a depth-first traversal of the entire syntax tree or a specific branch using -the [SyntaxTree::traverse_tree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxTree.html#method.traverse_tree) -and [SyntaxTree::traverse_subtree](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.SyntaxTree.html#method.traverse_subtree) +the [SyntaxTree::traverse_tree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxTree.html#method.traverse_tree) +and [SyntaxTree::traverse_subtree](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.SyntaxTree.html#method.traverse_subtree) functions, respectively. Both functions require a visitor object to be passed as an argument. This object should implement -a [Visitor](https://docs.rs/lady-deirdre/2.0.1/lady_deirdre/syntax/trait.Visitor.html) +a [Visitor](https://docs.rs/lady-deirdre/2.1.0/lady_deirdre/syntax/trait.Visitor.html) trait, which includes functions that will be triggered when the traversal procedure visits a node or token in the tree, according to the node-child relationships between the nodes. diff --git a/work/crates/derive/Cargo.toml b/work/crates/derive/Cargo.toml index a9958d9..0274efc 100644 --- a/work/crates/derive/Cargo.toml +++ b/work/crates/derive/Cargo.toml @@ -34,7 +34,7 @@ [package] name = "lady-deirdre-derive" -version = "2.0.1" +version = "2.1.0" authors = ["Ilya Lakhin (Илья Александрович Лахин) "] edition = "2021" description = "Compiler front-end foundation technology. Macro crate." diff --git a/work/crates/derive/src/token/mod.rs b/work/crates/derive/src/token/mod.rs index 299855e..ebebe9d 100644 --- a/work/crates/derive/src/token/mod.rs +++ b/work/crates/derive/src/token/mod.rs @@ -38,7 +38,6 @@ mod input; mod opt; mod output; mod regex; -#[path = "../../../main/src/lexis/ucd.rs"] mod ucd; mod variant; diff --git a/work/crates/derive/src/token/ucd.rs b/work/crates/derive/src/token/ucd.rs new file mode 120000 index 0000000..d421705 --- /dev/null +++ b/work/crates/derive/src/token/ucd.rs @@ -0,0 +1 @@ +../../../main/src/lexis/ucd.rs \ No newline at end of file diff --git a/work/crates/main/Cargo.toml b/work/crates/main/Cargo.toml index c44b212..72f5848 100644 --- a/work/crates/main/Cargo.toml +++ b/work/crates/main/Cargo.toml @@ -34,7 +34,7 @@ [package] name = "lady-deirdre" -version = "2.0.1" +version = "2.1.0" authors = ["Ilya Lakhin (Илья Александрович Лахин) "] edition = "2021" description = "Compiler front-end foundation technology. Main Crate." @@ -52,5 +52,5 @@ autotests = false autobenches = false [dependencies.lady-deirdre-derive] -version = "2.0" +version = "2.1" path = "../derive"