Kex

trait Inspectable

Types that can be rendered structurally, for a person reading output.

The rendering shows the value's STRUCTURE: quotes on strings, Just(...) around an optional, which is what makes it right for debugging and wrong for user-facing text. Showable is the other half of that pair.

Every type is inspectable through a structural fallback, so inspected and IO.inspect work on anything; a type that wants a different rendering overrides inspectValue.

[1, 2].inspected       # => "[1, 2]"
Just("hi").inspected   # => "Just(\"hi\")"

Implemented by Binary, Period, Date, Time, DateTime, URI, URL, Headers.

Provided methods

inspectValue(colors: Bool) -> String

[1, 2].inspectValue(false)   # => "[1, 2]"

trait Showable

Types that have a concise, user-facing text representation.

Showable is used by interpolation, printing, and to(String). Its output should describe the value itself rather than its implementation structure: a string is shown without quotes, Just(x) is shown as x, and None is shown as an empty string. Use Inspectable when debugging structure matters.

"hello".showValue          # => "hello"
Just("hello").showValue    # => "hello"
None.showValue             # => ""

Implemented by Binary, Optional<Showable>, Result<X, E>, Period, Date, Time, DateTime, Measure, URI, URL, Queue<A>, Set<A>, UnorderedSet<A>, Stack<A>, Headers.

Provided methods

showValue : String

to(_)

extends Optional<Showable>

More methods of Optional, added by this module.

Implements Showable.

showValue(_)

extends Result<X, E>

More methods of Result, added by this module.

Implements Showable.

The same for Result, with one deliberate asymmetry: SHOWING a result shows what it carries, so Ok(42) reads as 42 rather than leaking the wrapper into text, but an Error keeps its marker. Dropping it made a failure and a success print identically, and unlike None (which shows as "", visibly not a value) there would be nothing left to tell them apart.

The marker is spelled Error(...), matching how the same value renders as an ELEMENT of a collection: [1, Error(Bad(no))]. Elements render structurally rather than through showValue (as in Ruby, where nil.to_s is "" but [nil].to_s is "[nil]"), so this is the one spelling that reads the same at both levels.

What functions RETURN is unchanged: Integer.parse still answers with a Result, IO.inspect still shows Ok(42), and both arms are still matchable.

showValue(_)

module Kex

The running toolchain, which backend, which version, which features.

Kex.BACKEND                  # => Interpreter
Kex.BACKEND.compiled?        # => false
Kex.VERSION.release          # => "0.4.0"
Kex.Feature.has?(Kex.FileSystem)   # => true

BACKEND : Backend

Kex.BACKEND   # => Interpreter

VERSION : Version

Kex.VERSION.major     # => 0
Kex.VERSION.release   # => "0.4.0-alpha.2"

IO.printLine("built with Kex ${Kex.VERSION.number}")

load(path: String) -> Result<LoadedModule, String>

let theme = Kex.load("build/kex_theme.beam").try

loaded(name: Atom) -> LoadedModule?

let theme = Kex.loaded(:kex_theme).or(Kex.load(path).try)

hash(value: Any) -> Integer

let stamp = Kex.hash(paths.map { |path| (path, FS.File.info(path).try) })

type Backend

Which backend is executing the program: the tree-walking Interpreter, or the Beam virtual machine.

Variants

• Interpreter
• Beam

interpreted? : Bool

Kex.BACKEND.interpreted?   # => true under `kex -R file.kex`

compiled? : Bool

Kex.BACKEND.compiled?   # => true under `kex file.kex`

beam? : Bool

Kex.BACKEND.beam?   # => true under `kex file.kex`

type Feature

An optional capability a build may or may not include. Ask about one with Kex.Feature.has? before relying on it.

FileSystem: the program can read and write the host's files (FS). ExternalPrograms: it can run other programs (Process.run, Process.stream), which the browser build cannot.

Kex's own processes (spawn, receive) are not optional: every backend has them. Networking has its finer-grained report, Net.Support.current.

Variants

• FileSystem
• ExternalPrograms

record Version

Build identity for the compiler and runtime executing this program: Version and VERSION below.

Useful in bug reports, generated artifacts, and compatibility checks where Kex.BACKEND alone is not enough to identify the toolchain. The toolchain a program is running on. kex --version and the REPL banner report the same numbers.

revision is the git commit the compiler was built from: None when it was built from a source archive rather than a checkout, which is why it is an Optional rather than a String.

Examples

Kex.VERSION.major        # => 0
Kex.VERSION.revision     # => Just("a1b2c3d")
Kex.VERSION.to(String)   # => "0.3.0 (a1b2c3d)"

Fields

major

Integer

minor

Integer

patch

Integer

revision

String?

preRelease

String optional

tuple : (Integer, Integer, Integer, String?)

let (major, minor, patch, revision) = Kex.VERSION.tuple
major   # => 0

release : String

Kex.VERSION.release   # => "0.4.0-alpha.2"

number : String

Kex.VERSION.number   # => "0.4.0-alpha.2 (219e625)"

IO.printLine("built with Kex ${Kex.VERSION.number}")

record LoadedModule

A compiled module loaded into the running program by Kex.load.

For a program that decides at run time what code it needs: a site generator rendering a theme's templates, a plugin host. Compile the source with kex --compile -o <dir> once, then load the .beam and call it as often as needed, without starting another VM for every call (kexhq/kex#399).

Every entry module is named after its file (kex_<stem>.beam for <stem>.kex), and so is everything declared at the top level of that file. A let render = Template.html(Kex.embed(path)) written outside any module therefore lands in kex_<stem>, not in a module the file names; give each generated file a distinct name, or put the declaration inside a module, whose functions compile into Kex.<Name>.

The BEAM backend only: under the interpreter, Kex.load answers an error.

let theme = Kex.load("cache/kex_theme_3f2a.beam").try
let html = theme.call(:render, [context]).try

Fields

name

Atom

call(function: Atom, arguments: [Any]) -> Result<Any, String>

theme.call(:render, [context])   # => Ok("<html>...")

module Kex.Feature

Which optional capabilities this build includes.

Optional non-network capabilities in this build. Networking has its own granular opt-in Net.Support report.

has?(f: Feature) -> Bool

Kex.Feature.has?(Kex.ExternalPrograms)   # => true, except in a browser

list : [Feature]

Kex.Feature.list   # => [FileSystem, ExternalPrograms]

module Kex.Interface

Reading the typed public surface of a compiled Kex module.

read(path: FS.FilePath) -> Any?

Kex.Interface.read("build/runtime/beam/kex_prelude.beam")

function inspected

inspected(value: Inspectable) -> String

Returns the pretty-printed representation of any value as a STRING: the same form the REPL echoes. Universal: reachable on every type through UFCS.

Named apart from inspect, which prints and returns its INPUT so it can be dropped into a pipeline. Both spellings used to be called inspect, and which one a call reached depended on whether it was written x.inspect or IO.inspect(x), so [1, 2].inspect.count answered 24, the length of the rendered string, rather than 2.

Parameters

value

any value

Returns its rendered form

Examples

[1, 2].inspected            # => "[1, 2]"
{ a: 1 }.inspected          # => "{ a: 1 }"
{ "a": 1 }.inspected        # => "{ \"a\": 1 }"
Just("hi").inspected        # => "Just(\"hi\")"

Putting a rendering into a message

IO.printError("unexpected value: ${value.inspected}")

function inspect

inspect(value: A) -> A

Prints the pretty-printed form of value to stderr and returns value unchanged, so it can be dropped into any pipeline without changing what flows through it. The same operation as IO.inspect, reachable by UFCS.

Parameters

value

the value to show

Returns the same value, unchanged

Examples

[1, 2, 3, 4].map { |n| n * 3 }.inspect.filter(~even?)
# stderr: [3, 6, 9, 12] : [Int]
# => [6, 12]