conventions at compile time
a framework saves you typing by agreeing on names. in rails, a controller method called show in PostsController answers GET /posts/:id, and a model called Post reads the posts table. the app writes very little, and the framework fills in the rest by rule.
rails applies those rules while the program runs, by looking at its own classes and methods. a broken convention says nothing until a request reaches it. a misspelled action is a 404, and a view that reads post.titel fails the first time someone opens the page.
kanso applies a convention while the program compiles. a library writes it as an ordinary function, called a derivation, which the compiler runs during the build. the derivation is handed a description of the program and answers a list of declarations: constants, record types, source to add to a module, and compile errors. the compiler adds what it answered to the program before anything is checked, so a convention's output is checked like code you typed, and a mistake it finds is a compile error at the line that made it.
this chapter builds a small derivation from nothing, sets out what a derivation is handed and what it may answer, and then reads senro, kanso's web framework, whose conventions are all derivations.
a convention is a function
a command-line program usually keeps a table from each command's name to the code that runs it, and the table drifts from the code. here the table is derived. every public function in a module called commands is a command, named for the function and handed the words that follow its name. the derivation lives in a library of its own:
import "std/derive"
import "std/list"
import "std/text"
# Every pub function in the app's `commands` module is a command, named for
# the function and handed the words that follow its name.
pub fn commands p
found = list/to_list (list/select p.modules (m -> m.name == "commands"))
return [(derive/declare "commands" "commands" {})] if length found == 0
m = found[1]
table = list/fold m.functions {} (acc f -> put acc f.name f.reference)
names = list/sort (list/to_list (list/map m.functions (f -> f.name)))
usage = "commands: {text/join names ", "}"
declared = [
(derive/declare "commands" "commands" table)
(derive/declare "commands" "usage" usage)
]
odd = list/to_list (list/select m.functions (f -> length f.params != 1))
list/concat declared (list/to_list (list/map odd refused))
fn refused f
said = "a command takes one parameter, the words after its name"
derive/refuse "commands/{f.name}" said
# Runs a command looked up in the table, or says there is none.
pub fn run none _
"no such command"
pub fn run command words
command words
commands receives the program, p. it finds the module named commands, folds that module's functions into a map from each name to the function itself, and builds a usage line from the sorted names. derive/declare turns each into a constant. a function whose parameter count is wrong is refused, which the section on refusing comes back to. run is ordinary code for the entry to call.
the app writes its commands as plain functions, with no table anywhere:
import "std/text"
pub fn greet words
"hello, {text/join words " "}"
pub fn count words
"{length words} words"
the entry asks for the derivation with a derive line after its imports, and then uses the two constants it declared, commands and usage, as if it had written them:
import "../registry"
import "./commands"
derive registry/commands
print usage
.> (_ -> print (registry/run commands["greet"] ["Ada" "Lovelace"]))
.> (_ -> print (registry/run commands["count"] ["one" "two" "three"]))
.> (_ -> print (registry/run commands["grete"] []))
commands: count, greet
hello, Ada Lovelace
3 words
no such command
adding a command means writing a function. kanso derived commands prints what the derivation wrote, the map and the usage line, each with the name of the derivation that wrote it, so the table is always there to read even though nobody keeps it.
what a derivation is handed
the program a derivation receives lists the entry first, under its file's name, and then every module the entry imports by a ./ path. a library reached through ../, such as registry here, belongs to something else and is left out. the entry holds only statements, so it carries only its calls. for each module the description holds:
- functions: each public function's name, its parameters with their annotations (
id:intgives the annotation"int", an unannotated parameter""), and a reference to the function, which a declared table can hold and call. - constants: each public constant, evaluated. a constant built from calls arrives as the value those calls return.
- records: each record type with its fields.
- calls: every call the module's functions and constants make to a named function, in the order they are written. each carries the function that makes it, the function it calls, the name of every argument that is a name, the text of every argument that is a string written whole, and the line and column of the call.
- files: the text of each file in the module's directory that is not kanso source, such as a template. a directory that holds such files and no kanso source is still a module, and its functions are the ones a derivation writes.
- sources: which file declares each function and constant, for a convention that orders things by file name.
the program also carries the text files beside the entry, such as a schema.sql an app checks in. what it never carries is a function's body. a derivation sees a function's name, its shape and the calls it makes, which is enough to check how the function is used and not enough to depend on how it is written.
what a derivation answers
a derivation answers a list of declarations, each built by one of five functions in std/derive:
derive/declare origin name valuemakes a constant in the entry. the value is data: ints, strings, bools, lists, maps, records and function references.derive/declare_type origin name fieldsmakes a record type in the entry.derive/define origin sourceadds source text to the moduleoriginnames, compiled as one more of that module's files. the module checks it as code someone wrote there, so a record type defined this way is one the module's own functions can build and read. a module's files share their declarations but not their imports, so a definition that calls another module opens with theimportlines it needs, written from the derivation's own module as that module's imports are.derive/refuse origin messagemakes a compile error at the function, constant or typeoriginnames.derive/refuse_call call messagemakes a compile error at one of the calls the description listed.
the first three add to the program and the last two stop it. a derivation cannot remove or edit anything an author wrote.
derived source can say where each part of it came from. a comment of the form # from signed.kata:4, naming a file in the module and a line, marks what follows it. a compile error in derived source then quotes the derived line and adds = written from views/signed.kata:4, from the nearest such comment above it in the same definition, so the author is sent to the file they wrote.
refusing what does not fit
a convention that skips what it cannot place leaves the author's mistake in the program. the registry refuses a command with the wrong number of parameters, so a command written with a second parameter does not compile:
import "std/text"
pub fn greet words
"hello, {text/join words " "}"
pub fn count words
"{length words} words"
pub fn shout words loud
if loud (text/uppercase (text/join words " ")) (text/join words " ")
error[derive]: a command takes one parameter, the words after its name
--> shouty/commands.kso:9:8
9 | pub fn shout words loud
^
the error points at shout, in the app's file, because the refusal named commands/shout as its origin. the author reads it where they wrote the function, with no mention of the registry's code.
the rules a derivation runs under
a derivation only computes. it runs on the interpreter during the build, it cannot read a file, the clock or the network, and it learns about the app only from the description it is handed. a derivation that imports one of the modules it describes is refused. so the same source derives the same declarations every time, on every engine: a native build, an interpreted run and the compile in the playground all check the same derived code, and the rule that every engine behaves the same holds without extra work.
what a derivation does inside is unrestricted. senro pluralizes model names, parses rate limits and compiles templates in its derivations. what comes out is a finite list of declarations, and that list is printed by kanso derived and checked by the compiler. the work costs compile time like any other code, and the compile corpus behind the entry_instructions golden derives, so that cost is measured on every change.
senro, a case study
senro is a web framework in the shape of rails. it has no routes file and no schema file, and its templates become kanso functions. all of that is derivations: an app writes one line, derive app/conventions, and that runs five of them, kata/views, models/tables, routes/rest, jobs/performers and data/providers. this section reads the first four. the excerpts below are senro's own code at the release this site pins, and the site's checks hold them to it.
routes from module and function names
routes/rest reads each module of the app as a resource and each public function as one of the seven rest actions: index answers GET /posts, show answers GET /posts/:id, and so on. it builds the route table from the module's name, each function's name and each parameter: an action that takes note_id before id nests under /notes/:note_id, and an id:int annotation says the id is a number. the table is one constant, declared with derive/declare, and each row holds a reference to its action, so the server calls actions straight from it.
a public function that is not one of the seven would be a dead route, and the derivation refuses it at the function:
fn refused m f
actions = "index, new, create, show, edit, update or destroy"
said = "`{f.name}` is not an action: name it {actions}"
derive/refuse "{m.name}/{f.name}" said
links checked where they are written
an app builds a link with routes/path_to "notes/show" id. the route's name is a string written whole, so the description carries it among the module's calls, and the derivation checks each one against the table it just built:
fn links_of m placed
links = list/select m.calls (c -> c.callee == "routes/path_to")
list/fold links [] (acc c -> list/concat acc (named c c.strings[1] placed))
a link to a route that does not exist, or one that leaves out an id its route takes, is refused with derive/refuse_call at the line that wrote it.
the same reading of calls is how an app keeps an old URL. its legacy_route_aliases constant is a list of calls, (routes/moved "/signbook" entries/index), and moved itself does almost nothing:
pub fn moved path action
old_path path action
the work is in the derivation, which finds each call to routes/moved among the constant's calls and reads its path and the name of its action. because the action is written as code, the compiler resolves it as it resolves any name, so a misspelled action is an unknown name, and the alias takes its method from the action's route.
a schema from the migrations, records from the tables
an app's migrations are constants whose values are lists of changes, such as models/create_table "pages" [...]. constants arrive evaluated, so models/tables receives them as data, folds them in the order of their file names, which the description's sources give, and has the schema. for each model module, such as page.kso for the pages table, it writes the record type from the table's columns and adds it to that module:
fn typed_in m schema
return [] if wrote_model? m schema
fields = column_names schema[names/plural m.name]
lines = list/to_list (list/map fields (f -> " {f}"))
source = "pub type {m.name}\n{text/join lines "\n"}\n"
[(derive/define m.name source)]
the module's own functions then read p.body and p.note_id as fields of a record nobody typed, and the checker holds them to it: a field the table lacks is an error at the line that reads it. a module that declares its record itself keeps its own, and the derivation checks that record's fields against the columns instead.
templates that are functions
a module's directory can hold .kata templates, which arrive in the description's files. kata/views compiles each one into a function of that module with derive/define:
pub fn views p
list/fold p.modules [] (acc m -> list/concat acc (templated p m))
so views/signed.kata is called as views/signed, and nothing is written to disk beside it. the compiled source marks each part with the template line it came from, so a misspelled field in a template is a compile error that quotes the derived line and adds = written from ./views/list.kata:5.
jobs named by their module
a module named tidy_job with a perform function is the job tidy, and jobs/performers declares the table the worker dispatches from. an app queues a job by its name, jobs/perform_later db "tidy" args, and the derivation reads every such call:
fn unnamed m names
calls = list/to_list (list/select m.calls (c -> asks? c.callee))
list/fold calls [] (acc c -> list/concat acc (stray c c.strings[2] names))
fn asks? callee
callee == "jobs/perform_later" or callee == "jobs/perform_at"
fn stray _ none _
[]
fn stray _ "" _
[]
fn stray c name names
return [] if list/any? names (n -> n == name)
[(derive/refuse_call c "`{name}` names no job")]
a job name with no module behind it is refused at the call that queues it, before the app has run at all.
what the four have in common
each of the four reads names and shapes the app already has, declares what the app would otherwise keep by hand, and refuses at the author's own line whatever does not fit. none of them needed a change to the compiler. the compiler gained the description and the five declarations once, and each of senro's conventions is a function in senro.
its relatives
other languages run code at compile time too, and the comparison shows what kanso chose. haskell's deriving writes a class instance from one type's shape, and template haskell runs haskell during compilation to produce syntax. rust's #[derive] and procedural macros take one item's tokens and answer tokens. f#'s type providers make types from an outside schema, such as a database's. zig runs ordinary code at compile time with comptime.
a kanso derivation is handed a description of the whole program, and it answers declarations. it can add to the program and refuse parts of it, and it cannot change anything an author wrote. it sees each function's calls and none of its body. every error it raises lands on a line the author wrote. those limits are why a framework's conventions can be checked like the rest of the program.
what you can do now
you can write a convention as a function that reads the program's description and answers constants, record types, definitions and refusals. you can find what an app's functions, constants and calls say about it, refuse what does not fit at the author's own line, and print what a convention wrote with kanso derived. and you can read senro's routes, schema, templates and jobs as four uses of the same mechanism.
exercises
- give the registry a
helpcommand of its own that printsusage, and decide whether the derivation should refuse an app that also writes a function calledhelp. - refuse a command whose name is not lowercase. which declaration does the refusal name as its origin, and where does the error point?
- write a derivation that reads every call to
flags/on?whose first argument is a string written whole, declares the list of flag names the code asks about, and refuses a name that is not in aflagsconstant the app keeps. - run
kanso derivedon senro's guestbook example and find the record typemodels/tableswrote forsignature. which migration put each of its fields there?