@@ -75,22 +75,87 @@ by the contents of another array.
7575
7676## Bracketed tuples
7777
78- Under the hood, there are two kinds of tuples: bracketed and non-bracketed. We
79- have seen above that bracket tuples are used to create a tuple with @code`[]`
80- characters (ie: a tuple literal). The way a tuple literal is interpreted by
81- the compiler is one of the few ways in which bracketed tuples and non-bracketed
82- tuples differ:
83-
84- @ul{@li{Bracket tuples are interpreted as a tuple constructor rather than a
85- function call by the compiler.}
86- @li{When printed via @code`pp`, bracket tuples are printed with square
87- brackets instead of parentheses.}
88- @li{When passed as an argument to @code`tuple/type`, bracket tuples will
89- return @code`:brackets` instead of @code`:parens`.}}
90-
91- In all other ways, bracketed tuples behave identically to normal tuples. It is
92- not recommended to use bracketed tuples for anything outside of macros and
93- tuple constructors (ie: tuple literals).
78+ Under the hood, there are two kinds of tuples:
79+ normal (aka paren or non-bracketed), and bracketed ones.
80+
81+ @codeblock[janet]```
82+ # bracket tuples
83+ (def b-1 (tuple/brackets 1 2 3))
84+ (def b-2 '[1 2 3])
85+
86+ # paren tuples
87+ (def p-1 (tuple 1 2 3))
88+ (def p-2 '(1 2 3))
89+
90+ # tuple/type can distinguish between tuples
91+ (tuple/type b-1) # -> :brackets
92+ (tuple/type b-2) # -> :brackets
93+
94+ (tuple/type p-1) # -> :parens
95+ (tuple/type p-2) # -> :parens
96+ ```
97+
98+ The compiler interprets bracket tuples as a tuple constructor rather than
99+ a function call.
100+
101+ @codeblock[janet]```
102+ # create a function object that returns a tuple
103+ (def c-1 (compile (tuple/brackets 1 2 3)))
104+
105+ # create and return a (paren) tuple with elements 1, 2 and 3
106+ (c-2) # -> (1 2 3)
107+
108+ # create a function object with a call to +
109+ (def c-2 (compile (tuple '+ 1 2 3)))
110+
111+ # call the function named by + with 1, 2 and 3 as arguments
112+ (c-2) # -> 6
113+ ```
114+
115+ Considering that functions evaluate their arguments and the tuple literal (@code`[]`)
116+ evaluates to a normal (paren) tuple, the behavior of @code`tuple/type` can be
117+ surprising. It's best to use it with quoted values.
118+
119+ @codeblock[janet]```
120+ (tuple/type [1 2 3]) # -> :parens
121+
122+ (tuple/type '(1 2 3)) # -> :parens
123+ (tuple/type '[1 2 3]) # -> :brackets
124+
125+ (eval-string "[1 2 3]") # -> (1 2 3)
126+ (eval-string "'[1 2 3]") # -> [1 2 3]
127+ ```
128+
129+ When printed via @code`pp`, bracket tuples are printed with square brackets
130+ instead of parentheses.
131+
132+ @codeblock[janet]```
133+ (pp (tuple/brackets 1 2 3))
134+ # [1 2 3]
135+
136+ (pp (tuple 1 2 3))
137+ # (1 2 3)
138+
139+ # this can be surprising
140+ (pp [1 2 3])
141+ # (1 2 3)
142+ ```
143+
144+ Bracket and paren tuples with the same contents are not @code`=`,
145+ but are @code`deep=`.
146+
147+ @codeblock[janet]```
148+ (= '() '[]) # -> false
149+ (deep= '() '[]) # -> true
150+
151+ (= '(1 2 3) '[1 2 3]) # -> false
152+ (deep= '(1 2 3) '[1 2 3]) # -> true
153+ ```
154+
155+ In all other ways, bracketed tuples behave identically to normal tuples.
156+
157+ You should use bracketed tuples only in code that will be evaluated later
158+ (for example in macros).
94159
95160## More functions
96161
0 commit comments