From acc1dc23fa9a2a117579def9486ce1ab9fdc7152 Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Sun, 16 Nov 2008 09:08:38 -0600 Subject: [PATCH] More usages of $quotation --- basis/peg/peg-docs.factor | 4 ++-- .../tools/annotations/annotations-docs.factor | 2 +- core/sequences/sequences-docs.factor | 13 ++++------ extra/lists/lazy/lazy-docs.factor | 24 +++++++++---------- extra/lists/lists-docs.factor | 12 +++++----- extra/promises/promises-docs.factor | 6 ++--- 6 files changed, 29 insertions(+), 32 deletions(-) diff --git a/basis/peg/peg-docs.factor b/basis/peg/peg-docs.factor index 00390c1b1e..976c32d102 100644 --- a/basis/peg/peg-docs.factor +++ b/basis/peg/peg-docs.factor @@ -98,7 +98,7 @@ HELP: optional HELP: semantic { $values { "parser" "a parser" } - { "quot" "a quotation with stack effect ( object -- bool )" } + { "quot" { $quotation "( object -- ? )" } } } { $description "Returns a parser that succeeds if the 'p1' parser succeeds and the quotation called with " @@ -130,7 +130,7 @@ HELP: ensure-not HELP: action { $values { "parser" "a parser" } - { "quot" "a quotation with stack effect ( ast -- ast )" } + { "quot" { $quotation "( ast -- ast )" } } } { $description "Returns a parser that calls the 'p1' parser and applies the quotation to the AST resulting " diff --git a/basis/tools/annotations/annotations-docs.factor b/basis/tools/annotations/annotations-docs.factor index 41808d2f6a..c61b4547a9 100644 --- a/basis/tools/annotations/annotations-docs.factor +++ b/basis/tools/annotations/annotations-docs.factor @@ -28,7 +28,7 @@ HELP: breakpoint { $description "Annotates a word definition to enter the single stepper when executed." } ; HELP: breakpoint-if -{ $values { "quot" "a quotation with stack effect" { $snippet "( -- ? )" } } { "word" word } } +{ $values { "quot" { $quotation "( -- ? )" } } { "word" word } } { $description "Annotates a word definition to enter the single stepper if the quotation yields true." } ; HELP: annotate-methods diff --git a/core/sequences/sequences-docs.factor b/core/sequences/sequences-docs.factor index 2789fc36c1..cc8daba8c0 100644 --- a/core/sequences/sequences-docs.factor +++ b/core/sequences/sequences-docs.factor @@ -338,8 +338,7 @@ HELP: 2reduce { $values { "seq1" sequence } { "seq2" sequence } { "identity" object } - { "quot" "a quotation with stack effect " - { $snippet "( prev elt1 elt2 -- next )" } } + { "quot" { $quotation "( prev elt1 elt2 -- next )" } } { "result" "the final result" } } { $description "Combines successive pairs of elements from the two sequences using a ternary operation. The first input value at each iteration except the first one is the result of the previous iteration. The first input value at the first iteration is " { $snippet "identity" } "." } ; @@ -357,18 +356,16 @@ HELP: 2all? HELP: find { $values { "seq" sequence } - { "quot" "a quotation with stack effect " - { $snippet "( elt -- ? )" } } - { "i" "the index of the first match, or f" } + { "quot" { $quotation "( elt -- ? )" } } + { "i" "the index of the first match, or " { $link f } } { "elt" "the first matching element, or " { $link f } } } { $description "A simpler variant of " { $link find-from } " where the starting index is 0." } ; HELP: find-from { $values { "n" "a starting index" } { "seq" sequence } - { "quot" "a quotation with stack effect " - { $snippet "( elt -- ? )" } } - { "i" "the index of the first match, or f" } + { "quot" { $quotation "( elt -- ? )" } } + { "i" "the index of the first match, or " { $link f } } { "elt" "the first matching element, or " { $link f } } } { $description "Applies the quotation to each element of the sequence in turn, until it outputs a true value or the end of the sequence is reached. If the quotation yields a true value for some sequence element, the word outputs the element index and the element itself. Otherwise, the word outputs an index of f and " { $link f } " as the element." } ; diff --git a/extra/lists/lazy/lazy-docs.factor b/extra/lists/lazy/lazy-docs.factor index 6a9359027d..c402cdf15b 100644 --- a/extra/lists/lazy/lazy-docs.factor +++ b/extra/lists/lazy/lazy-docs.factor @@ -5,22 +5,22 @@ USING: help.markup help.syntax sequences strings lists ; IN: lists.lazy HELP: lazy-cons -{ $values { "car" "a quotation with stack effect ( -- X )" } { "cdr" "a quotation with stack effect ( -- cons )" } { "promise" "the resulting cons object" } } +{ $values { "car" { $quotation "( -- X )" } } { "cdr" { $quotation "( -- cons )" } } { "promise" "the resulting cons object" } } { $description "Constructs a cons object for a lazy list from two quotations. The " { $snippet "car" } " quotation should return the head of the list, and the " { $snippet "cons" } " quotation the tail when called. When " { $link cons } " or " { $link cdr } " are called on the lazy-cons object then the appropriate quotation is called." } { $see-also cons car cdr nil nil? } ; { 1lazy-list 2lazy-list 3lazy-list } related-words HELP: 1lazy-list -{ $values { "a" "a quotation with stack effect ( -- X )" } { "lazy-cons" "a lazy-cons object" } } +{ $values { "a" { $quotation "( -- X )" } } { "lazy-cons" "a lazy-cons object" } } { $description "Create a lazy list with 1 element. The element is the result of calling the quotation. The quotation is only called when the list element is requested." } ; HELP: 2lazy-list -{ $values { "a" "a quotation with stack effect ( -- X )" } { "b" "a quotation with stack effect ( -- X )" } { "lazy-cons" "a lazy-cons object" } } +{ $values { "a" { $quotation "( -- X )" } } { "b" { $quotation "( -- X )" } } { "lazy-cons" "a lazy-cons object" } } { $description "Create a lazy list with 2 elements. The elements are the result of calling the quotations. The quotations are only called when the list elements are requested." } ; HELP: 3lazy-list -{ $values { "a" "a quotation with stack effect ( -- X )" } { "b" "a quotation with stack effect ( -- X )" } { "c" "a quotation with stack effect ( -- X )" } { "lazy-cons" "a lazy-cons object" } } +{ $values { "a" { $quotation "( -- X )" } } { "b" { $quotation "( -- X )" } } { "c" { $quotation "( -- X )" } } { "lazy-cons" "a lazy-cons object" } } { $description "Create a lazy list with 3 elements. The elements are the result of calling the quotations. The quotations are only called when the list elements are requested." } ; HELP: @@ -31,11 +31,11 @@ HELP: { lazy-map lazy-map-with ltake lfilter lappend lfrom lfrom-by lconcat lcartesian-product lcartesian-product* lcomp lcomp* lmerge lwhile luntil } related-words HELP: lazy-map -{ $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( obj -- X )" } { "result" "resulting cons object" } } +{ $values { "list" "a cons object" } { "quot" { $quotation "( obj -- X )" } } { "result" "resulting cons object" } } { $description "Perform a similar functionality to that of the " { $link map } " word, but in a lazy manner. No evaluation of the list elements occurs initially but a " { $link } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ; HELP: lazy-map-with -{ $values { "value" "an object" } { "list" "a cons object" } { "quot" "a quotation with stack effect ( obj elt -- X )" } { "result" "resulting cons object" } } +{ $values { "value" "an object" } { "list" "a cons object" } { "quot" { $quotation "( obj elt -- X )" } } { "result" "resulting cons object" } } { $description "Variant of " { $link lazy-map } " which pushes a retained object on each invocation of the quotation." } ; HELP: ltake @@ -43,15 +43,15 @@ HELP: ltake { $description "Outputs a lazy list containing the first n items in the list. This is done a lazy manner. No evaluation of the list elements occurs initially but a " { $link } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ; HELP: lfilter -{ $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( -- X )" } { "result" "resulting cons object" } } +{ $values { "list" "a cons object" } { "quot" { $quotation "( -- X )" } } { "result" "resulting cons object" } } { $description "Perform a similar functionality to that of the " { $link filter } " word, but in a lazy manner. No evaluation of the list elements occurs initially but a " { $link } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ; HELP: lwhile -{ $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( X -- bool )" } { "result" "resulting cons object" } } +{ $values { "list" "a cons object" } { "quot" { $quotation "( X -- ? )" } } { "result" "resulting cons object" } } { $description "Outputs a lazy list containing the first items in the list as long as " { $snippet "quot" } " evaluates to t. No evaluation of the list elements occurs initially but a " { $link } " object is returned with conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ; HELP: luntil -{ $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( X -- bool )" } { "result" "resulting cons object" } } +{ $values { "list" "a cons object" } { "quot" { $quotation "( X -- ? )" } } { "result" "resulting cons object" } } { $description "Outputs a lazy list containing the first items in the list until after " { $snippet "quot" } " evaluates to t. No evaluation of the list elements occurs initially but a " { $link } " object is returned with conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required." } ; HELP: list>vector @@ -69,7 +69,7 @@ HELP: lappend { $description "Perform a similar functionality to that of the " { $link append } " word, but in a lazy manner. No evaluation of the list elements occurs initially but a " { $link } " object is returned which conforms to the list protocol. Calling " { $link car } ", " { $link cdr } " or " { $link nil? } " on this will evaluate elements as required. Successive calls to " { $link cdr } " will iterate through list1, followed by list2." } ; HELP: lfrom-by -{ $values { "n" "an integer" } { "quot" "a quotation with stack effect ( -- int )" } { "list" "a lazy list of integers" } } +{ $values { "n" "an integer" } { "quot" { $quotation "( -- int )" } } { "list" "a lazy list of integers" } } { $description "Return an infinite lazy list of values starting from n, with each successive value being the result of applying quot to n." } ; HELP: lfrom @@ -101,11 +101,11 @@ HELP: lcartesian-product* { $description "Given a list of lists, return a list containing the cartesian product of those lists." } ; HELP: lcomp -{ $values { "list" "a list of lists" } { "quot" "a quotation with stack effect ( seq -- X )" } { "result" "the resulting list" } } +{ $values { "list" "a list of lists" } { "quot" { $quotation "( seq -- X )" } } { "result" "the resulting list" } } { $description "Get the cartesian product of the lists in " { $snippet "list" } " and call " { $snippet "quot" } " call with each element from the cartesian product on the stack, the result of which is returned in the final " { $snippet "list" } "." } ; HELP: lcomp* -{ $values { "list" "a list of lists" } { "guards" "a sequence of quotations with stack effect ( seq -- bool )" } { "quot" "a quotation with stack effect ( seq -- X )" } { "list" "the resulting list" } { "result" "a list" } } +{ $values { "list" "a list of lists" } { "guards" "a sequence of quotations with stack effect ( seq -- bool )" } { "quot" { $quotation "( seq -- X )" } } { "list" "the resulting list" } { "result" "a list" } } { $description "Get the cartesian product of the lists in " { $snippet "list" } ", filter it by applying each guard quotation to it and call " { $snippet "quot" } " call with each element from the remaining cartesian product items on the stack, the result of which is returned in the final " { $snippet "list" } "." } { $examples { $code "{ 1 2 3 } >list { 4 5 6 } >list 2list { [ first odd? ] } [ first2 + ] lcomp*" } diff --git a/extra/lists/lists-docs.factor b/extra/lists/lists-docs.factor index cd2e6f7081..8807c8cf8a 100644 --- a/extra/lists/lists-docs.factor +++ b/extra/lists/lists-docs.factor @@ -61,19 +61,19 @@ HELP: uncons { leach foldl lmap>array } related-words HELP: leach -{ $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( obj -- )" } } +{ $values { "list" "a cons object" } { "quot" { $quotation "( obj -- )" } } } { $description "Call the quotation for each item in the list." } ; HELP: foldl -{ $values { "list" "a cons object" } { "identity" "an object" } { "quot" "a quotation with stack effect ( prev elt -- next )" } { "result" "the final result" } } +{ $values { "list" "a cons object" } { "identity" "an object" } { "quot" { $quotation "( prev elt -- next )" } } { "result" "the final result" } } { $description "Combines successive elements of the list (in a left-assocative order) using a binary operation and outputs the final result." } ; HELP: foldr -{ $values { "list" "a cons object" } { "identity" "an object" } { "quot" "a quotation with stack effect ( prev elt -- next )" } { "result" "the final result" } } +{ $values { "list" "a cons object" } { "identity" "an object" } { "quot" { $quotation "( prev elt -- next )" } } { "result" "the final result" } } { $description "Combines successive elements of the list (in a right-assocative order) using a binary operation, and outputs the final result." } ; HELP: lmap -{ $values { "list" "a cons object" } { "quot" "a quotation with stack effect ( old -- new )" } { "result" "the final result" } } +{ $values { "list" "a cons object" } { "quot" { $quotation "( old -- new )" } } { "result" "the final result" } } { $description "Applies the quotation to each element of the list in order, collecting the new elements into a new list." } ; HELP: lreverse @@ -97,8 +97,8 @@ HELP: seq>cons { $description "Recursively turns the given sequence into a cons object, maintaing order and also converting nested lists." } ; HELP: traverse -{ $values { "list" "a cons object" } { "pred" "a quotation with stack effect ( list/elt -- ? )" } - { "quot" "a quotation with stack effect ( list/elt -- result)" } { "result" "a new cons object" } } +{ $values { "list" "a cons object" } { "pred" { $quotation "( list/elt -- ? )" } } + { "quot" { $quotation "( list/elt -- result)" } } { "result" "a new cons object" } } { $description "Recursively traverses the list object, replacing any elements (which can themselves be sublists) that pred" " returns true for with the result of applying quot to." } ; diff --git a/extra/promises/promises-docs.factor b/extra/promises/promises-docs.factor index c482df0d15..4e8dc9a9a2 100755 --- a/extra/promises/promises-docs.factor +++ b/extra/promises/promises-docs.factor @@ -5,17 +5,17 @@ USING: help.markup help.syntax ; IN: promises HELP: promise -{ $values { "quot" "a quotation with stack effect ( -- X )" } { "promise" "a promise object" } } +{ $values { "quot" { $quotation "( -- X )" } } { "promise" "a promise object" } } { $description "Creates a promise to return a value. When forced this quotation is called and the value returned. The value is memorised so that calling " { $link force } " again does not call the quotation again, instead the previous value is returned directly." } { $see-also force promise-with promise-with2 } ; HELP: promise-with -{ $values { "value" "an object" } { "quot" "a quotation with stack effect ( value -- X )" } { "promise" "a promise object" } } +{ $values { "value" "an object" } { "quot" { $quotation "( value -- X )" } } { "promise" "a promise object" } } { $description "Creates a promise to return a value. When forced this quotation is called with the given value on the stack and the result returned. The value is memorised so that calling " { $link force } " again does not call the quotation again, instead the previous value is returned directly." } { $see-also force promise promise-with2 } ; HELP: promise-with2 -{ $values { "value1" "an object" } { "value2" "an object" } { "quot" "a quotation with stack effect ( value1 value2 -- X )" } { "promise" "a promise object" } } +{ $values { "value1" "an object" } { "value2" "an object" } { "quot" { $quotation "( value1 value2 -- X )" } } { "promise" "a promise object" } } { $description "Creates a promise to return a value. When forced this quotation is called with the given values on the stack and the result returned. The value is memorised so that calling " { $link force } " again does not call the quotation again, instead the previous value is returned directly." } { $see-also force promise promise-with2 } ;