Hello, library
writing a library of your own, and using it

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, 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).

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

A program imports the library under a prefix of its choosing. "h:" makes the library's l:h_ello this program's h:h_ello:

ʰ⁼u̲se< "Hello"
ʰh̲ello @

⍝ typed:
⍝   "h:" u_se< "Hello"
⍝   h:h_ello @

hello X̲ᵉTᵃL

The whole program is demos/hello-library.xtl; just run demos/hello-library.xtl prints the same greeting.

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

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:

"h:" u_se< "Hello"
h:g_oodbye @
error[not-exported]: h:g_oodbye is not defined by that library; it defines h_ello

And the types are checked across the import:

"h:" u_se< "Hello"
h:h_ello 42
error[type-mismatch]: expected Unit, found a number

A library can keep names to itself: a name without l: is private. userlibs/Greetings.xtl exports g_reet, which is monadic: it takes the greeting from the program and adds the name, kept in a private n_ame:

⍝ Greetings: a library with a private name. n_ame has no l:, so it is
⍝ used here but cannot be imported; g_reet is exported, and takes the
⍝ greeting from the program that calls it.

n̲ame ← { @ → "X̲ᵉTᵃL" }                      ⍝ private
ˡg̲reet ← { g → g c̲at " " c̲at n̲ame @ }        ⍝ monadic: the greeting

⍝ typed:
⍝   n_ame := { @ -> "X̲ᵉTᵃL" }                  # private
⍝   l:g_reet := { g -> g c_at " " c_at n_ame @ } # monadic: the greeting

X_eTaL reads right to left, so g c_at " " c_at n_ame @ is g joined to a space joined to the name. A program can import both libraries, each under its own prefix:

ᵍ⁼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 private name: g:n_ame @ is an error, not-exported, listing g_reet. demos/hello-library.xtl uses both, the niladic h:h_ello @ and the monadic g:g_reet "hi".