The Bach Programming Language

$ bach -q '"Hello world!" out'
Hello world!

Welcome to Bach, an experimental compositional programming language. Bach is a tool that enhances your command-line superpowers and helps you write concise, readable, and safe one-liners for text processing and other tasks. This book serves as an introduction and reference.

Introduction

In this introductory chapter, you can read about why I created Bach, and about its general design: Why Bach?

Alternatively, you can jump straight into trying Bach out with the sections on Installation and First Steps.

Why Bach?

Bach is a general-purpose programming language designed in particular for writing “one-liners” for text processing on the command line. It is designed to have the following properties:

• Concise. One-liners are quick to type, there is not much boiler plate.
• Readable. Bach programs consist mostly of English words. Bach makes minimal use of special characters. You can read a Bach program and get an idea of what it does even without being familiar with the language.
• Flowing. Bach programs are evaluated from left to right, and can be read and understood thus.
• Orthogonal. Bach’s language elements are designed so that there is one – and preferably only one – obvious way to do any given task. This makes life easier for both writers and readers of Bach programs. When in doubt, orthogonality trumps conciseness.

A Bach program is a series of functions. They are just written next to each other with spaces in between. Each function’s output is the next function’s input. In technical terms, a Bach program is a composition of its component functions. Schematically, this Bach program

f g h

corresponds to this expression in a traditional applicative programming language,

h(g(f))

and to this Unix pipeline:

f | g | h

In Bach, the concept of function composition is so central that there is no operator for it (like | in Unix shells or . in Haskell). It’s just what you get when you put two or more functions next to each other.

Installation

Unix-like systems

To install (or upgrade) Bach, install Go first. Then run:

go install github.com/texttheater/bach@latest

This will place the bach executable in $GOROOT/bin, thus in $HOME/go/bin by default. You may want to place it on your $PATH.

Windows

TBD

First Steps

The CLI

Call Bach and pass a Bach program to it as an argument on the command line. In our first example, our program consists of the string "Hello world!". Bach string literals use double quotes, so surround your program with single quotes.

$ bach '"Hello world!"'
"Hello world!"

Our program creates the string "Hello world!", and Bach shows this result to us, formatted as a string literal. If we want to print the message without the quotes, we can compose our pogram with the function out to print it out:

$ bach '"Hello world!" out'
Hello world!
"Hello world!"

out returns its input value unchanged, so we are still shown the string with the quotes at the end. To suppress this, we can call Bach with the -q flag:

$ bach -q '"Hello world!" out'
Hello world!

The REPL

Let us now use Bach in interactive mode by using its read-eval-print loop (REPL). To start it, we call Bach without an argument. Now we are shown the Bach prompt:

$ bach
bach>

Let us again create the string "Hello world!":

bach> "Hello world!"
"Hello world!"

Now let us compose this program with the function codePoints, which gives us the list of Unicode code points in the string:

bach> "Hello world!" codePoints
[72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33]

Let us add another function, len, to compute the length of the string (in terms of code points):

bach> "Hello world!" codePoints len
12

As a final example in this introduction, let us add 1 and 2:

bach> 1 +(2)
3

Bach does not have infix operators. + is just a function that takes an input value (1) and an argument (2). Arguments are given in parentheses. However, for the mathematical operators, you can leave the parentheses out. Note however, that you can't have a space between the + and the 2:

bach> 1 +2
3

To exit the REPL, press Ctrl+D.

Types

Bach has null, boolean, number, string, array, object, and union types. Additionally, there is the Void type (there are no values of this type) and the Any type (all values are of this type). If you are wondering what the output type of your program is, you can always compose it with the type function, and you will get a string representation of the output type.

The following table demonstrates this: in the Program column, there are a number of Bach programs, each consisting of some expression followed by the type function. The Type column indicates the output type of the whole program. Here, it’s always Str because that is the output type of type. Finally, the Value column contains the strings representing the types of the various expressions.

Simple Types

The simple types in Bach are Null, Bool, Num, and Str. The following table shows some examples of programs that evaluate to a value of each type.

The Null type has a single value, null.

The are two Bool values: true and false.

Num values are IEEE754 double-precision floating-point numbers.

Str values are sequences of bytes.

Array Types

The type of an array is written as Arr< … >. Between the angle brackets, the types of the array's elements are listed. If the last element type is followed by an ellipsis, this means that the length of the array is unknown and that there can be 0, 1, or more elements of this type here. Array functions such as each(...) usually return arrays with an unknown number of elements.

Object Types

An object is a unique mapping from strings (“properties”) to values. The most general object type is Obj<Any>. A more restrictive type can be specified for all values, e.g., Obj<Str>. If specific properties and their types are known, this can be part of the type too, e.g.: Obj<a: Num, b: Num, Str>. The type at the end then describes all other values.

Union Types

A union type indicates that a value could be of any of two or more types.

Expressions

In Bach, every expression denotes a function. For example:

• 2 denotes a function that takes any input, ignores it, and returns the number 2.
• join(",") denotes a function that takes a list of strings and concatenates them, using the comma as a separator.
• +(2) denotes a function that takes a number as input, adds 2 to it, and returns the result.
• +2 is the same, with syntactic sugar applied.
• if %3 ==0 then "multiple of 3" else "not a multiple of 3" ok denotes a function that takes a number and returns different strings depending on whether the number is divisible by 3.
• +2 *3 denotes a composition of two functions, which is, again, a function (one that takes a number, adds 2 to it, then multiplies the result by 3).

This chapter describes the different kinds of expressions in more detail.

Literal Expressions

Num Literals

Nonnegative real numbers can be written in the decimal system: as integers, with a decimal point, or in exponential notation.

There are no literals for negative, infinity, or NaN values. But they can be created using the builtin -, inf, and nan funcers. For details, see Math Funcers.

Str Literals

Strings are sequences of bytes. String literals are delimited by double quotes. Characters inside generally represent the byte sequence that is their UTF-8 encoding. For example:

• a represents the byte sequence 61 (hexadecimal notation; UTF-8 encoding of Latin Small Letter A)
• ~ represents the byte sequence 7E (UTF-8 encoding of Tilde)
• abc represents the byte sequence 61 62 63
• 日本語 represents the byte sequence E6 97 A5 E6 9C AC E8 AA 9E

There are, however, the following exceptions:

• \a represents the byte sequence 07 (UTF-8 encoding of Bell character)
• \b represents the byte sequence 08 (UTF-8 encoding of Backspace)
• \f represents the byte sequence 0C (UTF-8 encoding of Form feed)
• \n represents the byte sequence 0A (UTF-8 encoding of Line feed)
• \r represents the byte sequence 0D (UTF-8 encoding of Carriage return)
• \t represents the byte sequence 09 (UTF-8 encoding of Horizontal tab)
• \v represents the byte sequence 09 (UTF-8 encoding of Vertical tab)
• \\ represents the byte sequence 5C (UTF-8 encoding of Backslash)
• \" represents the byte sequence 22 (UTF-8 encoding of Quotation mark)
• \ followed by three octal digits in the range from 000 to 3ff (inclusive) represents the corresponding byte
• \x followed by two hexadecimal digits represents the corresponding byte
• \u followed by four hexadecimal digits represents the UTF-8 encoding of the corresponding code point, if defined
• \U followed by eight hexadecimal digits represents the UTF-8 encoding of the corresponding code point, if defined
• {{ represents the byte sequence 7B (UTF-8 encoding of Left curly bracket)
• }} represents the byte sequence 7D (UTF-8 encoding of Right curly bracket)
• {, followed by a Bach expression, followed by }, represents the UTF-8 encoding of what the expression evaluates to
• Other uses of \, ", {, or } inside the delimiting quotes are invalid, as is the line feed character

Arr Literals

Array literals are delimited by square brackets. Inside, a comma-separated sequence of Bach expressions represents the elements. An expression representing an array can be appended as a suffix using a semicolon.

Obj Literals

Obj literals are delimited by curly braces. Inside, each elements consists of a key, followed by a colon, followed by a value. Elements are separated by commas. The order of elements does not matter. Keys are always strings, but they can be written as identifiers or number literals; they are converted to strings automatically.

Funcer Call Expressions

Every Bach expression denotes a function that maps the input to the output. Funcers are generalizations of functions: in addition to the input, they can have arguments on which their output depends. But there are also 0-argument funcers. A number of funcers are built-in to Bach (see Builtin Funcer Reference), and you can define your own (see Funcer Definition Expressions). Arguments go between parentheses. No space is allowed between the funcer name and the opening parenthesis. For example, len returns the length of an array, join joins a list of strings with a given glue string, and +(1) adds 1 to a number.

Syntactic Sugar

To make arithmetic expressions etc. less noisy, when calling the funcers +, -, *, /, %, <, >, ==, <=, >=, ** with one argument that is a single literal or funcer call, the parentheses can be omitted. Note that there are no operator precedence rules in Bach – evaluation is from left to right. To change precedence, put arguments in parentheses by not omitting the parentheses.

With a single argument that is a string, regexp, array, or object literal, parentheses may also be omitted.

Overloading

Funcers are selected according to the input type, the name, and the number of arguments. For example, there are two builtin 1-arg funcers named +: one for Num inputs (which expects the first argument to evaluate to a Num and returns the sum) and one for Str inputs (which expectes the first argument to evaluate to a Str and returns the concatenation).

Partial Application

In most cases, funcers are defined so that their argument can be any type of expression as long as it has the right input and output type. But it is also possible for funcer parameters to require a partially applied funcer call with n remaining arguments to be filled in by the funcer. To call a funcer with m+n arguments to fill a parameter that requires n open arguments, pass only the first m arguments. As an example with m=0 and n=1, the builtin funcer sort takes a comparison funcer with an open argument as its sole argument. Here, we use the number comparison funcer >:

Funcer Definition Expressions

To define a funcer, use a funcer definition expression. It has the form for I def N(P1, P2, ..., Pn) O as B ok, where I is the funcer’s input type, N is its name (must start with a lower-case letter), P1, P2, ..., Pn are n or more parameters (if n=0, leave out the parentheses), O is the funcer’s output type, and B is its body. When called, the funcer will evaluate like B, with parameters bound to the arguments passed at call time.

Here are some examples of defining and then calling funcers without parameters:

Parameters

In addition to the input, funcers can take arguments, which are functions that can be called in the funcer body to use their outputs. Parameters specify what kind of arguments are expected. In the simplest case, a parameter is simply a name and a type. This means that inside the funcer body, the given function can be called with any input, by the given name, and will return a value of the given type.

Parameters with Parameters

In more complex cases, parameters can restrict arguments to be partially applied funcer calls. In such cases, the syntax for a parameter is for I N(P1, P2, ..., Pn) O. This means that inside the funcer body, for inputs of type I, the given funcer will be available to call by the name N with arguments as specified by the parameters P1, P2, ..., Pn (as before, drop the parentheses if n=0) and will return a value of type O. Here, P1, P2, ..., Pn do not contain names.

Type Variables

Funcer definition expressions can use type variables. They are written between angle brackets and start with an upper-case letter. When applying a funcer to an input expression, type variables are bound from left to right.

Type Variables with Bounds

Type variables can be given upper bounds, they are then constrained to match subtypes of the given upper bound type.

Overloading, Revisited

Funcers are looked up by input type, name, and number of parameters. So you can, for example, define two funcers with the same name but different input types, and use both:

Funcers cannot be overloaded with respect to the parameters themselves. Thus, calling a funcer on the wrong input or with the wrong number of arguments results in a NoSuchFuncer error. Calling it with the wrong kinds of arguments, by contrast, leads to an ArgHasWrongOutputType error.

Variable Capturing

Funcers have access to the variables defined before, but not after the definition.

Recursion

TBD

Assignment Expressions

An assignment expressions consists of the character = immediately followed by a pattern. It binds the names in the pattern to the corresponding parts of its input value so you can reuse them later in the program. A pattern can be a name, an array literal where the elements are patterns, or an object literal where the values are patterns.

An “impossible match” error occurs if the pattern cannot match any values of the input type, e.g., if an array pattern has a different length from the input, or matching objects with array patterns, or vice versa, or if an object pattern contains keys that the input doesn’t.

A “nonexhaustive match” error occurs if the pattern can match some but not all values of the input type, e.g., if a variable-length array type is matched as fixed-length, or if an object type is matched against a key it might or might not contain.

Conditional Expressions

Conditional expressions come in three flavors:

• if A then B else C ok (checks a boolean condition A)
• is A then B else C ok (matches the input against the pattern A)
• is A with D then B else C ok (matches the input against the pattern A and checks the boolean condition D)

A pattern can be a name, a type optionally combined with a name, an array literal where the elements are patterns, or an object literal where the values are patterns.

To check for additional alternative conditions, add alternative clauses before the final else clause. Alternative clauses, too, come in three flavors. All can be freely combined:

• elis A then B (checks a boolean condition A)
• elis A then B (matches the input against the pattern A)
• elis A with D then B (matches the input against the pattern A and checks the boolean condition D)

Names bound by a pattern can be used inside the following then clause.

Predicate Expressions

In Bach, a predicate is a function that for a given input I returns either {yes: I} or {no: I}. This is often useful, e.g., for checking the members of an array for some condition. Thus, several builtin array funcers accept them as arguments.

Bach provides a special syntax for making such conditions easy to write. A predicate expression is like a conditional expression, except it consists only of the first part, that is, the if ... clause, or the is ... clause, or the is ... with ... clause. The then {yes: id} else {no: id} part is filled in automatically.

Getter Expressions

A getter expressions consists of the @ character followed by an object property name or an array index. It retrieves the value of the property or the element at the index for an input object or array. The input type must guarantee the existence of the property/index, otherwise a type error is raised. If the input type cannot guarantee the existence of the property/index, use the get funcer for objects or for arrays.

Regexp Expressions

In Bach, a regexp is a function that takes a Str and returns either null or an object with at least a property start with type Num, and 0 with type Str.

Regexp expressions denote such functions. They have the syntax of re2 regular expressions, except for \C, delimited by ~. They search the input string for a substring that matches the regular expression. If none can be found, null is returned. Otherwise, an object is returned with start indicating the offset (in codepoints) of the first occurrence, and 0 containing the matched substring. If the regexp contains capturing groups, the substrings matched by the groups are included as additional properties – by group number and, in the case of named groups, additionally by name.

Regexp expressions can be used with regexp funcers for greater effect.

Composition Expressions

A composition expression consists of two other expressions, separated by whitespace. The output of the first expression is then used as the input to the other. By adding another expression at the end, you again create a larger composition expression, and so on.

Note that when you compose with expressions that ignore their input, such as literals, only the last one has any effect on the output.

Builtin Funcer Reference

Null Funcers

null

Returns the null value.

Examples

I/O Funcers

blocks

Groups lines into blocks separated by empty lines.

Each empty line in the input marks the end of a block. Blocks can be empty. The empty lines themselves are not included.

Examples

err

Writes to STDERR.

Identity function with the side effect of writing a string representation of the value to STDERR, followed by a line break.

Examples

err

Writes to STDERR with a custom line end.

Identity function with the side effect of writing a string representation of the value to STDERR, followed by a the specified line end.

Examples

in

Reads from STDIN.

Examples

json

Reads JSON values from a stream

Examples

lines

Reads a stream line-by-line

Examples

out

Writes to STDOUT.

Identity function with the side effect of writing a string representation of the value to STDERR, followed by a line break.

Examples

out

Writes to STDOUT with a custom line end.

Identity function with the side effect of writing a string representation of the value to STDOUT, followed by a line break.

Examples

reader

Creates a Reader from a Str.

Examples

Logic Funcers

true

Returns the value representing logical truth.

Examples

false

Returns the value representing logical falsehood.

Examples

and

Computes logical conjunction.

Examples

or

Computes logical disjunction.

Examples

not

Computes logical negation.

Examples

==

Checks equality of boolean values.

Examples

Math Funcers

+

Adds two numbers.

Examples

-

Subtracts a number from another.

Examples

-

Returns the additive inverse of a number.

Examples

*

Multiplies two numbers.

Examples

/

Divides a number by another.

Examples

%

Remainder

Examples

<

Less than

Examples

>

Greater than

Examples

<=

Less than or equal to

Examples

>=

Greater than or equal to

Examples

sum

Computes the sum of several numbers.

Examples

median

Computes the median of several numbers.

Examples

mean

Computes the arithmetic mean (average) of several numbers.

Examples

inf

Returns infinity.

Examples

nan

Returns NaN.

Examples

isFinite

Checks whether a number is finite.

Examples

isNaN

Checks whether a number is NaN.

Examples

epsilon

Returns the floating point epsilon.

Examples

largestSafeInteger

Returns the largest safe integer.

Examples

largestNum

Returns the largest representable number.

Examples

smallestSafeInteger

Returns the smallest safe integer.

Examples

smallestPositiveNum

Returns the smallest representable positive number.

Examples

isInteger

Checks whether a number is integer.

Examples

isSafeInteger

Checks whether a number is a safe integer.

Examples

toBase

Converts an integer to a specified base.

Examples

toExponential

Converts a number to exponential notation.

Examples

toExponential

Converts a number to exponential notation.

Examples

toFixed

Converts a number to fixed-point notation.

Examples

e

Returns Euler's number.

Examples

ln2

Returns the natural logarithm of 2.

Examples

ln10

Returns the natural logarithm of 10.

Examples

log2e

Returns the base-2 logarithm of e

Examples

log10e

Returns the base-10 logarithm of e

Examples

pi

Returns pi.

Examples

sqrt1_2

Returns the square root of 1/2.

Examples

sqrt2

Returns the square root of 2.

Examples

abs

Computes the absolute value.

Examples

acos

Computes the inverse cosine.

Examples

acosh

Computes the inverse hyperbolic cosine.

Examples

asin

Computes the inverse sine.

Examples

asinh

Computes the inverse hyperbolic sine.

Examples

atan

Computes the inverse tangent.

Examples

atan2

Computes the angle in the plane.

Examples

atanh

Computes the inverse hyperbolic tangent.

Examples

cbrt

Computes the cube root.

Examples

ceil

Rounds a number up.

Examples

clz32

Count leading zeros.

Examples

cos

Computes the cosine.

Examples

cosh

Computes the hyperbolic cosine.

Examples

exp

Computes the exponential function.

Examples

expm1

Computes the exponential function, subtracted by one.

e (Euler's number) raised to the exponent, minus 1

Examples

floor

Rounds down.

Examples

fround

Rounds to 32-bit precision.

Examples

hypot

Computes the square root of the sum of squares

Examples

imul

32-bit multiplication

Examples

log

Computes the natural logarithm.

Examples

log10

Computes the base 10 logarithm.

Examples

log1p

Computes the natural logarithm of x + 1.

the natural (base e) logarithm of (x + 1)

Examples

log2

Computes the base 2 logarithm.

Examples

max

Finds the largest number

Examples

min

Finds the smallest number

Examples

**

Computes powers (exponentiation).

Examples

random

Returns a random number between 0 and 1.

Examples

random

Returns a random integer number in a specified interval.

Examples

round

Rounds a number to the nearest integer.

Examples

sign

Determines the sign of a number.

Examples

sin

Computes the sine.

Examples

sinh

Computes the hyperbolic sine.

Examples

sqrt

Computes square roots.

Examples

tan

Computes the tangent.

Examples

tanh

Computes the hyperbolic tangent.

Examples

trunc

Rounds towards zero.

Examples

Text Funcers

<

Compares strings lexicographically.

Examples

>

Compares strings lexicographically.

Examples

<=

Compares strings lexicographically.

Examples

>=

Compares strings lexicographically.

Examples

+

Concatenates two strings.

Examples

bytes

Converts a string to bytes.

Examples

bytesToStr

Converts bytes to a string.

Examples

codePoints

Converts a string to Unicode code points.

If the input string contains invalid UTF-8 byte sequences, they will be represented by the Unicode replacement character (code point 65533).

Examples

codePointsToStr

Converts Unicode code points to a string.

Examples

fields

Splits a string around whitespace.