sigil

Libraries

Sigil includes a collection of libraries for building real applications. This overview highlights the most useful ones.

Core Language

These libraries form the foundation of Sigil and are available in every program.

(sigil core)

Essential utilities that extend R7RS: list operations, association lists, string helpers, and common patterns. This module is automatically imported everywhere.

(filter-map (lambda (x) (and (> x 0) (* x 2))) '(-1 2 -3 4))
; => (4 8)

(assoc-ref 'name '((name . "Alice") (age . 30)))
; => "Alice"

(sigil struct)

Define fixed-slot, opaque struct types with keyword construction and default values (the deftype role; for open, dict-backed typed data see (sigil record)).

(import (sigil struct))

(define-struct point (x) (y default: 0))

(define p (point x: 10 y: 20))
(point-x p)  ; => 10

(sigil record)

Define dict-backed typed values (the defrecord role): open, extensible, immutable records with unique type identity and single inheritance. Every dict operation works on a record.

(import (sigil record))

(define-record buffer (name))
(define-record editor-buffer include: buffer (text default: ""))

(define e (editor-buffer name: "*scratch*"))
(buffer? e)              ; => #t (inherited)
(dict-ref e name:)       ; => "*scratch*" (it IS a dict)
(editor-buffer e text: "hi")  ; immutable typed update

(sigil method)

Open dispatch (multimethods) over records, structs, or core values with one primitive: parent-chain inheritance, a default: catch-all, custom dispatch functions, and cached dispatch safe for live redefinition.

(import (sigil record) (sigil method))

(define-multi describe)
(define-method describe (b buffer) (list 'buffer (buffer-name b)))
(define-method describe (x default:) (list 'value x))

(describe (editor-buffer name: "*e*"))  ; => (buffer "*e*")

(sigil match)

Pattern matching for destructuring and control flow.

(import (sigil match))

(match '(1 2 3)
  ((a b c) (+ a b c))    ; => 6
  (_ 'no-match))

Data Formats

(sigil json)

Parse and generate JSON with hash-table literals.

(import (sigil json))

(define data #{ name: "Sigil" version: "0.1.0" })
(json-encode data)
; => "{\"name\":\"Sigil\",\"version\":\"0.1.0\"}"

(json-decode "{\"x\": 10}")
; => #{ x: 10 }

(sigil yaml)

Parse and generate YAML, with block and flow styles, anchors and aliases, and multi-document streams.

(import (sigil yaml))

(define data (yaml-read "name: sigil\nversion: 0.7.0"))
(yaml-write data)

(sigil markdown)

Parse Markdown to an AST for processing or rendering.

(import (sigil markdown))

(define doc (markdown-parse "# Hello\n\nSome *text*."))

(sigil sxml)

Work with XML/HTML as S-expressions.

(import (sigil sxml))

(sxml->string
  '(html (head (title "Hello"))
         (body (p "Welcome!"))))

(sigil org)

Parse Org Mode documents into SXML, ready to transform or render however you like.

(import (sigil org))

(org->sxml "#+TITLE: Notes\n\n* Tasks\n\nWrite the docs.")

Networking

(sigil http)

HTTP client and server with a simple, functional API.

(import (sigil http))

;; Client
(define response (http-get "https://example.com/api"))
(http-response-body response)

;; Server
(define (handler req)
  (http-response HTTP-OK "Hello, World!"))

(http-serve 8080 handler)

(sigil socket)

Low-level TCP and UDP networking.

(import (sigil socket))

(define sock (tcp-connect "example.com" 80))
(socket-send sock "GET / HTTP/1.0\r\n\r\n")
(socket-recv sock 1024)

(sigil websocket)

WebSocket client and server support.

(import (sigil websocket))

(websocket-connect "wss://echo.websocket.org"
  (lambda (ws)
    (websocket-send ws "Hello!")
    (display (websocket-recv ws))))

(sigil tls)

Secure TCP connections over TLS. Certificates are verified against your system's trust store by default, so you don't have to wire that up yourself.

(import (sigil tls))

(define conn (tls-connect "example.com" 443))
(tls-write conn "GET / HTTP/1.0\r\n\r\n")
(tls-read conn 1024)

(sigil irc)

Talk to IRC networks. It handles the protocol so you can focus on your bot or client: joining channels, sending messages, and reacting to events.

(sigil xmpp)

An XMPP client with STARTTLS and SASL authentication for chat and messaging, including full JID parsing.

Web

(sigil web)

A framework for building interactive web apps where the server stays in charge. You render views as SXML, push live updates to the browser over Server-Sent Events, and wire up interactions with declarative data-sg-* attributes, so there's no hand-written client JavaScript to maintain. Routing, middleware, static files, and cookies come built in.

(import (sigil web routes))

(define app
  (router
    (route GET "/" home-handler)
    (route GET "/users/:id" user-handler)
    (route POST "/api/login" login-handler)))

(sigil browser)

The other side of the browser story: Sigil compiled to WebAssembly, running client-side. This package bridges the core browser APIs (async scheduling, IndexedDB, and local storage), and the companion sigil-wasm-* libraries add the DOM, Canvas2D, WebGL, and networking bindings.

(sigil web client)

A react-like rendering layer for browser apps compiled to WebAssembly. You describe views as SXML and mount them into a DOM root, then re-render in place as your state changes. It builds on the WASM DOM bridge so your application code never touches the low-level backend, and it stays independent of the server-side (sigil web) framework.

(import (sigil web client))

(define root (web-client-root "#app"))
(web-client-mount root (lambda () `(div "Hello, world!")))
(web-client-update root (lambda () `(div "Updated!")))

Security

(sigil crypto)

Cryptographic building blocks: hashing, HMACs, key derivation, ECDSA and ECDH, AES-GCM, and secure random bytes. It's the foundation the TLS library is built on.

(import (sigil crypto))

(sha256 "hello")         ; => "2cf24dba5fb0a30e..."
(base64-encode "hello")  ; => "aGVsbG8="

(sigil jwt)

Create and verify JSON Web Tokens, the tokens behind most modern API authentication.

(import (sigil jwt))

(define token (jwt-encode '((sub . "user-123")) "my-secret"))
(jwt-decode token "my-secret")  ; => claims dict, or #f if invalid

(sigil oauth)

An OAuth 2.0 client for signing users in through providers like Google and GitHub. It handles the authorization redirect and the code-for-token exchange for you.

System

(sigil io)

File I/O beyond R7RS: read entire files, write strings, file metadata.

(import (sigil io))

(write-file "output.txt" "Hello, file!")
(read-file "output.txt")  ; => "Hello, file!"

(sigil fs)

Filesystem operations: directories, paths, globbing.

(import (sigil fs))

(directory-list ".")
(glob "src/**/*.sgl")
(file-exists? "config.json")

(sigil process)

Spawn and manage external processes.

(import (sigil process))

(define result (run "ls" "-la"))
(process-output result)

(sigil path)

Path manipulation that works across platforms.

(import (sigil path))

(path-join "src" "lib" "main.sgl")  ; => "src/lib/main.sgl"
(path-extname "file.tar.gz")        ; => ".gz"
(path-dirname "/home/user/file")    ; => "/home/user"

Concurrency

(sigil async)

Cooperative multitasking with lightweight tasks.

(import (sigil async))

(with-async
  (go (begin
        (display "Task A\n")
        (sleep 0.1)
        (display "Task A done\n")))
  (go (begin
        (display "Task B\n")
        (sleep 0.05)
        (display "Task B done\n"))))

(sigil channels)

CSP-style channels for communicating between tasks.

(import (sigil async)
        (sigil channels))

(with-async
  (define ch (make-channel))
  (go (channel-send ch "hello"))
  (display (channel-recv ch)))  ; => "hello"

Database

(sigil sqlite)

SQLite database access.

(import (sigil sqlite))

(define db (sqlite-open "app.db"))
(sqlite-exec db "CREATE TABLE users (id INTEGER, name TEXT)")
(sqlite-exec db "INSERT INTO users VALUES (1, 'Alice')")
(sqlite-query db "SELECT * FROM users")

Text Processing

(sigil string)

String utilities beyond R7RS.

(import (sigil string))

(string-split "a,b,c" ",")        ; => ("a" "b" "c")
(string-join '("a" "b" "c") "-")  ; => "a-b-c"
(string-trim "  hello  ")         ; => "hello"

(sigil regex)

Regular expressions in the RE2 / Go syntax. One match or search takes time linear in the input for every pattern, so a pattern like (a*)*b cannot hang a script the way it can with a backtracking engine. Positions are character indexes that work with substring. Also exported from the shell prelude.

(import (sigil regex))

(regex-match? "^[0-9a-f]{64}$" digest)                  ; whole string
(match-group (regex-search "v(\\d+)" "tag v12") 1)      ; => "12"
(regex-replace-all "(\\w+)@(\\w+)" "me@host" "$2/$1")   ; => "host/me"
(regex-split "\\s*,\\s*" "a , b,c")                     ; => ("a" "b" "c")

(sigil ansi)

Terminal colors and formatting.

(import (sigil ansi))

(display (ansi-bold (ansi-red "Error: ")))
(display "Something went wrong\n")

Command-Line Tools

(sigil args)

Parse command-line arguments with flags and subcommands.

(import (sigil args))

(define parser
  (args-parser
    (flag 'verbose "-v" "--verbose" "Enable verbose output")
    (option 'output "-o" "--output" "Output file" default: "out.txt")))

(define opts (args-parse parser (command-line)))

(sigil tui)

Build full-screen terminal interfaces with a render-and-update model, layout helpers, and mouse tracking. If you've enjoyed tools like htop or lazygit, this is how you write your own.

Development

(sigil test)

Testing framework with assertions and test suites.

(import (sigil test))

(test-group "math"
  (test "addition" (assert-equal (+ 1 2) 3))
  (test "multiplication" (assert-equal (* 3 4) 12)))

(run-tests)

(sigil repl)

Embed a REPL in your application for debugging.

(sigil nrepl)

Run a network REPL so your editor can connect and evaluate code in a live program. Point Emacs or VS Code at the port and start hacking.

(import (sigil nrepl))

(define server (nrepl-start 7888))

R7RS Compatibility

Sigil includes the standard R7RS libraries:

  • (scheme base) - Core language
  • (scheme write) - Output procedures
  • (scheme read) - Input procedures
  • (scheme file) - File ports
  • (scheme char) - Character operations
  • (scheme cxr) - Extended car/cdr
  • (scheme lazy) - Delayed evaluation
  • (scheme case-lambda) - Multi-arity procedures
  • (scheme process-context) - Environment access

All libraries

Beyond the libraries that ship with Sigil, the Sigil project publishes 59 more, each from its own repository. You add one to a project as a dependency in its package.sgl. A name with an arrow links to the library's repository, where its README is the documentation.

Ships with Sigil

Web and networking

Data and storage

Documents and publishing

Systems and terminals

Graphics and audio

Developer tools

Service clients