-USING: compiler.cfg.instructions help.markup help.syntax ;
+USING: compiler.cfg.instructions help.markup help.syntax kernel ;
IN: compiler.cfg.alias-analysis
HELP: useless-compare?
{ $values
{ "insn" "a " { $link ##compare } " instruction" }
- { "?" "a boolean" }
+ { "?" boolean }
}
{ $description "Checks if the comparison instruction is required." } ;
-USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax ;
+USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax kernel ;
IN: compiler.cfg.block-joining
HELP: join-block?
-{ $values { "bb" basic-block } { "?" "a boolean" } }
+{ $values { "bb" basic-block } { "?" boolean } }
{ $description "Whether the block can be joined with its predecessor or not." } ;
HELP: join-blocks
USING: assocs compiler.cfg compiler.cfg.builder.blocks
-compiler.cfg.stacks.local compiler.tree help.markup help.syntax literals math
-multiline sequences vectors words ;
+compiler.cfg.stacks.local compiler.tree help.markup help.syntax
+kernel literals math multiline sequences vectors words ;
IN: compiler.cfg.builder
<<
HELP: trivial-branch?
{ $values
{ "nodes" "a " { $link sequence } " of " { $link node } " instances" }
- { "value" "the pushed value or " { $link f } }
- { "?" "a boolean" }
+ { "value" { $maybe "the pushed value" } }
+ { "?" boolean }
}
{ $description "Checks whether nodes is a trivial branch or not. The branch is counted as trivial if all it does is push a literal value on the stack." }
{ $examples
{ $description "A basic block is divided into sections by " { $link ##call } " and " { $link ##phi } " instructions. For every section with at least one allocation, record the offset of its first instruction in a sequence." } ;
HELP: insert-gc-check?
-{ $values { "bb" basic-block } { "?" "a boolean" } }
+{ $values { "bb" basic-block } { "?" boolean } }
{ $description "Whether to insert a gc check in the block or not." } ;
HELP: insert-gc-checks
USING: assocs compiler.cfg compiler.cfg.instructions
compiler.cfg.linear-scan.allocation compiler.cfg.linear-scan.allocation.state
-compiler.cfg.linear-scan.live-intervals help.markup help.syntax sequences ;
+compiler.cfg.linear-scan.live-intervals help.markup help.syntax kernel sequences ;
IN: compiler.cfg.linear-scan.allocation
HELP: (allocate-registers)
{ $values
{ "sync-point" sync-point }
{ "live-interval" live-interval-state }
- { "?" "a boolean" }
+ { "?" boolean }
}
{ $description "Maybe spills the live-interval at the given sync point. If the interval was spilled, then " { $link f } " is put on the stack to indicate that the interval isn't live anymore, " { $link t } " otherwise." }
{ $see-also spill-at-sync-point? } ;
{ $values
{ "sync-point" sync-point }
{ "live-interval" live-interval-state }
- { "?" "a boolean" }
+ { "?" boolean }
}
{ $description "If the live interval has a definition at a keep-dst? sync-point, don't spill." } ;
compiler.cfg.linear-scan.allocation
compiler.cfg.linear-scan.allocation.spilling
compiler.cfg.linear-scan.live-intervals cpu.architecture heaps help.markup
-help.syntax math sequences vectors ;
+help.syntax kernel math sequences vectors ;
IN: compiler.cfg.linear-scan.allocation.state
HELP: activate-intervals
{ $see-also check-handled check-unhandled } ;
HELP: register-available?
-{ $values { "new" live-interval-state } { "result" "a pair" } { "?" "a boolean" } }
+{ $values { "new" live-interval-state } { "result" "a pair" } { "?" boolean } }
{ $description "Whether the register in 'result' can be used for the given live interval." } ;
HELP: registers
USING: assocs compiler.cfg compiler.cfg.def-use compiler.cfg.instructions
-compiler.cfg.representations help.markup help.syntax ;
+compiler.cfg.representations help.markup help.syntax kernel ;
IN: compiler.cfg.liveness
HELP: base-pointers
{ $description "All the virtual registers that are live in a basic block." } ;
HELP: live-in?
-{ $values { "vreg" "virtual register" } { "bb" basic-block } { "?" "a boolean" } }
+{ $values { "vreg" "virtual register" } { "bb" basic-block } { "?" boolean } }
{ $description "Whether the vreg is live in the block or not." } ;
HELP: live-ins
{ $see-also compute-live-sets } ;
HELP: lookup-base-pointer
-{ $values { "vreg" "vreg" } { "vreg/f" "vreg or " { $link f } } }
+{ $values { "vreg" "vreg" } { "vreg/f" { $maybe "vreg" } } }
{ $description "Tries to figure out what the base pointer for a vreg is. Can't use cache here because of infinite recursion inside the quotation passed to cache" }
{ $see-also base-pointers } ;
-USING: compiler.cfg.instructions help.markup help.syntax ;
+USING: compiler.cfg.instructions help.markup help.syntax kernel ;
IN: compiler.cfg.representations.peephole
HELP: convert-to-zero-vector?
-{ $values { "insn" insn } { "?" "a boolean" } }
+{ $values { "insn" insn } { "?" boolean } }
{ $description "When a literal zeroes/ones vector is unboxed, we replace the " { $link ##load-reference } " with a " { $link ##zero-vector } " or " { $link ##fill-vector } " instruction since this is more efficient." } ;
USING: compiler.cfg compiler.cfg.instructions help.markup help.syntax
-math sequences ;
+math sequences kernel ;
IN: compiler.cfg.save-contexts
HELP: insert-save-contexts
{ $see-also context-save-needed } ;
HELP: insns-needs-save-context?
-{ $values { "insns" sequence } { "?" "a boolean" } }
+{ $values { "insns" sequence } { "?" boolean } }
{ $description "Whether to insert a " { $link ##save-context } " instruction in the given instruction sequence or not." }
{ $see-also context-save-needed } ;
{ $var-description "Variable that holds a sequence of " { $link gc-map } " tuples." } ;
HELP: gc-map-needed?
-{ $values { "gc-map/f" "a " { $link gc-map } " or f" } { "?" "a boolean" } }
+{ $values { "gc-map/f" { $maybe gc-map } } { "?" boolean } }
{ $description "If all slots in the gc-map are empty, then it doesn't need to be emitted." } ;
HELP: serialize-gc-maps
IN: compiler.tree.debugger
HELP: #>r?
-{ $values { "#shuffle" #shuffle } { "?" "a boolean" } }
+{ $values { "#shuffle" #shuffle } { "?" boolean } }
{ $description "True if the #shuffle copies an item from the data stack to the retain stack." } ;
USING: combinators.private compiler.units effects help.markup help.syntax
-quotations ;
+kernel quotations words ;
IN: compiler.tree.propagation.call-effect
HELP: already-inlined-quot?
-{ $values { "quot" quotation } { "?" "a boolean" } }
+{ $values { "quot" quotation } { "?" boolean } }
{ $description "Some bookkeeping to make sure that crap like [ dup curry call( quot -- ) ] dup curry call( quot -- ) ] doesn't hang the compiler." } ;
HELP: cached-effect-valid?
-{ $values { "quot" quotation } { "?" "a boolean" } }
+{ $values { "quot" quotation } { "?" boolean } }
{ $description { $link t } " if the cached effect is valid." } ;
HELP: call-effect-ic
{ $description "Creates a quotation which wraps " { $link call-effect-unsafe } "." } ;
HELP: call-effect-unsafe?
-{ $values { "quot" quotation } { "effect" effect } { "?" "a boolean" } }
+{ $values { "quot" quotation } { "effect" effect } { "?" boolean } }
{ $description "Checks if the given effect is safe with regards to the quotation." } ;
HELP: update-inline-cache
-{ $values { "word/quot" "word or quotation" } { "ic" inline-cache } }
+{ $values { "word/quot" { $or word quotation } } { "ic" inline-cache } }
{ $description "Sets the inline caches " { $slot "value" } " to the given word/quot and updates its " { $slot "counter" } " to the value of the " { $link effect-counter } "." } ;
ARTICLE: "compiler.tree.propagation.call-effect" "Expansions of call( and execute( words"
{ $examples { $unchecked-example $[ ex-%write-barrier ] } } ;
HELP: test-instruction?
-{ $values { "?" "a boolean" } }
+{ $values { "?" boolean } }
{ $description "Does the current architecture have a test instruction? Used on x86 to rewrite some " { $link CMP } " instructions to less expensive " { $link TEST } "s." } ;
HELP: fused-unboxing?
{ $description "What registers that will be used for function return values of which class." } ;
HELP: return-struct-in-registers?
-{ $values { "c-type" class } { "?" "a boolean" } }
+{ $values { "c-type" class } { "?" boolean } }
{ $description "Whether the size of the struct is so small that it will be returned in registers or not." } ;
HELP: stack-cleanup
{ $errors "Throws an error if the deque is empty." } ;
HELP: ?peek-front
-{ $values { "deque" deque } { "obj/f" "an object or " { $link f } } }
+{ $values { "deque" deque } { "obj/f" { $maybe object } } }
{ $description "A forgiving version of " { $link peek-front } ". If the deque is empty, returns " { $link f } "." } ;
HELP: pop-front
{ $errors "Throws an error if the deque is empty." } ;
HELP: ?peek-back
-{ $values { "deque" deque } { "obj/f" "an object or " { $link f } } }
+{ $values { "deque" deque } { "obj/f" { $maybe object } } }
{ $description "A forgiving version of " { $link peek-back } ". If the deque is empty, returns " { $link f } "." } ;
HELP: pop-back
{ $description "Creates a new " { $link search-deque } " backed by a " { $link dlist } ", with a " { $link hashtable } " for fast membership tests." } ;
HELP: dlist-find
-{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } { "?" boolean } }
+{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" { $maybe object } } { "?" boolean } }
{ $description "Applies the quotation to each element of the " { $link dlist } " in turn, until it outputs a true value or the end of the " { $link dlist } " is reached. Outputs either the object it found or " { $link f } ", and a boolean which is true if an object is found." }
{ $notes "Returns a boolean to allow dlists to store " { $link f } "."
$nl
{ $notes "This operation is O(n)." } ;
HELP: delete-node-if*
-{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } { "?" boolean } }
+{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" { $maybe object } } { "?" boolean } }
{ $description "Calls " { $link dlist-find } " on the " { $link dlist } " and deletes the node returned, if any. Returns the value of the deleted node and a boolean to allow the deleted value to distinguished from " { $link f } ", for nothing deleted." }
{ $notes "This operation is O(n)." } ;
HELP: delete-node-if
-{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } }
+{ $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" { $maybe object } } }
{ $description "Like " { $link delete-node-if* } " but cannot distinguish from deleting a node whose value is " { $link f } " or not deleting an element." }
{ $notes "This operation is O(n)." } ;
{ $error-description "Thrown by " { $link http-request } " if the server returns a chain of than " { $link max-redirects } " redirections." } ;
HELP: <get-request>
-{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $values { "url" { $or url string } } { "request" request } }
{ $description "Constructs an HTTP GET request for retrieving the URL." }
{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
HELP: <post-request>
-{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $values { "post-data" object } { "url" { $or url string } } { "request" request } }
{ $description "Constructs an HTTP POST request for submitting post data to the URL." }
{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
HELP: <head-request>
-{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $values { "url" { $or url string } } { "request" request } }
{ $description "Constructs an HTTP HEAD request for retrieving the URL." }
{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
HELP: <delete-request>
-{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $values { "url" { $or url string } } { "request" request } }
{ $description "Constructs an HTTP DELETE request for the requested URL." }
{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
HELP: <options-request>
-{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $values { "url" { $or url string } } { "request" request } }
{ $description "Constructs an HTTP OPTIONS request for the requested URL." }
{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
HELP: <trace-request>
-{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $values { "url" { $or url string } } { "request" request } }
{ $description "Constructs an HTTP TRACE request for the requested URL." }
{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
HELP: download
-{ $values { "url" "a " { $link url } " or " { $link string } } }
+{ $values { "url" { $or url string } } }
{ $description "Downloads the contents of the URL to a file in the " { $link current-directory } " having the same file name." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: download-to
-{ $values { "url" "a " { $link url } " or " { $link string } } { "file" "a pathname string" } }
+{ $values { "url" { $or url string } } { "file" "a pathname string" } }
{ $description "Downloads the contents of the URL to a file with the given pathname." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: ?download-to
-{ $values { "url" "a " { $link url } " or " { $link string } } { "file" "a pathname string" } }
+{ $values { "url" { $or url string } } { "file" "a pathname string" } }
{ $description "Version of " { $link download-to } " that only downloads if " { $snippet "file" } " does not exist." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: http-get
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Downloads the contents of a URL." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: http-get*
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Downloads the contents of a URL, but does not check the HTTP response code for success." } ;
{ http-get http-get* } related-words
HELP: http-post
-{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Submits an HTTP POST request." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: http-post*
-{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Submits an HTTP POST request, but does not check the HTTP response code for success." } ;
{ http-post http-post* } related-words
HELP: http-put
-{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Submits an HTTP PUT request." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: http-put*
-{ $values { "post-data" object } { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "post-data" object } { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Submits an HTTP PUT request, but does not check the HTTP response code for success." } ;
{ http-put http-put* } related-words
HELP: http-head
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Same as " { $link http-get } " except that the server is not supposed to return a message-body in the response, as per RFC2616. However in practise, most web servers respond to GET and HEAD method calls with identical responses." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: http-head*
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Same as " { $link http-get* } " except that the server is not supposed to return a message-body in the response, as per RFC2616. However in practise, most web servers respond to GET and HEAD method calls with identical responses." } ;
{ http-head http-head* } related-words
HELP: http-delete
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Requests that the origin server delete the resource identified by the URL." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: http-delete*
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Requests that the origin server delete the resource identified by the URL, but does not check the HTTP response code for success." } ;
{ http-delete http-delete* } related-words
HELP: http-options
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Submits an HTTP OPTIONS request." }
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: http-options*
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Submits an HTTP OPTIONS request, but does not check the HTTP response code for success." } ;
{ http-options http-options* } related-words
{ $errors "Throws an error if the HTTP request fails." } ;
HELP: http-trace*
-{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $values { "url" { $or url string } } { "response" response } { "data" sequence } }
{ $description "Submits an HTTP TRACE request, but does not check the HTTP response code for success." } ;
{ http-trace http-trace* } related-words
-USING: help.markup help.syntax kernel prettyprint.config
+USING: help.markup help.syntax kernel math prettyprint.config
prettyprint.custom sequences strings words ;
IN: prettyprint.backend
$prettyprinting-note ;
HELP: do-length-limit
-{ $values { "seq" sequence } { "trimmed" "a trimmed sequence" } { "n/f" "an integer or " { $link f } } }
+{ $values { "seq" sequence } { "trimmed" "a trimmed sequence" } { "n/f" { $maybe integer } } }
{ $description "If the " { $link length-limit } " is set and the sequence length exceeds this limit, trims the sequence and outputs a the number of elements which were chopped off the end. Otherwise outputs " { $link f } "." }
$prettyprinting-note ;
{ $var-description "A " { $link min-heap } " storing the queue of sleeping threads." } ;
HELP: sleep-time
-{ $values { "nanos/f" "a non-negative integer or " { $link f } } }
+{ $values { "nanos/f" { $maybe "a non-negative integer" } } }
{ $description "Returns the time until the next sleeping thread is scheduled to wake up, which could be zero if there are threads in the run queue, or threads which need to wake up right now. If there are no runnable or sleeping threads, returns " { $link f } "." } ;
HELP: stop
{ $description "Adds the current thread to the end of the run queue, and switches to the next runnable thread." } ;
HELP: sleep-until
-{ $values { "n/f" "a non-negative integer or " { $link f } } }
+{ $values { "n/f" { $maybe "a non-negative integer" } } }
{ $description "Suspends the current thread until the given nanosecond count, returned by " { $link nano-count } ", is reached, or indefinitely if a value of " { $link f } " is passed in."
$nl
"Other threads may interrupt the sleep by calling " { $link interrupt } "." } ;
{ invoke-command +nullary+ } related-words
HELP: command-name
-{ $values { "command" "a command" } { "str" "a string" } }
+{ $values { "command" "a command" } { "str" string } }
{ $description "Outputs a human-readable name for the command." }
{ $examples
{ $example
} ;
HELP: command-description
-{ $values { "command" "a command" } { "str/f" "a string or " { $link f } } }
+{ $values { "command" "a command" } { "str/f" { $maybe string } } }
{ $description "Outputs the command's description." } ;
{ command-description +description+ } related-words
} } ;
HELP: operation-gesture
-{ $values { "operation" operation } { "gesture" "a gesture or " { $link f } } }
+{ $values { "operation" operation } { "gesture" { $maybe "a gesture" } } }
{ $description "Outputs the keyboard gesture associated with the operation." } ;
HELP: operations
ABOUT: "vocabs.metadata"
HELP: vocab-file-contents
-{ $values { "vocab" "a vocabulary specifier" } { "name" string } { "seq" "a sequence of lines, or " { $link f } } }
+{ $values { "vocab" "a vocabulary specifier" } { "name" string } { "seq" { $maybe "a sequence of lines" } } }
{ $description "Outputs the contents of the file named " { $snippet "name" } " from the vocabulary's directory, or " { $link f } " if the file does not exist." } ;
HELP: set-vocab-file-contents
{ $description "Stores a sequence of lines to the file named " { $snippet "name" } " from the vocabulary's directory." } ;
HELP: vocab-summary
-{ $values { "vocab" "a vocabulary specifier" } { "summary" "a string or " { $link f } } }
+{ $values { "vocab" "a vocabulary specifier" } { "summary" { $maybe string } } }
{ $description "Outputs a one-line string description of the vocabulary's intended purpose from the " { $snippet "summary.txt" } " file in the vocabulary's directory. Outputs " { $link f } " if the file does not exist." } ;
HELP: set-vocab-summary
-{ $values { "string" "a string or " { $link f } } { "vocab" "a vocabulary specifier" } }
+{ $values { "string" { $maybe string } } { "vocab" "a vocabulary specifier" } }
{ $description "Stores a one-line string description of the vocabulary to the " { $snippet "summary.txt" } " file in the vocabulary's directory." } ;
HELP: vocab-tags
{ $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" "a value or " { $link f } } }
+{ $values { "key" "a key" } { "seq" "a sequence of assocs" } { "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." } ;
HELP: value-at*
-{ $values { "value" object } { "assoc" assoc } { "key/f" "the key associated to the value, or " { $link f } } { "?" boolean } }
+{ $values { "value" object } { "assoc" assoc } { "key/f" { $maybe "the key associated to the value" } } { "?" boolean } }
{ $description "Looks up the key associated with a value. The boolean flag can decide between the case of a missing key, and a key of " { $link f } "." } ;
HELP: value-at
-{ $values { "value" object } { "assoc" assoc } { "key/f" "the key associated to the value, or " { $link f } } }
+{ $values { "value" object } { "assoc" assoc } { "key/f" { $maybe "the key associated to the value" } } }
{ $description "Looks up the key associated with a value. No distinction is made between a missing key and a key set to " { $link f } "." } ;
HELP: value?
{ $description "Tests if an assoc contains at least one key with the given value." } ;
HELP: delete-at*
-{ $values { "key" "a key" } { "assoc" assoc } { "old" "the previous value or " { $link f } } { "?" boolean } }
+{ $values { "key" "a key" } { "assoc" assoc } { "old" { $maybe "the previous value" } } { "?" boolean } }
{ $description "Removes an entry from the assoc and outputs the previous value together with a boolean indicating whether it was present." }
{ $side-effects "assoc" } ;
{ $description "Calls the quotation. If an exception is thrown in the dynamic extent of the quotation, restores the data stack and returns." } ;
HELP: in-callback?
-{ $values { "?" "a boolean" } }
+{ $values { "?" boolean } }
{ $description "t if Factor is currently executing a callback." } ;
HELP: rethrow
{ $contract "Outputs one of " { $link +byte+ } " or " { $link +character+ } "." } ;
HELP: stream-readln
-{ $values { "stream" "an input stream" } { "str/f" "a string or " { $link f } } }
+{ $values { "stream" "an input stream" } { "str/f" { $maybe string } } }
{ $contract "Reads a line of input from the stream. Outputs " { $link f } " on stream exhaustion." }
{ $notes "Most code only works on one stream at a time and should instead use " { $link readln } "; see " { $link "stdio" } "." }
$io-error ;
HELP: stream-read1
-{ $values { "stream" "an input stream" } { "elt" "an element or " { $link f } } }
+{ $values { "stream" "an input stream" } { "elt" { $maybe "an element" } } }
{ $contract "Reads an element from the stream. Outputs " { $link f } " on stream exhaustion." }
{ $notes "Most code only works on one stream at a time and should instead use " { $link read1 } "; see " { $link "stdio" } "." }
$io-error ;
$io-error ;
HELP: stream-read-until
-{ $values { "seps" string } { "stream" "an input stream" } { "seq" { $or byte-array string f } } { "sep/f" "a character or " { $link f } } }
+{ $values { "seps" string } { "stream" "an input stream" } { "seq" { $or byte-array string f } } { "sep/f" { $maybe "a character" } } }
{ $contract "Reads elements from the stream, until the first occurrence of a separator character, or stream exhaustion. In the former case, the separator is pushed on the stack, and is not part of the output string. In the latter case, the entire stream contents are output, along with " { $link f } "." }
{ $notes "Most code only works on one stream at a time and should instead use " { $link read-until } "; see " { $link "stdio" } "." }
$io-error ;
HELP: stream-length
{ $values
- { "stream" "a stream" } { "n/f" "an integer or " { $link f } }
+ { "stream" "a stream" } { "n/f" { $maybe integer } }
}
{ $description "Returns the length of the data supplied by " { $snippet "stream" } ", or " { $link f } " if the stream is not seekable or has unknown length." }
{ $notes "Stream seeking is not supported on streams that do not have a known length, e.g. TCP/IP streams." } ;
{ $var-description "Holds an error stream." } ;
HELP: readln
-{ $values { "str/f" "a string or " { $link f } } }
+{ $values { "str/f" { $maybe string } } }
{ $description "Reads a line of input from " { $link input-stream } ". Outputs " { $link f } " on stream exhaustion." }
$io-error ;
HELP: read1
-{ $values { "elt" "an element or " { $link f } } }
+{ $values { "elt" { $maybe "an element" } } }
{ $description "Reads an element from " { $link input-stream } ". Outputs " { $link f } " on stream exhaustion." }
$io-error ;
$io-error ;
HELP: read-until
-{ $values { "seps" string } { "seq" { $or byte-array string f } } { "sep/f" "a character or " { $link f } } }
+{ $values { "seps" string } { "seq" { $or byte-array string f } } { "sep/f" { $maybe "a character" } } }
{ $contract "Reads elements from " { $link input-stream } " until the first occurrence of a separator, or stream exhaustion. In the former case, the separator character is pushed on the stack, and is not part of the output. In the latter case, the entire stream contents are output, along with " { $link f } "." }
$io-error ;
{ $description "Closes a C FILE* handle." } ;
HELP: fgetc
-{ $values { "alien" "a C FILE* handle" } { "byte/f" "an integer from 0 to 255 or " { $link f } } }
+{ $values { "alien" "a C FILE* handle" } { "byte/f" { $maybe "an integer from 0 to 255" } } }
{ $description "Reads a single byte from a C FILE* handle, and outputs " { $link f } " on end of file." }
{ $errors "Throws an error if the input operation failed." } ;
{ $var-description "Number of distinct built-in types. This is one more than the maximum value from the " { $link tag } " primitive." } ;
HELP: type-number
-{ $values { "class" class } { "n" "an integer or " { $link f } } }
+{ $values { "class" class } { "n" { $maybe integer } } }
{ $description "Outputs the built-in type number instances of " { $link class } ". Will output " { $link f } " if this is not a built-in class." }
{ $see-also builtin-class } ;
{ $notes "This word is used to implement " { $link all? } "." } ;
HELP: find-integer
-{ $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i" "an integer or " { $link f } } }
+{ $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i" { $maybe integer } } }
{ $description "Applies the quotation to each integer from 0 up to " { $snippet "n" } ", excluding " { $snippet "n" } ". Iteration stops when the quotation outputs a true value or the end is reached. If the quotation yields a true value for some integer, this word outputs that integer. Otherwise, this word outputs " { $link f } "." }
{ $notes "This word is used to implement " { $link find } "." } ;
HELP: find-last-integer
-{ $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i" "an integer or " { $link f } } }
+{ $values { "n" integer } { "quot" { $quotation ( ... i -- ... ? ) } } { "i" { $maybe integer } } }
{ $description "Applies the quotation to each integer from " { $snippet "n" } " down to 0, inclusive. Iteration stops when the quotation outputs a true value or 0 is reached. If the quotation yields a true value for some integer, the word outputs that integer. Otherwise, the word outputs " { $link f } "." }
{ $notes "This word is used to implement " { $link find-last } "." } ;
{ $notes "This is one of the factors of " { $link string>number } "." } ;
HELP: base>
-{ $values { "str" string } { "radix" "an integer between 2 and 16" } { "n/f" "a real number or " { $link f } } }
+{ $values { "str" string } { "radix" "an integer between 2 and 16" } { "n/f" { $maybe real } } }
{ $description "Creates a real number from a string representation with the given radix. The radix for floating point literals can be either base 10 or base 16."
$nl
"Outputs " { $link f } " if the string does not represent a number." } ;
{ >base base> } related-words
HELP: string>number
-{ $values { "str" string } { "n/f" "a real number or " { $link f } } }
+{ $values { "str" string } { "n/f" { $maybe real } } }
{ $description "Creates a real number from a string representation of a number in base 10."
$nl
"Outputs " { $link f } " if the string does not represent a number." } ;
{ string>number number>string } related-words
HELP: bin>
-{ $values { "str" string } { "n/f" "a real number or " { $link f } } }
+{ $values { "str" string } { "n/f" { $maybe real } } }
{ $description "Creates a real number from a string representation of a number in base 2."
$nl
"Outputs " { $link f } " if the string does not represent a number." } ;
{ >bin bin> .b } related-words
HELP: oct>
-{ $values { "str" string } { "n/f" "a real number or " { $link f } } }
+{ $values { "str" string } { "n/f" { $maybe real } } }
{ $description "Creates a real number from a string representation of a number in base 8."
$nl
"Outputs " { $link f } " if the string does not represent a number." } ;
{ >oct oct> .o } related-words
HELP: hex>
-{ $values { "str" string } { "n/f" "a real number or " { $link f } } }
+{ $values { "str" string } { "n/f" { $maybe real } } }
{ $description "Creates a real number from a string representation of a number in base 16."
$nl
"Outputs " { $link f } " if the string does not represent a number." } ;
ABOUT: "namespaces"
HELP: get
-{ $values { "variable" "a variable, by convention a symbol" } { "value" "the value, or " { $link f } } }
+{ $values { "variable" "a variable, by convention a symbol" } { "value" { $maybe "the value" } } }
{ $description "Searches the name stack for a namespace containing the variable, and outputs the associated value. If no such namespace is found, outputs " { $link f } "." } ;
HELP: set
{ $description "Tests if the index is within the bounds of the sequence." } ;
HELP: bounds-error
-{ $values { "n" "a positive integer" } { "seq" sequence } }
+{ $values { "n" integer } { "seq" sequence } }
{ $description "Throws a " { $link bounds-error } "." }
{ $error-description "Thrown by " { $link nth } ", " { $link set-nth } " and " { $link set-length } " if the given index lies beyond the bounds of the sequence." } ;
HELP: bounds-check
-{ $values { "n" "a positive integer" } { "seq" sequence } }
+{ $values { "n" integer } { "seq" sequence } }
{ $description "Throws an error if " { $snippet "n" } " is negative or if it is greater than or equal to the length of " { $snippet "seq" } ". Otherwise the two inputs remain on the stack." } ;
HELP: ?nth
-{ $values { "n" integer } { "seq" sequence } { "elt/f" "an object or " { $link f } } }
+{ $values { "n" integer } { "seq" sequence } { "elt/f" { $maybe object } } }
{ $description "A forgiving version of " { $link nth } ". If the index is out of bounds, or if the sequence is " { $link f } ", simply outputs " { $link f } "." } ;
HELP: ?set-nth
{ $description "A forgiving version of " { $link set-nth } ". If the index is out of bounds, does nothing." } ;
HELP: ?first
-{ $values { "seq" sequence } { "elt/f" "an object or " { $link f } } }
+{ $values { "seq" sequence } { "elt/f" { $maybe object } } }
{ $description "A forgiving version of " { $link first } ". If the sequence is empty, or if the sequence is " { $link f } ", simply outputs " { $link f } "." }
{ $examples
"On an empty sequence:"
HELP: ?second
-{ $values { "seq" sequence } { "elt/f" "an object or " { $link f } } }
+{ $values { "seq" sequence } { "elt/f" { $maybe object } } }
{ $description "A forgiving version of " { $link second } ". If the sequence has less than two elements, or if the sequence is " { $link f } ", simply outputs " { $link f } "." } ;
HELP: ?last
-{ $values { "seq" sequence } { "elt/f" "an object or " { $link f } } }
+{ $values { "seq" sequence } { "elt/f" { $maybe object } } }
{ $description "A forgiving version of " { $link last } ". If the sequence is empty, or if the sequence is " { $link f } ", simply outputs " { $link f } "." } ;
HELP: nth-unsafe
{ $values { "n" "a starting index" }
{ "seq" sequence }
{ "quot" { $quotation ( ... elt -- ... ? ) } }
- { "i" "the index of the first match, or " { $link f } }
- { "elt" "the first matching element, or " { $link f } } }
+ { "i" { $maybe "the index of the first match" } }
+ { "elt" { $maybe "the first matching element" } } }
{ $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 " { $link f } " and " { $link f } " as the element." } ;
HELP: find-last
-{ $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "i" "the index of the first match, or f" } { "elt" "the first matching element, or " { $link f } } }
+{ $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "i" { $maybe "the index of the first match" } } { "elt" { $maybe "the first matching element" } } }
{ $description "A simpler variant of " { $link find-last-from } " where the starting index is one less than the length of the sequence." } ;
HELP: find-last-from
-{ $values { "n" "a starting index" } { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "i" "the index of the first match, or f" } { "elt" "the first matching element, or " { $link f } } }
+{ $values { "n" "a starting index" } { "seq" sequence } { "quot" { $quotation ( ... elt -- ... ? ) } } { "i" { $maybe "the index of the first match" } } { "elt" { $maybe "the first matching element" } } }
{ $description "Applies the quotation to each element of the sequence in reverse order, until it outputs a true value or the start 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 " { $link f } " and " { $link f } " as the element." } ;
HELP: find-index
{ $values { "seq" sequence }
{ "quot" { $quotation ( ... elt i -- ... ? ) } }
- { "i" "the index of the first match, or " { $link f } }
- { "elt" "the first matching element, or " { $link f } } }
+ { "i" { $maybe "the index of the first match" } }
+ { "elt" { $maybe "the first matching element" } } }
{ $description "A varient of " { $link find } " where the quotation takes both an element and its index." } ;
HELP: find-index-from
{ $values { "n" "a starting index" }
{ "seq" sequence }
{ "quot" { $quotation ( ... elt i -- ... ? ) } }
- { "i" "the index of the first match, or " { $link f } }
- { "elt" "the first matching element, or " { $link f } } }
+ { "i" { $maybe "the index of the first match" } }
+ { "elt" { $maybe "the first matching element" } } }
{ $description "A varient of " { $link find-from } " where the quotation takes both an element and its index." } ;
HELP: map-find
-{ $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... result/f ) } } { "result" "the first non-false result of the quotation" } { "elt" "the first matching element, or " { $link f } } }
+{ $values { "seq" sequence } { "quot" { $quotation ( ... elt -- ... result/f ) } } { "result" "the first non-false result of the quotation" } { "elt" { $maybe "the first matching element" } } }
{ $description "Applies the quotation to each element of the sequence, until the quotation outputs a true value. If the quotation ever yields a result which is not " { $link f } ", then the value is output, along with the element of the sequence which yielded this." } ;
HELP: any?
{ $description "Outputs the product of all elements of " { $snippet "seq" } ". Outputs one given an empty sequence." } ;
HELP: infimum
-{ $values { "seq" "a sequence of real numbers" } { "n" number } }
+{ $values { "seq" "a sequence of real numbers" } { "elt" object } }
{ $description "Outputs the least element of " { $snippet "seq" } "." }
{ $errors "Throws an error if the sequence is empty." } ;
HELP: supremum
-{ $values { "seq" "a sequence of real numbers" } { "n" number } }
+{ $values { "seq" "a sequence of real numbers" } { "elt" object } }
{ $description "Outputs the greatest element of " { $snippet "seq" } "." }
{ $errors "Throws an error if the sequence is empty." } ;
: product ( seq -- n ) 1 [ * ] binary-reduce ;
-: infimum ( seq -- n ) [ ] [ min ] map-reduce ;
+: infimum ( seq -- elt ) [ ] [ min ] map-reduce ;
-: supremum ( seq -- n ) [ ] [ max ] map-reduce ;
+: supremum ( seq -- elt ) [ ] [ max ] map-reduce ;
: map-sum ( ... seq quot: ( ... elt -- ... n ) -- ... n )
[ 0 ] 2dip [ dip + ] curry [ swap ] prepose each ; inline
{ $description "Create a new vector with one element." } ;
HELP: ?push
-{ $values { "elt" object } { "seq/f" "a resizable mutable sequence, or " { $link f } } { "seq" "a resizable mutable sequence" } }
+{ $values { "elt" object } { "seq/f" { $maybe "a resizable mutable sequence" } } { "seq" "a resizable mutable sequence" } }
{ $description "If the given sequence is " { $link f } ", creates and outputs a new one-element vector holding " { $snippet "elt" } ". Otherwise, pushes " { $snippet "elt" } " onto the given sequence." }
{ $errors "Throws an error if " { $snippet "seq" } " is not resizable, or if the type of " { $snippet "elt" } " is not permitted in " { $snippet "seq" } "." }
{ $side-effects "seq" } ;
USING: vocabs vocabs.loader.private help.markup help.syntax
-words strings io ;
+words strings io hashtables ;
IN: vocabs.loader
ARTICLE: "add-vocab-roots" "Working with code outside of the Factor source tree"
ABOUT: "vocabs.loader"
HELP: load-vocab
-{ $values { "name" "a string" } { "vocab" "a hashtable or " { $link f } } }
+{ $values { "name" "a string" } { "vocab" { $maybe hashtable } } }
{ $description "Attempts to load a vocabulary from disk, or looks up the vocabulary in the dictionary, and then outputs that vocabulary object." } ;
HELP: vocab-main
{ $description "Runs a vocabulary's main entry point. The main entry point is set with the " { $link POSTPONE: MAIN: } " parsing word." } ;
HELP: vocab-source-path
-{ $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } }
+{ $values { "vocab" "a vocabulary specifier" } { "path/f" { $maybe "a pathname string" } } }
{ $description "Outputs a pathname where source code for " { $snippet "vocab" } " might be found. Outputs " { $link f } " if the vocabulary does not have a directory on disk." } ;
HELP: vocab-docs-path
-{ $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string or " { $link f } } }
+{ $values { "vocab" "a vocabulary specifier" } { "path/f" { $maybe "a pathname string" } } }
{ $description "Outputs a pathname where the documentation for " { $snippet "vocab" } " might be found. Outputs " { $link f } " if the vocabulary does not have a directory on disk." } ;
{ $notes "Outputs " { $link f } " if the object is not a word." } ;
HELP: inline?
-{ $values { "obj" object } { "?" "a boolean" } }
+{ $values { "obj" object } { "?" boolean } }
{ $description "Tests if an object is " { $link POSTPONE: inline } "." }
{ $notes "Outputs " { $link f } " if the object is not a word." } ;
HELP: unmarshall-bool
{ $values
{ "n" number }
- { "?" "a boolean" }
+ { "?" boolean }
}
{ $description "Unmarshalls a number to a boolean." } ;
HELP: unmarshall-bool*
{ $values
{ "alien" alien }
- { "?" "a boolean" }
+ { "?" boolean }
}
{ $description "Unmarshalls a C pointer to a boolean." } ;
HELP: unmarshall-bool*-free
{ $values
{ "alien" alien }
- { "?" "a boolean" }
+ { "?" boolean }
}
{ $description "Unmarshalls a C pointer to a boolean and frees the pointer." } ;
projects / factor.git / commitdiff