From b8e09e12a32b81d5f19d876838af50fd593391aa Mon Sep 17 00:00:00 2001 From: sarna Date: Wed, 23 Jul 2025 19:01:00 +0200 Subject: [PATCH 1/5] Rewrite bracketed tuples section with examples --- content/docs/data_structures/tuples.mdz | 64 ++++++++++++++++++------- 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/content/docs/data_structures/tuples.mdz b/content/docs/data_structures/tuples.mdz index 06504e26..525210ca 100644 --- a/content/docs/data_structures/tuples.mdz +++ b/content/docs/data_structures/tuples.mdz @@ -75,22 +75,54 @@ by the contents of another array. ## Bracketed tuples -Under the hood, there are two kinds of tuples: bracketed and non-bracketed. We -have seen above that bracket tuples are used to create a tuple with @code`[]` -characters (ie: a tuple literal). The way a tuple literal is interpreted by -the compiler is one of the few ways in which bracketed tuples and non-bracketed -tuples differ: - -@ul{@li{Bracket tuples are interpreted as a tuple constructor rather than a - function call by the compiler.} - @li{When printed via @code`pp`, bracket tuples are printed with square - brackets instead of parentheses.} - @li{When passed as an argument to @code`tuple/type`, bracket tuples will - return @code`:brackets` instead of @code`:parens`.}} - -In all other ways, bracketed tuples behave identically to normal tuples. It is -not recommended to use bracketed tuples for anything outside of macros and -tuple constructors (ie: tuple literals). +Under the hood, there are two kinds of tuples - bracketed and non-bracketed: + +@codeblock[janet]``` +(def brackets '[1 2 3]) # same as (tuple 1 2 3) +(def parens '(1 2 3)) # same as (tuple/brackets 1 2 3) + +# you can check the type with tuple/type: +(tuple/type brackets) +# :brackets +(tuple/type parens) +# :parens + +# pp preserves bracketedness: +(pp brackets) +# [1 2 3] +(pp parens) +# (1 2 3) + +# bracketed and non-bracketed tuples +# with the same contents are not equal: +(= '() '[]) +# false +(= brackets parens) +# false + +# non-bracketed tuples evaluate to function calls: +(eval parens) +# error +(eval (tuple '+ 2 4 6)) # same as (eval '(+ 2 4 6)) +# 12 + +# bracketed tuples evaluate to non-bracketed ones: +(eval brackets) +# (1 2 3) +(eval (tuple/brackets '+ 2 4 6)) # same as (eval '[+ 2 4 6]) +# ( 2 4 6) +(eval (eval '[+ 2 4 6])) +# 12 + +# tuple literals evaluate to non-bracketed tuples too: +[4 5 6] # same as (eval '[4 5 6]) +# (4 5 6) +``` + +In all other ways, bracketed tuples behave identically to normal tuples. + +You should use bracketed tuples only in code that will be evaluated later +(for example in macros). ## More functions From 429e26c49cbbb939e2f4414b75853c603870a09f Mon Sep 17 00:00:00 2001 From: sarna Date: Thu, 24 Jul 2025 14:52:13 +0200 Subject: [PATCH 2/5] Correct order of comments --- content/docs/data_structures/tuples.mdz | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/data_structures/tuples.mdz b/content/docs/data_structures/tuples.mdz index 525210ca..538cbea9 100644 --- a/content/docs/data_structures/tuples.mdz +++ b/content/docs/data_structures/tuples.mdz @@ -78,8 +78,8 @@ by the contents of another array. Under the hood, there are two kinds of tuples - bracketed and non-bracketed: @codeblock[janet]``` -(def brackets '[1 2 3]) # same as (tuple 1 2 3) -(def parens '(1 2 3)) # same as (tuple/brackets 1 2 3) +(def brackets '[1 2 3]) # same as (tuple/brackets 1 2 3) +(def parens '(1 2 3)) # same as (tuple 1 2 3) # you can check the type with tuple/type: (tuple/type brackets) From ad7030699fe3c173ce7b16ed28466ece04a2a5c4 Mon Sep 17 00:00:00 2001 From: sarna Date: Thu, 24 Jul 2025 15:52:29 +0200 Subject: [PATCH 3/5] Add more prose, reword --- content/docs/data_structures/tuples.mdz | 100 ++++++++++++++++-------- 1 file changed, 66 insertions(+), 34 deletions(-) diff --git a/content/docs/data_structures/tuples.mdz b/content/docs/data_structures/tuples.mdz index 538cbea9..7cf53f2d 100644 --- a/content/docs/data_structures/tuples.mdz +++ b/content/docs/data_structures/tuples.mdz @@ -75,48 +75,80 @@ by the contents of another array. ## Bracketed tuples -Under the hood, there are two kinds of tuples - bracketed and non-bracketed: +Under the hood, there are two kinds of tuples: brackets (bracketed) and parens (non-bracketed). @codeblock[janet]``` -(def brackets '[1 2 3]) # same as (tuple/brackets 1 2 3) -(def parens '(1 2 3)) # same as (tuple 1 2 3) +# brackets tuples +(def b-1 (tuple/brackets 1 2 3)) +(def b-2 '[1 2 3]) -# you can check the type with tuple/type: -(tuple/type brackets) -# :brackets -(tuple/type parens) -# :parens +# parens tuples +(def p-1 (tuple 1 2 3)) +(def p-2 '(1 2 3)) -# pp preserves bracketedness: -(pp brackets) +# tuple/type can distinguish between tuples +(tuple/type b-1) # -> :brackets +(tuple/type b-2) # -> :brackets + +(tuple/type p-1) # -> :parens +(tuple/type p-2) # -> :parens +``` + +The compiler interprets brackets tuples as a tuple constructor rather than +a function call. + +@codeblock[janet]``` +# create a function object that returns a tuple +(def c-1 (compile (tuple/brackets 1 2 3))) + +# create and return a (parens) tuple with elements 1, 2 and 3 +(c-2) # -> (1 2 3) + +# create a function object with a call to + +(def c-2 (compile (tuple '+ 1 2 3))) + +# call the function named by + with 1, 2 and 3 as arguments +(c-2) # -> 6 +``` + +Considering that functions evaluate their arguments and the tuple literal (@code`[]`) +evaluates to a normal (parens) tuple, the behavior of @code`tuple/type` can be +surprising. It's best to use it with quoted values. + +@codeblock[janet]``` +(tuple/type [1 2 3]) # -> :parens + +(tuple/type '(1 2 3)) # -> :parens +(tuple/type '[1 2 3]) # -> :brackets + +(eval-string "[1 2 3]") # -> (1 2 3) +(eval-string "'[1 2 3]") # -> [1 2 3] +``` + +When printed via @code`pp`, brackets tuples are printed with square brackets +instead of parentheses. + +@codeblock[janet]``` +(pp (tuple/brackets 1 2 3)) # [1 2 3] -(pp parens) + +(pp (tuple 1 2 3)) # (1 2 3) -# bracketed and non-bracketed tuples -# with the same contents are not equal: -(= '() '[]) -# false -(= brackets parens) -# false - -# non-bracketed tuples evaluate to function calls: -(eval parens) -# error -(eval (tuple '+ 2 4 6)) # same as (eval '(+ 2 4 6)) -# 12 - -# bracketed tuples evaluate to non-bracketed ones: -(eval brackets) +# this can be surprising +(pp [1 2 3]) # (1 2 3) -(eval (tuple/brackets '+ 2 4 6)) # same as (eval '[+ 2 4 6]) -# ( 2 4 6) -(eval (eval '[+ 2 4 6])) -# 12 - -# tuple literals evaluate to non-bracketed tuples too: -[4 5 6] # same as (eval '[4 5 6]) -# (4 5 6) +``` + +Brackets and parens tuples with the same contents are not @code`=`, +but are @code`deep=`. + +@codeblock[janet]``` +(= '() '[]) # -> false +(deep= '() '[]) # -> true + +(= '(1 2 3) '[1 2 3]) # -> false +(deep= '(1 2 3) '[1 2 3]) # -> true ``` In all other ways, bracketed tuples behave identically to normal tuples. From 273b48826b5a88da06d4fbfe544862a5c1fb25d1 Mon Sep 17 00:00:00 2001 From: sarna Date: Thu, 24 Jul 2025 21:23:30 +0200 Subject: [PATCH 4/5] Use singular for tuple type --- content/docs/data_structures/tuples.mdz | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/docs/data_structures/tuples.mdz b/content/docs/data_structures/tuples.mdz index 7cf53f2d..aa903624 100644 --- a/content/docs/data_structures/tuples.mdz +++ b/content/docs/data_structures/tuples.mdz @@ -75,14 +75,14 @@ by the contents of another array. ## Bracketed tuples -Under the hood, there are two kinds of tuples: brackets (bracketed) and parens (non-bracketed). +Under the hood, there are two kinds of tuples: bracket (bracketed) and paren (non-bracketed). @codeblock[janet]``` -# brackets tuples +# bracket tuples (def b-1 (tuple/brackets 1 2 3)) (def b-2 '[1 2 3]) -# parens tuples +# paren tuples (def p-1 (tuple 1 2 3)) (def p-2 '(1 2 3)) @@ -94,14 +94,14 @@ Under the hood, there are two kinds of tuples: brackets (bracketed) and parens ( (tuple/type p-2) # -> :parens ``` -The compiler interprets brackets tuples as a tuple constructor rather than +The compiler interprets bracket tuples as a tuple constructor rather than a function call. @codeblock[janet]``` # create a function object that returns a tuple (def c-1 (compile (tuple/brackets 1 2 3))) -# create and return a (parens) tuple with elements 1, 2 and 3 +# create and return a (paren) tuple with elements 1, 2 and 3 (c-2) # -> (1 2 3) # create a function object with a call to + @@ -112,7 +112,7 @@ a function call. ``` Considering that functions evaluate their arguments and the tuple literal (@code`[]`) -evaluates to a normal (parens) tuple, the behavior of @code`tuple/type` can be +evaluates to a normal (paren) tuple, the behavior of @code`tuple/type` can be surprising. It's best to use it with quoted values. @codeblock[janet]``` @@ -125,7 +125,7 @@ surprising. It's best to use it with quoted values. (eval-string "'[1 2 3]") # -> [1 2 3] ``` -When printed via @code`pp`, brackets tuples are printed with square brackets +When printed via @code`pp`, bracket tuples are printed with square brackets instead of parentheses. @codeblock[janet]``` @@ -140,7 +140,7 @@ instead of parentheses. # (1 2 3) ``` -Brackets and parens tuples with the same contents are not @code`=`, +Bracket and paren tuples with the same contents are not @code`=`, but are @code`deep=`. @codeblock[janet]``` From fdedf1c70a538548aae7598cd70679593d633f90 Mon Sep 17 00:00:00 2001 From: sarna Date: Thu, 24 Jul 2025 21:49:59 +0200 Subject: [PATCH 5/5] Rephrase one sentence --- content/docs/data_structures/tuples.mdz | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/docs/data_structures/tuples.mdz b/content/docs/data_structures/tuples.mdz index aa903624..b6887598 100644 --- a/content/docs/data_structures/tuples.mdz +++ b/content/docs/data_structures/tuples.mdz @@ -75,7 +75,8 @@ by the contents of another array. ## Bracketed tuples -Under the hood, there are two kinds of tuples: bracket (bracketed) and paren (non-bracketed). +Under the hood, there are two kinds of tuples: +normal (aka paren or non-bracketed), and bracketed ones. @codeblock[janet]``` # bracket tuples