Editing this Documentation

Information Architecture

How-to guides

Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. Writing a good guide requires thinking about what your users are trying to do.

Further reading: how-to guides in the Diátaxis framework

Reference Pages

Reference pages are ideal for outlining how things work in terse and clear terms. Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you’re documenting.

Further reading: reference pages in the Diátaxis framework

Regular snippet

public fun main() {
  print("Hello, World!")
}

With title

src/main.hylo

public fun main() {
  print("Hello, World!")
}

Shell

No frame:

echo "Command without frame"

With frame (default):

echo "This terminal frame has no title"

With title:

PowerShell terminal example

Write-Output "This one has a title!"

Word wrap

No wrapping (default):

cmake -D LLVM_DIR=<LLVM>/lib/cmake/llvm -D CMAKE_BUILD_TYPE=<build-type> -D BUILD_TESTING=1 -G Ninja -S . -B .build

Wrap:

cmake -D LLVM_DIR=<LLVM>/lib/cmake/llvm -D CMAKE_BUILD_TYPE=<build-type> -D BUILD_TESTING=1 -G Ninja -S . -B .build

Hanging indent:

cmake -D LLVM_DIR=<LLVM>/lib/cmake/llvm -D CMAKE_BUILD_TYPE=<build-type> -D BUILD_TESTING=1 -G Ninja -S . -B .build

Highlights

internal type SpawnFrame<E: Movable & Deinitializable>: Deinitializable {

  /// The base frame object needed by the underlying implementation.
  private var base_frame: SpawnFrameBase

  /// What needs to be called to produce the value in the future.
  private var f: [E]() -> Int

  /// The result of the computation.
  private var r: Optional<Int>

  /// Initializes `self` with `f`, and spawns the computation.
  internal init(_ f: sink [E]() -> Int) {
    &self.base_frame = .new()
    &self.f = f
    &self.r = .none()

    let local_f = fun (_ frame: inout SpawnFrameBase) -> Void {
      var this = PointerToMutable<Self>(type_punning: mutable_pointer[to: &frame])
      &this.unsafe[].r = this.unsafe[].f() as _
    }
    concore2full_spawn2(&self.base_frame, local_f)
  }

  /// Awaits the result of the computation.
  ///
  /// - Note: May return on a different OS thread than the one that called this.
  internal fun await() inout -> Int {
    concore2full_await(self.base_frame)
    if let r: Int = self.r {
      let copy = r.copy()
      &self.r = .none()
      return copy
    } else {
      fatal_error()
    }
  }

  /// Allocate an object of `Self` on the heap and initialize it with `f`.
  internal static fun allocate(_ f: sink [E]() -> Int) -> PointerToMutable<Self> {
    let p: PointerToMutable<Self> = .allocate(count: 1)
    Self.`init`(self: &p.unsafe[], f)
    return p
  }

}

Squiggles

public fun main() {
  let gravity = 9.81
  &gravity = 11.2 error: cannot assign, `gravity` is a `let` binding
}

Folder Structure

• DirectorySources

  • DirectoryHello

    • Hello.hylo
  • DirectoryGreetings

    • Greetings.hylo

Runnable snippets

Wrap a code block in <Playground> to let readers run it in their browser, edit it, and open it in the full-screen playground. The code block renders as any other, highlights and all; the compiler, compiled to WebAssembly (the npm package @hylo-lang/hylo-wasm), is only downloaded when a reader first runs a snippet. That is about 15 MB compressed, once, which the browser then caches.

Only make a snippet runnable if the compiler can run it today. The expect attribute says what it does (exit N, trap, error or ok), and the site’s tests check every snippet still does it; the site does not build if a snippet has none.

The import path is relative to the page: from a page in src/content/docs/docs/<section>/, the component is four directories up.

import Playground from '../../../../components/playground/Playground.astro';

<Playground expect="exit 42">
```hylo
public fun main() -> Int32 { ... }
```
</Playground>

public fun main() -> Int32 {
  var x = 40
  &x = x + 2
  return if x == 42 { 42 } else { 1 }
}

RunEditOpen in the playground

Showing what the compiler makes of it

outputs lists what to show once the code has run, as tabs: result (the default), diagnostics, raw-ir, ir, llvm and assembly. focus limits Hylo IR to the functions named, and optimization sets LLVM’s level. Code fence attributes still apply: line 4 is highlighted here.

<Playground outputs="result ir llvm assembly" focus="factorial" optimization={2} expect="exit 120">

fun factorial(n: sink Int32) -> Int32 {
  var m: Int32 = 1
  while n > (0 as Int32) {
    &m = m * n
    &n = n - (1 as Int32)
  }
  return m
}

public fun main() -> Int32 {
  factorial(5 as Int32)
}

RunEditOpen in the playground

Showing an error

A snippet that does not compile shows its diagnostics; clicking one takes the reader to it.

public fun main() -> Int32 {
  40 + 2 // Integer literals are `Int` unless something says otherwise.
}

RunEditOpen in the playground

Checking code that is not a program

stopAfter="typing" only type checks, for a snippet with no main; stopAfter="lowering" also produces its IR. editable={false} keeps the reader from editing a snippet, and standardLibrary={false} compiles it without the standard library.

struct Pair is Deinitializable {
  public memberwise init
  public var a: Int32
  public var b: Int32
}

fun sum(_ p: Pair) -> Int32 { p.a + p.b }

CheckEditOpen in the playground

The Hylo IR and the WebAssembly assembly LLVM prints have code fence languages of their own, hylo-ir and wasm-asm:

fun main(set %p0: Int32) {
%b0:
  %r0 = subfield %p0 at 0 as i32
  %r1 = access [set] %r0
  %r2 = store i32 42 to %r1
  %r3 = end %r1
  %r4 = return
}