moonrockz/notebooks/dib

type Cell derive(Eq, @moonbitlang/core/debug.Debug)

An immutable source cell with a kernel name. Sources normalize line endings and trim only empty boundary lines. Notebook construction resolves kernel aliases; a standalone cell may still contain an alias.

fn Cell::Cell(source : String, kernel~ : KernelName) -> Cell

Normalize LF, CRLF and CR to LF and remove empty boundary lines. Retain whitespace-only and internal blank lines. Registry membership is checked by Notebook construction; selector conflicts are checked on writing.

fn Cell::directives(self : Cell) -> ReadOnlyArray[Directive]

Return column-zero #! lines in source order as immutable directive views. Indented lines are excluded. Kernel selectors consumed during parsing are cell properties and do not appear in parsed cell source.

fn Cell::equal(Cell, Cell) -> Bool

fn Cell::kernel(self : Cell) -> KernelName

Return the cell's kernel name. Notebook construction canonicalizes registered aliases; a standalone Cell retains the supplied name.

fn Cell::kind(self : Cell) -> @moonrockz/notebooks.CellKind

Classify markdown and md cells as Markdown and other kernels as Code.

fn Cell::metadata(_self : Cell) -> @moonrockz/notebooks.Metadata?

DIB has no stored MIME bundles, so capability inspection uses the shared default of None. It also has no cell-local metadata container.

fn Cell::mime_capability(_self : Cell) -> &@moonrockz/notebooks.MimeTyped?

DIB has no stored MIME bundles, so capability inspection uses the shared default of None. It also has no cell-local metadata container.

fn Cell::not_equal(x : Cell, y : Cell) -> Bool

fn Cell::source(self : Cell) -> String

Return normalized cell source without its kernel selector.

fn Cell::to_repr(Cell) -> @moonbitlang/core/debug.Repr

fn kind(self : Cell) -> @moonrockz/notebooks.CellKind

fn source(self : Cell) -> String?

type Directive derive(Eq, @moonbitlang/core/debug.Debug)

An immutable column-zero #! line retained in cell source, with a name, unparsed arguments, exact normalized line text and one-based source line. This view does not execute commands or interpret quoted arguments.

fn Directive::arguments(self : Directive) -> String

Return the remaining command text with leading whitespace removed. Arguments remain uninterpreted; quoting is not parsed.

fn Directive::equal(Directive, Directive) -> Bool

fn Directive::line(self : Directive) -> Int

Return the one-based line relative to normalized cell source, not the line number in the original DIB document.

fn Directive::name(self : Directive) -> String

Return the command token after #!, stopping at the first space or tab.

fn Directive::not_equal(x : Directive, y : Directive) -> Bool

fn Directive::text(self : Directive) -> String

Return the complete #! source line, without a newline terminator.

fn Directive::to_repr(Directive) -> @moonbitlang/core/debug.Repr

type KernelInfo derive(Eq, @moonbitlang/core/debug.Debug)

An immutable registration describing a canonical kernel name, its aliases and an optional language label. Names alone do not execute or install a kernel.

fn KernelInfo::KernelInfo(name : KernelName, aliases? : ReadOnlyArray[KernelName], language? : String?) -> KernelInfo

Describe a kernel using validated names. Defaults to no aliases and no language label. Registry construction checks name and alias collisions.

fn KernelInfo::aliases(self : KernelInfo) -> ReadOnlyArray[KernelName]

Return immutable case-sensitive aliases for this kernel.

fn KernelInfo::equal(KernelInfo, KernelInfo) -> Bool

fn KernelInfo::language(self : KernelInfo) -> String?

Return the optional language label supplied by the registration.

fn KernelInfo::name(self : KernelInfo) -> KernelName

Return this registration's canonical name.

fn KernelInfo::not_equal(x : KernelInfo, y : KernelInfo) -> Bool

fn KernelInfo::to_repr(KernelInfo) -> @moonbitlang/core/debug.Repr

type KernelName derive(Eq, @moonbitlang/core/debug.Debug)

A validated kernel name or alias. Names are case-sensitive and nonblank; they cannot start with #, contain line breaks or name a metadata header.

fn KernelName::KernelName(value : String) -> KernelName raise FormatError

Validate a case-sensitive kernel name or alias. Raise InvalidKernelName for blank names, leading #, line breaks or reserved metadata selectors. This validates spelling, not membership in a kernel registry.

test "doc: resolve a kernel alias" {
  let registry = @dib.KernelRegistry::standard()
  let name = @dib.KernelName("csharp")
  @expect.expect(registry.resolve("c#")).to_equal(Some(name))
}

fn KernelName::equal(KernelName, KernelName) -> Bool

fn KernelName::not_equal(x : KernelName, y : KernelName) -> Bool

fn KernelName::to_repr(KernelName) -> @moonbitlang/core/debug.Repr

fn KernelName::to_string(self : KernelName) -> String

Return the name or alias exactly as supplied.

type KernelRegistry derive(Eq, @moonbitlang/core/debug.Debug)

An immutable execution environment used to distinguish cell selectors from source directives. Lookups map canonical names and aliases to canonical KernelName values. Parsing also supplies the Markdown pseudo-kernel.

fn KernelRegistry::KernelRegistry(kernels : ReadOnlyArray[KernelInfo], default_kernel~ : KernelName) -> KernelRegistry raise FormatError

Build a registry and resolve its required default name or alias. Raise DuplicateKernelName for any repeated name/alias, including within one registration, or UnknownKernel if the default cannot be resolved.

fn KernelRegistry::default_kernel(self : KernelRegistry) -> KernelName

Return the default kernel's canonical name.

fn KernelRegistry::equal(KernelRegistry, KernelRegistry) -> Bool

fn KernelRegistry::kernels(self : KernelRegistry) -> ReadOnlyArray[KernelInfo]

Return immutable registrations in their stored order.

fn KernelRegistry::not_equal(x : KernelRegistry, y : KernelRegistry) -> Bool

fn KernelRegistry::resolve(self : KernelRegistry, name : String) -> KernelName?

Resolve an exact, case-sensitive name or alias to its canonical name. Return None for an unregistered name.

fn KernelRegistry::standard() -> KernelRegistry

Return the standard execution-kernel registrations with C# as default. Includes C#, F#, PowerShell, JavaScript, HTML, SQL, KQL, HTTP, value and Mermaid. Parsing and Notebook construction also add Markdown as needed.

fn KernelRegistry::to_repr(KernelRegistry) -> @moonbitlang/core/debug.Repr

pub(all) enum MetadataOutput {
  Auto
  Json
  Ion
} derive(Eq, @moonbitlang/core/debug.Debug)

DIB output keeps JSON when it preserves the metadata, otherwise uses Ion. Explicit Json requests reject metadata that cannot round-trip through JSON.

fn MetadataOutput::equal(MetadataOutput, MetadataOutput) -> Bool

fn MetadataOutput::not_equal(x : MetadataOutput, y : MetadataOutput) -> Bool

fn MetadataOutput::to_repr(MetadataOutput) -> @moonbitlang/core/debug.Repr

pub(all) enum Node {
  Notebook(Notebook)
  Cell(Cell)
  Directive(Directive)
} derive(Eq, @moonbitlang/core/debug.Debug)

A concrete DIB traversal node. Notebook children are cells in source order; cell children are retained directives in source order. Directives are leaves. Metadata and kernel registrations use their own accessors.

fn Node::at(self : Node, path : @moonrockz/notebooks.NodePath) -> Node?

Resolve a shared child-index path relative to this node, returning None for any invalid index. Cell child indices refer to retained directives.

fn Node::children(self : Node) -> ReadOnlyArray[Node]

Return immutable cells or directives in source order. Directive leaves have no children. Kernel selectors are properties of cells, not children.

fn Node::cursor(self : Node) -> @moonrockz/notebooks.Cursor[Node]

Establish a new navigation root at this node. Use an existing cursor to retain its original paths and ancestors.

fn Node::equal(Node, Node) -> Bool

fn Node::kind(self : Node) -> @moonrockz/notebooks.NodeKind

Classify this concrete node for shared traversal. Directive kinds retain the command name, while concrete nodes retain the complete directive.

fn Node::metadata(self : Node) -> @moonrockz/notebooks.Metadata?

Return this node's own metadata. Some(empty) retains an empty container; None means this node has none. Ancestor metadata is never inherited.

fn Node::not_equal(x : Node, y : Node) -> Bool

fn Node::source(self : Node) -> String?

Return normalized cell source or a directive's source line. Return None for a notebook node.

fn Node::to_repr(Node) -> @moonbitlang/core/debug.Repr

fn children(self : Node) -> ReadOnlyArray[Node]

fn kind(self : Node) -> @moonrockz/notebooks.NodeKind

fn metadata(self : Node) -> @moonrockz/notebooks.Metadata?

fn source(self : Node) -> String?

type Notebook derive(Eq, @moonbitlang/core/debug.Debug)

An immutable DIB source notebook with ordered cells, metadata and the kernel registry needed to interpret its selectors. DIB stores no outputs.

fn Notebook::Notebook(cells : ReadOnlyArray[Cell], metadata? : @moonrockz/notebooks.Metadata, registry? : KernelRegistry) -> Notebook raise FormatError

Build a notebook with empty metadata and the standard registry by default. Interpret metadata registrations and canonicalize each cell's kernel alias. Raise FormatError for invalid registration metadata, duplicate kernel names or unregistered cell kernels. Empty cells remain until serialization.

fn Notebook::cell(self : Notebook, index : Int) -> Cell?

Look up a zero-based cell index. Return None for negative or out-of-range indices.

fn Notebook::cells(self : Notebook) -> ReadOnlyArray[Cell]

Return immutable cells in source order, including constructed empty cells.

fn Notebook::cells_for_kernel(self : Notebook, name : String) -> ReadOnlyArray[Cell]

Resolve a canonical name or alias, then select matching cells in source order. Return an empty immutable array for an unknown name. Markdown is a selectable pseudo-kernel.

fn Notebook::cursor(self : Notebook) -> @moonrockz/notebooks.Cursor[Node]

Start a typed DIB cursor at this notebook with depth zero and path $.

fn Notebook::equal(Notebook, Notebook) -> Bool

fn[A] Notebook::fold(self : Notebook, init : A, f : (A, @moonrockz/notebooks.Cursor[Node]) -> A) -> A

Thread an accumulator through this notebook tree in pre-order, supplying typed DIB cursors. Use walk for pruning or early termination.

fn Notebook::metadata(self : Notebook) -> @moonrockz/notebooks.Metadata

Return immutable document metadata, retaining custom namespaces.

fn Notebook::not_equal(x : Notebook, y : Notebook) -> Bool

fn Notebook::registry(self : Notebook) -> KernelRegistry

Return the effective registry, including metadata declarations and Markdown. Retain it when rereading custom environment-dependent selectors.

fn Notebook::root(self : Notebook) -> Node

Wrap this notebook as the concrete root accepted by shared traversal.

fn Notebook::to_repr(Notebook) -> @moonbitlang/core/debug.Repr

fn Notebook::to_string(self : Notebook, metadata_output? : MetadataOutput) -> String raise FormatError

Serialize normalized DIB source using canonical kernel selectors. Omit empty cells and retain document metadata. Auto output uses JSON when it preserves the metadata, otherwise Ion. Explicit Json rejects data loss. Emit a header when needed to preserve later metadata directives as source. Raise UnrepresentableSource if embedded registered selectors would split a cell. Custom kernels supplied only by the environment require the same registry on subsequent reads; the writer does not inject those registrations.

pub(all) suberror FormatError {
  InvalidMetadata(line~ : Int, message~ : String)
  InvalidKernelName(String)
  DuplicateKernelName(String)
  UnknownKernel(String)
  UnrepresentableSource(cell~ : Int, line~ : Int)
} derive(Eq, @moonbitlang/core/debug.Debug)

A DIB metadata, kernel registration or serialization failure. UnrepresentableSource identifies a zero-based cell index and a one-based line within its normalized source. Metadata line numbers are one-based.

fn FormatError::equal(FormatError, FormatError) -> Bool

fn FormatError::not_equal(x : FormatError, y : FormatError) -> Bool

fn FormatError::to_repr(FormatError) -> @moonbitlang/core/debug.Repr

using @moonrockz/notebooks { type Control }

Shared navigation types. Explicit cursor annotations use Cursor[Node].

using @moonrockz/notebooks { type Cursor }

Shared navigation types. Explicit cursor annotations use Cursor[Node].

using @moonrockz/notebooks { type Metadata }

Shared navigation types. Explicit cursor annotations use Cursor[Node].

using @moonrockz/notebooks { type NodePath }

Shared navigation types. Explicit cursor annotations use Cursor[Node].

fn parse(source : String, registry? : KernelRegistry) -> Notebook raise FormatError

Read a DIB source notebook without executing it. Registered, exact column-zero selectors start cells; other directives remain source. Read the first exact metadata section and apply its registrations. #!meta and #!meta json read JSON; #!meta yaml, #!meta toml and #!meta ion are extensions. Normalize line endings, trim empty boundary lines and omit empty sections; an empty document yields one empty cell. Accept a leading BOM. Raise FormatError for invalid metadata or conflicting kernel registrations.

fn walk(root : Node, enter : (Node) -> @moonrockz/notebooks.Control, leave? : (Node) -> Unit) -> Unit

Walk concrete DIB nodes in depth-first pre-order with the shared engine. Use walk_cursor when callbacks need path or ancestor context.

fn walk_cursor(root : Node, enter : (@moonrockz/notebooks.Cursor[Node]) -> @moonrockz/notebooks.Control, leave? : (@moonrockz/notebooks.Cursor[Node]) -> Unit) -> Unit

Use the shared engine to walk typed DIB positions from a new root. SkipChildren still receives leave; Stop cancels pending leave calls.