1. Hello world¶
HQL is a statically typed expression and query language. You use it to read
data, transform it and write it out: records from a JSON file, rows of a
table, events from a stream, the notes in a folder of Markdown documents.
Where a shell pipeline would combine jq, grep and a script, an HQL program
is one expression that hql checks and runs.
Most of the data a query language handles was written by someone else, and
its shape is not guaranteed. HQL deals with this through types. Every value
has a type, and a type is a contract: it states what the value must look
like. hql checks a program against these contracts before running it, and
checks data against them when the data is read. A mistake in the program is
reported before anything runs. A mistake in the data is reported where the
data comes in, not three steps later.
A program goes through the same stages every time:
Hello, world¶
The smallest program that says hello is the text itself:
"Hello, world!"
"Hello, world!"
A program is an expression, and hql writes its value. A string prints
in quotes, the way it is written in a program. fmt builds a string from a
template, filling each {} with the next argument:
fmt("Hello, {}!", "world")
"Hello, world!"
Running a program¶
hql eval runs a program given on the command line:
$ hql eval 'fmt("Hello, {}!", "world")'
"Hello, world!"
hql run runs a program from a file. A file holds the same thing an
argument does:
$ cat hello.hql
title = "Dune"
pages = 412
fmt("{} has {} pages", title, pages)
$ hql run hello.hql
"Dune has 412 pages"
hql repl reads one program at a time and prints each value, which is
useful for trying things out. Chapter 2 starts there.
This book shows each program in a block, followed by what hql writes for
it. Most programs run against a small example vault, a reading club of books
and authors in
examples/reading-club/.
To follow along, clone the repository and pass the vault to hql:
$ hql --vault examples/reading-club eval 'cards | size'
15
Values and pipelines¶
Every value has a type. 412 is an Int, "Dune" is a String, and
[412, 280, 310] is a List<Int>. Operators and functions combine values
into new ones:
412 / 100
4
Both operands are Int, so / divides whole numbers and drops the
remainder.
Most HQL programs are pipelines. | passes the value on its left to the
step on its right, and each step returns a new value for the next one:
[412, 280, 310] | filter(n => n > 300) | size
2
filter keeps the elements for which a function returns true. Here the
function is n => n > 300, a lambda: a function written in place, with
its parameter before => and its result after it. size counts what is
left. Chapter 3 covers the steps, and
chapter 4 covers functions.
Bindings¶
name = expression binds a value to a name. The name can be used in the
statements after it, and the value of the program is its last expression:
pages = 280
chapters = 24
pages / chapters
11
A binding can state its type. The checker then rejects a value of any other type:
rating : Int = "five"
rating
check error[type-mismatch]: `rating` is declared Int but its value is String
--> <expression>:1:16
|
1 | rating : Int = "five"
| ^^^^^^
Without the declaration, the checker infers the type from the value. A declaration is useful where you want the program to state its intent, and for values whose type cannot be inferred, such as an empty list.
Checked before it runs¶
hql checks the whole program before it evaluates any of it. A check
error names the problem and points at the expression:
1 + "two"
check error[type-mismatch]: addition requires two Int, two Float or two Decimal operands
--> <expression>:1:5
|
1 | 1 + "two"
| ^^^^^
Nothing was evaluated. There is no value, only the report, and hql exits
with status 1. A name that was never bound is a check error too:
pages + 1
check error[unknown-name]: `pages` is not bound
--> <expression>:1:1
|
1 | pages + 1
| ^^^^^
hql check runs only the checker. It prints the type of the program and
evaluates nothing:
$ hql check - <<< '412 / 100'
Int
Errors while it runs¶
Some problems depend on values, and the checker cannot see values. Dividing by zero passes the check and fails when the program runs:
pages = 412
pages / 0
execute failure[division-by-zero]: division by zero
--> <expression>:2:1
|
2 | pages / 0
| ^^^^^^^^^
The report starts with the phase in which the problem was found: check
before the program runs, execute while it runs. Data that does not match
its type is also found in the execute phase, when the data is read.
Chapter 2 shows how, and chapter 12 covers
errors in full.
Choosing a value¶
a given condition otherwise b is a when the condition is true, and b
when it is false:
pages = 412
"long" given pages > 300 otherwise "short"
"long"
It is an expression, so it has a value and a type. Both branches must have the same type.
match compares a value with a list of patterns in order. The first pattern
that fits gives the result:
status = "reading"
match status {
"done" => "finished",
"reading" => "on the nightstand",
_ => "on the shelf",
}
"on the nightstand"
_ fits any value. A match must cover every possible value, and the
checker rejects one that does not:
match 3 { 1 => "one", 2 => "two" }
check error[non-exhaustive-match]: this match does not cover every Int: add a `_` arm
--> <expression>:1:1
|
1 | match 3 { 1 => "one", 2 => "two" }
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
What is next¶
Chapter 2 covers types as contracts, and the types values
are built from: numbers, text, dates and times, and Data, the tree that
JSON and YAML documents are read into.