Skip to content

Latest commit

 

History

History
176 lines (117 loc) · 6.69 KB

README.md

File metadata and controls

176 lines (117 loc) · 6.69 KB

txt

Command txt is a templating language for shell programming.

Input

The input to the template comes from stdin. It is parsed in one of five ways.

The default is to split stdin into records and fields, using the -R and -F flags respectively, similar to awk(1), and dot is set to a list of records (see below). If header is set, dot is a list of maps with the specified names as keys.

If the -L flag is specified stdin is broken into records as with the default, but the fields are defined by the capture groups of the regular expression -L. Records that do not match -L are skipped. If -L contains named capture groups each record is a dictionary of only the named captures' values for that record. Otherwise, dot is a list of records (see below) of the capture groups' values. If header is set, dot is a list of maps with the specified names as keys, overriding any names from capture groups.

If the -csv flag is specified, stdin is treated as a CSV file, as recognized by the encoding/csv package. If the -header flag is not specified, the first record is used as the header. Dot is set to a list of maps, with the header for each column as the key.

If the -json flag is specified, stdin is treated as JSON. Dot is set as the decoded JSON.

If the -no-stdin flag is specified, stdin is not read. Dot is not set.

Records

When using -F or -L without a header, or in the case of -L without named capture groups, dot is a list of records.

Each record has two fields, Fields and Line. Line is the complete unaltered input of that record. Fields are the values of each field in that record. If dot is a record

{{.}}

is the same as

{{.Line}}

Records have a method F that takes an integer n and returns the nth field if it exists and the empty string otherwise. If n is negative it returns the (n-1)th field from the end.

If n is positive and the nth field exists, then

{{.F n}}

is equivalent to

{{index . n}}

Templates

The templating language is documented at http://golang.org/pkg/text/template with the single difference that if the first line at the top of the file begins with #! that line is skipped. If the -html flag is used, escaping functions are automatically added to all outputs based on context.

Any command line arguments after the flags are treated as filenames of templates. The templates are named after the basename of the respective filename. The first file listed is the main template, unless the -template flag specifies otherwise. If the -e flag is used to define an inline template, it is always the main template, and the -template flag is illegal.

Regular Expressions

All regular expressions are RE2 regular expression with the Perl syntax and semantics. The syntax is documented at http://golang.org/pkg/regexp/syntax/#hdr-Syntax

Functions

Built in functions are documented at http://golang.org/pkg/text/template#hdr-Functions

The following additional functions are defined:

slice what start stop
	slices what from start to stop.
	stop is optional. what must be a list or string.
	start or stop may be negative. If start or stop exceed the bounds
	of what, the largest slice of what that exists is returned.

nl string
	append a newline to the end of string, if it does not end in newline.

parseCSV headerspec filename
	headerspec is a comma-separated list of headers or "" to use the headers
	in filename.
	Dot is set to the contents of the CSV file as with -csv.
	If the file cannot be opened or its contents are malformed, execution
	stops.

parseJSON filename
	Read the JSON encoded file into dot or halt execution if decoding fails
	or the file cannot be opened.
	Dot is set to the contents of the JSON file as with -json.

parseLine header FS LP filename
	Read filename with line pattern splitting as specified by the RS and
	LP regular expressions, and an optional header header.
	If header is not "", the names in header will be used as the field names.
	If RS or LP are "", the respective value of -R or -L is used.

parse header RS FS filename
	Read filename with the default record and file splitting as specified
	by the RS and FS regular expressions, and optional header header.
	If header is not "", the names in header will be used as the field names.
	If RS or FS are "", the respective value of -R or -F is used.

read filename
	Read filename completely as a single string.
	Execution halts if the file cannot be read.

quoteCSV string
	Apply the appropriate CSV quoting rules to string.

toJSON what
	Encode what as JSON. Execution halts if
	http://golang.org/pkg/encoding/json/#Marshal errors.

equalFold string-one string-two
	Reports whether the UTF-8 encoded string-one and string-two are equal
	under Unicode case-folding.

fields string
	Split string around whitespace.

join separator strings
	Join the list in strings by the string separator.

lower string
	Lowercase string.

upper string
	Uppercase string.

title string
	Titlecase string.

trimCutset cutset string
	Return string with all leading and trailing runes in cutset removed.

trimLeft cutset string
	Return string with all leading runes in cutset removed.

trimRight cutset string
	Return string with all trailing runes in cutset removed.

trimPrefix prefix string
	Return string with prefix removed.

trimSuffix suffix string
	Return string with suffix removed.

trim string
	Return string with all leading and trailing whitespace removed.

quoteGo string
	Return string quoted as a Go string literal. Escapes non-printable
	runes. Should work for most languages that accept UTF-8 source.

quoteGoASCII string
	As quoteGo except any non-ASCII runes are escaped to hexcodes.
	Should work for most languages.

match pattern string
	Return whether string matches the regex in pattern.
	Execution halts if pattern is not a valid regular expression.

find pattern string
	Returns all substrings of string that match pattern.
	Execution halts if pattern is not a valid regular expression.

replace pattern spec string
	Replace all substrings in string matching pattern by spec.
	Execution halts if pattern is not a valid regular expression.

split pattern string
	Split string into a list of substrings separated by pattern.
	Execution halts if pattern is not a valid regular expression.

env key
	Returns the environment variable key or "".

exec name args*
	Execute command name with args. Stdin is nil.
	Stderr shares the stderr of txt(1).
	Stdout is returned as a string.

pipe name args* input
	Execute command name with args with input as stdin.
	Otherwise, like exec.

Automatically generated by autoreadme