diff options
Diffstat (limited to 'src/construct')
| -rw-r--r-- | src/construct/mdx_expression_flow.rs | 44 | ||||
| -rw-r--r-- | src/construct/mdx_expression_text.rs | 36 | ||||
| -rw-r--r-- | src/construct/partial_mdx_expression.rs | 84 |
3 files changed, 152 insertions, 12 deletions
diff --git a/src/construct/mdx_expression_flow.rs b/src/construct/mdx_expression_flow.rs index 0faea31..ef3ca41 100644 --- a/src/construct/mdx_expression_flow.rs +++ b/src/construct/mdx_expression_flow.rs @@ -1,4 +1,38 @@ -//! To do. +//! MDX expression (flow) occurs in the [flow][] content type. +//! +//! ## Grammar +//! +//! MDX expression (flow) forms with the following BNF +//! (<small>see [construct][crate::construct] for character groups</small>): +//! +//! ```bnf +//! mdx_expression_flow ::= mdx_expression *space_or_tab +//! +//! ; See the `partial_mdx_expression` construct for the BNF of that part. +//! ``` +//! +//! As this construct occurs in flow, like all flow constructs, it must be +//! followed by an eol (line ending) or eof (end of file). +//! +//! See [`mdx_expression`][mdx_expression] for more info. +//! +//! ## Tokens +//! +//! * [`MdxFlowExpression`][Name::MdxFlowExpression] +//! * [`SpaceOrTab`][Name::SpaceOrTab] +//! * see [`mdx_expression`][mdx_expression] for more +//! +//! ## Recommendation +//! +//! See [`mdx_expression`][mdx_expression] for recommendations. +//! +//! ## References +//! +//! * [`syntax.js` in `micromark-extension-mdx-expression`](https://github.com/micromark/micromark-extension-mdx-expression/blob/main/packages/micromark-extension-mdx-expression/dev/lib/syntax.js) +//! * [`mdxjs.com`](https://mdxjs.com) +//! +//! [flow]: crate::construct::flow +//! [mdx_expression]: crate::construct::partial_mdx_expression use crate::construct::partial_space_or_tab::{space_or_tab, space_or_tab_min_max}; use crate::event::Name; @@ -6,7 +40,7 @@ use crate::state::{Name as StateName, State}; use crate::tokenizer::Tokenizer; use crate::util::constant::TAB_SIZE; -/// Start of MDX: expression (flow). +/// Start of an MDX expression (flow). /// /// ```markdown /// > | {Math.PI} @@ -35,7 +69,7 @@ pub fn start(tokenizer: &mut Tokenizer) -> State { } } -/// After optional whitespace, before of MDX expression (flow). +/// After optional whitespace, before expression. /// /// ```markdown /// > | {Math.PI} @@ -50,7 +84,7 @@ pub fn before(tokenizer: &mut Tokenizer) -> State { } } -/// After an MDX expression (flow). +/// After expression. /// /// ```markdown /// > | {Math.PI} @@ -66,7 +100,7 @@ pub fn after(tokenizer: &mut Tokenizer) -> State { } } -/// After an MDX expression (flow), after optional whitespace. +/// After expression, after optional whitespace. /// /// ```markdown /// > | {Math.PI}␠␊ diff --git a/src/construct/mdx_expression_text.rs b/src/construct/mdx_expression_text.rs index 8d061eb..53160a0 100644 --- a/src/construct/mdx_expression_text.rs +++ b/src/construct/mdx_expression_text.rs @@ -1,10 +1,40 @@ -//! To do. +//! MDX expression (text) occurs in the [text][] content type. +//! +//! ## Grammar +//! +//! MDX expression (text) forms with the following BNF +//! (<small>see [construct][crate::construct] for character groups</small>): +//! +//! ```bnf +//! mdx_expression_text ::= mdx_expression +//! +//! ; See the `partial_mdx_expression` construct for the BNF of that part. +//! ``` +//! +//! See [`mdx_expression`][mdx_expression] for more info. +//! +//! ## Tokens +//! +//! * [`MdxTextExpression`][Name::MdxTextExpression] +//! * see [`mdx_expression`][mdx_expression] for more +//! +//! ## Recommendation +//! +//! See [`mdx_expression`][mdx_expression] for recommendations. +//! +//! ## References +//! +//! * [`syntax.js` in `micromark-extension-mdx-expression`](https://github.com/micromark/micromark-extension-mdx-expression/blob/main/packages/micromark-extension-mdx-expression/dev/lib/syntax.js) +//! * [`mdxjs.com`](https://mdxjs.com) +//! +//! [text]: crate::construct::text +//! [mdx_expression]: crate::construct::partial_mdx_expression use crate::event::Name; use crate::state::{Name as StateName, State}; use crate::tokenizer::Tokenizer; -/// Start of MDX: expression (text). +/// Start of an MDX expression (text). /// /// ```markdown /// > | a {Math.PI} c @@ -22,7 +52,7 @@ pub fn start(tokenizer: &mut Tokenizer) -> State { } } -/// After an MDX expression (text) tag. +/// After expression. /// /// ```markdown /// > | a {Math.PI} c diff --git a/src/construct/partial_mdx_expression.rs b/src/construct/partial_mdx_expression.rs index aeea52e..31a9af8 100644 --- a/src/construct/partial_mdx_expression.rs +++ b/src/construct/partial_mdx_expression.rs @@ -1,4 +1,61 @@ -//! To do. +//! MDX expression occurs in [MDX expression (flow)][mdx_expression_flow] and +//! [MDX expression (text)][mdx_expression_text]. +//! +//! ## Grammar +//! +//! MDX expression forms with the following BNF +//! (<small>see [construct][crate::construct] for character groups</small>): +//! +//! ```bnf +//! mdx_expression ::= '{' *(expression_text | expression) '}' +//! expression_text ::= char - '{' - '}' +//! ``` +//! +//! ## Tokens +//! +//! * [`LineEnding`][Name::LineEnding] +//! * [`SpaceOrTab`][Name::SpaceOrTab] +//! * [`MdxExpressionMarker`][Name::MdxExpressionMarker] +//! * [`MdxExpressionData`][Name::MdxExpressionData] +//! +//! ## Recommendation +//! +//! When authoring markdown with JavaScript, keep in mind that MDX is a +//! whitespace sensitive and line-based language, while JavaScript is +//! insensitive to whitespace. +//! This affects how markdown and JavaScript interleave with eachother in MDX. +//! For more info on how it works, see [§ Interleaving][interleaving] on the +//! MDX site. +//! +//! ## Errors +//! +//! ### Unexpected end of file in expression, expected a corresponding closing brace for `{` +//! +//! This error occurs if a `{` was seen without a `}`. +//! For example: +//! +//! ```markdown +//! a { b +//! ``` +//! +//! ### Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc +//! +//! This error occurs if a a lazy line (of a container) is found in an expression. +//! For example: +//! +//! ```markdown +//! > {a + +//! b} +//! ``` +//! +//! ## References +//! +//! * [`micromark-factory-mdx-expression`](https://github.com/micromark/micromark-extension-mdx-expression/blob/main/packages/micromark-factory-mdx-expression/dev/index.js) +//! * [`mdxjs.com`](https://mdxjs.com) +//! +//! [mdx_expression_flow]: crate::construct::mdx_expression_flow +//! [mdx_expression_text]: crate::construct::mdx_expression_text +//! [interleaving]: https://mdxjs.com/docs/what-is-mdx/#interleaving use crate::construct::partial_space_or_tab::space_or_tab_min_max; use crate::event::Name; @@ -6,7 +63,7 @@ use crate::state::{Name as StateName, State}; use crate::tokenizer::Tokenizer; use alloc::format; -/// Start of MDX: expression. +/// Start of an MDX expression. /// /// ```markdown /// > | a {Math.PI} c @@ -21,6 +78,12 @@ pub fn start(tokenizer: &mut Tokenizer) -> State { State::Next(StateName::MdxExpressionBefore) } +/// Before data. +/// +/// ```markdown +/// > | a {Math.PI} c +/// ^ +/// ``` pub fn before(tokenizer: &mut Tokenizer) -> State { match tokenizer.current { None => { @@ -38,7 +101,7 @@ pub fn before(tokenizer: &mut Tokenizer) -> State { Some(b'}') if tokenizer.tokenize_state.size == 0 => { if tokenizer.tokenize_state.token_1 == Name::MdxJsxTagAttributeValueExpression && !tokenizer.tokenize_state.seen { State::Error(format!( - "{}:{}: Unexpected empty in expression, expected a value between braces", + "{}:{}: Unexpected empty expression, expected a value between braces", tokenizer.point.line, tokenizer.point.column )) } else { @@ -58,6 +121,12 @@ pub fn before(tokenizer: &mut Tokenizer) -> State { } } +/// In data. +/// +/// ```markdown +/// > | a {Math.PI} c +/// ^ +/// ``` pub fn inside(tokenizer: &mut Tokenizer) -> State { if matches!(tokenizer.current, None | Some(b'\n')) || (tokenizer.current == Some(b'}') && tokenizer.tokenize_state.size == 0) @@ -77,8 +146,15 @@ pub fn inside(tokenizer: &mut Tokenizer) -> State { } } +/// After eol. +/// +/// ```markdown +/// | a {b + +/// > | c} d +/// ^ +/// ``` pub fn eol_after(tokenizer: &mut Tokenizer) -> State { - // Lazy continuation in a flow expression (or in a flow tag) is a syntax error. + // Lazy continuation in a flow expression (or flow tag) is a syntax error. if (tokenizer.tokenize_state.token_1 == Name::MdxFlowExpression || tokenizer.tokenize_state.token_2 == Name::MdxJsxFlowTag) && tokenizer.lazy |