writerly

Parse, serialize, assemble, and convert Writerly documents.

Writerly is an indentation-based markup language descended from Elm-Markup. It represents elements, attributes, paragraphs, blank lines, comments, and fenced code blocks, and converts them to and from VXML.

Types

AssemblyError

</>

An error encountered while assembling Writerly source files.

pub type AssemblyError {
  ReadFileError(String)
  ReadFileOrDirectoryError(String)
  NoFilesFound(String)
}

Constructors

```
ReadFileError(String)
```
```
ReadFileOrDirectoryError(String)
```
```
NoFilesFound(String)
```

ParseError

</>

An error encountered while parsing Writerly source.

pub type ParseError {
  BadTag(blame: blame.Blame, bad_name: String)
  BadKey(blame: blame.Blame, bad_key: String)
  IndentationTooLarge(
    blame: blame.Blame,
    expected: String,
    found: String,
    line: String,
  )
  IndentationNotMultipleOfFour(blame: blame.Blame, line: String)
  CodeBlockInfoStartsWithSpace(
    blame: blame.Blame,
    bad_info: String,
  )
  CodeBlockNotClosed(blame: blame.Blame)
  CodeBlockUnwantedAnnotationAtClose(
    blame: blame.Blame,
    opening_blame: blame.Blame,
    annotation: String,
  )
  ExcessiveLeadingAttributeWhitespace(
    blame: blame.Blame,
    maximum: Int,
    found: Int,
  )
  NonUniqueRoot(blame: blame.Blame)
  MissingRoot(blame: blame.Blame)
}

Constructors

BadTag(blame: blame.Blame, bad_name: String)

BadKey(blame: blame.Blame, bad_key: String)

IndentationTooLarge(
  blame: blame.Blame,
  expected: String,
  found: String,
  line: String,
)

IndentationNotMultipleOfFour(blame: blame.Blame, line: String)

CodeBlockInfoStartsWithSpace(
  blame: blame.Blame,
  bad_info: String,
)

```
CodeBlockNotClosed(blame: blame.Blame)
```

CodeBlockUnwantedAnnotationAtClose(
  blame: blame.Blame,
  opening_blame: blame.Blame,
  annotation: String,
)

ExcessiveLeadingAttributeWhitespace(
  blame: blame.Blame,
  maximum: Int,
  found: Int,
)

```
NonUniqueRoot(blame: blame.Blame)
```
```
MissingRoot(blame: blame.Blame)
```

SerializationError

</>

An error encountered while converting VXML to Writerly or serializing Writerly source.

pub type SerializationError {
  EmptyTextNode(blame: blame.Blame)
  MalformedBlankLine(blame: blame.Blame)
  MalformedCodeBlock(blame: blame.Blame)
  MalformedComment(blame: blame.Blame)
  EmptyParagraph(blame: blame.Blame)
  EmptyComment(blame: blame.Blame)
  DuplicateCodeBlockInfoStringPrefix(blame: blame.Blame)
  ExcessiveLeadingAttributeWhitespaceInSerialization(
    blame: blame.Blame,
    maximum: Int,
    found: Int,
  )
}

Constructors

```
EmptyTextNode(blame: blame.Blame)
```
```
MalformedBlankLine(blame: blame.Blame)
```
```
MalformedCodeBlock(blame: blame.Blame)
```
```
MalformedComment(blame: blame.Blame)
```
```
EmptyParagraph(blame: blame.Blame)
```
```
EmptyComment(blame: blame.Blame)
```

DuplicateCodeBlockInfoStringPrefix(blame: blame.Blame)

ExcessiveLeadingAttributeWhitespaceInSerialization(
  blame: blame.Blame,
  maximum: Int,
  found: Int,
)

Writerly

</>

A node in a parsed Writerly document.

Every node and its contained VXML values retain source-provenance Blame.

pub type Writerly {
  BlankLine(blame: blame.Blame)
  Paragraph(blame: blame.Blame, lines: List(vxml.Line))
  Comment(blame: blame.Blame, lines: List(vxml.Line))
  CodeBlock(
    blame: blame.Blame,
    attrs: List(vxml.Attr),
    lines: List(vxml.Line),
  )
  Tag(
    blame: blame.Blame,
    name: String,
    attrs: List(vxml.Attr),
    children: List(Writerly),
  )
}

Constructors

```
BlankLine(blame: blame.Blame)
```

Paragraph(blame: blame.Blame, lines: List(vxml.Line))

Comment(blame: blame.Blame, lines: List(vxml.Line))

CodeBlock(
  blame: blame.Blame,
  attrs: List(vxml.Attr),
  lines: List(vxml.Line),
)

Tag(
  blame: blame.Blame,
  name: String,
  attrs: List(vxml.Attr),
  children: List(Writerly),
)

Values

annotate_blames

</>

pub fn annotate_blames(
  writerly: Writerly,
) -> Result(Writerly, SerializationError)

Adds structural descriptions to the blame comments throughout a tree.

This is intended for diagnostic tables. Source locations and node contents are otherwise unchanged.

assemble_input_lines

</>

pub fn assemble_input_lines(
  dirpath_or_filepath: String,
) -> Result(
  #(dirtree.DirTree, List(io_lines.InputLine)),
  AssemblyError,
)

Assembles every eligible .wly file from a file or directory.

Files and directories with a path component beginning with # are ignored. See assemble_input_lines_with_path_selector for selective assembly.

assemble_input_lines_with_path_selector

</>

pub fn assemble_input_lines_with_path_selector(
  dirpath_or_filepath: String,
  path_selector: fn(String) -> Bool,
) -> Result(
  #(dirtree.DirTree, List(io_lines.InputLine)),
  AssemblyError,
)

Assembles selected .wly files from a file or directory.

The selector receives paths relative to the input directory. A selected file is included along with any __parent.wly files needed to contain it. The returned directory tree records the selected layout; the input lines retain their relative source paths and are indented according to that tree.

code_block_info_string_prefix_attribute_key

</>

pub const code_block_info_string_prefix_attribute_key: String

The synthetic VXML attribute key used for the nonempty, unmarked prefix of a code block’s info string: the part before its first unescaped &key=value annotation. The attribute is absent when that prefix is empty.

commented_attribute_key

</>

pub fn commented_attribute_key(
  spaces: Int,
) -> option.Option(String)

Constructs a Writerly commented-attribute key for a bounded space count.

commented_attribute_spaces

</>

pub fn commented_attribute_spaces(
  key: String,
) -> option.Option(Int)

Returns the encoded number of spaces in a Writerly commented attribute. Only keys encoding between zero and 100 spaces are recognized.

input_lines_to_vxml

</>

pub fn input_lines_to_vxml(
  lines: List(io_lines.InputLine),
) -> Result(vxml.VXML, ParseError)

Parses input lines with one non-blank root and converts it to VXML.

input_lines_to_writerly

</>

pub fn input_lines_to_writerly(
  lines: List(io_lines.InputLine),
) -> Result(Writerly, ParseError)

Parses input lines containing exactly one non-blank top-level node.

Top-level blank lines do not count toward cardinality. Returns MissingRoot when there is no non-blank root and NonUniqueRoot when there is more than one.

input_lines_to_writerlys

</>

pub fn input_lines_to_writerlys(
  lines: List(io_lines.InputLine),
) -> Result(List(Writerly), ParseError)

Parses input lines into zero or more top-level Writerly nodes.

is_commented_attribute_key

</>

pub fn is_commented_attribute_key(key: String) -> Bool

Returns whether a key is a valid Writerly commented-attribute encoding.

path_selector_from_only_paths

</>

pub fn path_selector_from_only_paths(
  only_paths: List(String),
) -> fn(String) -> Bool

Builds a path selector from inclusive and exclusive path fragments.

Ordinary fragments include paths containing that fragment. Fragments beginning with ! exclude matching paths. With only exclusions, all other paths are included. With both forms, a path must match an inclusion and no exclusion. An empty list selects every path.

string_to_writerly

</>

pub fn string_to_writerly(
  source: String,
  filename: String,
) -> Result(Writerly, ParseError)

Parses a source string containing exactly one non-blank top-level node.

filename is recorded in the source blame attached to parsed values.

string_to_writerlys

</>

pub fn string_to_writerlys(
  source: String,
  filename: String,
) -> Result(List(Writerly), ParseError)

Parses a source string into zero or more top-level Writerly nodes.

filename is recorded in the source blame attached to parsed values.

vxml_to_writerly

</>

pub fn vxml_to_writerly(
  vxml: vxml.VXML,
) -> Result(Writerly, SerializationError)

Converts VXML that corresponds to exactly one Writerly node.

vxml_to_writerlys

</>

pub fn vxml_to_writerlys(
  vxml: vxml.VXML,
) -> Result(List(Writerly), SerializationError)

Converts one VXML node to a singleton list containing its Writerly node.

Reserved Writerly elements must have the structure produced by writerly_to_vxml.

vxmls_to_writerlys

</>

pub fn vxmls_to_writerlys(
  vxmls: List(vxml.VXML),
) -> Result(List(Writerly), SerializationError)

Converts VXML nodes to Writerly nodes in the same order.

writerly_table

</>

pub fn writerly_table(
  writerly: Writerly,
  banner: String,
  indent: Int,
) -> Result(String, SerializationError)

Renders a blame-annotated diagnostic table for one Writerly tree.

banner labels the table and indent sets its left margin.

writerly_to_output_lines

</>

pub fn writerly_to_output_lines(
  writerly: Writerly,
) -> Result(List(io_lines.OutputLine), SerializationError)

Serializes one Writerly node to Writerly OutputLine values.

writerly_to_string

</>

pub fn writerly_to_string(
  writerly: Writerly,
) -> Result(String, SerializationError)

Serializes one Writerly node to Writerly source.

writerly_to_vxml

</>

pub fn writerly_to_vxml(t: Writerly) -> vxml.VXML

Converts one Writerly node to its VXML representation.

Paragraphs become text nodes. Blank lines, comments, and code blocks use the reserved WriterlyBlankLine, WriterlyComment, and WriterlyCodeBlock element names.

writerlys_to_output_lines

</>

pub fn writerlys_to_output_lines(
  writerlys: List(Writerly),
) -> Result(List(io_lines.OutputLine), SerializationError)

Serializes Writerly nodes to one flat list of VXML OutputLine values.

writerlys_to_string

</>

pub fn writerlys_to_string(
  writerlys: List(Writerly),
) -> Result(String, SerializationError)

Serializes Writerly nodes to Writerly source in the same order.

writerlys_to_vxmls

</>

pub fn writerlys_to_vxmls(
  writerlys: List(Writerly),
) -> List(vxml.VXML)

Converts Writerly nodes to VXML nodes in the same order.