linebased

Overview ¶

Package linebased parses line-based scripts and provides template expansion.

A linebased script is a sequence of expressions. Each expression has a command name (the first word) and a body (everything that follows). No quotes, no escaping. The simplicity is the point: what you write is what you get.

echo hello world
set path /usr/local/bin

Multi-line bodies use tab-indented continuation lines:

sql query users
	SELECT id, name
	FROM users
	WHERE active = true

Templates let you define reusable expressions with parameters:

define greet name
	echo Hello, $name!
greet Alice
greet Bob

And includes let you compose scripts from multiple files:

include common.lb

Syntax ¶

The grammar in EBNF:

script       = { expression } .
expression   = { comment } ( command | blankline ) .
comment      = "#" text newline .
command      = name [ whitespace text ] newline { continuation } .
continuation = tab text newline .
blankline    = newline .
name         = nonwhitespace { nonwhitespace } .
whitespace   = " " | tab .
nonwhitespace = (* any character except space, tab, newline *) .
text         = (* any characters except newline *) .
tab          = "\t" .
newline      = "\n" .

A command line begins with a name (one or more non-whitespace characters). Everything after the name through the newline becomes part of the body. Continuation lines must start with exactly one tab, which is stripped. Lines starting with space are syntax errors.

Comments ¶

Lines starting with # are comments. They attach to the following expression and are available in the Comment field of Expanded:

# Set the greeting message.
# This supports multiple lines.
echo Hello, World!

Comments inside template bodies work the same way.

Templates ¶

Define templates with the "define" builtin. The first line names the template and lists parameters. Continuation lines form the template body:

define greet name
	echo Hello, $name!

Invoke templates by name. Arguments are split by whitespace, with the final argument consuming remaining text:

greet Alice           # echo Hello, Alice!
greet "Bob Smith"     # echo Hello, "Bob Smith"!   (quotes are literal)

Parameter references use $name or ${name}. The braced form allows adjacent text:

define shout word
	echo ${word}!!!

Templates can invoke other templates:

define inner x
	echo $x
define outer y
	inner $y
outer hello           # echo hello

Constraints:

• Recursion is forbidden.
• Templates cannot be redefined.
• Expanded templates cannot contain "define".

Includes ¶

The "include" builtin reads another file and processes it inline:

include helpers
include common

Include paths must be simple filenames without directory separators. The ".linebased" extension is added automatically, so "include helpers" opens "helpers.linebased" from the fs.FS passed to NewExpandingDecoder.

Included files can define templates used by the including file. Include cycles are detected and reported as errors.

Blank Lines ¶

Blank lines produce expressions with empty names. This preserves the visual structure of the source:

echo first

echo second

The blank line between commands appears in the expression stream. Like commands, blank lines can have preceding comments.

Unknown Commands ¶

Commands that are not templates pass through unchanged. This allows scripts to define their own command vocabulary:

define echo tail
echo hello           # your code interprets "echo"
custom arg1 arg2     # your code interprets "custom"

Error Handling ¶

Errors during parsing or expansion are reported as ExpressionError with location information:

for expr, err := range linebased.Expand("script.lb", fsys) {
	if err != nil {
		log.Fatal(err)  // includes file:line
	}
	// process expr
}