{ $notes "Custom assoc implementations should use this word to implement a method for the " { $link hashcode* } " generic word." } ;
HELP: assoc-stack
-{ $values { "key" "a key" } { "seq" "a sequence of assocs" } { "value" { $maybe "a value" } } }
+{ $values { "key" "a key" } { "seq" { $sequence assoc } } { "value" { $maybe "a value" } } }
{ $description "Searches for the key in successive elements of the sequence, starting from the end. If an assoc containing the key is found, the associated value is output. If no assoc contains the key, outputs " { $link f } "." }
{ $notes "This word is used to implement abstractions such as nested scopes; if the sequence is a stack represented by a vector, then the most recently pushed assoc -- the innermost scope -- will be searched first." } ;
{ $notes "This word is used by " { $link "syntax-immediate" } " to ensure that definitions in nested blocks are correctly recorded. User code should not depend on parser internals in such a way that calling this combinator is required." } ;
HELP: recompile
-{ $values { "words" "a sequence of words" } { "alist" "an association list mapping words to compiled definitions" } }
+{ $values { "words" { $sequence word } } { "alist" "an association list mapping words to compiled definitions" } }
{ $contract "Internal word which compiles words. Called at the end of " { $link with-compilation-unit } "." } ;
HELP: to-recompile
{ $notes "This word is called at the end of " { $link with-compilation-unit } "." } ;
HELP: compile
-{ $values { "words" "a sequence of words" } }
+{ $values { "words" { $sequence word } } }
{ $description "Compiles a set of words." } ;
} ;
HELP: throw-restarts
-{ $values { "error" object } { "restarts" "a sequence of " { $snippet "{ string object }" } " pairs" } { "restart" object } }
+{ $values { "error" object } { "restarts" { $sequence { { $snippet "{ string object }" } " pairs" } } } { "restart" object } }
{ $description "Throws a restartable error using " { $link throw } ". The " { $snippet "restarts" } " parameter is a sequence of pairs where the first element in each pair is a human-readable description and the second is an arbitrary object. If the error reaches the top-level error handler, the user will be presented with the list of possible restarts, and upon invoking one, execution will continue after the call to " { $link throw-restarts } " with the object associated to the chosen restart on the stack." }
{ $examples
"Try invoking one of the two restarts which are offered after the below code throws an error:"
} ;
HELP: rethrow-restarts
-{ $values { "error" object } { "restarts" "a sequence of " { $snippet "{ string object }" } " pairs" } { "restart" object } }
+{ $values { "error" object } { "restarts" { $sequence { { $snippet "{ string object }" } " pairs" } } } { "restart" object } }
{ $description "Throws a restartable error using " { $link rethrow } ". Otherwise, this word is identical to " { $link throw-restarts } "." } ;
{ throw rethrow throw-restarts rethrow-restarts throw-continue } related-words
{ $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
HELP: forget-all
-{ $values { "definitions" "a sequence of definition specifiers" } }
+{ $values { "definitions" { $sequence "definition specifiers" } } }
{ $description "Forgets every definition in a sequence." }
{ $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
{ $description "Creates a new method." } ;
HELP: order
-{ $values { "generic" generic } { "seq" "a sequence of classes" } }
+{ $values { "generic" generic } { "seq" { $sequence class } } }
{ $description "Outputs a sequence of classes for which methods have been defined on this generic word. The sequence is sorted in method dispatch order." } ;
HELP: check-method
ABOUT: "stream-binary"
HELP: be>
-{ $values { "seq" "a sequence of bytes" } { "x" "a non-negative integer" } }
+{ $values { "seq" { $sequence "bytes" } } { "x" "a non-negative integer" } }
{ $description "Converts a sequence of bytes in big endian order into an unsigned integer." } ;
HELP: le>
-{ $values { "seq" "a sequence of bytes" } { "x" "a non-negative integer" } }
+{ $values { "seq" { $sequence "bytes" } } { "x" "a non-negative integer" } }
{ $description "Converts a sequence of bytes in little endian order into an unsigned integer." } ;
HELP: nth-byte
$io-error ;
HELP: stream-lines
-{ $values { "stream" "an input stream" } { "seq" "a sequence of strings" } }
+{ $values { "stream" "an input stream" } { "seq" { $sequence string } } }
{ $description "Reads lines of text until the stream is exhausted, collecting them in a sequence of strings." } ;
HELP: lines
-{ $values { "seq" "a sequence of strings" } }
+{ $values { "seq" { $sequence string } } }
{ $description "Reads lines of text until from the " { $link input-stream } " until it is exhausted, collecting them in a sequence of strings." } ;
HELP: each-line
"Custom lexing can be implemented by delegating a tuple to an instance of this class and implementing the " { $link skip-word } " and " { $link skip-blank } " generic words." } ;
HELP: <lexer>
-{ $values { "text" "a sequence of strings" } { "lexer" lexer } }
+{ $values { "text" { $sequence string } } { "lexer" lexer } }
{ $description "Creates a new lexer for tokenizing the given sequence of lines." } ;
HELP: next-line
$parsing-note ;
HELP: map-tokens
-{ $values { "end" string } { "quot" { $quotation ( ... token -- ... elt ) } } { "seq" "a new sequence of " { $snippet "object" } "s" } }
+{ $values { "end" string } { "quot" { $quotation ( ... token -- ... elt ) } } { "seq" { $sequence object } } }
{ $description "Reads a sequence of tokens until the first occurrence of " { $snippet "end" } ". " { $snippet "quot" } " is called on each token as it is read, and the results are collected into a new output sequence." }
$parsing-note ;
HELP: parse-tokens
-{ $values { "end" string } { "seq" "a new sequence of strings" } }
+{ $values { "end" string } { "seq" { $sequence string } } }
{ $description "Reads a sequence of tokens until the first occurrence of " { $snippet "end" } ". The tokens remain as strings and are not processed in any way. This word is equivalent to " { $link map-tokens } " with an empty quotation." }
$parsing-note ;
"There are additional parsing words whose syntax is delimited by " { $link POSTPONE: ; } ", and they are all implemented by calling " { $link parse-definition } "." ;
ARTICLE: "parsing-tokens" "Parsing raw tokens"
-"So far we have seen how to read individual tokens, or read a sequence of parsed objects until a delimiter. It is also possible to read raw tokens from the input and perform custom processing."
+"So far we have seen how to read individual tokens, or read a of parsed objects until a delimiter. It is also possible to read raw tokens from the input and perform custom processing."
$nl
"One example is the " { $link POSTPONE: USING: } " parsing word."
{ $see POSTPONE: USING: }
{ $errors "Throws a " { $link lexer-error } " if the input is malformed." } ;
HELP: parse-lines
-{ $values { "lines" "a sequence of strings" } { "quot" "a new " { $link quotation } } }
+{ $values { "lines" { $sequence string } } { "quot" "a new " { $link quotation } } }
{ $description "Parses Factor source code which has been tokenized into lines. The vocabulary search path is taken from the current scope." }
{ $errors "Throws a " { $link lexer-error } " if the input is malformed." } ;
{ $description "Calls the quotation in a scope with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary." } ;
HELP: parse-fresh
-{ $values { "lines" "a sequence of strings" } { "quot" quotation } }
+{ $values { "lines" { $sequence string } } { "quot" quotation } }
{ $description "Parses Factor source code in a sequence of lines. The initial vocabulary search path is used (see " { $link with-file-vocabs } ")." }
{ $errors "Throws a parse error if the input is malformed." } ;
HELP: filter-moved
-{ $values { "set1" set } { "set2" set } { "seq" "an sequence of definitions" } }
+{ $values { "set1" set } { "set2" set } { "seq" { $sequence "definitions" } } }
{ $description "Removes all definitions from " { $snippet "set2" } " which are in " { $snippet "set1" } " or are no longer present in the " { $link current-source-file } "." } ;
HELP: forget-smudged
{ $description "Creates a new string buffer that can hold " { $snippet "n" } " characters before resizing." } ;
HELP: >sbuf
-{ $values { "seq" "a sequence of non-negative integers" } { "sbuf" sbuf } }
+{ $values { "seq" { $sequence "non-negative integers" } } { "sbuf" sbuf } }
{ $description "Outputs a freshly-allocated string buffer with the same elements as a given sequence." }
{ $errors "Throws an error if the sequence contains elements other than real numbers." } ;
{ $description "Returns the number of elements in the set. All sets support this operation." } ;
HELP: combine
-{ $values { "sets" "a sequence of sets" } { "set/f" { $maybe unordered-set } } }
+{ $values { "sets" { $sequence unordered-set } } { "set/f" { $maybe unordered-set } } }
{ $description "Outputs the union of a sequence of sets, or " { $link f } " if the sequence is empty." } ;
$low-level-note ;
HELP: define-accessors
-{ $values { "class" class } { "specs" "a sequence of " { $link slot-spec } " instances" } }
+{ $values { "class" class } { "specs" { $sequence slot-spec } } }
{ $description "Defines slot methods." }
$low-level-note ;
{ $warning "This word is in the " { $vocab-link "slots.private" } " vocabulary because it does not perform type or bounds checks, and slot numbers are implementation detail." } ;
HELP: slot-named
-{ $values { "name" string } { "specs" "a sequence of " { $link slot-spec } " instances" } { "spec/f" { $maybe slot-spec } } }
+{ $values { "name" string } { "specs" { $sequence slot-spec } } { "spec/f" { $maybe slot-spec } } }
{ $description "Outputs the " { $link slot-spec } " with the given name." } ;
{ $description "Sorts the elements of " { $snippet "obj" } " (converting to an alist first if not a sequence), comparing second elements of pairs using the " { $link <=> } " word." } ;
HELP: natural-sort
-{ $values { "seq" "a sequence of real numbers" } { "sortedseq" "a new sorted sequence" } }
+{ $values { "seq" sequence } { "sortedseq" "a new sorted sequence" } }
{ $description "Sorts a sequence of objects in natural order using the " { $link <=> } " word." } ;
HELP: sort-pair
{ $description "Like " { $link ?tail } ", except the resulting sequence is a " { $link slice } "." } ;
HELP: string-lines
-{ $values { "str" string } { "seq" "a sequence of strings" } }
+{ $values { "str" string } { "seq" { $sequence string } } }
{ $description "Splits a string along line breaks." }
{ $examples
{ $example "USING: prettyprint splitting ;" "\"Hello\\r\\nworld\\n\" string-lines ." "{ \"Hello\" \"world\" }" }
{ $description "Outputs a string of one character." } ;
HELP: >string
-{ $values { "seq" "a sequence of characters" } { "str" string } }
+{ $values { "seq" { $sequence "characters" } } { "str" string } }
{ $description "Outputs a freshly-allocated string with the same elements as a given sequence, by interpreting the sequence elements as Unicode code points." }
{ $notes "This operation is only appropriate if the underlying sequence holds Unicode code points, which is rare unless it is a " { $link slice } " of another string. To convert a sequence of bytes to a string, use the words documented in " { $link "io.encodings.string" } "." }
{ $errors "Throws an error if the sequence contains elements other than integers." } ;
HELP: SYMBOLS:
{ $syntax "SYMBOLS: words... ;" }
-{ $values { "words" "a sequence of new words to define" } }
+{ $values { "words" { $sequence "new words to define" } } }
{ $description "Creates a new symbol for every token until the " { $snippet ";" } "." }
{ $examples { $example "USING: prettyprint ;" "IN: scratchpad" "SYMBOLS: foo bar baz ;\nfoo . bar . baz ." "foo\nbar\nbaz" } } ;
HELP: SINGLETONS:
{ $syntax "SINGLETONS: words... ;" }
-{ $values { "words" "a sequence of new words to define" } }
+{ $values { "words" { $sequence "new words to define" } } }
{ $description "Creates a new singleton for every token until the " { $snippet ";" } "." } ;
HELP: ALIAS:
{ $errors "Throws a " { $link no-vocab } " error if the vocabulary does not exist on disk." } ;
HELP: require-when
-{ $values { "if" "a sequence of vocabulary specifiers" } { "then" "a vocabulary specifier" } }
+{ $values { "if" { $sequence "vocabulary specifiers" } } { "then" "a vocabulary specifier" } }
{ $description "Loads the " { $snippet "then" } " vocabulary if it is not loaded and all of the " { $snippet "if" } " vocabulary is. If some of the " { $snippet "if" } " vocabularies are not loaded now, but they are later, then the " { $snippet "then" } " vocabulary will be loaded along with the final one." }
{ $notes "This is used to express a joint dependency of vocabularies. If vocabularies " { $snippet "a" } " and " { $snippet "b" } " use code in vocabulary " { $snippet "c" } " to interact, then the following line, which can be placed in " { $snippet "a" } " or " { $snippet "b" } ", expresses the dependency."
{ $code "{ \"a\" \"b\" } \"c\" require-when" } } ;
{ $side-effects "word" } ;
HELP: remove-word-props
-{ $values { "word" word } { "seq" "a sequence of word property names" } }
+{ $values { "word" word } { "seq" { $sequence "word property names" } } }
{ $description "Removes all listed word properties from the word." }
{ $side-effects "word" } ;
projects / factor.git / commitdiff