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".

Literate documents · Live demo · Repository