Modules

Library definition, imports, and exports.

File Extension

Sigil source files use the .sgl extension:

• main.sgl - source files
• utils.sgl - library modules
• package.sgl - package definitions

The .scm and .sld extensions are supported for compatibility with existing Scheme code, but .sgl is the default and preferred extension for new Sigil projects.

define-library

Define a module with explicit imports and exports.

(define-library (myapp utils)
  (import (sigil string))
  (export helper-function
          useful-constant)
  (begin
    (define useful-constant 42)

    (define (helper-function x)
      (string-append "Result: " (number->string x)))))

Structure

A library definition contains:

• Name: List of symbols, e.g., (myapp utils)
• Imports: Libraries to import
• Exports: Bindings to make public
• Body: Definitions (inside begin)

File Naming

Library name maps to file path:

• (sigil json) → sigil/json.sgl
• (myapp utils) → myapp/utils.sgl

Files are searched in the library load path (SIGIL_LIB_PATH).

import

Bring bindings from other libraries into scope.

;; Import entire library
(import (sigil json))

;; Import multiple libraries
(import (sigil string)
        (sigil path))

Note: (sigil core) is automatically imported into every module—you don't need to import it explicitly.

Selective Import

;; Import only specific bindings
(import (only (sigil string)
              string-split
              string-join))

;; Import all except certain bindings
(import (except (sigil io) display))

;; Rename on import
(import (rename (sigil json)
                (json-encode encode)
                (json-decode decode)))

;; Add prefix to all imports
(import (prefix (sigil http) http:))
; Now use http:get, http:post, etc.

Combining Forms

(import (only (rename (sigil json)
                      (json-encode encode))
              encode))
; Imports json-encode as encode

export

Declare which bindings are public.

(define-library (myapp api)
  (export public-function
          PublicRecord
          CONSTANT)
  (begin
    ;; Exported
    (define (public-function x) ...)
    (define-record-type PublicRecord ...)
    (define CONSTANT 100)

    ;; Not exported (private)
    (define (internal-helper x) ...)))

Rename on Export

(export (rename internal-name external-name))

Implicit Imports

Every module implicitly imports (sigil core), which provides:

• Output: println, eprintln, print, eprint, format
• Basic list operations: map, filter, fold-left, append
• Predicates: null?, pair?, number?, string?
• Arithmetic: +, -, *, /, =, <, >
• Control: if, cond, case, when, unless
• And more...

You don't need to explicitly import (sigil core).

Library Search Order

When importing a library, Sigil searches:

1. Load path directories (SIGIL_LIB_PATH, in order)
2. Embedded modules (in bundled executables)
3. Standard library locations

First match wins. This allows overriding standard libraries for debugging.

Example: Complete Module

;;; (myapp strings) - String utilities for the myapp project.

(define-library (myapp strings)
  (import (sigil string))
  (export slug
          title-case)
  (begin

    ;;; Convert a string to a URL-friendly slug.
    (define (slug str)
      (string-join
        (string-split (string-downcase str) " ")
        "-"))

    ;;; Capitalize the first letter of each word.
    (define (title-case str)
      (string-join
        (map capitalize-word
             (string-split str " "))
        " "))

    ;; Internal helper
    (define (capitalize-word word)
      (if (string-empty? word)
          word
          (string-append
            (string-upcase (substring word 0 1))
            (substring word 1))))))