build/dev/lib/_pkg/sigil-stdlib/language/modules.md

2# Modules

4> Library definition, imports, and exports.

6## File Extension

8Sigil source files use the `.sgl` extension:

9- `main.sgl` - source files

10- `utils.sgl` - library modules

11- `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.

15## define-library

17Define a module with explicit imports and exports.

19```scheme

20(define-library (myapp utils)

21 (import (sigil string))

22 (export helper-function

23 useful-constant)

24 (begin

25 (define useful-constant 42)

27 (define (helper-function x)

28 (string-append "Result: " (number->string x)))))

29```

31### Structure

33A library definition contains:

34- **Name**: List of symbols, e.g., `(myapp utils)`

35- **Imports**: Libraries to import

36- **Exports**: Bindings to make public

37- **Body**: Definitions (inside `begin`)

39### File Naming

41Library name maps to file path:

42- `(sigil json)` → `sigil/json.sgl`

43- `(myapp utils)` → `myapp/utils.sgl`

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

47## import

49Bring bindings from other libraries into scope.

51```scheme

52;; Import entire library

53(import (sigil json))

55;; Import multiple libraries

56(import (sigil string)

57 (sigil path))

58```

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

62### Selective Import

64```scheme

65;; Import only specific bindings

66(import (only (sigil string)

67 string-split

68 string-join))

70;; Import all except certain bindings

71(import (except (sigil io) display))

73;; Rename on import

74(import (rename (sigil json)

75 (json-encode encode)

76 (json-decode decode)))

78;; Add prefix to all imports

79(import (prefix (sigil http) http:))

80; Now use http:get, http:post, etc.

81```

83### Combining Forms

85```scheme

86(import (only (rename (sigil json)

87 (json-encode encode))

88 encode))

89; Imports json-encode as encode

90```

92## export

94Declare which bindings are public.

96```scheme

97(define-library (myapp api)

98 (export public-function

99 PublicRecord

100 CONSTANT)

101 (begin

102 ;; Exported

103 (define (public-function x) ...)

104 (define-record-type PublicRecord ...)

105 (define CONSTANT 100)

106

107 ;; Not exported (private)

108 (define (internal-helper x) ...)))

109```

110

111### Rename on Export

112

113```scheme

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

115```

116

117## Implicit Imports

118

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

120- Output: `println`, `eprintln`, `print`, `eprint`, `format`

121- Basic list operations: `map`, `filter`, `fold-left`, `append`

122- Predicates: `null?`, `pair?`, `number?`, `string?`

123- Arithmetic: `+`, `-`, `*`, `/`, `=`, `<`, `>`

124- Control: `if`, `cond`, `case`, `when`, `unless`

125- And more...

126

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

128

129## Library Search Order

130

131When importing a library, Sigil searches:

132

1331. **Load path directories** (`SIGIL_LIB_PATH`, in order)

1342. **Embedded modules** (in bundled executables)

1353. **Standard library locations**

136

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

138

139## Example: Complete Module

140

141```scheme

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

143

144(define-library (myapp strings)

145 (import (sigil string))

146 (export slug

147 title-case)

148 (begin

149

150 ;;; Convert a string to a URL-friendly slug.

151 (define (slug str)

152 (string-join

153 (string-split (string-downcase str) " ")

154 "-"))

155

156 ;;; Capitalize the first letter of each word.

157 (define (title-case str)

158 (string-join

159 (map capitalize-word

160 (string-split str " "))

161 " "))

162

163 ;; Internal helper

164 (define (capitalize-word word)

165 (if (string-empty? word)

166 word

167 (string-append

168 (string-upcase (substring word 0 1))

169 (substring word 1))))))

170```