# [Zeolite Programming Language][zeolite] [![Haskell CI Status][action-status]][action-zeolite] [![Hackage Status][hackage-status]][hackage-zeolite-lang] Zeolite is a statically-typed, general-purpose programming language. The type system revolves around defining objects and their usage patterns. Zeolite prioritizes making it easy to write maintainable and understandable code. This is done by rethinking standard language idioms and limiting flexibility in some places while increasing it in others. In particular, emphasis is placed on the user's experience when troubleshooting code that is *incorrect*. The design of the type system and the language itself is influenced by positive and negative experiences with Java, C++, Haskell, Python, Ruby, and Go, with collaborative development, and with various systems of code-quality enforcement. Due to the way GitHub renders embedded HTML, the colors might not show up in the syntax-highlighted code in this document. If you use the Chrome browser, you can view the intended formatting using the [Markdown Viewer](https://chrome.google.com/webstore/detail/markdown-viewer/ckkdlimhmcjmikdlpkmbgfkaikojcbjk) extension to view the [raw version](https://raw.githubusercontent.com/ta0kira/zeolite/master/README.md) of this document. ## Table of Contents - [Project Status](#project-status) - [Language Overview](#language-overview) - [Programming Paradigms](#programming-paradigms) - [Parameter Variance](#parameter-variance) - [Parameters as Variables](#parameters-as-variables) - [Integrated Test Runner](#integrated-test-runner) - [Integrated Build System](#integrated-build-system) - [Data Encapsulation](#data-encapsulation) - [Quick Start](#quick-start) - [Installation](#installation) - [Hello World](#hello-world) - [Writing Programs](#writing-programs) - [Basic Ideas](#basic-ideas) - [Declaring Functions](#declaring-functions) - [Defining Functions](#defining-functions) - [Using Variables](#using-variables) - [Calling Functions](#calling-functions) - [Functions As Operators](#functions-as-operators) - [Data Members and Value Creation](#data-members-and-value-creation) - [Conditionals](#conditionals) - [Scoping and Cleanup](#scoping-and-cleanup) - [Loops](#loops) - [Multiple Returns](#multiple-returns) - [Optional and Weak Values](#optional-and-weak-values) - [Deferred Variable Initialization](#deferred-variable-initialization) - [Immediate Program Termination](#immediate-program-termination) - [Call Delegation](#call-delegation) - [Function Argument Labels](#function-argument-labels) - [Using Parameters](#using-parameters) - [Using Interfaces](#using-interfaces) - [Immutable Types](#immutable-types) - [The `#self` Parameter](#the-self-parameter) - [Type Inference](#type-inference) - [Other Features](#other-features) - [Meta Types](#meta-types) - [Explicit Type Conversion](#explicit-type-conversion) - [Runtime Type Reduction](#runtime-type-reduction) - [Value Instance Comparison](#value-instance-comparison) - [Limited Function Visibility](#limited-function-visibility) - [Builtins](#builtins) - [Reserved Words](#reserved-words) - [Builtin Types](#builtin-types) - [Builtin Constants](#builtin-constants) - [Builtin Functions](#builtin-functions) - [Procedural Operators](#procedural-operators) - [Layout and Dependencies](#layout-and-dependencies) - [Using Public Source Files](#using-public-source-files) - [Standard Library](#standard-library) - [Modules](#modules) - [Unit Testing](#unit-testing) - [Writing Tests](#writing-tests) - [Code Coverage](#code-coverage) - [Compiler Pragmas and Macros](#compiler-pragmas-and-macros) - [Source File Pragmas](#source-file-pragmas) - [Procedure Pragmas](#procedure-pragmas) - [`define` Pragmas](#define-pragmas) - [`unittest` Pragmas](#unittest-pragmas) - [Local Variable Rules](#local-variable-rules) - [Expression Macros](#expression-macros) - [Known Language Limitations](#known-language-limitations) - [Reference Counting](#reference-counting) ## Project Status Zeolite is still evolving in all areas (syntax, build system, etc.), and it still lacks a lot of standard library functionality. That said, it was designed with practical applications in mind. It *does not* prioritize having impressive toy examples (e.g., merge-sort or "Hello World" in one line); the real value is seen in programs with higher relational complexity. ## Language Overview This section discusses some of the features that make Zeolite unique. It does not go into detail about all of the language's features; see [Writing Programs](#writing-programs) and the [full examples][examples] for more specific language information. ### Programming Paradigms Zeolite currently uses both [procedural][procedural] and [object-oriented][oop] programming paradigms. It shares many features with Java, but it also has additional features and restrictions meant to simplify code maintenance. ### Parameter Variance The initial motivation for Zeolite was a type system that allows implicit conversions between different parameterizations of parameterized types. A parameterized type is a type with type "place-holders", e.g., `template`s in C++ and generics in Java. Java and C++ *do not* allow you to safely convert between different parameterizations. For example, you cannot safely convert a `List` into a `List` in Java. This is primarily because `List` uses its type parameter for both input and output. Zeolite, on the other hand, uses [declaration-site variance][variance] for each parameter. (C# also does this to a lesser extent.) This allows the language to support very powerful recursive type conversions for parameterized types. Zeolite *also* allows [use-site variance][variance] declarations, like Java uses. Building variance into the core of the type system also allows Zeolite to have a [special meta-type](#the-self-parameter) that interfaces can use to require that implementations return a value of *their own type* rather than *the type of the interface*. This is particularly useful for defining interfaces for iterators and builders, whose methods often perform an update and return a value of the same type. ### Parameters as Variables Zeolite treats type parameters both as type place-holders (like in C++ and Java) and as *type variables* that you can call functions on. This further allows Zeolite to have interfaces that declare functions that operate on *types* in addition to interfaces that declare functions that operate on *values*. (This would be like having `abstract static` methods in Java.) This helps solve a few separate problems: - Operations like `equals` comparisons in Java are always dispatched to the *left* object, which could lead to inconsistent results if the objects are swapped: `foo.equals(bar)` is not the same as `bar.equals(foo)`. This dispatching asymmetry can be eliminated by making `equals` a type function (e.g., `MyType.equals(foo, bar)`), and further creating an interface that requires implementations to support such calls. - Factory patterns can be abstracted out into interfaces. For example, you could create a factory interface that requires an implementation to parse a new object from a `String`, without needing to instantiate the factory object itself. You could just implement the factory function directly in `MyType`, without needing a separate `MyTypeFactory`. ### Integrated Test Runner The major advantage of statically-typed programming languages is their compile-time detection of code that *should not* be allowed. On the other hand, there is a major testability gap when it comes to ensuring that your statically-typed code *disallows* what you expect it to. Zeolite has a special source-file extension for unit tests, and a built-in compiler mode to run them. - Tests can check for runtime success, compilation success, compilation failure, and even crashes. Normally you would need a third-party test runner to check for required compilation failures and crashes. - The test mode includes a command-line option to collect code-coverage data, which can be critical for determining test efficacy. Nearly all of the integration testing of the Zeolite language itself is done using this feature, but it is also supported for general use with Zeolite projects. ### Integrated Build System The Zeolite compiler supports a module system that can incrementally compile projects without the user needing to create build scripts or `Makefile`s. - Modules are configured via a simple config file. - File-level and symbol-level imports and includes *are not* necessary, allowing module authors to freely rearrange file structure. - Type dependencies are automatically resolved during linking so that output binaries contain only the code that is relevant. - Module authors can back Zeolite code with C++. - The module system is integrated with the compiler's built-in testing mode. This means that the programmer can focus on code rather than on build rules, and module authors can avoid writing verbose build instructions for the users of their modules. ### Data Encapsulation The overall design of Zeolite revolves around data encapsulation: - **No default construction or copying.** This means that objects can only be created by explicit factory functions. (A very common mistake in C++ code is forgetting to *disallow or override* default construction or copying.) This also means that accidental deep copying is not even possible in Zeolite. - **Only abstract interfaces can be inherited.** Types that define procedures or contain data members *cannot* be further extended. This encourages the programmer to think more about usage patterns and less about data representation when designing interactions between types. - **No "privileged" data-member access.** No object has *direct* access to the data members of any other object; not even other objects of the same type. This forces the programmer to also think about usage patterns when dealing with other objects of the same type. - **No `null` values.** Every variable must be explicitly initialized. This obviates questions of whether or not a variable actually contains a value. When combined with the elimination of default construction, this means that a variable can only hold values that a type author has specifically allowed. Zeolite has an `optional` storage modifier for use in a variable's type, but it creates a new and incompatible type, whose value cannot be used without first extracting it. This is in contrast to Java allowing any variable to be `null`. (It is more like `Optional` in Java 8, but as built-in syntax, and with nesting disallowed.) - **No reflection or down-casting.** The only thing that has access to the "real" type of a value is the value itself. This means that the reflection and down-casting tricks available in Java to circumvent the compiler *are not* available in Zeolite. (User-defined types can selectively allow "down-casting like" semantics by reasoning about [parameters as variables](#parameters-as-variables), however.) - **Implementation details are kept separate.** In Zeolite, only *public inheritance* and *public functions* show up where an object type is declared, to discourage relying on implementation details of the type. C++ and Java allow (and in some cases *require*) implementation details (data members, function definitions, etc.) to show up in the same place as the user-accessible parts of a `class`. The result is that the user of the `class` will often rely on knowledge of how it works internally. Although all of these limitations preclude a lot of design decisions allowed in languages like Java, C++, and Python, they also drastically reduce the possible complexity of inter-object interactions. Additionally, they generally *do not* require ugly work-arounds; see the [full examples][examples]. ## Quick Start ### Installation Requirements: - A POSIX-compliant operating system. Zeolite has been tested on Linux and FreeBSD, and to a limited extent on MacOS. It probably _won't_ work on Windows, due to how it interacts with the filesystem and subprocesses. - A Haskell compiler such as [`ghc`][ghc] that can install packages using [`cabal`][cabal], as well as the [`cabal`][cabal] installer. - A C++ compiler such as [`clang++`][clang] or [`g++`][gcc] and the standard `ar` archiver present on most Unix-like operating systems. If you use a modern Linux distribution, most of the above can be installed using the package manager that comes with your distribution. On MacOS, you can install [Xcode][xcode] for a C++ compiler and [`brew install cabal-install`][brew-cabal] for `cabal`. Once you meet all of those requirements, follow the installation instructions for the [**`zeolite-lang`**][hackage-zeolite-lang] package on [Hackage][hackage]. Please take a look at the [issues page][zeolite-issues] if you run into problems. The entire process will probably look like this, once you have `cabal` and a C++ compiler installed: ```shell $ cabal update # Also add --overwrite-policy=always if you're upgrading to a specific version. $ cabal install zeolite-lang $ zeolite-setup -j8 # Follow interactive prompts... ``` **You might also need to add `$HOME/.cabal/bin` or `$HOME/.local/bin` to your `$PATH`.** For syntax highlighting in [Visual Studio Code][vscode], See "VS Code Support" in the [Zeolite releases][zeolite-releases] and download the `.vsix` file. If you happen to use the [`kate`][kate] text editor, you can use the syntax highlighting in [`zeolite.xml`][zeolite.xml]. ### Hello World It's the [any%](https://en.wiktionary.org/wiki/any%25) of programming. 
// hello-world.0rx

concrete HelloWorld {
  @type run () -> ()
}

define HelloWorld {
  run () {
    \ BasicOutput.stderr().writeNow("Hello World\n")
  }
}
```shell # Compile. zeolite -I lib/util --fast HelloWorld hello-world.0rx # Execute. ./HelloWorld ``` Also see some [full examples][examples] for more complete feature usage. ## Writing Programs This section breaks down the separate parts of a Zeolite program. See the [full examples][examples] for a more integrated language overview. ### Basic Ideas Zeolite programs use object-oriented and procedural programming paradigms. **Type categories** are used to define object types, much like `class`es in Java and C++. They *are not* called "classes", just to avoid confusion about semantic differences with Java and C++. All type-category names start with an uppercase letter and contain only letters and digits. All procedures and data live inside `concrete` type categories. Every program must have at least one `concrete` category with the procedure to be executed when the program is run. `concrete` categories are split into a **declaration** and a **definition**. Code for both should be in files ending with `.0rx`. (The `.0rp` file type contains only declarations, and will be discussed later.) 
// myprogram/myprogram.0rx

// This declares the type.
concrete MyProgram {
  // The entry point must be a () -> () function. This means that it takes no
  // arguments and returns no arguments. (@type will be discussed later.)
  @type run () -> ()
}

// This defines the type.
define MyProgram {
  run () {
    // ...
  }
}
**IMPORTANT:** All programs or modules must be in their own directory so that `zeolite` is able to cache information about the build. Unlike some other compilers, you *do not* specify all command-line options every time you recompile a binary or module. ```shell # Create a new .zeolite-module config. (Only once!) zeolite -m MyProgram myprogram # Recompile the module and binary. (After any config or code updates.) # All sources in myprogram will be compiled. -m MyProgram selects the entry # point. The default output name for the binary here is myprogram/MyProgram. zeolite -r myprogram # Execute. myprogram/MyProgram ``` ```shell # An alternative, if you only have one .0rx and want to quickly iterate. zeolite --fast MyProgram myprogram/myprogram.0rx ``` ### Declaring Functions A **function declaration** specifies the **scope** of the function and its **argument** and **return** types. (And optionally type parameters and parameter filters, to be discussed later.) The declaration simply indicates the existence of a function, without specifying its behavior. All function names start with a lowercase letter and contain only letters and digits. 
concrete MyCategory {
  // @value indicates that this function requires a value of type MyCategory.
  // This function takes 2x Int and returns 2x Int.
  @value minMax (Int, Int) -> (Int, Int)

  // @type indicates that this function operates on MyCategory itself. This is
  // like a static function in C++.
  // This function takes no arguments and returns MyCategory.
  @type create () -> (MyCategory)

  // @category indicates that this function operates on MyCategory itself. This
  // is like a static function in Java. (The semantics of @category are similar
  // to those of @type unless there are type parameters.)
  @category copy (MyCategory) -> (MyCategory)
}
In many cases, the choice between using a `@category` function or a `@type` function is arbitrary, but there are pros and cons of each: - **`@category` functions** *do not* inherit any of the [category's parameters](#using-parameters), or their filters. This can be useful in a few situations: 1. You want to impose additional restrictions on what parameters can be used. For example, `Vector:createSize` ([`lib/container`][lib/container]) requires that param `#y defines Default` so that it can populate the `Vector` with default values. 2. The caller will pass arguments that can be used to [infer the category's parameters](#type-inference). For example, `Vector:duplicateSize` ([`lib/container`][lib/container]) takes a single `#y`. Since `#y` is a function param, it can be inferred from the argument that gets passed, e.g., `Vector:duplicateSize(0, 25)`. If neither of these situations apply, a `@type` function might be better. - **`@type` functions** *do* inherit the [category's parameters](#using-parameters) and their filters, which means that they do not need to be specified again, and they do not need to be passed again when calling from another `@type` or `@value` function. This is more efficient to maintain and execute. [`@type interface`s](#using-interfaces) are another advantage of `@type` functions. ### Defining Functions Functions are defined in the category definition. They *do not* need to repeat the function declaration; however, they can do so in order to refine the argument and return types for internal use. All function names start with a lowercase letter and contain only letters and digits. The category definition can also declare *additional* functions that are not visible externally. 
concrete MyCategory {
  @type minMax (Int, Int) -> (Int, Int)
}

define MyCategory {
  // minMax is defined here.
  minMax (x, y) {
    if (superfluousCheck(x, y)) {
      return x, y
    } else {
      return y, x
    }
  }

  // superfluousCheck is only available inside of MyCategory.
  @type superfluousCheck (Int, Int) -> (Bool)
  superfluousCheck (x, y) {
    return x < y
  }
}
All arguments must either have a unique name or be ignored with `_`. `@value` functions have access to a special constant **`self`**, which refers to the object against which the function was called. #### Using Variables **Variables** are assigned with `<-` to indicate the direction of assignment. *Every* variable must be initialized; there are no `null` values in Zeolite. (However, see `optional` later on.) All variable names start with a lowercase letter and contain only letters and digits. When a location is needed for assignment (e.g., handling a function return, taking a function argument), you can use `_` in place of a variable name to ignore the value. 
// Initialize with a literal.
Int value <- 0

// Initialize with a function result.
Int value <- getValue()
Unlike other languages, Zeolite *does not* allow variable masking. For example, if there is already a variable named `x` available, you *cannot* create a new `x` variable even in a smaller scope. All variables are **shared** and their values *are not* scoped like they are in C++. You should not count on knowing the lifetime of any given value. As of compiler version `0.24.0.0`, you can also **swap** the values of two variables that have the same type, as long as both are writable. This is more efficient than "manually" swapping using a temp variable. 
Int foo <- 123
Int bar <- 456
foo <-> bar
#### Calling Functions Return values from **function calls** must *always* be explicitly handled by assigning them to a variable, passing them to another function or ignoring them. (This is required even if the function does not return anything, primarily to simplify parsing.) 
// Utilize the return.
Int value <- getValue()

// Explicitly ignore a single value.
_ <- getValue()

// Ignore all aspects of the return.
// (Prior to compiler version 0.3.0.0, ~ was used instead of \.)
\ printHelp()
- Calling a function with `@value` scope requires a value of the correct type, and uses `.` notation, e.g., `foo.getValue()`. - Calling a function with `@type` scope requires the type with parameter substitution (if applicable), and uses `.` notation, e.g., `MyCategory.create()`. (Prior to compiler version `0.9.0.0`, `$` was used instead of `.`.) - Calling a function with `@category` scope requires the category itself, and uses the `:` notation, e.g., `MyCategory:foo()`. (Prior to compiler version `0.9.0.0`, `$$` was used instead of `:`.) - You can skip qualifying function calls (e.g., in the example above) if the function being called is in the same scope or higher. For example, you can call a `@type` function from the procedure for a `@value` function in the same category. Functions *cannot* be overloaded like in Java and C++. Every function must have a unique name. Functions inherited from different places can be explicitly merged, however. This can be useful if you want interfaces to have overlapping functionality without having an explicit parent for the overlap. 
@value interface ForwardIterator<|#x> {
  next () -> (optional #self)
  get () -> (#x)
}

@value interface ReverseIterator<|#x> {
  prev () -> (optional #self)
  get () -> (#x)
}

concrete Iterator<|#x> {
  refines ForwardIterator<#x>
  refines ReverseIterator<#x>

  // An explicit override is required in order to merge get from both parents.
  get () -> (#x)
}
#### Functions As Operators Zeolite allows some functions to be used as **operators**. This allows users to avoid excessive parentheses when using named mathematical functions. Functions with two arguments can use **infix** notation. The operator precedence is always between comparisons (e.g., `==`) and logical (e.g., `&&`). Functions with one argument can use **prefix** notation. These are evaluated strictly before all infix operators. 
concrete Math {
  @type plus (Int, Int) -> (Int)
  @type neg (Int) -> (Int)
}

// ...

// Math.plus is evaluated first.
Int x <- 1 `Math.plus` 2 * 5
// Math.neg is evaluated first.
Int y <- `Math.neg` x `Math.plus` 2
#### Data Members and Value Creation Unlike Java and C++, there is no "default construction" in Zeolite. In addition, Zeolite also lacks the concept of "copy construction" that C++ has. This means that new values can only be created using a factory function. In combination with required variable initialization, this ensures that the programmer never needs to worry about unexpected missing or uninitialized values. Data members are never externally visible; they only exist in the category definition. Any access outside of the category must be done using explicitly-defined functions. 
concrete MyCategory {
  @type create () -> (MyCategory)
}

define MyCategory {
  // A data member unique to each MyCategory value.
  @value Int value

  create () {
    // Initialization is done with direct assignment.
    return MyCategory{ 0 }
  }
}

// ...

// Create a new value in some other procedure.
MyCategory myValue <- MyCategory.create()
There *is no syntax* for accessing a data member from another object; even objects of the same type. This effectively makes all variables **internal** rather than just `private` like in Java and C++. As long as parameter variance is respected, you can provide access to an individual member with getters and setters. As of compiler version `0.14.0.0`, you can use [`#self`](#the-self-parameter) in place of the full type when you are creating a value of the same type from a `@type` or `@value` function. 
concrete MyCategory {
  @type create () -> (MyCategory)
}

define MyCategory {
  @value Int value

  create () {
    return #self{ 0 }
  }
}
A category can also have `@category` members, but *not* `@type` members. (The latter is so that the runtime implementation can clean up unused `@type`s without introducing ambiguitites regarding member lifespan.) 
concrete MyCategory {
  @type global () -> (MyCategory)
}

define MyCategory {
  @value Int value

  // @category members use inline initialization.
  @category MyCategory singleton <- MyCategory{ 0 }

  global () {
    // @category members are accessible from all functions in the category.
    return singleton
  }
}
#### Conditionals Zeolite uses the `if`/`elif`/`else` conditional construct. The `elif` and `else` clauses are always optional. 
if (x) {
  // something
} elif (y) {
  // something
} else {
  // something
}
#### Scoping and Cleanup Variables can be scoped to specific blocks of code. Additionally, you can provide a cleanup procedure to be executed upon exit from the block of code. This is useful if you want to free resources without needing to explicitly do so for every `return` statement. 
// Simple scoping during evaluation.
scoped {
  Int x <- getValue()
} in if (x < 0) {
  // ...
} elif (x > 0) {
  // ...
} else {
  // ...
}

// Simple scoping during assignment.
scoped {
  Int x <- getValue1()
  Int y <- getValue2()
} in Int z <- x+y

// Scoping with cleanup.
scoped {
  // ...
} cleanup {
  // ...
} in {
  // ...
}

// Cleanup without scoping.
cleanup {
  i <- i+1  // Post-increment behavior.
} in return i
The `cleanup` block is executed at every `return`, `break`, and `continue` in the respective `in` block, and right after the `in` block. For this reason, you *cannot* use `return`, `break`, or `continue` within a `cleanup` block. Additionally, you cannot overwrite named returns. You *can* use `fail`, however, since that just ends program execution. When `cleanup` is executed at a `return` statement in the `in` block, the returns from the `return` statement are "locked in", then `cleanup` is executed, *then* those locked-in return values are returned. (This is what allows the post-increment example above to work.) #### Loops Zeolite supports two loop types: 1. **`while`** loops, which are the traditional repetition of a procedure while a predicate holds. 
   // With break and continue.
   while (true) {
     if (true) {
       break
     } else {
       continue
     }
   }

   // With an update after each iteration.
   while (true) {
     // ...
   } update {
     // ...
   }
2. **`traverse`** loops (as of compiler version `0.16.0.0`), which automatically iterate over the `#x` values in an `optional Order<#x>`. This is similar to `for (int i : container) { ... }` in C++ and `for i in container: ...` in Python. 
   traverse (orderedStrings -> String s) {
     // executed once per String s in orderedStrings
     // you can also use break and continue
   }

   // With an update after each iteration.
   traverse (orderedStrings -> String s) {
     // ...
   } update {
     // ...
   }
Since the `Order` is optional, `empty` can be used to iterate zero times. **IMPORTANT:** Most containers *are not* iterable by `traverse` as-is; you will need to call a `@value` function to get the `Order`. Some categories `refine DefaultOrder<#x>` (such as `String`, and `Vector` in `lib/container`), which allows you to use its `defaultOrder()`. Other categories provide multiple ways to `Order` the container, such as `SearchTree` in `lib/container`. 
   traverse ("hello".defaultOrder() -> Char c) {
     // executed once per Char c in "hello"
   }
`for` loops (e.g., `for (int i = 0; i < foo; ++i) { ... }` in C++) *are not* supported, since such syntax is too restrictive to scale, and they can be replaced with `traverse` or `scoped`+`while` in nearly all situations. 
// Combine while with scoped to create a for loop.
scoped {
  Int i <- 0
  Int limit <- 10
} in while (i < limit) {
  // ...
} update {
  i <- i+1
}
#### Multiple Returns A procedure definition has two options for returning multiple values: 1. Return all values. (Prior to compiler version `0.3.0.0`, multiple returns were enclosed in `{}`, e.g., `return { x, y }`.) 
   define MyCategory {
     minMax (x, y) {
       if (x < y) {
         return x, y
       } else {
         return y, x
       }
     }
   }
2. Naming the return values and assigning them individually. This can be useful (and less error-prone) if the values are determined at different times. The compiler uses static analysis to ensure that all named variables are guaranteed to be set via all possible control paths. 
   define MyCategory {
     // Returns are named on the first line.
     minMax (x, y) (min, max) {
       // Returns are optionally initialized up front.
       min <- y
       max <- x
       if (x < y) {
         // Returns are overwritten.
         min <- x
         max <- y
       }
       // Implicit return makes sure that all returns are assigned. Optionally,
       // you can use return _.
     }
   }
3. To return early when using named returns or when the function has no returns, use `return _`. You will get an error if a named return might not be set. The caller of a function with multiple returns also has a few options: 1. Assign the returns to a set of variables. You can ignore a position by using `_` in that position. (Prior to compiler version `0.3.0.0`, multiple assignments were enclosed in `{}`, e.g., `{ Int min, _ } <- minMax(4,3)`.) 
   Int min, _ <- minMax(4, 3)
2. Pass them directly to a function that requires the same number of compatible arguments. (Note that you *cannot* concatenate the returns of multiple functions.) 
   Int delta <- diff(minMax(4, 3))
3. If you need to immediately perform an operation on just one of the returned values while ignoring the others, you can select just that return inline. (As of compiler version `0.21.0.0`.) 
   // Select return 0 from minMax.
   return minMax(4, 3){0}
Note that the position *must* be an integer literal so that the compiler can validate both the position and the return type. #### Optional and Weak Values Zeolite requires that all variables be initialized; however, it provides the **`optional`** storage modifier to allow a *specific* variable to be **`empty`**. This *is not* the same as `null` in Java because `optional` variables need to be `require`d before use. 
// empty is a special value for use with optional.
optional Int value <- empty

// Non-optional values automatically convert to optional.
value <- 1

// present returns true iff the value is not empty.
if (present(value)) {
  // Use require to convert the value to something usable.
  \ foo(require(value))
}
As of compiler version `0.24.0.0`, you can use **`<-|`** to conditionally overwrite an `optional` variable if it's currently `empty`. 
optional Int value <- empty
value <-| 123    // Assigned, because value was empty.
value <-| 456    // Not assigned, because value wasn't empty.
value <-| foo()  // foo() isn't called unless value is empty.
Note that if the right side _isn't_ optional then you can use the result as non-optional. 
optional Int value <- empty
Int value2 <- (value <-| 123)
As of compiler version `0.24.0.0`, you can conditionally call a function on an `optional` value if it's non-`empty` using **`&.`**. 
optional Int value <- 123
// All returned values will be optional.
optional Formatted formatted <- value&.formatted()
// foo() won't be called unless the readAt call is going to be made.
optional Char char <- formatted&.readAt(foo())
As of compiler version `0.24.1.0`, you can use **`x <|| y`** to use `y` if `x` is empty. Note that `x` must have an `optional` type, and the resulting type of the entire expression is the [type union](#meta-types) of the types of `x` and `y`. **`weak`** values allow your program to access a value *if it is available*, without holding up that value's cleanup if nothing else needs it. This can be used to let threads clean themselves up (example below) or to handle cycles in references between objects. 
concrete MyRoutine {
  @type createAndRun () -> (MyRoutine)
  @value waitCompletion () -> ()
}

define MyRoutine {
  refines Routine

  // (See lib/thread.)
  @value weak Thread thread

  createAndRun () {
    // Create a new MyRoutine and then start the thread.
    return MyRoutine{ empty }.start()
  }

  run () {
    // routine
  }

  waitCompletion () {
    scoped {
      // Use strong to turn weak into optional. If the return is non-empty, the
      // value is guaranteed to remain valid while using thread2.
      optional Thread thread2 <- strong(thread)
    } in if (present(thread2)) {
      \ require(thread2).join()
    }
  }

  @value start () -> (#self)
  start () {
    // ProcessThread holds a reference to itself only while the Routine is
    // running. Making thread weak means that the ProcessThread can clean itself
    // up once the Routine terminates.
    thread <- ProcessThread.from(self).start()
    return self
  }
}
#### Deferred Variable Initialization In some situations, a variable's value depends on conditional logic, and there is no low-cost default value. In such situations, you can use the **`defer`** keyword to allow a variable to be *temporarily* uninitialized. (As of compiler version `0.20.0.0`.) 
LargeObject object <- defer

if (debug) {
  object <- LargeObject.newDebug()
} else {
  object <- LargeObject.new()
}

\ object.execute()
In this example, `object` is declared without an initializer, and is then initialized in *both* the `if` and `else` clauses. - A variable initialized with `defer` *must* be initialized via *all possible* control paths prior to its use. This is checked at compile time. - An *existing* variable can also be marked as `defer`red. This *will not* change its value, but will instead require that it be assigned a new value before it gets used again. - If you never *read* the variable in a particular control branch then you do not need to initialize it; initialization is only checked where necessary. #### Immediate Program Termination There are two ways to terminate the program immediately. 1. The `fail` builtin can be used to immediately terminate the program _with a stack trace_. This *is not* considered a function call since it cannot return; therefore, _do not_ precede it with `\`. 
   define MyProgram {
     run () {
       fail("MyProgram does nothing")
     }
   }
The value passed to `fail` must implement the [`Formatted` builtin](#builtins) `@value interface`. The output to `stderr` will look something like this: ```text ./MyProgram: Failed condition: MyProgram does nothing From MyProgram.run at line 7 column 5 of myprogram.0rx From main Terminated ``` 1. The `exit` builtin can be used to immediately terminate the program _with a traditional `Int` exit code_. (0 conventionally means program success.) This *is not* considered a function call since it cannot return; therefore, _do not_ precede it with `\`. 
   define MyProgram {
     run () {
       exit(0)
     }
   }
The value passed to `exit` must be an `Int`. #### Call Delegation As of compiler version `0.24.0.0`, you can delegate function calls using the **`delegate`** keyword. This has the effect of forwarding _all_ of the arguments passed to the enclosing function call to the handler specified. (The call is actually rewritten using a substitution during compilation.) 
new (value1,value2) {
  // Same as Value{ value1, value2 }.
  \ delegate -> Value

  // Same as foo(value1,value2).
  \ delegate -> `foo`

  // Same as something(123).bar(value1,value2).
  \ delegate -> `something(123).bar`
}
**IMPORTANT:** If the enclosing function specifies [argument labels](#function-argument-labels) then those will be used in the forwarded call. 
@type new (String name:, Int) -> (Value)
new (value1,value2) {
  // Same as foo(name: value1, value2).
  return delegate -> `foo`
}
**IMPORTANT:** Delegation will fail to compile if: 1. One or more function arguments is ignored with `_`, e.g., `call(_) { ... }`. 2. One or more function arguments is hidden with `$Hidden[]$`, e.g., `$Hidden[someArg]$`. This is primarily as a sanity check, since all of the above imply that a given argument should not be used. ### Function Argument Labels As of compiler version `0.24.0.0`, function declarations in Zeolite can _optionally_ have labels for any individual argument. Note that this is a _label_ and _not_ an argument name. All labels start with a lowercase letter and contain only letters and digits, and end with `:`. - The syntax for labeling an argument in the function declaration is to specify it after the type. 
  concrete Value {
    // The first argument requires start: as a label.
    @type new (Int start:) -> (Value)
  }
- The syntax for labeling an argument in the function call is to precede the argument with the label. 
  // The first argument is labeled with start:.
  Value foo <- Value.new(start: 123)
**IMPORTANT:** If the function declaration specifies a label, the label must _always_ be used when calling that function. Additionally, arguments must still be passed in the same order; labels _don't_ allow you to reorder arguments. When defining a function, the name you give to an argument _should_ match the label, but that isn't a requirement. Also note that labels _can_ be reused, e.g., `@value swapRows (Int row:, Int row:) -> ()`. This allows the label to be descriptive rather than just an identifier. ### Using Parameters All `concrete` categories and all `interface`s can have type parameters. Each parameter can have a variance rule assigned to it. This allows the compiler to do type conversions between different parameterizations. Parameter names must start with `#` and a lowercase letter, and can only contain letters and digits. Parameters are *never* repeated in the category or function definitions. (Doing so would just create more opportunity for unnecessary compile-time errors.) 
// #x is covariant (indicated by being to the right of |), which means that it
// can only be used for output purposes.
@value interface Reader<|#x> {
  read () -> (#x)
}

// #x is contravariant (indicated by being to the left of |), which means that
// it can only be used for input purposes.
@value interface Writer<#x|> {
  write (#x) -> ()
}

// #x is for output and #y is for input, from the caller's perspective.
@value interface Function<#x|#y> {
  call (#x) -> (#y)
}

// By default, parameters are invariant, i.e., cannot be converted. You can also
// explicitly specify invariance with <|#x|>. This allows all three variance
// types to be present.
concrete List<#x> {
  @value append (#x) -> ()
  @value head () -> (#x)
}

// Use , to separate multiple parameters that have the same variance.
concrete KeyValue<#k, #v> {
  @type new (#k, #v) -> (#self)
  @value key   () -> (#k)
  @value value () -> (#v)
}
- Specifying parameter variance allows the compiler to automatically convert between different types. This is done recursively in terms of parameter substitution. 
  // Covariance allows conversion upward.
  Reader<MyValue> reader <- // ...
  Reader<MyBase>  reader2 <- reader

  // Contravariance allows conversion downward.
  Writer<MyBase>  writer <- // ...
  Writer<MyValue> writer2 <- writer

  // Conversion is also recursive.
  Writer<Reader<MyBase>>  readerWriter <- // ...
  Writer<Reader<MyValue>> readerWriter2 <- readerWriter

  // Invariance does not allow conversions.
  List<MyValue> list <- // ...
  List<MyBase>  list2 <- // ...
- You can apply **filters** to type parameters to require that the parameters meet certain requirements. This allows you to call `interface` functions on parameters and their values in procedure definitions. 
  concrete Helper {
    @type format<#x>
      // Ensures that #x -> Formatted. (Like T extends Foo in Java.)
      // Example: String f <- Helper.format(123)
      #x requires Formatted
    (#x) -> (String)

    @type get<#x>
      // Ensures that #x <- String. (Like T super Foo in Java.)
      // Example: AsBool v <- Helper.get<AsBool>()
      #x allows String
    () -> (#x)

    @type create<#x>
      // Ensures that #x defines the Default @type interface.
      // Example: Int v <- Helper.create<Int>()
      #x defines Default
    () -> (#x)
  }

  define Helper {
    format (x) {
      // #x -> Formatted means x has formatted().
      return x.formatted()
    }

    get () {
      // #x <- String means we can return a String here.
      return "message"
    }

    create () {
      // #x defines Default means #x has default().
      return #x.default()
    }
  }
Filters on category params must be specified after all `refines`/`defines` and before any function declarations. **IMPORTANT:** As of compiler version `0.16.0.0`, you can no longer use parameter filters in `@value interface`s and `@type interface`s. ### Using Interfaces Zeolite has `@value interface`s that are similar to Java `interface`s, which declare functions that implementations must define. In addition, Zeolite also has `@type interface`s that declare `@type` functions that must be defined. (This would be like having `abstract static` functions in Java.) 
// @value indicates that the interface declares @value functions.
@value interface Printable {
  // @value is not allowed in the declaration.
  print () -> ()
}

// @type indicates that the interface declares @type functions.
@type interface Diffable<#x> {
  // @type is not allowed in the declaration.
  diff (#x, #x) -> (#x)
}
|Type|Param Variance|Param Filters|Can Inherit|`@category` Funcs|`@type` Funcs|`@value` Funcs|Define Procedures| |:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:| |**`concrete`**|✓|✓|`@value interface` `@type interface`|✓|✓|✓|✓| |**`@value interface`**|✓||`@value interface`|||✓|| |**`@type interface`**|✓||--||✓|| - `@value interface`s can be **inherited** by other `@value interface`s and `concrete` categories using `refines`. 
  concrete MyValue {
    refines Printable

    @type new (Int) -> (MyValue)

    // The functions of Printable do not need to be declared again, but you can do
    // so to refine the argument and return types.
  }

  define MyValue {
    @value Int value

    new (value) {
      return MyValue{ value }
    }

    // Define Printable.print like any other MyValue function.
    print () {
      \ BasicOutput.writeNow(value)
    }
  }
- `@type interface`s can only be **inherited** by `concrete` categories. 
  concrete MyValue {
    defines Diffable<MyValue>

    @type new (Int) -> (MyValue)

    // The functions of Diffable do not need to be declared again, but you can do
    // so to refine the argument and return types.
  }

  define MyValue {
    @value Int value

    new (value) {
      return MyValue{ value }
    }

    // Define Diffable.diff like any other MyValue function.
    diff (x, y) {
      return MyValue{ x.get() - y.get() }
    }

    // A getter is needed to access the value outside of the object that owns it.
    @value get () -> (Int)
    get () {
      return value
    }
  }
- You can also specify `refines` and `defines` when *defining* a `concrete` category. This allows the inheritance to be private. 
  concrete MyValue {
    @type create () -> (Formatted)
  }

  define MyValue {
    // Formatted is not a visible parent outside of MyValue.
    refines Formatted

    create () {
      return MyValue{ }
    }

    // Inherited from Formatted.
    formatted () {
      return "MyValue"
    }
  }
### Immutable Types You can modify `interface` and `concrete` with **`immutable`** at the very top of the declaration. (As of compiler version `0.20.0.0`.) This creates two requirements for `@value` members: 1. They are marked as read-only, and cannot be overwritten with `<-`. 2. They must have a type that is also `immutable`. (`@category` members are not affected.) Note that this applies to the *entire* implementation; not just to the implementations of functions required by the `immutable` `interface`. `immutable` is therefore intended for objects that cannot be modified, rather than as a way to define a read-only view (e.g., `const` in C++) of an object. 
@value interface Foo {
  immutable

  call () -> ()
}

concrete Bar {
  refines Foo

  @type new () -> (Bar)
  @value mutate () -> ()
}

define Bar {
  @value Int value

  new () { return Bar{ 0 } }

  call () {
    // call cannot overwrite value
  }

  mutate () {
    // mutate also cannot overwrite value, even though mutate isn't in Foo.
  }
}
For members that use a parameter as a type, you can use `immutable` as a filter if the other filters do not otherwise imply it. Note that this will prevent substituting in a non-`immutable` type when calling `@type` functions. 
concrete Type<#x> {
  immutable

  #x immutable
}

define Type {
  // #x is allowed as a member type because of the immutable filter.
  @value #x value
}
### The `#self` Parameter Every category has an implicit *covariant* parameter **`#self`**. (As of compiler version `0.14.0.0`.) It *always* means the type of the current category, even when inherited. (`#self` is covariant because it needs to be convertible to a parent of the current category.) For example: 
@value interface Iterator<|#x> {
  next () -> (#self)
  get () -> (#x)
}

concrete CharIterator {
  refines Iterator<Char>
  // next must return CharIterator because #self = CharIterator here.
}
The primary purpose of this is to support combining multiple interfaces with iterator or builder semantics into composite types *without* getting backed into a corner when calling functions from a single interface. 
@value interface ForwardIterator<|#x> {
  next () -> (#self)
  get () -> (#x)
}

@value interface ReverseIterator<|#x> {
  prev () -> (#self)
  get () -> (#x)
}

concrete CharIterator {
  refines ForwardIterator<Char>
  refines ReverseIterator<Char>
  get () -> (Char)  // (Remember that merging needs to be done explicitly.)
}

concrete Parser {
  // trimWhitespace can call next and still return the original type. In
  // contrast, if next returned ForwardIterator<#x> then trimWhitespace would
  // need to return ForwardIterator<Char> to the caller instead of #i.
  @type trimWhitespace<#i>
    #i requires ForwardIterator<Char>
  (#i) -> (#i)
}
`#self` can also be used to generalize a factory pattern: 
@type interface ParseFactory {
  fromString (String) -> (#self)
}

concrete FileParser {
  @type parseFromFile<#x>
    #x defines ParseFactory
  (String) -> (#x)
}

define FileParser {
  parseFromFile (filename) {
    String content <- FileHelper.readAll(filename)
    // Notice that ParseFactory doesn't need a type parameter to indicate what
    // type is going to be parsed in fromString; it's sufficient to know that #x
    // implements ParseFactory and that fromString returns #self.
    return #x.fromString(content)
  }
}

concrete Value {
  defines ParseFactory
}

define Value {
  fromString (string) {
    if (string == "Value") {
      return Value{ }
    } else {
      fail("could not parse input")
    }
  }
}
`#self` is nothing magical; this could all be done by explicitly adding a covariant `#self` parameter to *every* type, with the appropriate `requires` and `defines` filters. ### Type Inference Starting with compiler version `0.7.0.0`, Zeolite supports optional inference of specific function parameters by using **`?`**. This must be at the top level (no nesting), and it cannot be used outside of the parameters of the function. The type-inference system is intentionally "just clever enough" to do things that the programmer can easily guess. More sophisticated inference is feasible in theory (like Haskell uses); however, type errors with such systems can draw a significant amount of attention away from the task at hand. (For example, a common issue with Haskell is not knowing *which line of code* contains the actual mistake causing a type error.) 
concrete Value<#x> {
  @category create1<#x> (#x) -> (Value<#x>)
  @type     create2     (#x) -> (Value<#x>)
}

// ...

// This is fine.
Value<Int> value1 <- Value:create1<?>(10)

// These uses of ? are not allowed:
// Value<Int> value2 <- Value<?>.create2(10)
// Value<?>   value2 <- Value<Int>.create2(10)
Only the function arguments and the parameter filters are used to infer the type substitution; return types are ignored. If inference fails, you will see a compiler error and will need to explicitly write out the type. As of compiler version `0.21.0.0`, if you want to infer *all* params, you can skip `<...>` entirely. If you only want to infer some of the params, you must specify all params, using `?` for those that should be inferred. Type inference will *only* succeed if: 1. There is a valid pattern match between the expected argument types and the types of the passed arguments. 2. There is *exactly one* type that matches best: - For params only used in *covariant* positions, the *lower bound* of the type is unambiguous. - For params only used in *contravariant* positions, the *upper bound* of the type is unambiguous. - For all other situations, the *upper and lower bounds* are unambiguous and *equal* to each other. Type inference in the context of parameterized types is specifically disallowed in order to limit the amount of code the reader needs to search to figure out what types are being used. Forcing explicit specification of types for local variables is more work for the programmer, but it makes the code easier to reason about later on. ### Other Features This section discusses language features that are less frequently used. #### Meta Types Zeolite provides two **meta types** that allow unnamed combinations of other types. - A value with an **intersection type** `[A & B]` can be assigned from something that is *both* `A` and `B`, and can be assigned to *either* an `A` or `B`. There is a special empty intersection named **`any`** that can be assigned from any value but cannot be assigned to any other type. Intersections can be useful for requiring multiple interfaces without creating a new category that refines all of those interfaces. An intersection `[Foo & Bar]` in Zeolite is semantically similar to the existential type `forall a. (Foo a, Bar a) => a` in Haskell and `? extends Foo & Bar` in Java, except that in Zeolite `[Foo & Bar]` can be used as a first-class type. 
  @value interface Reader { }

  @value interface Writer { }

  concrete Data {
    refines Reader
    refines Writer
    @type new () -> (Data)
  }

  // ...

  [Reader & Writer] val <- Data.new()
  Reader val2 <- val
  Writer val3 <- val
- A value with a **union type** `[A | B]` can be assigned from *either* `A` or `B`, but can only be assigned to something that *both* `A` and `B` can be assigned to. There is a special empty union named **`all`** that cannot ever be assigned a value but that can be assigned to everything. (`empty` is actually of type `optional all`.) Unions can be useful if you want to artificially limit what types can be used in a particular context. This can be useful for disallowing use of "unknown" implementations in critical or risky functions, etc. - When used with `requires`, a union can limit the allowed types _without_ losing the original type. 
    concrete Helper {
      @type describe<#x>
        #x requires Formatted
        #x requires [String | Int]  // <- limits allowed types
      (#x) -> (String)
    }

    define Helper {
      describe (value) {
        return String.builder()
            .append(typename<#x>())  // <- original type is still available
            .append(": ")
            .append(value)
            .build()
      }
    }

    // ...

    \ Helper.describe(123)        // Fine.
    \ Helper.describe("message")  // Fine.
    \ Helper.describe(123.0)      // Error!
- When used as a variable type, the original type is lost, but you can still convert to a common parent type. 
    [String | Int] value <- 123
    // You can only convert to types that _all_ constituent types convert to.
    Formatted formatted <- value  // Fine.
    Int number <- value           // Error!
Intersection and union types also come up in [type inference](#type-inference). - If there are two or more incompatible guesses for an inferred type _used only for input_, the union of those types will be used. - If there are two or more incompatible guesses for an inferred type _used only for output_, the intersection of those types will be used. 
// (Just for creating an output parameter.)
concrete Writer<#x|> {
  @type new () -> (#self)
}

concrete Helper {
  // #x is only used for input to the function.
  @type inferInput<#x> (#x, #x) -> (String)

  // #x is only used for output from the function.
  // (This is due to contravariance of #x in Writer.)
  @type inferOutput<#x> (Writer<#x>, Writer<#x>) -> (String)
}

define Helper {
  inferInput (_, _) { return typename<#x>().formatted() }
  inferOutput (_, _) { return typename<#x>().formatted() }
}

define Writer {
  new () { return #self{ } }
}

// ...

// Returns "[Int | String]".
\ Helper.inferInput(123, "message")

// Returns "[Int & String]".
\ Helper.inferOutput(Writer<Int>.new(), Writer<String>.new())
In this context, unions/intersections are the _most restrictive_ valid types that will work for the substution. (They are respectively the [coproduct][category-coproduct]/[product][category-product] of the provided types under implicit type conversion.) #### Explicit Type Conversion In some situations, you might want to peform an explicit type conversion on a `@value`. The syntax for such conversions is _`value`_**`?`**_`Type`_, where *`value`* is any `@value` and *`Type`* is any type, including params and [meta types](#meta-types). - With values that have a [union type](#meta-types) (e.g., `[A | B]`), you might need an explicit type conversion when making a function call. 
  @value interface Object<|#x> {
    get () -> (#x)
  }

  concrete IntObject {
    refines Object<Int>
    @type new (Int) -> (IntObject)
  }

  concrete StringObject {
    refines Object<String>
    @type new (String) -> (StringObject)
  }

  // ...

  [IntObject | StringObject] value <- StringObject.new("message")

  // Convert to Object<Formatted> before calling get().
  Formatted formatted <- value?Object<Formatted>.get()

  // Should get() return Int or String here?
  // Formatted formatted <- value.get()
- Type conversions of function arguments can be used for influencing [type inference](#type-inference). 
  concrete Helper {
    @category call<#x> (#x) -> ()
  }

  // ...

  Int value <- 1

  // #x will be inferred as Formatted rather than as Int here.
  \ Helper:call(value?Formatted)
- You can also explicitly convert `optional` and `weak` values, although they will still retain their original storage modifier. 
  optional Int value <- 1

  // Passed as optional Formatted.
  \ call(value?Formatted)

  // Not allowed, since value.Formatted is still optional.
  // String string <- value?Formatted.formatted()
#### Runtime Type Reduction The **`reduce`** builtin function enables very limited runtime reasoning about type conversion. - The call `reduce(value)` will return `value` with type `optional Bar` iff `Foo` can be converted to `Bar`. Note that `value` must itself be convertible to `optional Foo`. - When type params are used, the types that are assigned at the point of execution are checked. For example, the result of `reduce<#x, #y>(value)` will depend on the *specific* types assigned to `#x` and `#y` upon execution. Here are a few motivating use-cases: - Allowing creation of a container that can hold objects of different types while still being able to access the objects with their original types. (Also see `TypeMap` in [`lib/container`][lib/container], which was actually the original target use-case for the initial version of Zeolite.) - Enabling optional functionality for a parameter without using a filter. For example, printing info about `value` if available using `reduce<#x, Formatted>(value)` during debugging. 
@value interface AnyObject {
  getAs<#y> () -> (optional #y)
}

concrete Object<#x> {
  @category create<#x> (#x) -> (AnyObject)
}

define Object {
  refines AnyObject

  @value #x value

  create (value) { return Object<#x>{ value } }
  getAs  ()      { return reduce<#x, #y>(value) }
}
AnyObject value <- Object:create<?>("message")

// This will be empty because String does not convert to Int.
optional Int value1 <- value.getAs<Int>()

// This will be "message" as Formatted because String converts to Formatted.
optional Formatted value2 <- value.getAs<Formatted>()
`reduce` *cannot* be used to "downcast" a value (e.g., converting a `Formatted` to a `Float`) since the argument has the same type as the first parameter. For example, `reduce<#x, #y>(value)` checks `#x`→`#y`, and since `value` must be `optional #x`, `value` can only be converted upward. In other words, it only allows conversions that would otherwise be allowed, returning `empty` for all other conversions. The `AnyObject` example above works because `Object` stores the *original type* passed to `create` as `#x`, which it then has available for the `reduce` call. The type variables `#x` and `#y` are the primary inputs to `reduce`; there is absolutely no examination of the "real" type of `value` at runtime. 
// Here we explicitly set #x = Formatted when calling create.
AnyObject value <- Object:create<Formatted>("message")

// This will be empty even though the actual value is a String because getAs
// uses #x = Formatted in the reduce call.
optional String value1 <- value.getAs<String>()
#### Value Instance Comparison As of compiler version `0.24.0.0`, you can get a value that identifies a specific `@value` instance using the **`identify`** builtin.. This can be useful for creating identifiers that don't otherwise have a unique member. 
String value <- "value"
Identifier<String> valueId <- identify(value)
- You can use comparison operators (e.g., `==`, `<`) between `Identifier`s of _any_ two types. - The `Identifier` remains valid even if the original `@value` is deallocated. - `identify` can also be used for `optional` types, but _not_ for `weak` types. - Type conversions have no effect on the resulting `Identifier`, other than the type used for compile-time checking. 
  String value <- "value"
  // The following are equivalent:
  Identifier<Formatted> id1 <- identify(value)
  Identifier<Formatted> id2 <- identify(value?Formatted)
- `Identifier` uniqueness isn't reliable for unboxed types (e.g., `Int`) because the values are stored without being contained in a Zeolite object. (Also see [Builtin Types](#builtin-types).) For example, `identifier(2) == identifier(2)`, whereas `identifier("value") != identifier("value")`, due to storage differences. #### Limited Function Visibility As of compiler version `0.24.0.0`, you can restrict where `@value` and `@type` functions can be called from with the **`visibility`** keyword. 
concrete Value {
  // This applies to everything below.
  visibility Factory

  // This can only be called from Factory.
  @type new () -> (Value)

  // This resets the visibility to the default.
  visibility _

  // This can be called from anywhere.
  @value call () -> ()
}
- You can specify multiple types separated by `,`. - You will get a compiler error if you declare a `@category` function when the visibility is other than the default. - Functions with restricted visibility can't be called from `@category` functions because the full type where the call originates isn't defined. - The category's own definition and `unittest`s are exempt from visibility requirements. - `visibility all` will prevent functions from being called outside of the category itself and `unittest`. - `visibility any` will prevent functions from getting called in `@category` functions but not anywhere else. - For `@value` functions with limited visibility, sometimes an [explicit type conversion](#explicit-type-conversion) of the value will be needed prior to making the function call, e.g., `value?Parent.call()`. The effect is that the allowed argument and return types could be more limited. ### Builtins #### Reserved Words [`#self`](#the-self-parameter) [`@category`](#declaring-functions) [`@type`](#declaring-functions) [`@value`](#declaring-functions) [`_`](#calling-functions) [`all`](#meta-types) [`allows`](#using-parameters) [`any`](#meta-types) [`break`](#loops) [`cleanup`](#scoping-and-cleanup) [`concrete`](#basic-ideas) [`continue`](#loops) [`defer`](#deferred-variable-initialization) [`define`](#basic-ideas) [`defines`](#using-interfaces) [`delegate`](#call-delegation) [`elif`](#conditionals) [`else`](#conditionals) [`empty`](#optional-and-weak-values) [`exit`](#immediate-program-termination) [`fail`](#immediate-program-termination) [`false`](#builtin-types) [`identify`](#value-instance-comparison) [`if`](#conditionals) [`immutable`](#immutable-types) [`in`](#scoping-and-cleanup) [`interface`](#using-interfaces) [`optional`](#optional-and-weak-values) [`present`](#optional-and-weak-values) [`reduce`](#runtime-type-reduction) [`refines`](#using-interfaces) [`require`](#optional-and-weak-values) [`requires`](#using-parameters) [`return`](#defining-functions) [`scoped`](#scoping-and-cleanup) [`self`](#defining-functions) [`strong`](#optional-and-weak-values) [`testcase`](#writing-tests) [`traverse`](#loops) [`true`](#builtin-types) [`typename`](#builtin-functions) [`unittest`](#writing-tests) [`update`](#loops) [`visibility`](#limited-function-visibility) [`weak`](#optional-and-weak-values) [`while`](#loops) #### Builtin Types See [`builtin.0rp`](https://github.com/ta0kira/zeolite/blob/master/base/builtin.0rp) and [`testing.0rp`](https://github.com/ta0kira/zeolite/blob/master/base/testing.0rp) for more details about builtin types. (For your locally-installed version, which might differ, see `$(zeolite --get-path)/base/builtin.0rp`.) Builtin `concrete` types: - **`Bool`** _[unboxed]_: Either `true` or `false`. - **`Char`** _[unboxed]_: Use single quotes, e.g., `'a'`. Use literal characters, standard escapes (e.g., `'\n'`), 2-digit hex (e.g., `\x0B`), or 3-digit octal (e.g., `'\012'`). At the moment this only supports ASCII; see [Issue #22](https://github.com/ta0kira/zeolite/issues/22). - **`CharBuffer`**: Mutable, fixed-size buffer of `Char`. This type has no literals. - **`Float`** _[unboxed]_: Use decimal notation, e.g., `0.0` or `1.0E1`. You *must* have digits on both sides of the `.`. As of compiler version `0.24.0.0`, you can also escape hex with `\x`, octal with `\o`, and binary with `\b`. - **`Identifier<#x>`** _[unboxed]_: An opaque identifier used to compare underlying `@value` instances. - **`Int`** _[unboxed]_: Use decimal (e.g., `1234`), hex (e.g., `\xABCD`), octal (e.g., `\o0123`), or binary (e.g., `\b0100`). - **`Pointer<#x>`** _[unboxed]_: An opaque pointer type for use in C++ extensions. Only C++ extensions can create and access `Pointer` contents, but Zeolite code can still store and pass them around. - **`String`**: Use double quotes to sequence `Char` literals, e.g., `"hello\012"`. You can build a string efficiently using `String.builder()`, e.g., `String foo <- String.builder().append("bar").append("baz").build()`. Builtin `@value interface`s: - **`Append<#x>`**: Supports appending `#x`. - **`AsBool`**: Convert a value to `Bool` using `asBool()`. - **`AsChar`**: Convert a value to `Char` using `asChar()`. - **`AsFloat`**: Convert a value to `Float` using `asFloat()`. - **`AsInt`**: Convert a value to `Int` using `asInt()`. - **`Build<#x>`**: Build a `#x` from the current state. - **`Container`**: Contains multiple values. - **`DefaultOrder<#x>`**: The container provides a default `Order<#x>` for use with `traverse`. - **`Duplicate`**: Duplicate the value with `duplicate()`. - **`Formatted`**: Format the value as a `String` using `formatted()`. - **`Hashed`**: Hash the value as an `Int` using `hashed()`. - **`Order<#x>`**: An ordering of `#x` values, for use with the `traverse` - **`ReadAt<#x>`**: Random access reads from a container with values of type `#x`. - **`SubSequence`**: Extract a subsequence from the object. - **`WriteAt<#x>`**: Random access writes to a container with values of type `#x`. Builtin `@type interface`s: - **`Default`**: Get the default `@value` with `default()`. - **`Equals<#x>`**: Compare values using `equals(x,y)`. - **`LessThan<#x>`**: Compare values using `lessThan(x,y)`. - **`Testcase`**: For use in `testcase`. Builtin meta-types: - **`#self`**: The type of the category where it is used. See [`#self`](#the-self-parameter). - **`any`**: Value type that can be assigned a value of any type. (This is the [terminal object][initial-terminal] in the [category][category] of Zeolite types.) - **`all`**: Value type that can be assigned to all other types. (This is the [initial object][initial-terminal] in the [category][category] of Zeolite types.) #### Builtin Constants - **`empty`** (`optional all`): A missing `optional` value. - **`false`** (`Bool`): Obvious. - **`self`** (`#self`): The value being operated on in `@value` functions. - **`true`** (`Bool`): Obvious. #### Builtin Functions - **`identify`**: Returns an `Identifier<#x>` for the value. - **`present`**: Check `optional` for `empty`. - **`reduce<#x, #y>(value)`**: See [Runtime Type Reduction](#runtime-type-reduction). - **`require`**: Convert `optional` to non-`optional`. - **`strong`**: Convert `weak` to `optional`. - **`typename<#x>()`**: Formats the *real* type of `#x` as a `Formatted` value. #### Procedural Operators |Operators|Semantics|Example|Input Types|Result Type|Notes| |:--:|:--:|:--:|:--:|:--:|:--:| |`+`,`-`,`*`,`/`|arithmetic|`x + y`|`Int`,`Float`|original type|| |`%`|arithmetic|`x % y`|`Int`|`Int`|| |`-`|arithmetic|`x - y`|`Char`|`Int`|| |`^`,`\|`,`&`,`<<`,`>>`,`~`|bit operations|`x ^ y`|`Int`|`Int`|| |`+`|concatenation|`x + y`|`String`|`String`|| |`^`,`!`,`\|\|`,`&&`|logical|`x && y`|`Bool`|`Bool`|| |`<`,`>`,`<=`,`==`,`>=`,`!=`|comparison|`x < y`|built-in unboxed, `String`|`Bool`|not available for `Pointer`| |`.`|function call|`x.foo()`|value|function return type(s)|| |`.`|function call|`T.foo()`|type instance|function return type(s)|| |`:`|function call|`T:foo()`|category|function return type(s)|| |`&.`|conditional function call|`x&.foo()`|`optional` value|function return type(s) converted to `optional`|skips evaluation of args if call is skipped| |`?`|type conversion|`x?T`|_left:_ value
_right:_ type instance|right type with optionality of left|can also be used with `optional` values| |`<-`|assignment|`x <- y`|_left:_ variable
_right:_ expression|right type|| |`<-\|`|conditional assignment|`x <-\| y`|_left:_ `optional` variable
_right:_ non-`weak` expression|left type with optionality of right|skips evaluation of right if left is `present`| |`<\|\|`|fallback value|`x <\|\| y`|_left:_ `optional` expression
_right:_ non-`weak` expression|union of left and right types with optionality of right|skips evaluation of right if left is `present`| ## Layout and Dependencies ### Using Public Source Files You can create **public** `.0rp` source files to declare `concrete` categories and `interface`s that are available for use in other sources. This is the only way to share code between different source files. `.0rp` *cannot* contain `define`s for `concrete` categories. During compilation, *all* `.0rp` files in the project directory are loaded up front. This is then used as the set of public symbols available when each `.0rx` is *separately* compiled. ### Standard Library The standard library currently temporary and lacks a lot of functionality. See the public `.0rp` sources in [`lib`][lib]. Documentation will eventually follow. ### Modules You can depend on another module using `-i lib/util` for a public dependency and `-I lib/util` for a private dependency when calling `zeolite`. (A private dependency is not visible to modules that depend on your module.) Dependency paths are first checked relative to the module depending on them. If the dependency is not found there, the compiler then checks the global location specified by `zeolite --get-path`. Public `.0rp` source files are loaded from all dependencies during compilation, and so their symbols are available to all source files in the module. There is currently no language syntax for explicitly importing or including modules or other symbols. If you are interested in backing a `concrete` category with C++, you will need to write a custom `.zeolite-module` file. Better documentation will eventually follow, but for now: 1. Create a `.0rp` with declarations of all of the `concrete` categories you intend to define in C++ code. 2. Run `zeolite` in `--templates` mode to generate `.cpp` templates for all `concrete` categories that lack a definition in your module. 3. Run `zeolite` in `-c` mode to get a basic `.zeolite-module`. After this, *always* use recompile mode (`-r`) to use your `.zeolite-module`. 4. Take a look at `.zeolite-module` in [`lib/file`][lib/file] to get an idea of how to tell the compiler where your category definitions are. 5. Add your code to the generated `.cpp` files. [`lib/file`][lib/file] is also a reasonable example for this. 6. If you need to depend on external libraries, fill in the `include_paths` and `link_flags` sections of `.zeolite-module`. **IMPORTANT:** `@value` functions for `immutable` categories will be marked as `const` in C++ extensions. `immutable` also requires that `@value` members have `immutable` types, but there is no reasonable way to enforce this in C++. You will need to separately ensure that the implementation only stores other `immutable` types, just for consistency with categories implemented in Zeolite. ## Unit Testing Unit testing is a built-in capability of Zeolite. Unit tests use `.0rt` source files, which are like `.0rx` source files with `testcase` metadata. The test files go in the same directory as the rest of your source files. (Elsewhere in this project these tests are referred to as "integration tests" because this testing mode is used to ensure that the `zeolite` compiler operates properly end-to-end.) ### Writing Tests **IMPORTANT:** Prior to compiler version `0.10.0.0`, the `testcase` syntax was slightly different, and `unittest` was not available. 
// myprogram/tests.0rt

// Each testcase starts with a header specifying a name for the group of tests.
// This provides common setup code for a group of unit tests.

testcase "passing tests" {
  // All unittest are expected to execute without any issues.
  success
}

// Everything after the testcase (up until the next testcase) is like a .0rx.

// At least one unittest must be defined when success is expected. Each unittest
// must have a distinct name within the testcase. Each unittest is run in a
// separate process, making it safe to alter global state.

unittest myTest1 {
  // The test content goes here. It has access to anything within the testcase
  // besides other unittest.
}

unittest myTest2 {
  \ empty
}


// A new testcase header indicates the end of the previous test.

testcase "missing function" {
  // The test is expected to have a compilation error. Note that this cannot be
  // used to check for parser failures!
  //
  // Any testcase can specify require and exclude regex patterns for checking
  // test output. Each pattern can optionally be qualified with one of compiler,
  // stderr, or stdout, to specify the source of the output.
  error
  require compiler "run"  // The compiler error should include "run".
  exclude compiler "foo"  // The compiler error should not include "foo".
}

// You can include unittest when an error is expected; however, they will not be
// run even if compilation succeeds.

define MyType {
  // Error! MyType does not have a definition for run.
}

concrete MyType {
  @type run () -> ()
}


testcase "intentional failure" {
  // The test is expected to fail.
  failure
  require stderr "message"  // stderr should include "message".
}

// Exactly one unittest must be defined when a failure is expected.

unittest myTest {
  // Use the fail built-in to cause a test failure.
  fail("message")
}


testcase "compilation tests" {
  // Use compiles to check only Zeolite compilation, with no C++ compilation or
  // execution of tests.
  compiles
}

unittest myTest {
  // unittest is optional in this mode, but can still be used if the tests does
  // not require any new types.
}
Unit tests have access to all public and `$ModuleOnly$` symbols in the module. You can run all tests for module `myprogram` using `zeolite -t myprogram`. Specific things to keep in mind with `testcase`: - All individual `unittest` have a default timeout of 30 seconds. This is to prevent automated test runners from hanging indefinitely if there is a deadlock or an infinite loop. This can be changed with `timeout t`, where `t` is specified in seconds. Specifing `timeout 0` disables the time limit. - To simplify parsing, there are a few limitations with how you order the fields in a `testcase`: - The expected outcome (`success`, `failure`, `error`, `compiles`) must be at the top. (Prior to compiler version `0.24.0.0`, `crash` was used instead of `failure`.) - All `require` and `exclude` patterns must be grouped together. (Put another way, if a field other than `require` or `exclude` follows one of those two, the parser will move on.) ### Code Coverage As of compiler version `0.16.0.0`, you can get a log of all lines of Zeolite code (from `.0rx` or `.0rt` sources) with the `--log-traces `*`[filename]`* option when running tests with `zeolite -t`. - If *`[filename]`* is not an absolute path, it will be created relative to the path specified with `-p` if used. *The file will be overwritten*, and will contain all traces from a single call to `zeolite -t`. - The current format is `.csv` with the following columns (includes a header): - `"microseconds"`: The call time from a monotonic microseconds timer, with an unspecified starting point. - `"pid"`: A unique ID for the current process. This *is not* the real process ID from the system, since that will often not be unique. - `"function"`: The name of the function where the line was executed. - `"context"`: The source-code context (e.g., file, line) of the call. The context has the same format as stack traces for crashes. - If a procedure uses the [`$NoTrace$` pragma](#procedure-pragmas), there will be no trace information in the log for that procedure. This is because the logging uses the same tooling that is used for stack traces. Similarly, if a specific `unittest` uses the [`$DisableCoverage$` pragma](#unittest-pragmas), no coverage will be recorded as a result of that `unittest`. - Nothing will be logged for `testcase` that use `compiles` or `error`, since those modes do not actually execute any compiled code. - Keep in mind that the simple act of processing text for logging can obscure race conditions in a program; therefore, `--log-traces` should be skipped when troubleshooting race conditions. - Check the size of the log file before attempting to open it in a desktop application. In many cases, it will be too large to display. As of compiler version `0.20.0.0`, `zeolite -r` will cache information about the possible `.0rx` lines that can show up in `--log-traces` mode. - You can access this information using `zeolite --show-traces `*`[module path]`*. This can then be compared to the `"context"` field in the output `.csv` to determine if any code was missed by the executed tests. - Alternatively, you can have `zeolite` compute the missed lines using `zeolite --missed-lines `*`[filename] [module path]`*, where *`[filename]`* is the file written by `--log-traces`. If a single `zeolite -t` command executed tests for multiple modules, you can pass all of those modules to a single `zeolite --missed-lines` call. For example: ```shell # Run the tests. zeolite -t --log-traces traces.csv your/module1 your/module2 # Output the line numbers missed by the tests. zeolite --missed-lines traces.csv your/module1 your/module2 ``` Note that `--missed-lines` *does not* account for which module's test was responsible for covering a line during the tests. For example, if you run `zeolite -t --log-traces traces.csv your/module1 your/module2` and `your/module2` depends on `your/module1`, tests from `your/module2` that execute `your/module1` code will contribute to `your/module1`'s coverage. ## Compiler Pragmas and Macros (As of compiler version `0.5.0.0`.) Pragmas allow compiler-specific directives within source files that do not otherwise need to be a part of the language syntax. Macros have the same format, and are used to insert code *after* parsing but *before* compilation. The syntax for both is `$SomePragma$` (no options) or `$AnotherPragma[`*`OPTIONS`*`]$` (uses pragma-specific options). The syntax for _`OPTIONS`_ depends on the pragma being used. Pragmas are specific to the context they are used in. ### Source File Pragmas These must be at the top of the source file, before declaring or defining categories or `testcase`s. - **`$ModuleOnly$`**. This can only be used in `.0rp` files. It takes an otherwise-public source file and limits visibility to the module. (This is similar to package-private in Java.) - **`$TestsOnly$`**. This can be used in `.0rp` and `.0rx` files. When used, the file is only visible to other sources that use it, as well as `.0rt` sources. `.0rp` sources still remain public unless `$ModuleOnly$` is used. The transitive effect of `$TestsOnly$` is preventing the use of particular categories in output binaries. ### Procedure Pragmas These must occur at the very top of a function definition. - **`$NoTrace$`**. (As of compiler version `0.6.0.0`.) Disables stack-tracing within this procedure. This is useful for recursive functions, so that trace information does not take up stack space. This does not affect tracing for functions that are called from within the procedure. - **`$TraceCreation$`**. (As of compiler version `0.6.0.0`.) Includes a trace of the value's creation when the given `@value` function is called. If multiple functions in a call stack use `$TraceCreation$`, only the trace from the bottom-most function will be included. `$TraceCreation$` is useful when the context that the value was created in is relevant when debugging crashes. The added execution cost for the function is trivial; however, it increases the memory size of the value by a few bytes per call currently on the stack at the time it gets created. ### `define` Pragmas These must be at the top of a category `define` immediately following `{`. - **`$FlatCleanup[`**_`memberName`_**`]$`**. (As of compiler version `0.21.0.0`.) Clear the `@value` member `memberName` before actually cleaning up the `@value` itself to avoid recursive cleanup. Use this when recursive cleanup might otherwise result in a stack overflow, e.g., with linked lists. Only *one* member can be specified in this pragma so that the implementation does not need to use a dynamically-sized cleanup queue to handle branching. - **`$ReadOnly[`**_`var1, var2, ...`_**`]$`**. (As of compiler version `0.16.0.0`.) See [Local Variable Rules](#local-variable-rules). Only applies to `@category` and `@value` members. - **`$Hidden[`**_`var1, var2, ...`_**`]$`**. (As of compiler version `0.16.0.0`.) See [Local Variable Rules](#local-variable-rules). Only applies to `@category` and `@value` members. - **`$ReadOnlyExcept[`**_`var1, var2, ...`_**`]$`**. (As of compiler version `0.22.1.0`.) Marks all `@category` and `@value` members as read-only *except* those listed. - If multiple `ReadOnlyExcept` are used, they are unioned rather than intersected. For example, `$ReadOnlyExcept[foo]$` and `$ReadOnlyExcept[bar]$` together make `$ReadOnlyExcept[foo, bar]$` and *not* `$ReadOnlyExcept[]$`. - If a variable is listed in both `ReadOnly` and `ReadOnlyExcept`, the variable is marked as read-only. ### `unittest` Pragmas These must be at the top of a `unittest` immediately following `{`. - **`$DisableCoverage$`**. (As of compiler version `0.20.0.0`.) Disables *all* collection of code coverage when `--log-traces` is used. This is useful if a particular unit test causes a massive number of lines to be executed. ### Local Variable Rules These pragmas alter how variables are dealt with locally: - **`$ReadOnly[`**_`var1, var2, ...`_**`]$`**. (As of compiler version `0.13.0.0`.) Marks `var1`, `var2`, etc. as read-only for the remainder of the statements in this context. Note that this only prevents *assignment* to the variable; it does not prevent making calls to functions that change the state of the underlying value. It also does not prevent calls to other functions modifying the variable. 
  scoped {
    Int i <- 0
  } in while (i < 100) {
    // i can still be overwritten here
    $ReadOnly[i]$
    // i can not be overwritten below here within the while block
  } update {
    // this is fine because it's in a different scope
    i <- i+1
  }
This can be used for any variable name visible in the current scope, including `@value` and `@category` members and argument and return variables. - **`$Hidden[`**_`var1, var2, ...`_**`]$`**. (As of compiler version `0.13.0.0`.) This works the same way as `ReadOnly` except that it also makes the variables inaccessible for reading. Note that this *does not* allow you to reuse a variable name; the variable name remains reserved. - As of compiler version `0.16.0.0` both `$ReadOnly[...]$` and `$Hidden[...]$` can be used at the top of a `define` for a `concrete` category to protect member variables. 
  define Type {
    $Hidden[foo]$
    $ReadOnly[bar]$

    @category Int foo <- 1
    // foo can still be read here for the purposes of initialization.
    @category Int bar <- foo
  }
Zeolite uses pragmas instead of something like `final` in Java for a few reasons: - In practice, a large percentage of variables to be treated as read-only require some sort of iterative or conditional setup. Marking the variable as `final` at declaration time would require creating a helper to initialize it. 
  Int nextPow2 <- 1
  while (nextPow2 < n) {
    nextPow2 <- 2*nextPow2
  }
  $ReadOnly[nextPow2]$
- A frequent source of errors in any language is multiple variables of the same type in the same scope. Marking some of them as read-only (or as hidden) within a certain context helps prevent errors caused by inadvertently using the wrong variable. - If your code works correctly *with* variables marked as read-only or as hidden, then it will also work correctly *without* such markings; the markings are only there to *cause* compile-time errors. This means that they add limited value to interpreting the code, and can therefore be kept separate from the respective variable's definition without loss of clarity. ### Expression Macros These can be used in place of language expressions. - **`$SourceContext$`**. (As of compiler version `0.7.1.0`.) Inserts a `String`-literal with information about the macro's location within the source file. Note that if this is used within an expression macro in `.zeolite-module` (see `ExprLookup` below), the context will be within the `.zeolite-module` file itself. (Remember that macro substitution *is not* a preprocessor stage, unlike the C preprocessor.) - **`$CallTrace$`**. (As of compiler version `0.24.0.0`.) Inserts an `optional Order` containing the current call trace. This is only available in `.0rt` test files and in `.0rx` with `$TestsOnly$`. This cannot be used outside of non-test code, just so that logic can't depend on where the call originated from. - **`$ExprLookup[`**_`MACRO_NAME`_**`]$`**. (As of compiler version `0.6.0.0`.) This directly substitutes in a language expression, as if it was parsed from that exact code location. _`MACRO_NAME`_ is the key used to look up the expression. Symbols will be resolved in the context that the substutition happens in. - **`MODULE_PATH`** is always defined. It is a `String`-literal containing the absolute path to the module owning the source file. This can be useful for locating data directories within your module independently of `$PWD`. - Custom macros can be included in the `.zeolite-module` for your module. This can be useful if your module requires different parameters from one system to another. 
    // my-module/.zeolite-module

    // (Standard part of .zeolite-module.)
    path: "."

    // Define your macros here.
    expression_map: [
      expression_macro {
        name: USE_DATA_VERSION    // Access using $ExprLookup[USE_DATA_VERSION]$.
        expression: "2020-05-12"  // Substituted in as a Zeolite expression.
      }
      expression_macro {
        name: RECURSION_LIMIT
        expression: 100000
      }
      expression_macro {
        name: SHOW_LIMIT
        // All Zeolite expressions are allowed.
        expression: "limit: " + $ExprLookup[RECURSION_LIMIT]$.formatted()
      }
    ]

    // (Standard part of .zeolite-module.)
    mode: incremental { }
The `name:` must only contain uppercase letters, numbers, and `_`, and the `expression:` must parse as a valid Zeolite expression. This is similar to C++ macros, except that the substitution must be *independently* parsable as a valid expression, and it can only be used where expressions are otherwise allowed. ## Known Language Limitations ### Reference Counting Zeolite currently uses reference counting rather than a garbage-collection system that might otherwise search for unreferenced objects in the background. While this simplifies the implementation, it is possible to have a reference cycle that prevents cleanup of the involved objects, thereby causing a memory leak. This can be mitigated by using [`weak` references](#optional-and-weak-values) in categories where a cycle is probable or guaranteed. For example, `LinkedNode` in `lib/container` is a doubly-linked list, which would create a reference cycle if both forward and reverse references were non-`weak`. [action-status]: https://github.com/ta0kira/zeolite/actions/workflows/haskell-ci.yml/badge.svg [action-zeolite]: https://github.com/ta0kira/zeolite/actions/workflows/haskell-ci.yml [brew-cabal]: https://formulae.brew.sh/formula/cabal-install [cabal]: https://www.haskell.org/cabal/#install-upgrade [category]: https://en.wikipedia.org/wiki/Category_theory [category-coproduct]: https://en.wikipedia.org/wiki/Coproduct [category-product]: https://en.wikipedia.org/wiki/Product_(category_theory) [clang]: https://clang.llvm.org/cxx_status.html [examples]: https://github.com/ta0kira/zeolite/tree/master/example [gcc]: https://gcc.gnu.org/ [ghc]: https://www.haskell.org/ghc/ [hackage]: http://hackage.haskell.org [hackage-status]: https://img.shields.io/hackage/v/zeolite-lang.svg?style=flat [hackage-zeolite-lang]: http://hackage.haskell.org/package/zeolite-lang [initial-terminal]: https://en.wikipedia.org/wiki/Initial_and_terminal_objects [kate]: https://kate-editor.org/ [lib]: https://github.com/ta0kira/zeolite/tree/master/lib [lib/container]: https://github.com/ta0kira/zeolite/tree/master/lib/container [lib/file]: https://github.com/ta0kira/zeolite/tree/master/lib/file [procedural]: https://en.wikipedia.org/wiki/Procedural_programming [oop]: https://en.wikipedia.org/wiki/Object-oriented_programming [variance]: https://en.wikipedia.org/wiki/Covariance_and_contravariance_%28computer_science%29 [xcode]: https://developer.apple.com/xcode/ [vscode]: https://code.visualstudio.com/ [zeolite]: https://github.com/ta0kira/zeolite [zeolite-issues]: https://github.com/ta0kira/zeolite/issues [zeolite-releases]: https://github.com/ta0kira/zeolite/releases [zeolite.xml]: https://github.com/ta0kira/zeolite/blob/master/editors/kate/zeolite.xml