transcript

Documentation

Overview

Package transcript contains utilities for working with Elvish transcripts.

Basic syntax

In its most basic form, a transcript consists of a series of code entered after a prompt, each followed by the resulting output:

~> echo foo
foo
~> echo lorem
   echo ipsum
lorem
ipsum

A line starting with a prompt (as defined by PromptPattern) is considered to start code; code extends to further lines that are indented to align with the prompt. The other lines are considered output.

Headings and sessions

Two levels of headings are supported: "# h1 #" and "## h2 ##". They split a transcript into a tree of multiple sessions, and the titles become their names.

For example, suppose that a.elvts contains the following content:

~> echo hello
hello

# foo #

~> foo
something is done

# bar #

## 1 ##
~> bar 1
something is 1 done

## 2 ##
~> bar 2
something is 2 done

This file contains the following tree:

a.elvts
	foo
	bar
		1
		2

Leading and trailing empty lines are stripped from a session, but internal empty lines are kept intact. This also applies to transcripts with no headings (and thus consisting of exactly one session).

Comments and directives

A line starting with "// " or consisting of 2 or more "/"s and nothing else is a comment. Comments are ignored and can appear anywhere, except that they can't interrupt multi-line code.

A line starting with "//" but is not a comment is a directive. Directives can only appear at the beginning of a session, possibly after other directives, comments or empty lines.

Sessions in .elv files

An .elv file may contain elvdocs for their variables or functions, which in turn may contain examples given as elvish-transcript code blocks.

Each of those code block is considered a transcript, named $filename/$symbol/$name, where $name is the additional words after the "elvish-transcript" in the opening fence, defaulting to an empty string.

File-level directives and symbol-level directives starting with "#//" are supported.

As an example, suppose a.elv contains the following content:

#//dir1

#//dir2
# Does something.
#
# Example:
#
# ```elvish-transcript
# ~> foo
# something is done
# ```
fn foo {|| }

# Does something depending on argument.
#
# Example:
#
# ```elvish-transcript 1
# ~> bar 1
# something 1 is done
# ```
#
# Another example:
#
# ```elvish-transcript 2
# ~> bar 2
# something 2 is done
# ```
fn bar {|x| }

This creates the following tree:

a.elv
	foo
		unnamed
	bar
		1
		2

These transcripts can also contain headings, which split them into further smaller sessions.

Index

• Variables
• type Interaction
  • func (i Interaction) PromptAndCode() string
• type Node
  • func Parse(path string, r io.Reader) (*Node, error)
  • func ParseFromFS(fsys fs.FS) ([]*Node, error)

Variables

var PromptPattern = regexp.MustCompile(`^[~/][^ ]*> `)

PromptPattern defines how to match prompts, used to determine which lines start the code part of an interaction.

Types

type Interaction

type Interaction struct {
	Prompt string
	Code   string
	// [CodeLineFrom, CodeLineTo) identifies the range of code lines.
	CodeLineFrom, CodeLineTo int

	Output string
	// [OutputLineFrom, OutputlineTo) identifies the range of output lines,
	// excluding any leading and trailing comment lines.
	OutputLineFrom, OutputLineTo int
}

Interaction represents a single REPL interaction - user input followed by the shell's output. Prompt is never empty.

func (Interaction) PromptAndCode

func (i Interaction) PromptAndCode() string

PromptAndCode returns prompt and code concatenated, with spaces prepended to continuation lines in Code to align with the first line.

type Node

type Node struct {
	Name         string
	Directives   []string
	Interactions []Interaction
	Children     []*Node
	// [LineFrom, LineTo)
	LineFrom, LineTo int
}

Node is the result of parsing transcripts. It can represent an .elvts file, a elvish-transcript block within the elvdoc of an .elv file, or an section within them started by a header.

func Parse

func Parse(path string, r io.Reader) (*Node, error)

Parse parses the transcript sessions from an .elvts file.

func ParseFromFS

func ParseFromFS(fsys fs.FS) ([]*Node, error)

ParseFromFS scans fsys recursively for .elv and .elvts files, and extract transcript sessions from them.