! Copyright (C) 2009 Slava Pestov.
! See http://factorcode.org/license.txt for BSD license.
-USING: alien alien.syntax assocs help.markup help.syntax strings words
-;
+USING: alien alien.syntax assocs help.markup help.syntax kernel
+strings ;
IN: alien.libraries
HELP: add-library
} ;
HELP: library-dll
-{ $values { "name" string } { "dll" "a DLL handle" } }
+{ $values { "obj" object } { "dll" "a DLL handle" } }
{ $description "Looks up a library by logical name and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." } ;
HELP: remove-library
{ $description "Creates the defining quotation for the primitive. If 'vm-func' is a string, then it is prefixed with 'primitive_' and a quotation calling that C++ function is generated." } ;
ARTICLE: "bootstrap.image.primitives" "Bootstrap primitives"
-"This vocab contains utilities for declaring primitives to be added to the bootstrap image. It is used by " { $vocab-link "bootstrap.primitives" }
+"This vocab contains utilities for declaring primitives to be added to the bootstrap image. It is used by the file " { $snippet "resource:core/bootstrap/primitives.factor" }
$nl
{ $link all-primitives } " is an assoc where all primitives are declared. See that constant for a description of the format." ;
-USING: assocs compiler.cfg compiler.cfg.builder.blocks
-compiler.cfg.instructions compiler.cfg.stacks.local compiler.tree
-help.markup help.syntax kernel literals math multiline quotations
-sequences vectors words ;
+USING: arrays assocs compiler.cfg compiler.cfg.builder.blocks
+compiler.cfg.instructions compiler.cfg.stacks.local
+compiler.tree help.markup help.syntax kernel literals math
+multiline quotations sequences vectors words ;
IN: compiler.cfg.builder
<<
{ $description "Ends the word by adding a basic block containing a " { $link ##return } " instructions to the " { $link cfg } "." } ;
HELP: height-changes
-{ $values { "#shuffle" #shuffle } { "height-changes" sequence } }
+{ $values { "#shuffle" #shuffle } { "height-changes" pair } }
{ $description "Returns a two-tuple which represents how much the " { $link #shuffle } " node increases or decreases the data and retainstacks." }
{ $examples
{ $example
} ;
HELP: out-vregs/stack
-{ $values { "#shuffle" #shuffle } { "seq" sequence } }
+{ $values { "#shuffle" #shuffle } { "pair" sequence } }
{ $description "Returns a sequence of what vregs are on which stack locations after the shuffle instruction." } ;
HELP: trivial-branch?
{ $see-also lookup-spill-slot pending-interval-assoc } ;
HELP: vregs>regs
-{ $values { "assoc" "an " { $link assoc } " (set) of virtual registers" } { "assoc" assoc } }
+{ $values { "assoc" "an " { $link assoc } " (set) of virtual registers" } { "assoc'" assoc } }
{ $description "Creates a mapping of virtual registers to registers." } ;
HELP: vreg>spill-slot
: remove-pending ( live-interval -- )
vreg>> pending-interval-assoc get delete-at ;
-: vreg>spill-slot ( vreg -- slot )
+: vreg>spill-slot ( vreg -- spill-slot )
dup rep-of lookup-spill-slot ;
: vreg>reg ( vreg -- reg/spill-slot )
{ $see-also inc-stack reset-incs } ;
HELP: height-state>insns
-{ $values { "state" sequence } { "insns" sequence } }
+{ $values { "height-state" height-state } { "insns" sequence } }
{ $description "Converts a " { $link height-state } " tuple to 0-2 stack height change instructions." }
{ $examples
"In this example the datastacks height is increased by 4 and the retainstacks decreased by 2."
{ $description "Increases or decreases the data or retain stack depending on if loc is a " { $link ds-loc } " or " { $link rs-loc } " instance. An " { $link ##inc } " instruction will later be inserted." } ;
HELP: local-loc>global
-{ $values { "loc" loc } { "bb" basic-block } { "loc'" loc } }
+{ $values { "loc" loc } { "height-state" height-state } { "loc'" loc } }
{ $description "Translates a stack location relative to a block to an absolute one. The word does the opposite to " { $link global-loc>local } "." } ;
HELP: loc>vreg
HELP: local-kill-set
{ $values
- { "ds-height" integer }
+ { "ds-begin" integer }
{ "ds-inc" integer }
- { "rs-height" integer }
+ { "rs-begin" integer }
{ "rs-inc" integer }
+ { "set" hash-set }
}
{ $description "The set of stack locations that was killed. Locations on a stack are deemed killed if that stacks height is decremented." }
{ $see-also compute-local-kill-set } ;
HELP: %alien-invoke
{ $values
+ { "varargs?" boolean }
{ "reg-inputs" sequence }
{ "stack-inputs" sequence }
{ "reg-outputs" sequence }
HELP: %test-imm-branch
{ $values
{ "label" "branch destination" }
+ { "cc" "comparison symbol" }
{ "src1" "register" }
{ "src2" "immediate" }
- { "cc" "comparison symbol" }
} { $description "Emits a TEST instruction with a register and an immediate, followed by a branch." } ;
HELP: %unbox
+{ $values
+ { "dst" "destination register" }
+ { "src" "source register" }
+ { "func" "function?" }
+ { "rep" representation }
+}
{ $description "Call a function to convert a tagged pointer into a value that can be passed to a C function, or returned from a callback." } ;
HELP: %vector>scalar
HOOK: immediate-arithmetic? cpu ( n -- ? )
HOOK: immediate-bitwise? cpu ( n -- ? )
HOOK: immediate-comparand? cpu ( n -- ? )
-HOOK: immediate-store? cpu ( obj -- ? )
+HOOK: immediate-store? cpu ( n -- ? )
M: object immediate-comparand? ( n -- ? )
{
} ;
HELP: ?pluralize
-{ $values { "count" number } { "singular" string } { "singluar/plural" string } }
+{ $values { "count" number } { "singular" string } { "singular/plural" string } }
{ $description "A simpler variant of " { $link count-of-things } " which omits its input value from the output. As with " { $link count-of-things } ", " { $snippet "word" } " is expected to be in singular form." }
{ $notes { $list $keep-case $0-plurality } }
{ $examples
} ;
HELP: or-markup-example
-{ $values { "markup" "a sequence of markup elements" } { "classes" "a sequence of words" } }
+{ $values { "classes" "a sequence of words" } { "markup" "a sequence of markup elements" } }
{ $description "Used to implement " { $link $or-markup-example } " and demonstrate " { $link comma-list } "." }
{ $examples { "See the examples in " { $link $or-markup-example } "." } } ;
GENERIC: article-title ( topic -- string )
GENERIC: article-name ( topic -- string )
GENERIC: article-content ( topic -- content )
-GENERIC: article-parent ( topic -- parent )
+GENERIC: article-parent ( topic -- parent/f )
GENERIC: set-article-parent ( parent topic -- )
M: object article-name article-title ;
"This variable should never be set directly; instead, use " { $link set-current-directory } " or " { $link with-directory } ". This preserves the invariant that the value of this variable is an absolute path." } ;
HELP: make-parent-directories
-{ $values { "path" "a pathname string" } }
+{ $values { "filename" "a pathname string" } }
{ $description "Creates all parent directories of the path which do not yet exist." }
{ $errors "Throws an error if the directories could not be created." } ;
{ $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 lazy-append } " 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" integer } { "quot" { $quotation ( n -- o ) } } { "lazy-from-by" "a lazy list of integers" } }
+{ $values { "n" integer } { "quot" { $quotation ( n -- o ) } } { "result" "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 the previous value." } ;
HELP: lfrom
-{ $values { "n" integer } { "list" "a lazy list of integers" } }
+{ $values { "n" integer } { "result" "a lazy list of integers" } }
{ $description "Return an infinite lazy list of incrementing integers starting from n." } ;
HELP: sequence-tail>list
{ $examples { $example "USING: math.vectors prettyprint ;" "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
HELP: vclamp
-{ $values { "v" "a sequence of real numbers" } { "min" "a sequence of real numbers" } { "max" "a sequence of real numbers" } }
+{ $values { "v" "a sequence of real numbers" } { "min" "a sequence of real numbers" } { "max" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
{ $description "Creates a sequence where each element is clamped to the minimum and maximum elements of the " { $snippet "min" } " and " { $snippet "max" } " sequences." }
{ $examples
{ $example
{ $values
{ "shaders" sequence }
{ "quot" quotation }
+ { "program" "a new " { $link gl-program } }
} { $description
"Creates a gl program and attaches the shaders to it. Then applies the quotation to the program and finally links it."
}
{ $description "Word that indicates that the dependency is a definition dependency. It is a dependency among two words in which one word depends on the definition of the another. For example, if two words are defined as " { $snippet ": o ( -- ) i ;" } " and " { $snippet ": i ( -- ) ; inline" } ", then 'o' has a definition dependency to 'i' because 'i' is inline. If the definition of 'i' changes 'o' must be recompiled." } ;
HELP: add-depends-on-class
-{ $values { "obj" classoid } }
+{ $values { "classoid" classoid } }
{ $description "Adds a " { $link +conditional+ } " dependency from the word to the classes mentioned in the classoid." } ;
HELP: conditional-dependencies
HELP: >suffix-array
{ $values
{ "seq" sequence }
- { "array" array } }
+ { "suffix-array" array } }
{ $description "Creates a suffix array from the input sequence. Suffix arrays are arrays of slices." } ;
HELP: SA{
{ $example
"USING: kernel math math.libm prettyprint typed ;
IN: scratchpad
-
+<<
TYPED:: quadratic-roots ( a: float b: float c: float -- q1: float q2: float )
b neg
b sq 4.0 a * c * - fsqrt
[ + ] [ - ] 2bi
[ 2.0 a * / ] bi@ ;
-
+>>
1 0 -9/4 quadratic-roots [ . ] bi@"
"1.5
-1.5" } } ;
HELP: key-sym
{ $values
- { "event" GdkEventKey }
- { "sym/f" { $maybe string } }
+ { "keyval" GdkEventKey }
+ { "string/f" { $maybe string } }
{ "action?" boolean }
} { $description "Gets the key symbol and action indicator from a " { $link GdkEventKey } " struct. If 'action?' is " { $link t } ", then the key is one of the special keys in " { $link codes } "." } ;
HELP: on-configure
{ $values
- { "win" alien }
+ { "window" alien }
{ "event" alien }
{ "user-data" alien }
{ "?" boolean }
ABOUT: "vocabs.metadata"
HELP: vocab-file-lines
-{ $values { "vocab" "a vocabulary specifier" } { "name" string } { "lines" { $maybe { $sequence "lines" } } } }
+{ $values { "vocab" "a vocabulary specifier" } { "name" string } { "lines/f" { $maybe { $sequence "lines" } } } }
{ $description "Outputs the lines of the file named " { $snippet "name" } " from the vocabulary's directory, or " { $link f } " if the file does not exist." } ;
HELP: set-vocab-file-lines
} ;
HELP: wrap-words
-{ $values { "words" { "a sequence of " { $instance wrapping-word } "s" } } { "line-max" integer } { "line-ideal" integer } { "lines" "a sequence of sequences of words" } }
+{ $values { "words" { "a sequence of " { $instance wrapping-word } "s" } } { "width" integer } { "lines" "a sequence of sequences of words" } }
{ $description "Divides the words into lines, where the sum of the lengths of the words on a line (not counting breaks at the end of the line) is at most the given maximum. The returned set of lines is optimized to minimize the square of the deviation of each line from the ideal width. It is not guaranteed to be the minimal number of lines. Every line except for the first one starts with a non-break, and every one but the last ends with a break." } ;
HELP: wrapping-word
! Copyright (C) 2009 Daniel Ehrenberg
! See http://factorcode.org/license.txt for BSD license.
-USING: help.syntax help.markup strings math kernel ;
+USING: arrays help.markup help.syntax kernel math strings ;
IN: wrap
ABOUT: "wrap"
} ;
HELP: wrap
-{ $values { "elements" { $sequence element } } { "width" real } }
+{ $values { "elements" { $sequence element } } { "width" real } { "array" array } }
{ $description "Break the " { $snippet "elements" } " into lines such that the total width of each line tries to be less than " { $snippet "width" } " while attempting to minimize the raggedness represented by the amount of space at the end of each line. Returns an array of lines." } ;
{ $class-description "Class of objects consisting of aliens, byte arrays and " { $link f } ". These objects all can be used as values of " { $link pointer } " C types." } ;
HELP: alien-invoke
-{ $values { "args..." "zero or more objects passed to the C function" } { "return" "a C return type" } { "library" "a logical library name" } { "function" "a C function name" } { "parameters" "a sequence of C parameter types" } { "return..." "the return value of the function, if not " { $link void } } }
+{ $values { "args..." "zero or more objects passed to the C function" } { "return" "a C return type" } { "library" "a logical library name" } { "function" "a C function name" } { "parameters" "a sequence of C parameter types" } { "varargs?" boolean } { "return..." "the return value of the function, if not " { $link void } } }
{ $description "Calls a C library function with the given name. Input parameters are taken from the data stack, and the return value is pushed on the data stack after the function returns. A return type of " { $link void } " indicates that no value is to be expected." }
{ $notes "C type names are documented in " { $link "c-types-specs" } "." }
{ $errors "Throws an " { $link callsite-not-compiled } " if the word calling " { $link alien-invoke } " was not compiled with the optimizing compiler." } ;
{ $error-description "Thrown if an attempt is made to subclass a class that is not a tuple class, or a tuple class declared " { $link POSTPONE: final } "." } ;
HELP: ?offset-of-slot
-{ $values { "name" string } { "tuple" tuple } { "n" { $maybe integer } } }
+{ $values { "name" string } { "tuple" tuple } { "n/f" { $maybe integer } } }
{ $description "Returns the offset of a tuple slot accessed by " { $snippet "name" } ", or " { $link f } " if no slot with that name." } ;
HELP: offset-of-slot
{ curry curried compose prepose composed } related-words
HELP: 2curry
-{ $values { "obj1" object } { "obj2" object } { "quot" callable } { "curry" curried } }
+{ $values { "obj1" object } { "obj2" object } { "quot" callable } { "curried" curried } }
{ $description "Outputs a " { $link callable } " which pushes " { $snippet "obj1" } " and " { $snippet "obj2" } " and then calls " { $snippet "quot" } "." }
{ $notes "This operation is efficient and does not copy the quotation." }
{ $examples
} ;
HELP: 3curry
-{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quot" callable } { "curry" curried } }
+{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quot" callable } { "curried" curried } }
{ $description "Outputs a " { $link callable } " which pushes " { $snippet "obj1" } ", " { $snippet "obj2" } " and " { $snippet "obj3" } ", and then calls " { $snippet "quot" } "." }
{ $notes "This operation is efficient and does not copy the quotation." } ;
HELP: with
-{ $values { "param" object } { "obj" object } { "quot" { $quotation ( param elt -- ... ) } } { "curry" curried } }
+{ $values { "param" object } { "obj" object } { "quot" { $quotation ( param elt -- ... ) } } { "curried" curried } }
{ $description "Partial application on the left. The following two lines are equivalent:"
{ $code "swap [ swap A ] curry B" }
{ $code "[ A ] with B" }
{ "param2" object }
{ "obj" object }
{ "quot" { $quotation ( param1 param2 elt -- ... ) } }
- { "curry" curried }
+ { "curried" curried }
}
{ $description "Partial application on the left of two parameters." } ;
} ;
HELP: prepose
-{ $values { "quot1" callable } { "quot2" callable } { "compose" composed } }
+{ $values { "quot1" callable } { "quot2" callable } { "composed" composed } }
{ $description "Quotation composition. Outputs a " { $link callable } " which calls " { $snippet "quot2" } " followed by " { $snippet "quot1" } "." }
{ $notes "See " { $link compose } " for details." } ;
HELP: when-zero
{ $values
- { "n" number } { "quot" "the first quotation of an " { $link if-zero } } }
+ { "n" number } { "quot" "the first quotation of an " { $link if-zero } } { "x" object } }
{ $description "Makes an implicit check if the number is zero. A zero is dropped and the " { $snippet "quot" } " is called." }
{ $examples "This word is equivalent to " { $link if-zero } " with an empty second quotation:"
{ $example
{ min max supremum infimum } related-words
HELP: shortest
-{ $values { "seq" sequence } { "elt" object } }
-{ $description "Outputs the shortest element of " { $snippet "seq" } "." } ;
+{ $values { "seqs" sequence } { "elt" object } }
+{ $description "Outputs the shortest sequence from " { $snippet "seqs" } "." } ;
HELP: longest
-{ $values { "seq" sequence } { "elt" object } }
-{ $description "Outputs the longest element of " { $snippet "seq" } "." } ;
+{ $values { "seqs" sequence } { "elt" object } }
+{ $description "Outputs the longest sequence from " { $snippet "seqs" } "." } ;
{ shortest longest } related-words
} ;
HELP: ctags
-{ $values { "alist" "ctags" } }
+{ $values { "ctags" "alist" } }
{ $description "Make a sequence of ctags from " { $link all-words } ", sorted by word name." } ;
ABOUT: "ctags"
{ $description "All the parent articles for the article and ensures that the ancestor always is 'handbook'." } ;
HELP: get-article
-{ $values { "name" string } { "str" string } }
+{ $values { "name" string } { "element" string } }
{ $description "If an article and a vocab share name, we render the vocab instead." } ;
HELP: find-word
{ "vertex-buffer" "a vertex buffer" }
{ "program-instance" program-instance }
{ "format" vertex-format }
+ { "vertex-array" vertex-array }
}
{ $description "Creates a new vertex array object." } ;
HELP: odbc-describe-column
{ $values
{ "statement" "an ODBC statement handle" }
- { "n" "a column number starting from one" }
+ { "columnNumber" "a column number starting from one" }
{ "column" "a column object" }
}
{ $description
HELP: odbc-get-field
{ $values
{ "statement" "an ODBC statement handle" }
- { "column" "a column number starting from one or a <column> object" }
+ { "column!" "a column number starting from one or a <column> object" }
{ "field" "a <field> object" }
}
{ $description
IN: succesor
HELP: successor
-{ $values { "str" string } }
+{ $values { "str" string } { "str'" string } }
{ $description
"Returns the successor to " { $snippet "str" } ". The successor is calculated by incrementing characters starting from the rightmost alphanumeric (or the rightmost character if there are no alphanumerics) in the string. Incrementing a digit always results in another digit, and incrementing a letter results in another letter of the same case. "
$nl
HELP: pop-tree-left
{ $values
{ "tree" tree }
- { "pair/f" { $maybe pair } }
+ { "node/f" { $maybe pair } }
}
{ $description "Removes and returns a key-value mapping associated with the lowest key in this map, or " { $link f } " if the map is empty." } ;
HELP: pop-tree-right
{ $values
{ "tree" tree }
- { "pair/f" { $maybe pair } }
+ { "node/f" { $maybe pair } }
}
{ $description "Removes and returns a key-value mapping associated with the highest key in this map, or " { $link f } " if the map is empty." } ;
HELP: y-at
{ $description "Given two points on a straight line and an " { $snippet "x" } " coordinate, calculate the " { $snippet "y" } " coordinate at " { $snippet "x" } " on that line." }
+{ $values
+ { "x" object }
+ { "point1" object }
+ { "point2" object }
+ { "y" object }
+}
{ $examples
{ $example
"USING: ui.gadgets.charts.lines.private prettyprint ;"
HELP: calc-x
{ $description "Given the " { $snippet "slope" } " of a line and a random " { $snippet "point" } " belonging to that line, calculate the " { $snippet "x" } " coordinate corresponding to the given " { $snippet "y" } "." }
+{ $values
+ { "slope" object }
+ { "y" object }
+ { "point" object }
+ { "x" object }
+}
{ $examples
{ $example
"USING: ui.gadgets.charts.lines.private prettyprint ;"
HELP: calc-y
{ $description "Given the " { $snippet "slope" } " of a line and a random " { $snippet "point" } " belonging to that line, calculate the " { $snippet "y" } " coordinate corresponding to the given " { $snippet "x" } "." }
+{ $values
+ { "slope" object }
+ { "x" object }
+ { "point" object }
+ { "y" object }
+}
{ $examples
{ $example
"USING: ui.gadgets.charts.lines.private prettyprint ;"
HELP: calc-line-slope
{ $description "Given the two points belonging to a straight line, calculate the " { $snippet "slope" } " of the line, assuming the line equation is " { $snippet "y(x) = slope * x + b" } "."
+{ $values
+ { "point1" object }
+ { "point2" object }
+ { "slope" object }
+}
$nl
"The formula for the calculation is " { $snippet "slope = (y1-y2) / (x1-x2)" } ", therefore it'll throw a division by zero error if both points have the same " { $snippet "x" } " coordinate." }
{ $examples
projects / factor.git / commitdiff