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 ¶
Constants ¶
This section is empty.
Variables ¶
var PromptPattern = regexp.MustCompile(`^[~/][^ ]*> `)
PromptPattern defines how to match prompts, used to determine which lines start the code part of an interaction.
Functions ¶
This section is empty.
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 ¶ added in v0.21.0
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.