From 1c27fcc9f32a2d9f1062458c9cc41f56ca4bd2eb Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Thu, 11 Dec 2008 23:00:23 -0800
Subject: [PATCH] docs and metadata for literals

---
 extra/literals/authors.txt           |  1 +
 extra/literals/literals-docs.factor  | 61 ++++++++++++++++++++++++++++
 extra/literals/literals-tests.factor |  4 +-
 extra/literals/literals.factor       |  4 +-
 extra/literals/summary.txt           |  1 +
 extra/literals/tags.txt              |  1 +
 6 files changed, 70 insertions(+), 2 deletions(-)
 create mode 100644 extra/literals/authors.txt
 create mode 100644 extra/literals/literals-docs.factor
 create mode 100644 extra/literals/summary.txt
 create mode 100644 extra/literals/tags.txt

diff --git a/extra/literals/authors.txt b/extra/literals/authors.txt
new file mode 100644
index 0000000000..f13c9c1e77
--- /dev/null
+++ b/extra/literals/authors.txt
@@ -0,0 +1 @@
+Joe Groff
diff --git a/extra/literals/literals-docs.factor b/extra/literals/literals-docs.factor
new file mode 100644
index 0000000000..ae25c75495
--- /dev/null
+++ b/extra/literals/literals-docs.factor
@@ -0,0 +1,61 @@
+! Copyright (C) 2008 Joe Groff.
+! See http://factorcode.org/license.txt for BSD license.
+USING: help.markup help.syntax multiline ;
+IN: literals
+
+HELP: $
+{ $syntax "$ word" }
+{ $description "Executes " { $snippet "word" } " at parse time and adds the result(s) to the parser accumulator." }
+{ $notes "Since " { $snippet "word" } " is executed at parse time, " { $snippet "$" } " cannot be used with words defined in the same compilation unit." }
+{ $examples
+
+    { $example <"
+USING: kernel literals prettyprint ;
+IN: scratchpad
+
+<< : five 5 ; >>
+{ $ five } .
+    "> "{ 5 }" }
+
+    { $example <"
+USING: kernel literals prettyprint ;
+IN: scratchpad
+
+<< : seven-eleven 7 11 ; >>
+{ $ seven-eleven } .
+    "> "{ 7 11 }" }
+
+} ;
+
+HELP: $[
+{ $syntax "$[ code ]" }
+{ $description "Calls " { $snippet "code" } " at parse time and adds the result(s) to the parser accumulator." }
+{ $notes "Since " { $snippet "code" } " is executed at parse time, it cannot reference any words defined in the same compilation unit." }
+{ $examples
+
+    { $example <"
+USING: kernel literals math prettyprint ;
+IN: scratchpad
+
+<< : five 5 ; >>
+{ $[ five dup 1+ dup 2 + ] } .
+    "> "{ 5 6 8 }" }
+
+} ;
+
+{ POSTPONE: $ POSTPONE: $[ } related-words
+
+ARTICLE: "literals" "Interpolating code results into literal values"
+"The " { $vocab-link "literals" } " vocabulary contains words to run code at parse time and insert the results into more complex literal values."
+{ $example <"
+USING: kernel literals math prettyprint ;
+IN: scratchpad
+
+<< : five 5 ; >>
+{ $ five $[ five dup 1+ dup 2 + ] } .
+    "> "{ 5 5 6 8 }" }
+{ $subsection POSTPONE: $ }
+{ $subsection POSTPONE: $[ }
+;
+
+ABOUT: "literals"
diff --git a/extra/literals/literals-tests.factor b/extra/literals/literals-tests.factor
index b88a286a59..185d672dd3 100644
--- a/extra/literals/literals-tests.factor
+++ b/extra/literals/literals-tests.factor
@@ -1,4 +1,4 @@
-USING: kernel literals tools.test ;
+USING: kernel literals math tools.test ;
 IN: literals.tests
 
 <<
@@ -10,3 +10,5 @@ IN: literals.tests
 [ { 5 } ] [ { $ five } ] unit-test
 [ { 7 11 } ] [ { $ seven-eleven } ] unit-test
 [ { 6 6 6 } ] [ { $ six-six-six } ] unit-test
+
+[ { 8 8 8 } ] [ { $[ six-six-six [ 2 + ] tri@ ] } ] unit-test
diff --git a/extra/literals/literals.factor b/extra/literals/literals.factor
index d46f492cd4..a450c2118e 100644
--- a/extra/literals/literals.factor
+++ b/extra/literals/literals.factor
@@ -1,4 +1,6 @@
-USING: continuations kernel parser words ;
+! (c) Joe Groff, see license for details
+USING: continuations kernel parser words quotations ;
 IN: literals
 
 : $ scan-word [ execute ] curry with-datastack ; parsing
+: $[ \ ] parse-until >quotation with-datastack ; parsing
diff --git a/extra/literals/summary.txt b/extra/literals/summary.txt
new file mode 100644
index 0000000000..dfeb9fe797
--- /dev/null
+++ b/extra/literals/summary.txt
@@ -0,0 +1 @@
+Expression interpolation into sequence literals
diff --git a/extra/literals/tags.txt b/extra/literals/tags.txt
new file mode 100644
index 0000000000..71c0ff7282
--- /dev/null
+++ b/extra/literals/tags.txt
@@ -0,0 +1 @@
+syntax