}
} ;
-HELP: dlopen ( path -- dll )
+HELP: dlopen
{ $values { "path" "a pathname string" } { "dll" "a DLL handle" } }
{ $description "Opens a native library and outputs a handle which may be passed to " { $link dlsym } " or " { $link dlclose } "." }
{ $errors "Throws an error if the library could not be found, or if loading fails for some other reason." }
{ $notes "This is the low-level facility used to implement " { $link load-library } ". Use the latter instead." } ;
-HELP: dlsym ( name dll -- alien )
+HELP: dlsym
{ $values { "name" "a C symbol name" } { "dll" "a DLL handle" } { "alien" { $maybe alien } } }
{ $description "Looks up a symbol in a native library. If " { $snippet "dll" } " is " { $link f } " looks for the symbol in the runtime executable. If the symbol was not found, outputs " { $link f } "." } ;
-HELP: dlclose ( dll -- )
+HELP: dlclose
{ $values { "dll" "a DLL handle" } }
{ $description "Closes a DLL handle created by " { $link dlopen } ". This word might not be implemented on all platforms." } ;
HELP: bit-array
{ $description "The class of fixed-length bit arrays." } ;
-HELP: <bit-array> ( n -- bit-array )
+HELP: <bit-array>
{ $values { "n" "a non-negative integer" } { "bit-array" "a new " { $link bit-array } } }
{ $description "Creates a new bit array with the given length and all elements initially set to " { $link f } "." } ;
sequences vocabs vocabs.parser words ;
IN: help.syntax
-<PRIVATE
-
-: check-effect ( word seq -- word seq' )
- dup ?first effect? [
- unclip pick stack-effect effect= [ bad-effect ] unless
- ] when ;
-
-PRIVATE>
-
SYNTAX: HELP:
scan-word bootstrap-word
[ >link save-location ]
- [ \ ; parse-until check-effect >array swap set-word-help ]
+ [ [ \ ; parse-until >array ] dip set-word-help ]
bi ;
SYNTAX: ARTICLE:
USING: help.syntax help.markup ;
IN: io.encodings.strict
-HELP: strict ( code -- strict )
+HELP: strict
{ $values { "code" "an encoding descriptor" } { "strict" "a strict encoding descriptor" } }
{ $description "Makes an encoding strict, that is, in the presence of a malformed code point, an error is thrown. Note that the existence of a replacement character in a file (U+FFFD) also throws an error." } ;
{ $class-description "A virtual sequence which presents a merged view of its underlying elements. New instances are created by calling one of " { $link <merged> } ", " { $link <2merged> } ", or " { $link <3merged> } "." }
{ $see-also merge } ;
-HELP: <merged> ( seqs -- merged )
+HELP: <merged>
{ $values { "seqs" "a sequence of sequences to merge" } { "merged" "a virtual sequence" } }
{ $description "Creates an instance of the " { $link merged } " virtual sequence. The length of the created virtual sequences is the minimum length of the input sequences times the number of input sequences." }
{ $see-also <2merged> <3merged> merge } ;
-HELP: <2merged> ( seq1 seq2 -- merged )
+HELP: <2merged>
{ $values { "seq1" sequence } { "seq2" sequence } { "merged" "a virtual sequence" } }
{ $description "Creates an instance of the " { $link merged } " virtual sequence which merges the two input sequences." }
{ $see-also <merged> <3merged> 2merge } ;
-HELP: <3merged> ( seq1 seq2 seq3 -- merged )
+HELP: <3merged>
{ $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "merged" "a virtual sequence" } }
{ $description "Creates an instance of the " { $link merged } " virtual sequence which merges the three input sequences." }
{ $see-also <merged> <2merged> 3merge } ;
-HELP: merge ( seqs -- seq )
+HELP: merge
{ $values { "seqs" "a sequence of sequences to merge" } { "seq" "a new sequence" } }
{ $description "Outputs a new sequence which merges the elements of each sequence in " { $snippet "seqs" } "." }
{ $examples
}
{ $see-also 2merge 3merge <merged> } ;
-HELP: 2merge ( seq1 seq2 -- seq )
+HELP: 2merge
{ $values { "seq1" sequence } { "seq2" sequence } { "seq" "a new sequence" } }
{ $description "Creates a new sequence of the same type as " { $snippet "seq1" } " which merges the elements of " { $snippet "seq1" } " and " { $snippet "seq2" } }
{ $see-also merge 3merge <2merged> } ;
-HELP: 3merge ( seq1 seq2 seq3 -- seq )
+HELP: 3merge
{ $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "seq" "a new sequence" } }
{ $description "Creates a new sequence of the same type as " { $snippet "seq1" } " which merges the elements of all three sequences" }
{ $see-also merge 2merge <3merged> } ;
HELP: method-profile.
{ $description "Print a table of cumilative call counts for each method. Methods which were not called are supressed from the output." } ;
-HELP: profiling ( ? -- )
+HELP: profiling
{ $values { "?" "a boolean" } }
{ $description "Internal primitive to switch on call counting. This word should not be used; instead use " { $link profile } "." } ;
HELP: dll
{ $class-description "The class of native library handles. See " { $link "syntax-aliens" } " for syntax and " { $link "dll.private" } " for general information." } ;
-HELP: dll-valid? ( dll -- ? )
+HELP: dll-valid?
{ $values { "dll" dll } { "?" "a boolean" } }
{ $description "Returns true if the library exists and is loaded." } ;
{ $values { "alien" c-ptr } }
{ $description "Constructs an invalid alien pointer that has expired." } ;
-HELP: <displaced-alien> ( displacement c-ptr -- alien )
+HELP: <displaced-alien>
{ $values { "displacement" "an integer" } { "c-ptr" c-ptr } { "alien" "a new alien" } }
{ $description "Creates a new alien address object, wrapping a raw memory address. The alien points to a location in memory which is offset by " { $snippet "displacement" } " from the address of " { $snippet "c-ptr" } "." }
{ $notes "Passing a value of " { $link f } " for " { $snippet "c-ptr" } " creates an alien with an absolute address; this is how " { $link <alien> } " is implemented."
{ <alien> <displaced-alien> alien-address } related-words
-HELP: alien-address ( c-ptr -- addr )
+HELP: alien-address
{ $values { "c-ptr" c-ptr } { "addr" "a non-negative integer" } }
{ $description "Outputs the address of an alien." }
{ $notes "Taking the address of a " { $link byte-array } " is explicitly prohibited since byte arrays can be moved by the garbage collector between the time the address is taken, and when it is accessed. If you need to pass pointers to C functions which will persist across alien calls, you must allocate unmanaged memory instead. See " { $link "malloc" } "." } ;
HELP: array
{ $description "The class of fixed-length arrays. See " { $link "syntax-arrays" } " for syntax and " { $link "arrays" } " for general information." } ;
-HELP: <array> ( n elt -- array )
+HELP: <array>
{ $values { "n" "a non-negative integer" } { "elt" "an initial element" } { "array" "a new array" } }
{ $description "Creates a new array with the given length and all elements initially set to " { $snippet "elt" } "." } ;
{ $values { "w" object } { "x" object } { "y" object } { "z" object } { "array" array } }
{ $description "Create a new array with four elements, with " { $snippet "w" } " appearing first." } ;
-HELP: resize-array ( n array -- new-array )
+HELP: resize-array
{ $values { "n" "a non-negative integer" } { "array" array } { "new-array" array } }
{ $description "Resizes the array to have a length of " { $snippet "n" } " elements. When making the array shorter, this word may either create a new array or modify the existing array in place. When making the array longer, this word always allocates a new array, filling remaining space with " { $link f } "." }
{ $side-effects "array" } ;
HELP: byte-array
{ $description "The class of byte arrays. See " { $link "syntax-byte-arrays" } " for syntax and " { $link "byte-arrays" } " for general information." } ;
-HELP: <byte-array> ( n -- byte-array )
+HELP: <byte-array>
{ $values { "n" "a non-negative integer" } { "byte-array" "a new byte array" } }
{ $description "Creates a new byte array holding " { $snippet "n" } " bytes." } ;
{ 1byte-array 2byte-array 3byte-array 4byte-array } related-words
-HELP: resize-byte-array ( n byte-array -- new-byte-array )
+HELP: resize-byte-array
{ $values { "n" "a non-negative integer" } { "byte-array" byte-array } { "new-byte-array" byte-array } }
{ $description "Resizes the byte array to have a length of " { $snippet "n" } " elements. When making the byte array shorter, this word may either create a new byte array or modify the existing byte array in place. When making the byte array longer, this word always allocates a new byte array, filling remaining space with zeroes." }
{ $side-effects "byte-array" } ;
}
} ;
-HELP: tuple>array ( tuple -- array )
+HELP: tuple>array
{ $values { "tuple" tuple } { "array" array } }
{ $description "Outputs an array having the tuple's slots as elements. The first element is the tuple class word and remainder are declared slots." } ;
-HELP: <tuple> ( layout -- tuple )
+HELP: <tuple>
{ $values { "layout" "a tuple layout array" } { "tuple" tuple } }
{ $description "Low-level tuple constructor. User code should never call this directly, and instead use " { $link new } "." } ;
-HELP: <tuple-boa> ( slots... layout -- tuple )
+HELP: <tuple-boa>
{ $values { "slots..." "values" } { "layout" "a tuple layout array" } { "tuple" tuple } }
{ $description "Low-level tuple constructor. User code should never call this directly, and instead use " { $link boa } "." } ;
{ $description "Sorts the entries of " { $snippet "assoc" } " into buckets, using the quotation to yield a set of keys for each entry. The hashcode of each key is computed, and the entry is placed in all corresponding buckets. Each bucket is initially cloned from " { $snippet "initial" } "; this should either be an empty vector or a one-element vector containing a pair." }
{ $notes "This word is used in the implementation of " { $link hash-case-quot } " and " { $link standard-combination } "." } ;
-HELP: dispatch ( n array -- )
+HELP: dispatch
{ $values { "n" "a fixnum" } { "array" "an array of quotations" } }
{ $description "Calls the " { $snippet "n" } "th quotation in the array." }
{ $warning "This word is in the " { $vocab-link "kernel.private" } " vocabulary because it is an implementation detail used by the generic word system to accelerate method dispatch. It does not perform type or bounds checks, and user code should not need to call it directly." } ;
{ $description "Throws a " { $link no-compilation-unit } " error." }
{ $error-description "Thrown when an attempt is made to define a word outside of a " { $link with-compilation-unit } " combinator." } ;
-HELP: modify-code-heap ( alist update-existing? reset-pics? -- )
+HELP: modify-code-heap
{ $values { "alist" "an association list with words as keys" } { "update-existing?" "a boolean" } { "reset-pics?" "a boolean" } }
{ $description "Lowest-level primitive for defining words. Associates words with code blocks in the code heap."
$nl
{ $description "Writes some bytes to a C FILE* handle." }
{ $errors "Throws an error if the output operation failed." } ;
-HELP: fflush ( alien -- )
+HELP: fflush
{ $values { "alien" "a C FILE* handle" } }
{ $description "Forces pending output on a C FILE* handle to complete." }
{ $errors "Throws an error if the output operation failed." } ;
-HELP: fclose ( alien -- )
+HELP: fclose
{ $values { "alien" "a C FILE* handle" } }
{ $description "Closes a C FILE* handle." } ;
-HELP: fgetc ( alien -- byte/f )
+HELP: fgetc
{ $values { "alien" "a C FILE* handle" } { "byte/f" "an integer from 0 to 255 or " { $link f } } }
{ $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." } ;
-HELP: fputc ( byte alien -- )
+HELP: fputc
{ $values { "byte" "an integer from 0 to 255" } { "alien" "a C FILE* handle" } }
{ $description "Writes a single byte to a C FILE* handle." }
{ $errors "Throws an error if the output operation failed." } ;
-HELP: fread-unsafe ( n buf alien -- str/f )
+HELP: fread-unsafe
{ $values { "n" "a positive integer" } { "buf" c-ptr } { "alien" "a C FILE* handle" } { "count" integer } }
{ $description "Reads " { $snippet "n" } " bytes from a C FILE* handle into the memory referenced by " { $snippet "buf" } ", and outputs the number of characters read. Zero is output on end of file." }
{ $warning "This word does not check whether " { $snippet "buf" } " is large enough to accommodate the requested number of bytes. Memory corruption will occur if this is not the case." }
assocs arrays math.order ;
IN: kernel
-HELP: eq? ( obj1 obj2 -- ? )
+HELP: eq?
{ $values { "obj1" object } { "obj2" object } { "?" "a boolean" } }
{ $description "Tests if two references point at the same object." } ;
-HELP: drop ( x -- ) $shuffle ;
-HELP: 2drop ( x y -- ) $shuffle ;
-HELP: 3drop ( x y z -- ) $shuffle ;
-HELP: dup ( x -- x x ) $shuffle ;
-HELP: 2dup ( x y -- x y x y ) $shuffle ;
-HELP: 3dup ( x y z -- x y z x y z ) $shuffle ;
-HELP: nip ( x y -- y ) $shuffle ;
-HELP: 2nip ( x y z -- z ) $shuffle ;
-HELP: over ( x y -- x y x ) $shuffle ;
-HELP: 2over $shuffle ;
-HELP: pick ( x y z -- x y z x ) $shuffle ;
-HELP: swap ( x y -- y x ) $shuffle ;
-
-HELP: rot ( x y z -- y z x ) $complex-shuffle ;
-HELP: -rot ( x y z -- z x y ) $complex-shuffle ;
-HELP: dupd ( x y -- x x y ) $complex-shuffle ;
-HELP: swapd ( x y z -- y x z ) $complex-shuffle ;
-
-HELP: datastack ( -- array )
+HELP: drop $shuffle ;
+HELP: 2drop $shuffle ;
+HELP: 3drop $shuffle ;
+HELP: dup $shuffle ;
+HELP: 2dup $shuffle ;
+HELP: 3dup $shuffle ;
+HELP: nip $shuffle ;
+HELP: 2nip $shuffle ;
+HELP: over $shuffle ;
+HELP: 2over $shuffle ;
+HELP: pick $shuffle ;
+HELP: swap $shuffle ;
+
+HELP: rot $complex-shuffle ;
+HELP: -rot $complex-shuffle ;
+HELP: dupd $complex-shuffle ;
+HELP: swapd $complex-shuffle ;
+
+HELP: datastack
{ $values { "array" array } }
{ $description "Outputs an array containing a copy of the data stack contents right before the call to this word, with the top of the stack at the end of the array." } ;
-HELP: set-datastack ( array -- )
+HELP: set-datastack
{ $values { "array" array } }
{ $description "Replaces the data stack contents with a copy of an array. The end of the array becomes the top of the stack." } ;
-HELP: retainstack ( -- array )
+HELP: retainstack
{ $values { "array" array } }
{ $description "Outputs an array containing a copy of the retain stack contents right before the call to this word, with the top of the stack at the end of the array." } ;
-HELP: set-retainstack ( array -- )
+HELP: set-retainstack
{ $values { "array" array } }
{ $description "Replaces the retain stack contents with a copy of an array. The end of the array becomes the top of the stack." } ;
-HELP: callstack ( -- callstack )
+HELP: callstack
{ $values { "callstack" callstack } }
{ $description "Outputs a copy of the call stack contents, with the top of the stack at the end of the vector. The stack frame of the caller word is " { $emphasis "not" } " included." } ;
-HELP: set-callstack ( callstack -- * )
+HELP: set-callstack
{ $values { "callstack" callstack } }
{ $description "Replaces the call stack contents. Control flow is transferred immediately to the innermost frame of the new call stack." } ;
{ $url "http://www.jargon.net/jargonfile/f/feppedout.html" }
} ;
-HELP: (clone) ( obj -- newobj )
+HELP: (clone)
{ $values { "obj" object } { "newobj" "a shallow copy" } }
{ $description "Outputs a byte-by-byte copy of the given object. User code should call " { $link clone } " instead." } ;
{ $code "{ float } declare 2 + 10 *" }
} ;
-HELP: tag ( object -- n )
+HELP: tag
{ $values { "object" object } { "n" "a tag number" } }
{ $description "Outputs an object's tag number, between zero and one less than " { $link num-types } ". This is implementation detail and user code should call " { $link class } " instead." } ;
-HELP: special-object ( n -- obj )
+HELP: special-object
{ $values { "n" "a non-negative integer" } { "obj" object } }
{ $description "Reads an object from the Factor VM's special object table. User code never has to read the special object table directly; instead, use one of the callers of this word." } ;
-HELP: set-special-object ( obj n -- )
+HELP: set-special-object
{ $values { "obj" object } { "n" "a non-negative integer" } }
{ $description "Writes an object to the Factor VM's special object table. User code never has to write to the special object table directly; instead, use one of the callers of this word." } ;
{ $values { "x" real } { "y" float } }
{ $description "Converts a real to a float. This is the identity on floats, and performs a floating point division on rationals." } ;
-HELP: bits>double ( n -- x )
+HELP: bits>double
{ $values { "n" "a 64-bit integer representing an IEEE 754 double-precision float" } { "x" float } }
{ $description "Creates a " { $link float } " object from a 64-bit binary representation. This word is usually used to reconstruct floats read from streams." } ;
{ bits>double bits>float double>bits float>bits } related-words
-HELP: bits>float ( n -- x )
+HELP: bits>float
{ $values { "n" "a 32-bit integer representing an IEEE 754 single-precision float" } { "x" float } }
{ $description "Creates a " { $link float } " object from a 32-bit binary representation. This word is usually used to reconstruct floats read from streams." } ;
-HELP: double>bits ( x -- n )
+HELP: double>bits
{ $values { "x" float } { "n" "a 64-bit integer representing an IEEE 754 double-precision float" } }
{ $description "Creates a 64-bit binary representation of a " { $link float } " object. This can be used in the process of writing a float to a stream." } ;
-HELP: float>bits ( x -- n )
+HELP: float>bits
{ $values { "x" float } { "n" "a 32-bit integer representing an IEEE 754 single-precision float" } }
{ $description "Creates a 32-bit binary representation of a " { $link float } " object. This can be used in the process of writing a float to a stream." } ;
! Unsafe primitives
-HELP: float+ ( x y -- z )
+HELP: float+
{ $values { "x" float } { "y" float } { "z" float } }
{ $description "Primitive version of " { $link + } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
-HELP: float- ( x y -- z )
+HELP: float-
{ $values { "x" float } { "y" float } { "z" float } }
{ $description "Primitive version of " { $link - } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
-HELP: float* ( x y -- z )
+HELP: float*
{ $values { "x" float } { "y" float } { "z" float } }
{ $description "Primitive version of " { $link * } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
-HELP: float/f ( x y -- z )
+HELP: float/f
{ $values { "x" float } { "y" float } { "z" float } }
{ $description "Primitive version of " { $link /f } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /f } " instead." } ;
-HELP: float< ( x y -- ? )
+HELP: float<
{ $values { "x" float } { "y" float } { "?" "a boolean" } }
{ $description "Primitive version of " { $link < } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
-HELP: float<= ( x y -- ? )
+HELP: float<=
{ $values { "x" float } { "y" float } { "?" "a boolean" } }
{ $description "Primitive version of " { $link <= } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
-HELP: float> ( x y -- ? )
+HELP: float>
{ $values { "x" float } { "y" float } { "?" "a boolean" } }
{ $description "Primitive version of " { $link > } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
-HELP: float>= ( x y -- ? )
+HELP: float>=
{ $values { "x" float } { "y" float } { "?" "a boolean" } }
{ $description "Primitive version of " { $link u>= } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u>= } " instead." } ;
-HELP: float-u< ( x y -- ? )
+HELP: float-u<
{ $values { "x" float } { "y" float } { "?" "a boolean" } }
{ $description "Primitive version of " { $link u< } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u< } " instead." } ;
-HELP: float-u<= ( x y -- ? )
+HELP: float-u<=
{ $values { "x" float } { "y" float } { "?" "a boolean" } }
{ $description "Primitive version of " { $link u<= } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u<= } " instead." } ;
-HELP: float-u> ( x y -- ? )
+HELP: float-u>
{ $values { "x" float } { "y" float } { "?" "a boolean" } }
{ $description "Primitive version of " { $link u> } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u> } " instead." } ;
-HELP: float-u>= ( x y -- ? )
+HELP: float-u>=
{ $values { "x" float } { "y" float } { "?" "a boolean" } }
{ $description "Primitive version of " { $link u>= } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link u>= } " instead." } ;
{ $description "Tests if an integer is odd." } ;
! Unsafe primitives
-HELP: fixnum+ ( x y -- z )
+HELP: fixnum+
{ $values { "x" fixnum } { "y" fixnum } { "z" integer } }
{ $description "Primitive version of " { $link + } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
-HELP: fixnum- ( x y -- z )
+HELP: fixnum-
{ $values { "x" fixnum } { "y" fixnum } { "z" integer } }
{ $description "Primitive version of " { $link - } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
-HELP: fixnum* ( x y -- z )
+HELP: fixnum*
{ $values { "x" fixnum } { "y" fixnum } { "z" integer } }
{ $description "Primitive version of " { $link * } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
-HELP: fixnum/i ( x y -- z )
+HELP: fixnum/i
{ $values { "x" fixnum } { "y" fixnum } { "z" integer } }
{ $description "Primitive version of " { $link /i } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /i } " instead." } ;
-HELP: fixnum-mod ( x y -- z )
+HELP: fixnum-mod
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link mod } ". The result always fits in a fixnum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ;
-HELP: fixnum/mod ( x y -- z w )
+HELP: fixnum/mod
{ $values { "x" fixnum } { "y" fixnum } { "z" integer } { "w" fixnum } }
{ $description "Primitive version of " { $link /mod } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /mod } " instead." } ;
-HELP: fixnum< ( x y -- ? )
+HELP: fixnum<
{ $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
{ $description "Primitive version of " { $link < } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
-HELP: fixnum<= ( x y -- z )
+HELP: fixnum<=
{ $values { "x" fixnum } { "y" fixnum } { "z" integer } }
{ $description "Primitive version of " { $link <= } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
-HELP: fixnum> ( x y -- ? )
+HELP: fixnum>
{ $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
{ $description "Primitive version of " { $link > } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
-HELP: fixnum>= ( x y -- ? )
+HELP: fixnum>=
{ $values { "x" fixnum } { "y" fixnum } { "?" "a boolean" } }
{ $description "Primitive version of " { $link >= } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ;
-HELP: fixnum-bitand ( x y -- z )
+HELP: fixnum-bitand
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link bitand } ". The result always fits in a fixnum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitand } " instead." } ;
-HELP: fixnum-bitor ( x y -- z )
+HELP: fixnum-bitor
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link bitor } ". The result always fits in a fixnum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitor } " instead." } ;
-HELP: fixnum-bitxor ( x y -- z )
+HELP: fixnum-bitxor
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link bitxor } ". The result always fits in a fixnum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitxor } " instead." } ;
-HELP: fixnum-bitnot ( x -- y )
+HELP: fixnum-bitnot
{ $values { "x" fixnum } { "y" fixnum } }
{ $description "Primitive version of " { $link bitnot } ". The result always fits in a fixnum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitnot } " instead." } ;
-HELP: fixnum-shift ( x y -- z )
+HELP: fixnum-shift
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link shift } ". The result may overflow to a bignum." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ;
-HELP: fixnum-shift-fast ( x y -- z )
+HELP: fixnum-shift-fast
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link shift } ". Unlike " { $link fixnum-shift } ", does not perform an overflow check, so the result may be incorrect." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ;
-HELP: fixnum+fast ( x y -- z )
+HELP: fixnum+fast
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link + } ". Unlike " { $link fixnum+ } ", does not perform an overflow check, so the result may be incorrect." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
-HELP: fixnum-fast ( x y -- z )
+HELP: fixnum-fast
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link - } ". Unlike " { $link fixnum- } ", does not perform an overflow check, so the result may be incorrect." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
-HELP: fixnum*fast ( x y -- z )
+HELP: fixnum*fast
{ $values { "x" fixnum } { "y" fixnum } { "z" fixnum } }
{ $description "Primitive version of " { $link * } ". Unlike " { $link fixnum* } ", does not perform an overflow check, so the result may be incorrect." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
-HELP: bignum+ ( x y -- z )
+HELP: bignum+
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link + } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link + } " instead." } ;
-HELP: bignum- ( x y -- z )
+HELP: bignum-
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link - } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link - } " instead." } ;
-HELP: bignum* ( x y -- z )
+HELP: bignum*
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link * } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link * } " instead." } ;
-HELP: bignum/i ( x y -- z )
+HELP: bignum/i
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link /i } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /i } " instead." } ;
-HELP: bignum-mod ( x y -- z )
+HELP: bignum-mod
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link mod } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link mod } " instead." } ;
-HELP: bignum/mod ( x y -- z w )
+HELP: bignum/mod
{ $values { "x" bignum } { "y" bignum } { "z" bignum } { "w" bignum } }
{ $description "Primitive version of " { $link /mod } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link /mod } " instead." } ;
-HELP: bignum< ( x y -- ? )
+HELP: bignum<
{ $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
{ $description "Primitive version of " { $link < } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link < } " instead." } ;
-HELP: bignum<= ( x y -- ? )
+HELP: bignum<=
{ $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
{ $description "Primitive version of " { $link <= } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link <= } " instead." } ;
-HELP: bignum> ( x y -- ? )
+HELP: bignum>
{ $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
{ $description "Primitive version of " { $link > } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link > } " instead." } ;
-HELP: bignum>= ( x y -- ? )
+HELP: bignum>=
{ $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
{ $description "Primitive version of " { $link >= } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link >= } " instead." } ;
-HELP: bignum= ( x y -- ? )
+HELP: bignum=
{ $values { "x" bignum } { "y" bignum } { "?" "a boolean" } }
{ $description "Primitive version of " { $link number= } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link number= } " instead." } ;
-HELP: bignum-bitand ( x y -- z )
+HELP: bignum-bitand
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link bitand } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitand } " instead." } ;
-HELP: bignum-bitor ( x y -- z )
+HELP: bignum-bitor
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link bitor } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitor } " instead." } ;
-HELP: bignum-bitxor ( x y -- z )
+HELP: bignum-bitxor
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link bitxor } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitxor } " instead." } ;
-HELP: bignum-bitnot ( x -- y )
+HELP: bignum-bitnot
{ $values { "x" bignum } { "y" bignum } }
{ $description "Primitive version of " { $link bitnot } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link bitnot } " instead." } ;
-HELP: bignum-shift ( x y -- z )
+HELP: bignum-shift
{ $values { "x" bignum } { "y" bignum } { "z" bignum } }
{ $description "Primitive version of " { $link shift } "." }
{ $warning "This word does not perform type checking, and passing objects of the wrong type can crash the runtime. User code should call the generic word " { $link shift } " instead." } ;
{ $values { "quot" { $quotation "( obj -- ? )" } } { "seq" "a fresh sequence" } }
{ $description "Outputs a sequence of all objects in the heap which satisfy the quotation." } ;
-HELP: gc ( -- )
+HELP: gc
{ $description "Performs a full garbage collection." } ;
-HELP: size ( obj -- n )
+HELP: size
{ $values { "obj" "an object" } { "n" "a size in bytes" } }
{ $description "Outputs the size of the object in memory, in bytes. Tagged immediate objects such as fixnums and " { $link f } " will yield a size of 0." } ;
-HELP: save-image ( path -- )
+HELP: save-image
{ $values { "path" "a pathname string" } }
{ $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists." } ;
-HELP: save-image-and-exit ( path -- )
+HELP: save-image-and-exit
{ $values { "path" "a pathname string" } }
{ $description "Saves a snapshot of the heap to the given file, overwriting the file if it already exists. This word compacts the code heap and immediately exits Factor, since the Factor VM cannot continue executing after compiled code blocks have been moved around." } ;
HELP: wrapper
{ $description "The class of wrappers. Wrappers are created by calling " { $link literalize } ". See " { $link "syntax-words" } " for syntax." } ;
-HELP: <wrapper> ( obj -- wrapper )
+HELP: <wrapper>
{ $values { "obj" object } { "wrapper" wrapper } }
{ $description "Creates an object which pushes " { $snippet "obj" } " on the stack when evaluated. User code should call " { $link literalize } " instead, since it avoids wrapping self-evaluating objects (which is redundant)." } ;
{ $description "Defines slot methods." }
$low-level-note ;
-HELP: slot ( obj m -- value )
+HELP: slot
{ $values { "obj" object } { "m" "a non-negative fixnum" } { "value" object } }
{ $description "Reads the object stored at the " { $snippet "n" } "th slot of " { $snippet "obj" } "." }
{ $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: set-slot ( value obj n -- )
+HELP: set-slot
{ $values { "value" object } { "obj" object } { "n" "a non-negative fixnum" } }
{ $description "Writes " { $snippet "value" } " to the " { $snippet "n" } "th slot of " { $snippet "obj" } "." }
{ $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." } ;
{ $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: resize-string ( n str -- newstr )
+HELP: resize-string
{ $values { "n" "a non-negative integer" } { "str" string } { "newstr" string } }
{ $description "Resizes the string to have a length of " { $snippet "n" } " elements. When making the string shorter, this word may either create a new string or modify the existing string in place. When making the string longer, this word always allocates a new string, filling remaining space with zeroes." }
{ $side-effects "str" } ;
{ $values { "?" "a boolean" } }
{ $description "Tests if this Factor instance is embedded in another application." } ;
-HELP: exit ( n -- * )
+HELP: exit
{ $values { "n" "an integer exit code" } }
{ $description "Exits the Factor process." } ;
-HELP: nano-count ( -- ns )
+HELP: nano-count
{ $values { "ns" integer } }
{ $description "Outputs a monotonically increasing count of nanoseconds elapsed since an arbitrary starting time. The difference of two calls to this word allows timing. This word is unaffected by system clock changes." }
{ $notes "This is a low-level word. The " { $vocab-link "tools.time" } " vocabulary defines words to time code execution time." } ;
{ $description "Removes a word property, so future lookups will output " { $link f } " until it is set again. Word property names are conventionally strings." }
{ $side-effects "word" } ;
-HELP: word-code ( word -- start end )
+HELP: word-code
{ $values { "word" word } { "start" "the word's start address" } { "end" "the word's end address" } }
{ $description "Outputs the memory range containing the word's machine code." } ;
$low-level-note
{ $side-effects "word" } ;
-HELP: <word> ( name vocab -- word )
+HELP: <word>
{ $values { "name" string } { "vocab" string } { "word" word } }
{ $description "Allocates a word with the specified name and vocabulary. User code should call " { $link <uninterned-word> } " to create uninterned words and " { $link create } " to create interned words, instead of calling this constructor directly." }
{ $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
-HELP: <uninterned-word> ( name -- word )
+HELP: <uninterned-word>
{ $values { "name" string } { "word" word } }
{ $description "Creates an uninterned word with the specified name, that is not equal to any other word in the system." }
{ $notes "Unlike " { $link create } ", this word does not have to be called from inside " { $link with-compilation-unit } "." } ;
USING: help.markup help.syntax math kernel ;
IN: 24-game
-HELP: play-game ( -- )
+HELP: play-game
{ $description "Starts the game!" }
{ $examples
{ $unchecked-example
}
} ;
-HELP: 24-able ( -- vector )
+HELP: 24-able
{ $values { "vector" "vector of 4 integers" } }
{ $description
"Produces a vector with 4 integers. With the following condition: "
{ $notes { $link 24-able? } " is used in " { $link 24-able } "." }
} ;
-HELP: 24-able? ( quad -- t/f )
+HELP: 24-able?
{ $values
{ "quad" "vector of 4 integers" }
{ "t/f" "a boolean" }
"with this sequence."
} ;
-HELP: build-quad ( -- array )
+HELP: build-quad
{ $values
{ "array" "an array of 4 numbers" }
}
ctag-lineno
} ;
-HELP: ctags ( path -- )
+HELP: ctags
{ $values { "path" "a pathname string" } }
{ $description "Generates a index file in ctags format and stores in " { $snippet "path" } "." }
{ $examples
}
} ;
-HELP: ctags-write ( seq path -- )
+HELP: ctags-write
{ $values { "seq" sequence }
{ "path" "a pathname string" } }
{ $description "Stores a " { $snippet "alist" } " in " { $snippet "path" } ". " { $snippet "alist" } " must be an association list with ctags format: key must be a valid word and value a sequence whose first element is a resource name and second element is a line number" }
}
} ;
-HELP: ctag ( seq -- str )
+HELP: ctag
{ $values { "seq" sequence }
{ "str" string } }
{ $description "Outputs a string " { $snippet "str" } " in ctag format for sequence with two elements, first one must be a valid word and second one a sequence whose first element is a resource name and second element is a line number" }
}
} ;
-HELP: ctag-lineno ( ctag -- n )
+HELP: ctag-lineno
{ $values { "ctag" sequence }
{ "n" integer } }
{ $description "Provides de line number " { $snippet "n" } " from a sequence in ctag format " }
}
} ;
-HELP: ctag-path ( ctag -- path )
+HELP: ctag-path
{ $values { "ctag" sequence }
{ "path" string } }
{ $description "Provides a path string " { $snippet "path" } " from a sequence in ctag format" }
}
} ;
-HELP: ctag-word ( ctag -- word )
+HELP: ctag-word
{ $values { "ctag" sequence }
{ "word" word } }
{ $description "Provides the " { $snippet "word" } " from a sequence in ctag format " }
etag-header
}
-HELP: etags ( path -- )
+HELP: etags
{ $values { "path" string } }
{ $description "Generates a index file in etags format and stores in " { $snippet "path" } "." }
{ $examples
}
} ;
-HELP: etags-write ( alist path -- )
+HELP: etags-write
{ $values { "alist" sequence }
{ "path" string } }
{ $description "Stores a " { $snippet "alist" } " in " { $snippet "path" } ". " { $snippet "alist" } " must be an association list with etags format: its key must be a resource path and its value a vector, containing pairs of words and lines" }
}
} ;
-HELP: etag-strings ( alist -- seq )
+HELP: etag-strings
{ $values { "alist" sequence }
{ "seq" sequence } }
{ $description "Converts an " { $snippet "alist" } " with etag format (a path as key and a vector containing word/line pairs) in a " { $snippet "seq" } " of strings." } ;
-ABOUT: "etags" ;
\ No newline at end of file
+ABOUT: "etags" ;
HELP: unit-ratio
{ $description "Scaling ratio for the coordinates of the tags being read." } ;
-HELP: string>numbers ( string -- number-seq )
+HELP: string>numbers
{ $values { "string" string } { "number-seq" sequence } }
{ $description "Splits a string on whitespace and converts the elements to a number sequence." } ;
\r
\r
HELP: space-transform \r
-" ( space m -- space )" \r
{ $values { "space" "a space" } { "m" "a matrix" } }\r
{ $description "Transform a space using a matrix" } ;\r
\r
{ $values { "space" "a space" } { "v" "a vector" } }\r
{ $description "Translate a space following a vector" } ;\r
\r
-HELP: describe-space " ( space -- )"\r
+HELP: describe-space\r
{ $values { "space" "a space" } }\r
{ $description "return a description of space" } ;\r
\r
USING: help.markup help.syntax ;
IN: animations
-HELP: animate ( quot duration -- )
+HELP: animate
{ $values
{ "quot" "a quot which uses " { $link progress } }
{ $notes "The amount of time elapsed between these iterations will very." }
} ;
-HELP: reset-progress ( -- )
+HELP: reset-progress
{ $description
"Initiates the timer. Call this before using "
"a loop which makes use of " { $link progress } "."
"used when one's quote runs for a specific number of iterations, instead "
"of a length of time. If the animation is like most, and is expected to "
"run for a specific length of time, " { $link animate } " should be used." ;
-ABOUT: "animations"
\ No newline at end of file
+ABOUT: "animations"
USING: help.markup help.syntax math math.functions ;
IN: math.derivatives
-HELP: derivative ( x function -- m )
+HELP: derivative
{ $values { "x" "a position on the function" } { "function" "a differentiable function" } { "m" number } }
{ $description
"Approximates the slope of the tangent line by using Ridders' "
projects / factor.git / commitdiff