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

2# Syntax

4> Expressions, literals, quoting, and comments.

6## Expressions

8Sigil code consists of expressions. Every expression evaluates to a value.

10```scheme

1142 ; number literal

12"hello" ; string literal

13(+ 1 2) ; procedure call

14(if (> x 0) "pos" "neg") ; conditional

15```

17Procedure calls use prefix notation: `(operator operand ...)`.

19## Literals

21### Numbers

23```scheme

2442 ; integer

25-17 ; negative integer

263.14159 ; floating point

271.5e10 ; scientific notation

28#xff ; hexadecimal (255)

29#b1010 ; binary (10)

30#o755 ; octal (493)

31```

33Integers are 62-bit signed on 64-bit platforms. Floating point uses IEEE 754 double precision.

35### Strings

37Strings are enclosed in double quotes. They store UTF-8 text internally.

39```scheme

40"hello, world"

41"line one\nline two" ; newline escape

42"tab\there" ; tab escape

43"quote: \"hi\"" ; escaped quote

44"unicode: \u03BB" ; lambda character

45```

47Escape sequences:

48- `\n` newline, `\t` tab, `\r` carriage return

49- `\\` backslash, `\"` double quote

50- `\xNN` hex byte, `\uNNNN` unicode code point

52### Characters

54Characters represent single Unicode code points.

56```scheme

57#\a ; lowercase a

58#\Z ; uppercase Z

59#\space ; space character

60#\newline ; newline

61#\tab ; tab

62#\x03BB ; lambda by hex code

63```

65### Booleans

67```scheme

68#t ; true

69#f ; false

70```

72Only `#f` is false in conditionals; everything else (including `0`, `""`, `'()`) is true.

74### Symbols

76Symbols are interned identifiers. They're often used as keys or enum values.

78```scheme

79'hello ; quoted symbol

80'with-hyphen ; hyphens are valid

81'+ ; operators are symbols too

82```

84### Lists

86Lists are built from pairs (cons cells). The empty list is `'()`. Lists are the primary sequence type in Sigil.

88```scheme

89'(1 2 3) ; list of numbers

90'(a b c) ; list of symbols

91'(1 "two" three) ; mixed types

92(list 1 2 3) ; same as '(1 2 3)

93(cons 1 '(2 3)) ; => (1 2 3)

94```

96### Pairs

98A pair holds two values: car (first) and cdr (rest).

100```scheme

101(cons 'a 'b) ; => (a . b) - dotted pair

102(car '(a . b)) ; => a

103(cdr '(a . b)) ; => b

104```

105

106### Vectors

107

108Vectors are fixed-size mutable arrays with O(1) random access.

109

110```scheme

111#(1 2 3) ; vector literal

112(vector 1 2 3) ; same as #(1 2 3)

113(vector-ref #(a b c) 1) ; => b

114```

115

116### Arrays

117

118Sigil arrays use `#[...]` syntax and provide O(1) indexed access with persistent (immutable) semantics.

119

120```scheme

121#[1 2 3] ; array literal

122(array 1 2 3) ; same as #[1 2 3]

123(array-ref #[a b c] 0) ; => a

124```

125

126### Dicts

127

128Dicts are hash maps with keyword keys.

129

130```scheme

131#{ name: "Alice" age: 30 } ; dict literal

132(dict name: "Alice" age: 30) ; same thing

133(dict-ref d name:) ; => "Alice"

134(dict-set d city: "Boston") ; returns new dict

135```

136

137## Quoting

138

139Quote (`'`) prevents evaluation:

140

141```scheme

142'hello ; symbol hello, not variable lookup

143'(1 2 3) ; list, not procedure call

144```

145

146Quasiquote (`` ` ``) allows selective evaluation within a quoted template:

147

148```scheme

149`(1 2 ,(+ 1 2)) ; => (1 2 3)

150`(a ,@'(b c) d) ; => (a b c d) - splicing

151```

152

153## Comments

154

155```scheme

156; line comment - everything to end of line

157

158#; (this entire expression is commented out)

159

160#|

161 Block comment.

162 Can span multiple lines.

163|#

164```

165

166Use `;;` for section headers and internal notes, `;;;` for docstrings on exported definitions.