From b3e20dfdf2bba6c85c6828e7f38876fc35a54d08 Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Fri, 13 Feb 2009 15:10:46 -0600
Subject: [PATCH 1/2] better factor annotations docs
---
extra/annotations/annotations-docs.factor | 30 ++++++++++++++---------
1 file changed, 19 insertions(+), 11 deletions(-)
diff --git a/extra/annotations/annotations-docs.factor b/extra/annotations/annotations-docs.factor
index c340554119..1effdf4067 100644
--- a/extra/annotations/annotations-docs.factor
+++ b/extra/annotations/annotations-docs.factor
@@ -9,6 +9,22 @@ IN: annotations
: comment-usage.-word ( base -- word ) "s." append "annotations" lookup ;
PRIVATE>
+: $annotation ( element -- )
+ P first
+ [ "!" " your comment here" surround 1array $syntax ]
+ [ [ "Treats the rest of the line after the exclamation point as a code annotation that can be looked up with the " \ $link ] dip comment-usage.-word 2array " word." 3array $description ]
+ [ ": foo ( x y z -- w )\n !" " --w-ó()ò-w-- kilroy was here\n + * ;" surround 1array $unchecked-example ]
+ tri ;
+
+: $annotation-usage. ( element -- )
+ first
+ [ "Displays a list of words, help articles, and vocabularies that contain " \ $link ] dip comment-word 2array " annotations." 3array $description ;
+
+: $annotation-usage ( element -- )
+ first
+ { "usages" sequence } $values
+ [ "Returns a list of words, help articles, and vocabularies that contain " \ $link ] dip [ comment-word 2array " annotations. For a more user-friendly display, use the " \ $link ] [ comment-usage.-word 2array " word." 6 narray ] bi 1array $description ;
+
"Code annotations"
{
"The " { $vocab-link "annotations" } " vocabulary provides syntax for comment-like annotations that can be looked up with Factor's " { $link usage } " mechanism."
@@ -26,17 +42,9 @@ annotation-tags natural-sort
annotation-tags [
{
- [ [ \ $syntax ] dip "!" " your comment here" surround 2array ]
- [ [ \ $description "Treats the rest of the line after the exclamation point as a code annotation that can be looked up with the " \ $link ] dip comment-usage.-word 2array " word." 4array ]
- [ [ \ $unchecked-example ] dip ": foo ( x y z -- w )\n !" " --w-ó()ò-w-- kilroy was here\n + * ;" surround 2array 3array ]
- [ comment-word set-word-help ]
-
- [ [ \ $description "Displays a list of words, help articles, and vocabularies that contain " \ $link ] dip comment-word 2array " annotations." 4array 1array ]
- [ comment-usage.-word set-word-help ]
-
- [ [ { $values { "usages" sequence } } \ $description "Returns a list of words, help articles, and vocabularies that contain " \ $link ] dip [ comment-word 2array " annotations. For a more user-friendly display, use the " \ $link ] [ comment-usage.-word 2array " word." 6 narray 2array ] bi ]
- [ comment-usage-word set-word-help ]
-
+ [ [ \ $annotation swap 2array 1array ] [ comment-word set-word-help ] bi ]
+ [ [ \ $annotation-usage swap 2array 1array ] [ comment-usage-word set-word-help ] bi ]
+ [ [ \ $annotation-usage. swap 2array 1array ] [ comment-usage.-word set-word-help ] bi ]
[ [ comment-word ] [ comment-usage-word ] [ comment-usage.-word ] tri 3array related-words ]
} cleave
] each
From ddce0e0a107ffdb295b02363c553d562641b72b9 Mon Sep 17 00:00:00 2001
From: Joe Groff <arcata@gmail.com>
Date: Wed, 18 Feb 2009 16:57:20 -0600
Subject: [PATCH 2/2] change literals so that $ works with constants in same
compilation unit
---
extra/literals/literals-docs.factor | 8 ++++----
extra/literals/literals-tests.factor | 5 +++--
extra/literals/literals.factor | 4 ++--
3 files changed, 9 insertions(+), 8 deletions(-)
diff --git a/extra/literals/literals-docs.factor b/extra/literals/literals-docs.factor
index ae25c75495..6525264f6a 100644
--- a/extra/literals/literals-docs.factor
+++ b/extra/literals/literals-docs.factor
@@ -1,19 +1,19 @@
! Copyright (C) 2008 Joe Groff.
! See http://factorcode.org/license.txt for BSD license.
-USING: help.markup help.syntax multiline ;
+USING: help.markup help.syntax kernel 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." }
+{ $notes { $snippet "word" } "'s definition is looked up and " { $link call } "ed at parse time, so words that reference words in the current compilation unit cannot be used with " { $snippet "$" } "." }
{ $examples
{ $example <"
USING: kernel literals prettyprint ;
IN: scratchpad
-<< : five 5 ; >>
+CONSTANT: five 5
{ $ five } .
"> "{ 5 }" }
@@ -30,7 +30,7 @@ IN: scratchpad
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." }
+{ $notes "Since " { $snippet "code" } " is " { $link call } "ed at parse time, it cannot reference any words defined in the same compilation unit." }
{ $examples
{ $example <"
diff --git a/extra/literals/literals-tests.factor b/extra/literals/literals-tests.factor
index 34ea4d6415..0e933d5209 100644
--- a/extra/literals/literals-tests.factor
+++ b/extra/literals/literals-tests.factor
@@ -2,11 +2,12 @@ USING: kernel literals math tools.test ;
IN: literals.tests
<<
-: five 5 ;
-: seven-eleven 7 11 ;
: six-six-six 6 6 6 ;
>>
+: five 5 ;
+: seven-eleven 7 11 ;
+
[ { 5 } ] [ { $ five } ] unit-test
[ { 7 11 } ] [ { $ seven-eleven } ] unit-test
[ { 6 6 6 } ] [ { $ six-six-six } ] unit-test
diff --git a/extra/literals/literals.factor b/extra/literals/literals.factor
index 6df51a35ef..d3cfcaae23 100644
--- a/extra/literals/literals.factor
+++ b/extra/literals/literals.factor
@@ -1,6 +1,6 @@
! (c) Joe Groff, see license for details
-USING: continuations kernel parser words quotations vectors ;
+USING: accessors continuations kernel parser words quotations vectors ;
IN: literals
-: $ scan-word [ execute ] curry with-datastack >vector ; parsing
+: $ scan-word [ def>> call ] curry with-datastack >vector ; parsing
: $[ \ ] parse-until >quotation with-datastack >vector ; parsing