Hello, library
writing a library of your own, and using it
Table of Contents
A library is an ordinary X_eTaL file. The names it exports start with
l:; a program imports it with u_se< and chooses the prefix those
names get. This document writes the smallest library there is, one
greeting, and uses it. Every block below is run by xetal through
ob-xetal, and its result recorded under it.
The library
userlibs/Hello.xtl, the whole file:
⍝│ Hello: the smallest library, one greeting. A library is an ordinary ⍝│ file whose exported names start with l:; libraries of your own live ⍝│ in userlibs/, on the search path. demos/hello-library.xtl imports it ⍝│ ("hi:" u_se< "Hello"), and docs/literate/hello.org walks through ⍝│ both. The name in the string is the logo: typed X_ e:T a:L, drawn, ⍝│ spaces removed (a string may hold any Unicode). ⍝│ The greeting, as text (niladic: call it with @). ⍝│ >> "hi:" u_se< "Hello" ⍝│ >> hi:h_ello @ ⍝│ hello X̲ᵉTᵃL ˡh̲ello ← { @ → "hello X̲ᵉTᵃL" } ⍝ niladic: call it with @ ⍝ typed: ⍝ l:h_ello := { @ -> "hello X̲ᵉTᵃL" } # niladic: call it with @
h_ello is a function (its h is underlined); l: exports it. Its
argument is @, Unit, the value that stands for nothing: { @ -> ... }
is a function of no real argument: it is niladic. It gives a string,
which in X_eTaL is a vector of characters. The name in it is the logo:
typed X_ e:T a:L, drawn, with the spaces removed; a string (and a
comment) may hold any Unicode, though the rest of the source is ASCII. xetal type on the library file lists what
it exports:
$ xetal type userlibs/Hello.xtl l:h_ello : Unit -> Char
The type of a string is Char: types say what the items are, not how
many there are.
Using it
A program imports the library under a prefix of its choosing. "h:"
makes the library's l:h_ello this program's hi:h_ello:
"hi:" u̲se< "Hello" ʰⁱh̲ello @ ⍝ typed: ⍝ "hi:" u_se< "Hello" ⍝ hi:h_ello @
hello X̲ᵉTᵃL
The whole program is demos/hello-library.xtl; just run
demos/hello-library.xtl prints the same greeting.
Where a library is found
"Hello" is looked for as Hello.xtl beside the importing file, then
in userlibs/ (libraries of your own, in the directory xetal runs in:
the repository's root), then in each directory of XETAL_PATH
(separated by :), then among the standard libraries built into
xetal (Stats, Maybe, Combinators, TTTML, whose source is in
lib/). A path finds one file exactly: "hi:" u_se< "userlibs/Hello.xtl".
Libraries are not programs: they are not executable, and xetal run (or
just show) on one lists its exports instead of running it. This
document's blocks run from its own directory, with XETAL_PATH set to
userlibs/.
In the live demo, the library is one of your files: open Hello.xtl,
change the greeting, Save, and run the hello-library demo again.
Mistakes it catches
The prefix is required, so every name says where it comes from:
u_se< "Hello" error[missing-alias]: u_se< needs an alias on its left: "c:" u_se< "Library"
Only what the library exports can be used, and the error says what it does export:
"hi:" u_se< "Hello" hi:g_oodbye @ error[not-exported]: hi:g_oodbye is not defined by that library; it defines h_ello
And the types are checked across the import:
"hi:" u_se< "Hello" hi:h_ello 42 error[type-mismatch]: expected Unit, found a number
A second greeting
A library can keep names to itself: a helper written with h: is
private to its file.
userlibs/Greetings.xtl exports g_reet, which is monadic: it takes the
greeting from the program and adds the name, kept in a helper h:n_ame:
⍝│ Greetings: a library with a private name. h:n_ame is file-private, so it is ⍝│ used here but cannot be imported; g_reet is exported, and takes the ⍝│ greeting from the program that calls it. Import it with an alias of ⍝│ your choice: "g:" u_se< "Greetings" (it is found in userlibs/). ⍝│ The name a greeting is addressed to, the logo drawn (niladic: call ⍝│ it with @). ʰn̲ame ← { @ → "X̲ᵉTᵃL" } ⍝ private ⍝│ The greeting g, given by the caller, followed by the name: monadic, ⍝│ ᵍg̲reet "hi". ⍝│ >> "g:" u_se< "Greetings" ⍝│ >> g:g_reet "hi" ⍝│ hi X̲ᵉTᵃL ˡg̲reet ← { g → g c̲at " " c̲at ʰn̲ame @ } ⍝ monadic: the greeting ⍝ typed: ⍝ h:n_ame := { @ -> "X̲ᵉTᵃL" } # private ⍝ l:g_reet := { g -> g c_at " " c_at h:n_ame @ } # monadic: the greeting
X_eTaL reads right to left, so g c_at " " c_at h:n_ame @ is g joined
to a space joined to the name. A program can import both libraries,
each under its own prefix:
"g:" u̲se< "Greetings" ᵍg̲reet "hi" ᵍg̲reet "welcome to" ⍝ typed: ⍝ "g:" u_se< "Greetings" ⍝ g:g_reet "hi" ⍝ g:g_reet "welcome to"
hi X̲ᵉTᵃL welcome to X̲ᵉTᵃL
but not the helper: g:n_ame @ is an error, not-exported,
listing g_reet. demos/hello-library.xtl uses both, the niladic
hi:h_ello @ and the monadic g:g_reet "hi".