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 multiple sessions and are used to name them.

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 three sessions: a.elvts, a.elvts/foo, a.elvts/bar/1 and a.elvts/bar/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.

Directives propagate to "lower-level" sessions. This mechanism is best shown with an example:

//top

# h1 #
//h1

## h2 ##
//h2

~> echo foo
foo

In the "echo foo" session, all of "top", "h1" and "h2" directives are active.

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. If there are additional words after the "elvish-transcript" in the opening fence, they are appended to name of the transcript, becoming $filename/$symbol/$name.

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

# 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 three sessions: a.elv/foo, a.elv/bar/1 and a.elv/bar/2.

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

Index

• Variables
• type Interaction
  • func (i Interaction) PromptAndCode() string
• type Session
  • func ParseSessionsInBlock(namePrefix string, r io.Reader) ([]Session, error)
  • func ParseSessionsInFS(fsys fs.FS) ([]Session, 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
	Output string
}

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 Session

type Session struct {
	Name         string
	Directives   []string
	Interactions []Interaction
}

Session represents a REPL session.

func ParseSessionsInBlock

func ParseSessionsInBlock(namePrefix string, r io.Reader) ([]Session, error)

ParseSessionsInBlock splits one block of Elvish transcript (which could be a .elvts file or an elvish-transcript code block) into multiple sessions separated by headings.

func ParseSessionsInFS

func ParseSessionsInFS(fsys fs.FS) ([]Session, error)

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