Data Literals: #map{...}, #set{...}, and [...]

Turmeric's data literals give map, vec, and set construction a compact literal syntax whose slot values are ordinary expressions, evaluated at runtime in the surrounding scope. They are sugar over the hamt-of, vec-of, and set-of stdlib macros.

(def payload #map{:name name :age (+ age 1) :active 1})
(def points  [(make-point 0 0) (make-point 1 1) origin])
(def small   #set{1 2 3})

def payload #map{:name name :age {age + 1} :active 1}
def points [make-point(0 0) make-point(1 1) origin]
def small #set{1 2 3}

The three forms

[1 2 3]                       ; => (vec-of 1 2 3)
#map{:a 1 :b x}               ; => map {:a -> 1, :b -> x}
#set{:literal x (compute)}    ; (compute) evaluated once

[1 2 3]
; => (vec-of 1 2 3)
#map{:a 1 :b x}
; => map {:a -> 1, :b -> x}
#set{:literal x (compute)}
; (compute) evaluated once

Element types

[...] and the value slots of #map{...} accept any scalar element type -- :int, :cstr, :bool, :nil, or :float -- not just :int. All elements of a vector must unify to one type, and all map values to one type (a mixed literal such as [1 "x"] is a TUR-E0001 on the offending element). Elements are stored through an :int carrier slot, so reads recover the type with an ascription:

[1.5 2.5 3.5]                 ; Vec[float]
(:: (vec-get fs 0) :float)    ; => 1.5

#map{1 "one" 2 "two"}         ; Map[int cstr]
(:: (map-get m 1) :cstr)      ; => "one"

[1.5 2.5 3.5]
; Vec[float]
::(vec-get(fs 0) :float)
; => 1.5
#map{1 "one" 2 "two"}
; Map[int cstr]
::(map-get(m 1) :cstr)
; => "one"

Map keys may be any Hash/MapKey scalar -- int, keyword, string, bool, float32, float, or a user type with Hash/Eq/MapKey instances. The literal has type Map[K V]: the typed map-get/map-assoc/ map-has?/map-dissoc surface reads and writes it, and a key/value-type mismatch is a TUR-E0001. Int and keyword keys are int-valued (a keyword normalizes to a content hash); string keys are compared by content (two distinct pointers with equal text are one key). See #map{...} keys below.

Keyword keys: a keyword key is a first-class :Sym value rather than a content-hashed string -- the map is keyed by Sym pointer identity via Hash[Sym] / MapKey[Sym]. See the symbols guide. Aggregate (multi-word struct/ADT) key types must supply their own MapKey instance; values may be any type (scalars, floats, and heap handles like Vec[A] all ride the int64 carrier).

Slots are arbitrary expressions -- variable references, calls, nested literals -- and the normal typechecker handles them.

[...] is only a vec in expression position

The reader parses every [...] as the same vector form. Binding forms (defn/fn/defmethod parameter lists, and let/loop/for/... binding vectors) consume that form as a binding spec before it is ever treated as a value. Only a [...] that reaches expression position lowers to (vec-of ...). This is the same rule Clojure uses: [x y] is always a vector; the surrounding form decides whether it is read as a binding spec or a value.

(defn add [x : int y : int] : int (+ x y))   ; [x :int y :int] is a param list
(let [a 1 b 2] (+ a b))                   ; [a 1 b 2] is a binding vector
(def v [1 2 3])                           ; [1 2 3] is a vec literal

defn add [x :int y :int] :int
  +(x y)
; [x :int y :int] is a param list
let [a 1 b 2]
  +(a b)
; [a 1 b 2] is a binding vector
def v [1 2 3]
; [1 2 3] is a vec literal

#map{...} keys

Keys must be a keyword, string literal, or int literal -- anything else (a variable, a call) is rejected at read time with TUR-E0282. Computed keys are intentionally disallowed so a reader can tell keys from values at a glance.

How a key lowers depends on its form:

• An int key passes through unchanged (identity-keyed, zero overhead).
• A keyword key lowers to (hamt/hash-str "name") -- the keyword's content hash is the int key, so two equal keywords collide deliberately. Look a keyword key back up by hashing it the same way:

turmeric (let [m #map{:name 1 :age 2} k (hamt/hash-str "name")] (map-get m k)) ; => 1

let [m #map{:name 1 :age 2}
        k (hamt/hash-str "name")]
  map-get(m k)
; => 1

• A literal whose keys are all string literals lowers to a content-keyed map. The string itself is the key (compared by content, not by pointer or hash), so two distinct pointers with equal text are one key. Read string keys with the same unified map-get / map-has? / map-dissoc accessors (they dispatch through Hash[cstr] / MapKey[cstr] by content):

turmeric (let [m #map{"name" 1 "age" 2}] (:: (map-get m "name") :int)) ; => 1

let [m #map{"name" 1 "age" 2}]
  ::(map-get(m "name") :int)
; => 1

A direct (hamt-of "k" v ...) call with string keys is content-keyed too -- there is one hamt-of builder for every key type (the old smap-of / smap-* split was retired in TMS3). (Runtime-built string keys must outlive the map -- the HAMT does not copy keys; see GMK / TCE4.)

An odd number of slot forms is a TUR-E0280 read error.

#set{...} elements and hashing

Set elements are arbitrary value expressions (no key-form restriction). Each element is used as its own hash -- the identity-hash convention the typed Set[A] uses everywhere ((set-add s 42 42)). Scalar element types (int, etc.) dedupe by value:

#set{1 1 2}        ; => set with two elements, {1, 2}
#set{x (+ x x) y}  ; each element expression evaluated exactly once

#set{1 1 2}
; => set with two elements, {1, 2}
#set{x (+ x x) y}
; each element expression evaluated exactly once

Note on hashing. Scalar elements are their own hash (the identity-hash convention above). Keyword elements are first-class :Sym values, so #set{:a :b} builds a Set[Sym] content-keyed on the interned symbol; membership tests take the symbol's hash explicitly, e.g. (set-member? s (hash :a) :a). See the symbols guide.

Empty literals

#map{}   ; => empty Map
#set{}   ; => empty Set
[]       ; => empty Vec  (expression position)

#map{}
; => empty Map
#set{}
; => empty Set
[]
; => empty Vec  (expression position)

Typed empty literals -- []:T / #set{}:T / #map{}:(K V)

An empty literal has no element to infer a type from, so a later typed operation (.eq?, .push!) can't recover its element type. Pin it with a fused :T element-type suffix immediately after the closer:

[]:int             ; empty Vec[int]
#set{}:cstr        ; empty Set[cstr]
[]:(Vec int)       ; empty Vec[Vec[int]]  (parenthesize a compound element type)
#map{}:(cstr int)  ; empty Map[cstr, int]  (a pair -- Map takes two parameters)

[]:int
; empty Vec[int]
#set{}:cstr
; empty Set[cstr]
[]:(Vec int)
; empty Vec[Vec[int]]  (parenthesize a compound element type)
#map{}:(cstr int)
; empty Map[cstr, int]  (a pair -- Map takes two parameters)

#map{} is the one two-parameter case, so its suffix is a parenthesised pair of types rather than a single one: #map{}:(cstr int) is Map[cstr, int]. The parentheses are required -- the arity has to come from somewhere, and a bare #map{}:cstr int would swallow whatever token followed the literal. This does not clash with the compound-element reading above ([]:(Vec int) is one element type that happens to be parenthesised): which reading applies is fixed by the literal kind, not by the shape of the suffix.

The #set{}:cstr above pins the element type, but note the element type you pick still matters for lifetimes: a Set[cstr] of computed keys borrows each key pointer and dangles once the source is freed. When the keys are built or stored (not static literals), use #set{}:String -- a Set[String] copies each key into a box the set owns. See strings-guide.md.

The suffix desugars to an ascription on the literal, so []:int is exactly (:: (vec-of) (Vec int)), #set{}:T is (:: (set-of) (Set T)), and #map{}:(K V) is (:: #map{} (Map K V)) -- the generated code is identical, and the suffix is neither stronger nor weaker than the ascription it stands for. It replaces the verbose (:: (vec-new) (Vec int)) scaffolding that empty containers previously needed:

;; before
(let [a (:: (vec-new) (Vec int))]
  (vec-push! a 1) ...)

;; after
(let [a []:int]
  (vec-push! a 1) ...)

;; before
let [a (:: (vec-new) (Vec int))]
  vec-push!(a 1)
  ...
;; after
let [a []:int]
  vec-push!(a 1)
  ...

Rules:

• The : must be immediately adjacent to the closing ] / } (no intervening whitespace). A space-separated [] :int is two forms, not a suffix -- this is what keeps binding vectors ([x :int y :int], whose ] is followed by a space) unaffected.
• A :: after the closer is not a suffix (it is the ascription operator).
• The suffix also works on non-empty literals ([1 2 3]:int), where it is merely a redundant re-statement of the inferred type.
• Missing type after the : is a read error: "expected an element type after the ':' container-literal suffix".
• On #map{} the suffix must be a parenthesised pair. #map{}:int, #map{}:(int), and #map{}:(a b c) are all read errors naming the expected #map{}:(<key> <value>) shape, rather than reaching the elaborator as a mis-arity type application.

Numeric literals: #rat{...} and #cx{...}

The numeric tower ships two more literals, for the exact rational type in stdlib/rational.tur and the complex type in stdlib/complex.tur. Both are always on -- they are core data-literal dispatches, not #lang layers.

#rat{n/d} -- exact rationals

#rat{3/4}      ; => (rat/of! 3 4)
#rat{-3/4}     ; => (rat/of! -3 4)
#rat{3/-4}     ; => (rat/of! -3 4)   -- the sign moves to the numerator
#rat{6/8}      ; => (rat/of! 3 4)    -- normalized at READ time
#rat{5}        ; => (rat/of! 5 1)    -- a bare whole number
#rat{1/0}      ; => read-time error (TUR-E0284)

(eq? #rat{2/4} #rat{1/2})   ; => true

#cx{3.25 -1.5}        ; => (complex/of 3.25 -1.5)
#cx{3.25 {1.0 + 0.5}} ; => (complex/of 3.25 (+ 1.0 0.5))

#lang sweet-exp

(defn build [] :int
  (let [m #map{:a 1 :b 2}]
    map-count(m)))

#lang sweet-exp

defn build [] :int
  let [m #map{:a 1 :b 2}]
    map-count(m)