The Standard Library

Cone's standard library is a set of packages that come with the language, in the packages folder of its repository. Each is written in Cone (a few lean on the C library or the operating system), each is built on its own, and a program uses one by importing it by name. This page lists them, says what each is for, how to import it, and where it is documented. Four of them have pages of their own: files, folders, paths, the environment and processes; time; HTTP, TLS and URLs; and testing.

The graphics, windowing and 3-D packages in the same folder are not described here.

Importing a package#

A package is imported by its name, with the import statement of import and extern. There is no list of dependencies to write: Congo reads the import lines, finds each package by name (Packages and Congo), builds it, and links it. The three usual forms:

mod tour;

import stdio use *;
import collections use *;
import time use Duration;
import textdiff;

fn main() {
  // 'use *' brings in every public name: List, String, Dict...
  mut names = List[String].empty();
  names.push(String.from("collections"));
  names.push(String.from("time"));
  printUInt(u64.from(names.len()));
  printStr(" packages used\n");

  // 'use Duration' brings in just that one
  imm pause = Duration.fromMillis(1500);
  printInt(pause.millis());
  printStr(" ms\n");

  // with no 'use', the package's name is the way in: textdiff.unifiedText
  imm shown = textdiff.unifiedText("a\n", "b\n", "old", "new");
  printStr(shown.view());
}

which prints:

2 packages used
1500 ms
--- old
+++ new
@@ -1 +1 @@
-a
+b

One package needs no import at all: core, the prelude, whose names ( Option, Result, str, the atomic values, the panic functions) every module has already.

The packages#

Foundations#

Package	What it is for
core (no import)	The prelude: Option, Result, str and the other types and functions of the language itself, and its intrinsics (Intrinsics).
stdio import stdio use *;	Printing text and numbers to standard output and standard error: printStr, printInt, print <- x, and the eprint forms for standard error. Standard output is buffered; print.flush() writes it out before another program writes to the same place.
libc import libc;	The ISO C library as C spells it: C names, C types, errors as C reports them. A raw layer for programs that call C; the packages below wrap it.
posix import posix;	The POSIX functions beyond ISO C (files, directories, processes, the environment), as raw bindings over the Windows C runtime. fs and env are the Cone layer over it.
conestd (no import)	The runtime every program links beside its own code: the end of a panic, printing, and the raw blocks the heap's memory comes from. A program never imports it.

Collections and memory#

Package	What it is for
collections import collections use *;	List, String, Dict, OrderedDict, Set and Deque (Collection Types).
arena import arena use *;	Arena: values allocated one after another and freed together (Region Strategies).
pool import pool use *;	Pool[T]: values added and removed one at a time, reached by a generational Ref that stops reaching anything once its value is removed (Region Strategies).
rcweak import rcweak use *;	Rcw and Weak[T]: reference counting with weak references that do not keep a value alive (Weak References).
collector import collector;	Gc, a tracing garbage-collected region. Single-threaded, for code outside actors only, and discouraged: inside an actor, use the actor's own collected region (Region Strategies).

Threads, locks and actors#

Package	What it is for
thread import thread;	OS threads: start, join, detach, sleep, park (Concurrency).
sync import sync use *;	What threads share safely: Arc, the futex, Mutex, Rwlock, Condvar, Once, channels and the one-shot Oneshot (Concurrency, Thread Communications).
actors import actors;	The runtime an actor declaration runs on: mailboxes, the scheduler of worker threads, futures, parallel loops. A module that declares an actor or uses parallel each imports it (Actors, Parallel each).

Files, paths, environment and processes#

Package	What it is for
fs import fs;	Files and folders: read and write whole files, list, walk, rename, remove, stat, the current folder.
path import path;	File paths taken apart and put together as text; never asks the file system anything.
env import env;	The program's environment variables.
process import process;	Running another program and waiting for it; the program's own arguments.

All four are on their own page.

Time#

Package	What it is for
time import time use *;	Duration, Instant, Timestamp and Clock.
calendar import calendar;	Civil dates and times over a Timestamp, and RFC 3339 and HTTP date text.
timewheel import timewheel use *;	Timers that cost almost nothing to arm and cancel, for the I/O loop.

All three are on their own page.

Asynchronous I/O#

Package	What it is for
iobuf import iobuf use *;	Owned buffers for I/O, lent to an operation by moving them: IoBuf, Pool, Bytes, Chain.
iocore import iocore use *;	The completion loop: hand it a job (receive, send, accept, read a file, wake at a time) and later get exactly one answer. Jobs may carry a deadline and join a cancel group.
aio import aio;	I/O an actor awaits: a behaviour awaits a socket's operation and pauses until the answer comes.
diag import diag;	Records of where an I/O operation's time went: one record per operation, a loop's counters, latency histograms.

I/O and Concurrency describes them.

HTTP, TLS and URLs#

Package	What it is for
url import url;	URLs read, resolved and written as text.
http import http;	HTTP's message types, shared by every version.
http1 import http1;	HTTP/1.1's connection core, with no I/O of its own.
httpconn import httpconn;	HTTP over sockets on an I/O loop, client and server.
httpclient import httpclient;	Fetching an http:// or https:// URL in one call.
tls import tls;	TLS 1.2 and 1.3 over OpenSSL, with no I/O of its own.

All six are on their own page.

Text: textdiff and toml#

Package	What it is for
textdiff import textdiff;	The differences between two texts, line by line, and the unified diff that shows them, as diff -u prints it.
toml import toml;	A reader for a subset of TOML: tables, and string, integer, boolean and list-of-string values. It reads Congo's manifests, and suits any small configuration file that keeps to the subset.

textdiff#

textdiff.unifiedText(a, b, aName, bName) compares two texts, split into lines, and answers the unified diff as a String, empty when the texts are the same. A fifth argument, around, sets how many unchanged lines show around each change (3 unless given). unified does the same for two lists of lines, and spans answers the edit itself as a list of stretches, each equal, deleted, inserted or replaced.

mod showdiff;

import stdio use *;
import textdiff;

fn main() {
  imm shown = textdiff.unifiedText("one\ntwo\nthree\n", "one\n2\nthree\n", "want", "got");
  printStr(shown.view());
}

prints:

--- want
+++ got
@@ -1,3 +1,3 @@
 one
-two
+2
 three

toml#

toml.parse(text) answers a Result[Document, TomlError]. A Document holds tables, and doc["package"] is a table (a panic if there is none; ask doc.has("package") first). A table answers getString, getInt, getBool and getStrings, each an Option that is None when the key is missing or holds another kind of value. A TOML feature outside the subset (floats, dates, inline tables, dotted names) is an error whose message names the line.

mod readname;

import stdio use *;
import toml;

fn main() i32 {
  mut doc = new toml.Document();
  match toml.parse("[package]\nname = \"hello\"\nversion = \"0.1.0\"\n") {
    case mut ok Ok { doc <=> ok; }
    case imm e Error {
      imm m = e.message();
      printStr(m.view());
      return 1i32;
    }
  }
  match doc["package"].getString("name") {
    case imm n Some { printStr(n.view()); printStr("\n"); }
    case is None { printStr("no name\n"); }
  }
  0i32;
}

prints hello.

Testing#

Package	What it is for
testing import testing use *;	Checks for a package's tests (expectInt, require, done), run by congo test; see Testing.

Where they run#

These run on Windows only: posix, fs, env (over posix), process, iobuf (its blocks come from VirtualAlloc), and every package built on iobuf or iocore: iocore (over an I/O completion port) itself, aio, http1, httpconn, httpclient and tls. path reads Windows' paths: drive letters and shares, and both / and \ as separators.

The others use nothing that belongs to Windows alone. Of these, sync, thread, actors and time are the ones that have been run on Linux so far, with core and a program that only prints.