Files and Standard Endpoints¶
An endpoint states where bytes are. Constructing one performs no I/O: it opens, stats and resolves nothing, and prints as it was written:
file("examples/io/sightings.jsonl")
file("examples/io/sightings.jsonl")
Four endpoints are bound by the host, as vault is, and need no
configuration: stdin, stdout, stderr and file(path).
What an endpoint can do is its type¶
An endpoint's capabilities are its supertypes. A Readable endpoint is read
by source and tap, a Writable one is written by target and sink, and
a Replayable endpoint is a Readable one that gives the same bytes on every
read within one evaluation. Stdin is Readable, Stdout and Stderr are
Writable, and File is Replayable and Writable. Reading an endpoint
that is not readable is a type error, reported before the program runs:
source(stdout, Json)
check error[type-mismatch]: `source` needs (Readable | String), not Stdout
--> <expression>:1:1
|
1 | source(stdout, Json)
| ^^^^^^^^^^^^^^^^^^^^
The String in the diagnostic is the other form of source, a configured
endpoint named by its id (endpoints by id).
A file and its end¶
file(p) is the whole file. file(p).end is a second endpoint, the end of the
same file: Readable and Writable, and not Replayable, since what comes
after the end is not there yet. Which endpoint a step names decides what the
step does, so a file has no open mode:
file(p) |
file(p).end |
|
|---|---|---|
source |
every document in the file, as a Seq |
a type error naming tap |
tap |
the documents one at a time, then it ends | the documents appended from now on, as tail -f gives them |
target, sink |
replace the file | append to the file |
source(file("app.log").end, Lines)
check error[type-mismatch]: the end of a file holds nothing yet; follow what is appended there with `tap`
--> <expression>:1:8
|
1 | source(file("app.log").end, Lines)
| ^^^^^^^^^^^^^^^^^^^
Where a relative path resolves¶
A relative path resolves against the source directory of the unit that
names it: the document for hql render, the program file for hql run, the
module's own directory for a function of a module, and the working directory
for hql eval and the REPL, which have no file. A document, program or
module reads the same file wherever it is run from or called from. The
programs in this chapter run from the repository root, so
examples/io/sightings.jsonl is the file in the
I/O examples.
The working directory, the directory hql was started in, resolves no
path in HQL source. io.fs reads both, as Path values a program composes
paths from explicitly:
import io.fs
fs.source_dir().join("data/users.csv") // beside this file
fs.working_dir().join("out.csv") // where hql was started
A path with a scheme is a type error naming the network endpoint, since a URL is not a file:
file("https://example.com/x.json")
check error[type-mismatch]: "https://example.com/x.json" is a URL, not a file; a network resource is read with `http`
--> <expression>:1:1
|
1 | file("https://example.com/x.json")
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The network adds http, websocket and tcp with
import net, and a channel is an endpoint of values rather
than bytes.