\r
ARTICLE: "alarms" "Alarms"\r
"The " { $vocab-link "alarms" } " vocabulary provides a lightweight way to schedule one-time and recurring tasks without spawning a new thread."\r
-{ $subsection alarm }\r
-{ $subsection add-alarm }\r
-{ $subsection later }\r
-{ $subsection cancel-alarm }\r
+{ $subsections\r
+ alarm\r
+ add-alarm\r
+ later\r
+ cancel-alarm\r
+}\r
"Alarms do not persist across image saves. Saving and restoring an image has the effect of calling " { $link cancel-alarm } " on all " { $link alarm } " instances." ;\r
\r
ABOUT: "alarms"\r
"A frequently-occurring idiom in C code is the \"out parameter\". If a C function returns more than one value, the caller passes pointers of the correct type, and the C function writes its return values to those locations."
$nl
"Each numerical C type, together with " { $snippet "void*" } ", has an associated " { $emphasis "out parameter constructor" } " word which takes a Factor object as input, constructs a byte array of the correct size, and converts the Factor object to a C value stored into the byte array:"
-{ $subsection <char> }
-{ $subsection <uchar> }
-{ $subsection <short> }
-{ $subsection <ushort> }
-{ $subsection <int> }
-{ $subsection <uint> }
-{ $subsection <long> }
-{ $subsection <ulong> }
-{ $subsection <longlong> }
-{ $subsection <ulonglong> }
-{ $subsection <float> }
-{ $subsection <double> }
-{ $subsection <void*> }
+{ $subsections
+ <char>
+ <uchar>
+ <short>
+ <ushort>
+ <int>
+ <uint>
+ <long>
+ <ulong>
+ <longlong>
+ <ulonglong>
+ <float>
+ <double>
+ <void*>
+}
"You call the out parameter constructor with the required initial value, then pass the byte array to the C function, which receives a pointer to the start of the byte array's data area. The C function then returns, leaving the result in the byte array; you read it back using the next set of words:"
-{ $subsection *char }
-{ $subsection *uchar }
-{ $subsection *short }
-{ $subsection *ushort }
-{ $subsection *int }
-{ $subsection *uint }
-{ $subsection *long }
-{ $subsection *ulong }
-{ $subsection *longlong }
-{ $subsection *ulonglong }
-{ $subsection *float }
-{ $subsection *double }
-{ $subsection *void* }
+{ $subsections
+ *char
+ *uchar
+ *short
+ *ushort
+ *int
+ *uint
+ *long
+ *ulong
+ *longlong
+ *ulonglong
+ *float
+ *double
+ *void*
+}
"Note that while structure and union types do not get these words defined for them, there is no loss of generality since " { $link <void*> } " and " { $link *void* } " may be used." ;
ARTICLE: "c-types.primitives" "Primitive C types"
"Struct and union types are identified by their class word. See " { $link "classes.struct" } "." ;
ARTICLE: "c-types-specs" "C type specifiers"
-"C types are identified by special words, and type names occur as parameters to the " { $link alien-invoke } ", " { $link alien-indirect } " and " { $link alien-callback } " words. New C types can be defined by the words " { $link POSTPONE: STRUCT: } ", " { $link POSTPONE: UNION-STRUCT: } ", " { $link POSTPONE: CALLBACK: } ", and " { $link POSTPONE: TYPEDEF: } "."
-{ $subsection "c-types.primitives" }
-{ $subsection "c-types.pointers" }
-{ $subsection "c-types.ambiguity" }
-{ $subsection "c-types.structs" }
+"C types are identified by special words, and type names occur as parameters to the " { $link alien-invoke } ", " { $link alien-indirect } " and " { $link alien-callback } " words."
+$nl
+"Defining new C types:"
+{ $subsections
+ POSTPONE: STRUCT:
+ POSTPONE: UNION-STRUCT:
+ POSTPONE: CALLBACK:
+ POSTPONE: TYPEDEF:
+}
+{ $heading "Related articles" }
+{ $subsections
+ "c-types.primitives"
+ "c-types.pointers"
+ "c-types.ambiguity"
+ "c-types.structs"
+}
;
ABOUT: "c-types-specs"
"Sometimes data passed to C functions must be allocated at a fixed address. See " { $link "byte-arrays-gc" } " for an explanation of when this is the case."
$nl
"Allocating a C datum with a fixed address:"
-{ $subsection malloc-object }
-{ $subsection malloc-byte-array }
-{ $subsection malloc-file-contents }
-"There is a set of words in the " { $vocab-link "libc" } " vocabulary which directly call C standard library memory management functions:"
-{ $subsection malloc }
-{ $subsection calloc }
-{ $subsection realloc }
+{ $subsections
+ malloc-object
+ malloc-byte-array
+ malloc-file-contents
+}
+"The " { $vocab-link "libc" } " vocabulary defines several words which directly call C standard library memory management functions:"
+{ $subsections
+ malloc
+ calloc
+ realloc
+}
"You must always free pointers returned by any of the above words when the block of memory is no longer in use:"
-{ $subsection free }
+{ $subsections free }
"Utilities for automatically freeing memory in conjunction with " { $link with-destructors } ":"
-{ $subsection &free }
-{ $subsection |free }
+{ $subsections
+ &free
+ |free
+}
"The " { $link &free } " and " { $link |free } " words are generated using " { $link "alien.destructors" } "."
$nl
"You can unsafely copy a range of bytes from one memory location to another:"
-{ $subsection memcpy }
+{ $subsections memcpy }
"You can copy a range of bytes from memory into a byte array:"
-{ $subsection memory>byte-array }
+{ $subsections memory>byte-array }
"You can copy a byte array to memory unsafely:"
-{ $subsection byte-array>memory } ;
+{ $subsections byte-array>memory } ;
ARTICLE: "c-pointers" "Passing pointers to C functions"
"The following Factor objects may be passed to C function parameters with pointer types:"
{ "Any data type which defines a method on " { $link >c-ptr } " that returns an instance of one of the above. This includes " { $link "classes.struct" } " and " { $link "specialized-arrays" } "." }
}
"The class of primitive C pointer types:"
-{ $subsection c-ptr }
+{ $subsections c-ptr }
"A generic word for converting any object to a C pointer; user-defined types may add methods to this generic word:"
-{ $subsection >c-ptr }
+{ $subsections >c-ptr }
"More about the " { $link alien } " type:"
-{ $subsection "aliens" }
+{ $subsections "aliens" }
{ $warning
"The Factor garbage collector can move byte arrays around, and code passing byte arrays, or objects backed by byte arrays, must obey important guidelines. See " { $link "byte-arrays-gc" } "." } ;
"Two defining characteristics of Factor are dynamic typing and automatic memory management, which are somewhat incompatible with the machine-level data model exposed by C. Factor's C library interface defines its own set of C data types, distinct from Factor language types, together with automatic conversion between Factor values and C types. For example, C integer types must be declared and are fixed-width, whereas Factor supports arbitrary-precision integers."
$nl
"Furthermore, Factor's garbage collector can move objects in memory; for a discussion of the consequences, see " { $link "byte-arrays-gc" } "."
-{ $subsection "c-types-specs" }
-{ $subsection "c-pointers" }
-{ $subsection "malloc" }
-{ $subsection "c-strings" }
-{ $subsection "c-out-params" }
+{ $subsections
+ "c-types-specs"
+ "c-pointers"
+ "malloc"
+ "c-strings"
+ "c-out-params"
+}
"Important guidelines for passing data in byte arrays:"
-{ $subsection "byte-arrays-gc" }
+{ $subsections "byte-arrays-gc" }
"C-style enumerated types are supported:"
-{ $subsection POSTPONE: C-ENUM: }
+{ $subsections POSTPONE: C-ENUM: }
"C types can be aliased for convenience and consitency with native library documentation:"
-{ $subsection POSTPONE: TYPEDEF: }
+{ $subsections POSTPONE: TYPEDEF: }
"A utility for defining " { $link "destructors" } " for deallocating memory:"
-{ $subsection "alien.destructors" }
+{ $subsections "alien.destructors" }
"C struct and union types can be defined with " { $link POSTPONE: STRUCT: } " and " { $link POSTPONE: UNION: } ". See " { $link "classes.struct" } " for details. For passing arrays to and from C, use the " { $link "specialized-arrays" } " vocabulary." ;
HELP: malloc-string
"Care must be taken if the C function expects a " { $link char* } " with a length in bytes, rather than a null-terminated " { $link char* } "; passing the result of calling " { $link length } " on the string object will not suffice. This is because a Factor string of " { $emphasis "n" } " characters will not necessarily encode to " { $emphasis "n" } " bytes. The correct idiom for C functions which take a string with a length is to first encode the string using " { $link encode } ", and then pass the resulting byte array together with the length of this byte array."
$nl
"Sometimes a C function has a parameter type of " { $link void* } ", and various data types, among them strings, can be passed in. In this case, strings are not automatically converted to aliens, and instead you must call one of these words:"
-{ $subsection string>alien }
-{ $subsection malloc-string }
+{ $subsections
+ string>alien
+ malloc-string
+}
"The first allocates " { $link byte-array } "s, and the latter allocates manually-managed memory which is not moved by the garbage collector and has to be explicitly freed by calling " { $link free } ". See " { $link "byte-arrays-gc" } " for a discussion of the two approaches."
$nl
"A word to read strings from arbitrary addresses:"
-{ $subsection alien>string }
+{ $subsections alien>string }
"For example, if a C function returns a " { $link char* } " but stipulates that the caller must deallocate the memory afterward, you must define the function as returning " { $link void* } ", and call one of the above words before passing the pointer to " { $link free } "." ;
ARTICLE: "alien.destructors" "Alien destructors"
"The " { $vocab-link "alien.destructors" } " vocabulary defines a utility parsing word for defining new disposable classes."
-{ $subsection POSTPONE: DESTRUCTOR: } ;
+{ $subsections POSTPONE: DESTRUCTOR: } ;
ABOUT: "alien.destructors"
\ No newline at end of file
ARTICLE: "alien.fortran" "Fortran FFI"
"The " { $vocab-link "alien.fortran" } " vocabulary provides an interface to code in shared libraries written in Fortran."
-{ $subsection "alien.fortran-types" }
-{ $subsection "alien.fortran-abis" }
-{ $subsection add-fortran-library }
-{ $subsection POSTPONE: LIBRARY: }
-{ $subsection POSTPONE: FUNCTION: }
-{ $subsection POSTPONE: SUBROUTINE: }
-{ $subsection fortran-invoke }
-;
+{ $subsections
+ "alien.fortran-types"
+ "alien.fortran-abis"
+ add-fortran-library
+ POSTPONE: LIBRARY:
+ POSTPONE: FUNCTION:
+ POSTPONE: SUBROUTINE:
+ fortran-invoke
+} ;
ABOUT: "alien.fortran"
ARTICLE: "loading-libs" "Loading native libraries"
"Before calling a C library, you must associate its path name on disk with a logical name which Factor uses to identify the library:"
-{ $subsection add-library }
-{ $subsection remove-library }
+{ $subsections
+ add-library
+ remove-library
+}
"Once a library has been defined, you can try loading it to see if the path name is correct:"
-{ $subsection load-library }
+{ $subsections load-library }
"If the compiler cannot load a library, or cannot resolve a symbol in a library, a linkage error is reported using the compiler error mechanism (see " { $link "compiler-errors" } "). Once you install the right library, reload the source file containing the " { $link add-library } " form to force the compiler to try loading the library again." ;
{ $notes "Alien objects are invalidated between image saves and loads, and hence source files should not contain alien literals; this word is for interactive use only. See " { $link "alien-expiry" } " for details." } ;
ARTICLE: "syntax-aliens" "Alien object literal syntax"
-{ $subsection POSTPONE: ALIEN: }
-{ $subsection POSTPONE: DLL" } ;
+{ $subsections
+ POSTPONE: ALIEN:
+ POSTPONE: DLL"
+} ;
HELP: LIBRARY:
{ $syntax "LIBRARY: name" }
"The " { $vocab-link "ascii" } " vocabulary implements support for the legacy ASCII character set. Most applications should use " { $link "unicode" } " instead."\r
$nl\r
"ASCII character classes:"\r
-{ $subsection blank? }\r
-{ $subsection letter? }\r
-{ $subsection LETTER? }\r
-{ $subsection digit? }\r
-{ $subsection printable? }\r
-{ $subsection control? }\r
-{ $subsection quotable? }\r
-{ $subsection ascii? }\r
+{ $subsections\r
+ blank?\r
+ letter?\r
+ LETTER?\r
+ digit?\r
+ printable?\r
+ control?\r
+ quotable?\r
+ ascii?\r
+}\r
"ASCII case conversion:"\r
-{ $subsection ch>lower }\r
-{ $subsection ch>upper }\r
-{ $subsection >lower }\r
-{ $subsection >upper } ;\r
+{ $subsections\r
+ ch>lower\r
+ ch>upper\r
+ >lower\r
+ >upper\r
+} ;\r
\r
ABOUT: "ascii"\r
ARTICLE: "base64" "Base 64 conversions"
"The " { $vocab-link "base64" } " vocabulary implements conversions of sequences to printable characters in base 64. These plain-text representations of binary data may be passed around and converted back to binary data later." $nl
"Converting to and from base64 as strings:"
-{ $subsection >base64 }
-{ $subsection >base64-lines }
-{ $subsection base64> }
+{ $subsections
+ >base64
+ >base64-lines
+ base64>
+}
"Using base64 from streams:"
-{ $subsection encode-base64 }
-{ $subsection encode-base64-lines }
-{ $subsection decode-base64 } ;
+{ $subsections
+ encode-base64
+ encode-base64-lines
+ decode-base64
+} ;
ABOUT: "base64"
"Bidirectional assocs implement the entire " { $link "assocs-protocol" } " with the exception of " { $link delete-at } ". Duplicate values are allowed, however value lookups with " { $link value-at } " only return the first key that a given value was stored with."
$nl
"The class of biassocs:"
-{ $subsection biassoc }
-{ $subsection biassoc? }
+{ $subsections
+ biassoc
+ biassoc?
+}
"Creating new biassocs:"
-{ $subsection <biassoc> }
-{ $subsection <bihash> }
+{ $subsections
+ <biassoc>
+ <bihash>
+}
"Converting existing assocs to biassocs:"
-{ $subsection >biassoc } ;
+{ $subsections >biassoc } ;
ABOUT: "biassocs"
ARTICLE: "binary-search" "Binary search"
"The " { $emphasis "binary search" } " algorithm allows elements to be located in sorted sequence in " { $snippet "O(log n)" } " time."
-{ $subsection search }
+{ $subsections search }
"Variants of sequence words optimized for sorted sequences:"
-{ $subsection sorted-index }
-{ $subsection sorted-member? }
-{ $subsection sorted-memq? }
+{ $subsections
+ sorted-index
+ sorted-member?
+ sorted-memq?
+}
{ $see-also "order-specifiers" "sequences-sorting" } ;
ABOUT: "binary-search"
"Bit arrays play a special role in the C library interface; they can be used to pass binary data back and forth between Factor and C. See " { $link "c-pointers" } "."
$nl
"Bit arrays form a class of objects:"
-{ $subsection bit-array }
-{ $subsection bit-array? }
+{ $subsections
+ bit-array
+ bit-array?
+}
"Creating new bit arrays:"
-{ $subsection >bit-array }
-{ $subsection <bit-array> }
+{ $subsections
+ >bit-array
+ <bit-array>
+}
"Efficiently setting and clearing all bits in a bit array:"
-{ $subsection set-bits }
-{ $subsection clear-bits }
+{ $subsections
+ set-bits
+ clear-bits
+}
"Converting between unsigned integers and their binary representation:"
-{ $subsection integer>bit-array }
-{ $subsection bit-array>integer }
+{ $subsections
+ integer>bit-array
+ bit-array>integer
+}
"Bit array literal syntax:"
-{ $subsection POSTPONE: ?{ } ;
+{ $subsections POSTPONE: ?{ } ;
ABOUT: "bit-arrays"
"A bit vector is a resizable mutable sequence of bits. Bit vector words are found in the " { $vocab-link "bit-vectors" } " vocabulary."\r
$nl\r
"Bit vectors form a class:"\r
-{ $subsection bit-vector }\r
-{ $subsection bit-vector? }\r
+{ $subsections\r
+ bit-vector\r
+ bit-vector?\r
+}\r
"Creating bit vectors:"\r
-{ $subsection >bit-vector }\r
-{ $subsection <bit-vector> }\r
+{ $subsections\r
+ >bit-vector\r
+ <bit-vector>\r
+}\r
"Literal syntax:"\r
-{ $subsection POSTPONE: ?V{ }\r
+{ $subsections POSTPONE: ?V{ }\r
"If you don't care about initial capacity, a more elegant way to create a new bit vector is to write:"\r
{ $code "?V{ } clone" } ;\r
\r
ARTICLE: "bootstrap.image" "Bootstrapping new images"
"A new image can be built from source; this is known as " { $emphasis "bootstrap" } ". Bootstrap is a two-step process. The first stage is the creation of a bootstrap image from a running Factor instance:"
-{ $subsection make-image }
+{ $subsections make-image }
"The second bootstrapping stage is initiated by running the resulting bootstrap image:"
{ $code "./factor -i=boot.x86.32.image" }
"This stage loads additional code, compiles all words, and dumps a final " { $snippet "factor.image" } "."
\r
ARTICLE: "boxes" "Boxes"\r
"A " { $emphasis "box" } " is a container which can either be empty or hold a single value."\r
-{ $subsection box }\r
+{ $subsections box }\r
"Creating an empty box:"\r
-{ $subsection <box> }\r
+{ $subsections <box> }\r
"Storing a value and removing a value from a box:"\r
-{ $subsection >box }\r
-{ $subsection box> }\r
+{ $subsections\r
+ >box\r
+ box>\r
+}\r
"Safely removing a value:"\r
-{ $subsection ?box }\r
+{ $subsections ?box }\r
"Testing if a box is full can be done by reading the " { $snippet "occupied" } " slot." ;\r
\r
ABOUT: "boxes"\r
ARTICLE: "calendar" "Calendar"
"The two data types used throughout the calendar library:"
-{ $subsection timestamp }
-{ $subsection duration }
+{ $subsections
+ timestamp
+ duration
+}
"Durations represent spans of time:"
-{ $subsection "using-durations" }
+{ $subsections "using-durations" }
"Arithmetic on timestamps and durations:"
-{ $subsection "timestamp-arithmetic" }
+{ $subsections "timestamp-arithmetic" }
"Getting the current timestamp:"
-{ $subsection now }
-{ $subsection gmt }
+{ $subsections
+ now
+ gmt
+}
"Converting between timestamps:"
-{ $subsection >local-time }
-{ $subsection >gmt }
+{ $subsections
+ >local-time
+ >gmt
+}
"Converting between timezones:"
-{ $subsection convert-timezone }
+{ $subsections convert-timezone }
"Timestamps relative to each other:"
-{ $subsection "relative-timestamps" }
+{ $subsections "relative-timestamps" }
"Operations on units of time:"
-{ $subsection "years" }
-{ $subsection "months" }
-{ $subsection "days" }
+{ $subsections
+ "years"
+ "months"
+ "days"
+}
"Meta-data about the calendar:"
-{ $subsection "calendar-facts" }
+{ $subsections "calendar-facts" }
;
ARTICLE: "timestamp-arithmetic" "Timestamp arithmetic"
"Adding timestamps and durations, or durations and durations:"
-{ $subsection time+ }
+{ $subsections time+ }
"Subtracting:"
-{ $subsection time- }
+{ $subsections time- }
"Element-wise multiplication:"
-{ $subsection time* } ;
+{ $subsections time* } ;
ARTICLE: "using-durations" "Using durations"
"Creating a duration object:"
-{ $subsection years }
-{ $subsection months }
-{ $subsection weeks }
-{ $subsection days }
-{ $subsection hours }
-{ $subsection minutes }
-{ $subsection seconds }
-{ $subsection milliseconds }
-{ $subsection microseconds }
-{ $subsection nanoseconds }
-{ $subsection instant }
+{ $subsections
+ years
+ months
+ weeks
+ days
+ hours
+ minutes
+ seconds
+ milliseconds
+ microseconds
+ nanoseconds
+ instant
+}
"Converting a duration to a number:"
-{ $subsection duration>years }
-{ $subsection duration>months }
-{ $subsection duration>days }
-{ $subsection duration>hours }
-{ $subsection duration>minutes }
-{ $subsection duration>seconds }
-{ $subsection duration>milliseconds }
-{ $subsection duration>microseconds }
-{ $subsection duration>nanoseconds } ;
+{ $subsections
+ duration>years
+ duration>months
+ duration>days
+ duration>hours
+ duration>minutes
+ duration>seconds
+ duration>milliseconds
+ duration>microseconds
+ duration>nanoseconds
+} ;
ARTICLE: "relative-timestamps" "Relative timestamps"
"In the future:"
-{ $subsection hence }
+{ $subsections hence }
"In the past:"
-{ $subsection ago }
+{ $subsections ago }
"Invert a duration:"
-{ $subsection before }
+{ $subsections before }
"Days of the week relative to " { $link now } ":"
-{ $subsection sunday }
-{ $subsection monday }
-{ $subsection tuesday }
-{ $subsection wednesday }
-{ $subsection thursday }
-{ $subsection friday }
-{ $subsection saturday }
+{ $subsections
+ sunday
+ monday
+ tuesday
+ wednesday
+ thursday
+ friday
+ saturday
+}
"New timestamps relative to calendar events:"
-{ $subsection beginning-of-year }
-{ $subsection beginning-of-month }
-{ $subsection beginning-of-week }
-{ $subsection midnight }
-{ $subsection noon }
-;
+{ $subsections
+ beginning-of-year
+ beginning-of-month
+ beginning-of-week
+ midnight
+ noon
+} ;
ARTICLE: "days" "Day operations"
"Naming days:"
-{ $subsection day-abbreviation2 }
-{ $subsection day-abbreviations2 }
-{ $subsection day-abbreviation3 }
-{ $subsection day-abbreviations3 }
-{ $subsection day-name }
-{ $subsection day-names }
+{ $subsections
+ day-abbreviation2
+ day-abbreviations2
+ day-abbreviation3
+ day-abbreviations3
+ day-name
+ day-names
+}
"Calculating a Julian day number:"
-{ $subsection julian-day-number }
+{ $subsections julian-day-number }
"Calculate a timestamp:"
-{ $subsection julian-day-number>date }
-;
+{ $subsections julian-day-number>date } ;
ARTICLE: "calendar-facts" "Calendar facts"
"Calendar facts:"
-{ $subsection average-month }
-{ $subsection months-per-year }
-{ $subsection days-per-year }
-{ $subsection hours-per-year }
-{ $subsection minutes-per-year }
-{ $subsection seconds-per-year }
-{ $subsection days-in-month }
-{ $subsection day-of-year }
-{ $subsection day-of-week }
-;
+{ $subsections
+ average-month
+ months-per-year
+ days-per-year
+ hours-per-year
+ minutes-per-year
+ seconds-per-year
+ days-in-month
+ day-of-year
+ day-of-week
+} ;
ARTICLE: "years" "Year operations"
"Leap year predicate:"
-{ $subsection leap-year? }
+{ $subsections leap-year? }
"Find the number of days in a year:"
-{ $subsection days-in-year }
-;
+{ $subsections days-in-year } ;
ARTICLE: "months" "Month operations"
"Naming months:"
-{ $subsection month-name }
-{ $subsection month-names }
-{ $subsection month-abbreviation }
-{ $subsection month-abbreviations }
-;
+{ $subsections
+ month-name
+ month-names
+ month-abbreviation
+ month-abbreviations
+} ;
ABOUT: "calendar"
ARTICLE: "channels" "Channels"
"The " { $vocab-link "channels" } " vocabulary provides a simple abstraction to send and receive objects." $nl
"Opening a channel:"
-{ $subsection <channel> }
+{ $subsections <channel> }
"Sending a message:"
-{ $subsection to }
+{ $subsections to }
"Receiving a message:"
-{ $subsection from } ;
+{ $subsections from } ;
ABOUT: "channels"
ARTICLE: "checksums.adler-32" "Adler-32 checksum"
"The Adler-32 checksum algorithm implements simple and fast checksum. It is used in zlib and rsync."
-{ $subsection adler-32 } ;
+{ $subsections adler-32 } ;
ABOUT: "checksums.adler-32"
ARTICLE: "checksums.fnv1" "Fowler-Noll-Vo checksum"
"The Fowler-Noll-Vo checksum algorithm is another simple and fast checksum. It comes in 32, 64, 128, 256, 512 and 1024-bit versions, each in 1 and 1a variants. The 1a variants tend to produce a slightly better result. See http://en.wikipedia.org/wiki/Fowler_Noll_Vo_hash for more details."
-
- { $subsection fnv1-32 }
- { $subsection fnv1a-32 }
-
- { $subsection fnv1-64 }
- { $subsection fnv1a-64 }
-
- { $subsection fnv1-128 }
- { $subsection fnv1a-128 }
-
- { $subsection fnv1-256 }
- { $subsection fnv1a-256 }
-
- { $subsection fnv1-512 }
- { $subsection fnv1a-512 }
-
- { $subsection fnv1-1024 }
- { $subsection fnv1a-1024 }
- ;
+{ $subsections
+ fnv1-32
+ fnv1a-32
+}
+{ $subsections
+ fnv1-64
+ fnv1a-64
+}
+{ $subsections
+ fnv1-128
+ fnv1a-128
+}
+{ $subsections
+ fnv1-256
+ fnv1a-256
+}
+{ $subsections
+ fnv1-512
+ fnv1a-512
+}
+{ $subsections
+ fnv1-1024
+ fnv1a-1024
+} ;
ABOUT: "checksums.fnv1"
ARTICLE: "checksums.md5" "MD5 checksum"
"The MD5 checksum algorithm implements a one-way hash function. While it is widely used, many weaknesses are known and it should not be used in new applications (" { $url "http://www.schneier.com/blog/archives/2005/03/more_hash_funct.html" } ")."
-{ $subsection md5 } ;
+{ $subsections md5 } ;
ABOUT: "checksums.md5"
ARTICLE: "checksums.openssl" "OpenSSL checksums"
"The OpenSSL library provides a large number of efficient checksum (message digest) algorithms which may be used independently of its SSL functionality."
-{ $subsection openssl-checksum }
+{ $subsections openssl-checksum }
"Constructing a checksum from a known name:"
-{ $subsection <openssl-checksum> }
+{ $subsections <openssl-checksum> }
"Two utility words:"
-{ $subsection openssl-md5 }
-{ $subsection openssl-sha1 }
+{ $subsections
+ openssl-md5
+ openssl-sha1
+}
"An error thrown if the digest name is unrecognized:"
-{ $subsection unknown-digest }
+{ $subsections unknown-digest }
"An example where we compute the SHA1 checksum of a string using the OpenSSL implementation of SHA1:"
{ $example "USING: byte-arrays checksums checksums.openssl ;" "\"hello world\" >byte-array openssl-sha1 checksum-bytes hex-string ." "\"2aae6c35c94fcfb415dbe95f408b9ce91ee846ed\"" }
"If we use the Factor implementation, we get the same result, just slightly slower:"
ARTICLE: "checksums.sha" "SHA-2 checksum"
"The SHA family of checksum algorithms are one-way hashes useful for checksumming data. SHA-1 is considered insecure, while SHA-2 It is generally considered to be pretty strong." $nl
"SHA-2 checksums:"
-{ $subsection sha-224 }
-{ $subsection sha-256 }
+{ $subsections
+ sha-224
+ sha-256
+}
"SHA-1 checksum:"
-{ $subsection sha1 } ;
+{ $subsections sha1 } ;
ABOUT: "checksums.sha"
ARTICLE: "circular" "Circular sequences"
"The " { $vocab-link "circular" } " vocabulary implements the " { $link "sequence-protocol" } " to allow an arbitrary start index and wrap-around indexing." $nl
"Creating a new circular object:"
-{ $subsection <circular> }
-{ $subsection <circular-string> }
-{ $subsection <growing-circular> }
+{ $subsections
+ <circular>
+ <circular-string>
+ <growing-circular>
+}
"Changing the start index:"
-{ $subsection change-circular-start }
-{ $subsection rotate-circular }
+{ $subsections
+ change-circular-start
+ rotate-circular
+}
"Pushing new elements:"
-{ $subsection push-circular }
-{ $subsection push-growing-circular } ;
+{ $subsections
+ push-circular
+ push-growing-circular
+} ;
ABOUT: "circular"
ARTICLE: "classes.struct.define" "Defining struct classes"
"Struct classes are defined using a syntax similar to the " { $link POSTPONE: TUPLE: } " syntax for defining tuple classes:"
-{ $subsection POSTPONE: STRUCT: }
+{ $subsections POSTPONE: STRUCT: }
"Union structs are also supported, which behave like structs but share the same memory for all the slots."
-{ $subsection POSTPONE: UNION-STRUCT: } ;
+{ $subsections POSTPONE: UNION-STRUCT: } ;
ARTICLE: "classes.struct.create" "Creating instances of structs"
"Structs can be allocated with " { $link new } "- and " { $link boa } "-like constructor words. Additional words are provided for building structs from C memory and from existing buffers:"
-{ $subsection <struct> }
-{ $subsection <struct-boa> }
-{ $subsection malloc-struct }
-{ $subsection memory>struct }
+{ $subsections
+ <struct>
+ <struct-boa>
+ malloc-struct
+ memory>struct
+}
"When the contents of a struct will be immediately reset, faster primitive words are available that will create a struct without initializing its contents:"
-{ $subsection (struct) }
-{ $subsection (malloc-struct) }
+{ $subsections
+ (struct)
+ (malloc-struct)
+}
"Structs have literal syntax, similar to " { $link POSTPONE: T{ } " for tuples:"
-{ $subsection POSTPONE: S{ } ;
+{ $subsections POSTPONE: S{ } ;
ARTICLE: "classes.struct.c" "Passing structs to C functions"
"Structs can be passed and returned by value, or by reference."
ARTICLE: "classes.struct" "Struct classes"
"The " { $vocab-link "classes.struct" } " vocabulary implements " { $link struct } " classes. They are similar to " { $link tuple } " classes, but their slots exhibit value semantics, and they are backed by a contiguous structured block of memory. Structs can be used for space-efficient storage of data in the Factor heap, as well as for passing data to and from C libraries using the " { $link "alien" } "."
-{ $subsection "classes.struct.examples" }
-{ $subsection "classes.struct.define" }
-{ $subsection "classes.struct.create" }
-{ $subsection "classes.struct.c" } ;
+{ $subsections
+ "classes.struct.examples"
+ "classes.struct.define"
+ "classes.struct.create"
+ "classes.struct.c"
+} ;
ABOUT: "classes.struct"
ARTICLE: "cocoa-application-utils" "Cocoa application utilities"
"Utilities:"
-{ $subsection NSApp }
-{ $subsection add-observer }
-{ $subsection remove-observer }
-{ $subsection install-delegate }
+{ $subsections
+ NSApp
+ add-observer
+ remove-observer
+ install-delegate
+}
"Combinators:"
-{ $subsection cocoa-app }
-{ $subsection with-autorelease-pool }
-{ $subsection with-cocoa } ;
+{ $subsections
+ cocoa-app
+ with-autorelease-pool
+ with-cocoa
+} ;
IN: cocoa.application
ABOUT: "cocoa-application-utils"
ARTICLE: "objc-calling" "Calling Objective C code"
"Before an Objective C class can be used, it must be imported; by default, a small set of common classes are imported automatically, but additional classes can be imported as needed."
-{ $subsection POSTPONE: IMPORT: }
+{ $subsections POSTPONE: IMPORT: }
"Every imported Objective C class has as corresponding class word in the " { $vocab-link "cocoa.classes" } " vocabulary. Class words push the class object in the stack, allowing class methods to be invoked."
$nl
"Messages can be sent to classes and instances using a pair of parsing words:"
-{ $subsection POSTPONE: -> }
-{ $subsection POSTPONE: SUPER-> }
+{ $subsections
+ POSTPONE: ->
+ POSTPONE: SUPER->
+}
"These parsing words are actually syntax sugar for a pair of ordinary words; they can be used instead of the parsing words if the selector name is dynamically computed:"
-{ $subsection send }
-{ $subsection super-send } ;
+{ $subsections
+ send
+ super-send
+} ;
ARTICLE: "cocoa" "Cocoa bridge"
"The " { $vocab-link "cocoa" } " vocabulary implements a Factor-Cocoa bridge for Mac OS X (GNUstep is not supported)."
"The lowest layer uses the " { $link "alien" } " to define bindings for the various functions in Apple's Objective-C runtime. This is defined in the " { $vocab-link "cocoa.runtime" } " vocabulary."
$nl
"On top of this, a dynamic message send facility is built:"
-{ $subsection "objc-calling" }
-{ $subsection "objc-subclassing" }
+{ $subsections
+ "objc-calling"
+ "objc-subclassing"
+}
"A utility library is built to faciliate the development of Cocoa applications in Factor:"
-{ $subsection "cocoa-application-utils" }
-{ $subsection "cocoa-dialogs" }
-{ $subsection "cocoa-pasteboard-utils" }
-{ $subsection "cocoa-view-utils" }
-{ $subsection "cocoa-window-utils" } ;
+{ $subsections
+ "cocoa-application-utils"
+ "cocoa-dialogs"
+ "cocoa-pasteboard-utils"
+ "cocoa-view-utils"
+ "cocoa-window-utils"
+} ;
IN: cocoa
ABOUT: "cocoa"
ARTICLE: "cocoa-dialogs" "Cocoa file dialogs"
"Open dialogs:"
-{ $subsection <NSOpenPanel> }
-{ $subsection open-panel }
+{ $subsections
+ <NSOpenPanel>
+ open-panel
+}
"Save dialogs:"
-{ $subsection <NSSavePanel> }
-{ $subsection save-panel } ;
+{ $subsections
+ <NSSavePanel>
+ save-panel
+} ;
IN: cocoa.dialogs
ABOUT: "cocoa-dialogs"
{ $description "Sets the contents of the pasteboard." } ;
ARTICLE: "cocoa-pasteboard-utils" "Cocoa pasteboard utilities"
-{ $subsection pasteboard-string? }
-{ $subsection pasteboard-string }
-{ $subsection set-pasteboard-string } ;
+{ $subsections
+ pasteboard-string?
+ pasteboard-string
+ set-pasteboard-string
+} ;
IN: cocoa.pasteboard
ABOUT: "cocoa-pasteboard-utils"
ARTICLE: "objc-subclassing" "Subclassing Objective C classes"
"Objective C classes can be subclassed, with new methods defined in Factor, using a parsing word:"
-{ $subsection POSTPONE: CLASS: }
+{ $subsections POSTPONE: CLASS: }
"This word is actually syntax sugar for an ordinary word:"
-{ $subsection define-objc-class }
+{ $subsections define-objc-class }
"Objective C class definitions are saved in the image. If the image is saved and Factor is restarted with the saved image, custom class definitions are made available to the Objective C runtime when they are first accessed from within Factor." ;
IN: cocoa.subclassing
{ $description "Outputs the current mouse location." } ;
ARTICLE: "cocoa-view-utils" "Cocoa view utilities"
-{ $subsection <GLView> }
-{ $subsection view-dim }
-{ $subsection mouse-location } ;
+{ $subsections
+ <GLView>
+ view-dim
+ mouse-location
+} ;
IN: cocoa.views
ABOUT: "cocoa-view-utils"
{ $description "Creates a new " { $snippet "NSWindow" } " with the specified dimensions, containing the given view." } ;
ARTICLE: "cocoa-window-utils" "Cocoa window utilities"
-{ $subsection <NSWindow> }
-{ $subsection <ViewWindow> } ;
+{ $subsections
+ <NSWindow>
+ <ViewWindow>
+} ;
IN: cocoa.windows
ABOUT: "cocoa-window-utils"
ARTICLE: "colors.protocol" "Color protocol"
"Abstract superclass for colors:"
-{ $subsection color }
+{ $subsections color }
"All color objects must are required to implement a method on the " { $link >rgba } " generic word."
$nl
"Optionally, they can provide methods on the accessors " { $link red>> } ", " { $link green>> } ", " { $link blue>> } " and " { $link alpha>> } ", either by defining slots with the appropriate names, or with methods which calculate the color component values. The accessors should return color components which are real numbers in the range between 0 and 1."
"The " { $vocab-link "colors" } " vocabulary defines a protocol for colors, with a concrete implementation for RGBA colors. This vocabulary is used by " { $vocab-link "io.styles" } ", " { $vocab-link "ui" } " and other vocabularies, but it is independent of them."
$nl
"RGBA colors with floating point components in the range " { $snippet "[0,1]" } ":"
-{ $subsection rgba }
-{ $subsection <rgba> }
+{ $subsections
+ rgba
+ <rgba>
+}
"Converting a color to RGBA:"
-{ $subsection >rgba }
+{ $subsections >rgba }
"Extracting RGBA components of colors:"
-{ $subsection >rgba-components }
+{ $subsections >rgba-components }
"Further topics:"
-{ $subsection "colors.protocol" }
-{ $subsection "colors.constants" }
+{ $subsections
+ "colors.protocol"
+ "colors.constants"
+}
{ $vocab-subsection "Grayscale colors" "colors.gray" }
{ $vocab-subsection "HSV colors" "colors.hsv" } ;
ARTICLE: "colors.constants" "Standard color database"
"The " { $vocab-link "colors.constants" } " vocabulary bundles the X11 " { $snippet "rgb.txt" } " database and Factor's " { $snippet "factor-colors.txt" } " theme database to provide words for looking up color values by name."
-{ $subsection named-color }
-{ $subsection named-colors }
-{ $subsection POSTPONE: COLOR: } ;
+{ $subsections
+ named-color
+ named-colors
+ POSTPONE: COLOR:
+} ;
ABOUT: "colors.constants"
\ No newline at end of file
ARTICLE: "colors.gray" "Grayscale colors"
"The " { $vocab-link "colors.gray" } " vocabulary implements grayscale colors. These colors hold a single value, and respond to " { $link red>> } ", " { $link green>> } ", " { $link blue>> } " with that value. They also have an independent alpha channel, " { $link alpha>> } "."
-{ $subsection gray }
-{ $subsection <gray> } ;
+{ $subsections
+ gray
+ <gray>
+} ;
ABOUT: "colors.gray"
\ No newline at end of file
ARTICLE: "colors.hsv" "HSV colors"
"The " { $vocab-link "colors.hsv" } " vocabulary implements colors specified by their hue, saturation, and value, together with an alpha channel."
-{ $subsection hsva }
-{ $subsection <hsva> }
+{ $subsections
+ hsva
+ <hsva>
+}
{ $see-also "colors" } ;
ABOUT: "colors.hsv"
\ No newline at end of file
ARTICLE: "columns" "Column sequences"
"A " { $emphasis "column" } " presents a column of a matrix represented as a sequence of rows:"
-{ $subsection column }
-{ $subsection <column> }
+{ $subsections
+ column
+ <column>
+}
"A utility word:"
-{ $subsection <flipped> } ;
+{ $subsections <flipped> } ;
ABOUT: "columns"
ARTICLE: "combinators.short-circuit" "Short-circuit combinators"
"The " { $vocab-link "combinators.short-circuit" } " vocabulary stops a computation early once a condition is met." $nl
"AND combinators:"
-{ $subsection 0&& }
-{ $subsection 1&& }
-{ $subsection 2&& }
-{ $subsection 3&& }
+{ $subsections
+ 0&&
+ 1&&
+ 2&&
+ 3&&
+}
"OR combinators:"
-{ $subsection 0|| }
-{ $subsection 1|| }
-{ $subsection 2|| }
-{ $subsection 3|| }
+{ $subsections
+ 0||
+ 1||
+ 2||
+ 3||
+}
"Generalized combinators:"
-{ $subsection n&& }
-{ $subsection n|| }
+{ $subsections
+ n&&
+ n||
+}
;
ABOUT: "combinators.short-circuit"
"The " { $vocab-link "combinators.short-circuit.smart" } " vocabulary is similar to " { $vocab-link "combinators.short-circuit" } " except the combinators here infer the number of inputs that the sequence of quotations takes."
$nl
"Generalized AND:"
-{ $subsection && }
+{ $subsections && }
"Generalized OR:"
-{ $subsection || } ;
+{ $subsections || } ;
ABOUT: "combinators.short-circuit.smart"
ARTICLE: "combinators.smart" "Smart combinators"
"A " { $emphasis "smart combinator" } " is a macro which reflects on the stack effect of an input quotation. The " { $vocab-link "combinators.smart" } " vocabulary implements a few simple smart combinators which look at the static stack effects of input quotations and generate code which produces or consumes the relevant number of stack values." $nl
"Call a quotation and discard all output values or preserve all input values:"
-{ $subsection drop-outputs }
-{ $subsection keep-inputs }
+{ $subsections
+ drop-outputs
+ keep-inputs
+}
"Take all input values from a sequence:"
-{ $subsection input<sequence }
+{ $subsections input<sequence }
"Store all output values to a sequence:"
-{ $subsection output>sequence }
-{ $subsection output>array }
+{ $subsections
+ output>sequence
+ output>array
+}
"Reducing the set of output values:"
-{ $subsection reduce-outputs }
+{ $subsections reduce-outputs }
"Summing output values:"
-{ $subsection sum-outputs }
+{ $subsections sum-outputs }
"Concatenating output values:"
-{ $subsection append-outputs }
-{ $subsection append-outputs-as }
+{ $subsections
+ append-outputs
+ append-outputs-as
+}
"New smart combinators can be created by defining " { $link "macros" } " which call " { $link infer } "." ;
ABOUT: "combinators.smart"
"The botstrap initialization file is named " { $snippet "factor-boot-rc" } " on Windows and " { $snippet ".factor-boot-rc" } " on Unix. This file can contain " { $link require } " calls for vocabularies you use frequently, and other such long-running tasks that you do not want to perform every time Factor starts."
$nl
"A word to run this file from an existing Factor session:"
-{ $subsection run-bootstrap-init }
+{ $subsections run-bootstrap-init }
"For example, if you changed " { $snippet ".factor-boot-rc" } " and do not want to bootstrap again, you can just invoke " { $link run-bootstrap-init } " in the listener." ;
ARTICLE: "factor-rc" "Startup initialization file"
"The startup initialization file is named " { $snippet "factor-rc" } " on Windows and " { $snippet ".factor-rc" } " on Unix. If it exists, it is run every time Factor starts."
$nl
"A word to run this file from an existing Factor session:"
-{ $subsection run-user-init } ;
+{ $subsections run-user-init } ;
ARTICLE: "factor-roots" "Additional vocabulary roots file"
"The vocabulary roots file is named " { $snippet "factor-roots" } " on Windows and " { $snippet ".factor-roots" } " on Unix. If it exists, it is loaded every time Factor starts. It contains a newline-separated list of " { $link "vocabs.roots" } "."
$nl
"A word to run this file from an existing Factor session:"
-{ $subsection load-vocab-roots } ;
+{ $subsections load-vocab-roots } ;
ARTICLE: "rc-files" "Running code on startup"
"Factor looks for three optional files in your home directory."
-{ $subsection "factor-boot-rc" }
-{ $subsection "factor-rc" }
-{ $subsection "factor-roots" }
+{ $subsections
+ "factor-boot-rc"
+ "factor-rc"
+ "factor-roots"
+}
"The " { $snippet "-no-user-init" } " command line switch will inhibit loading running of these files."
$nl
"If you are unsure where the files should be located, evaluate the following code:"
"Factor command line usage:"
{ $code "factor [system switches...] [script args...]" }
"Zero or more system switches can be passed in, followed by an optional script file name. If the script file is specified, it will be run on startup, any arguments after the script file are stored in a variable, with no further processing by Factor itself:"
-{ $subsection command-line }
+{ $subsections command-line }
"Instead of running a script, it is also possible to run a vocabulary; this invokes the vocabulary's " { $link POSTPONE: MAIN: } " word:"
{ $code "factor [system switches...] -run=<vocab name>" }
"If no script file or " { $snippet "-run=" } " switch is specified, Factor will start " { $link "listener" } " or " { $link "ui-tools" } ", depending on the operating system."
{ { $snippet "-no-" { $emphasis "foo" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $link f } }
{ { $snippet "-" { $emphasis "foo" } "=" { $emphasis "bar" } } " - sets the global variable " { $snippet "\"" { $emphasis "foo" } "\"" } " to " { $snippet "\"" { $emphasis "bar" } "\"" } }
}
-{ $subsection "runtime-cli-args" }
-{ $subsection "bootstrap-cli-args" }
-{ $subsection "standard-cli-args" }
+{ $subsections
+ "runtime-cli-args"
+ "bootstrap-cli-args"
+ "standard-cli-args"
+}
"The raw list of command line arguments can also be obtained and inspected directly:"
-{ $subsection (command-line) }
+{ $subsections (command-line) }
"There is a way to override the default vocabulary to run on startup, if no script name or " { $snippet "-run" } " switch is specified:"
-{ $subsection main-vocab-hook } ;
+{ $subsections main-vocab-hook } ;
ABOUT: "cli"
ARTICLE: "compiler-usage" "Calling the optimizing compiler"
"Normally, new word definitions are recompiled automatically. This can be changed:"
-{ $subsection disable-optimizer }
-{ $subsection enable-optimizer }
+{ $subsections
+ disable-optimizer
+ enable-optimizer
+}
"Removing a word's optimized definition:"
-{ $subsection decompile }
+{ $subsections decompile }
"Compiling a single quotation:"
-{ $subsection compile-call }
+{ $subsections compile-call }
"Higher-level words can be found in " { $link "compilation-units" } "." ;
ARTICLE: "compiler-impl" "Compiler implementation"
"The " { $vocab-link "compiler" } "vocabulary, in addition to providing the user-visible words of the compiler, implements the main compilation loop."
$nl
"Words are added to the " { $link compile-queue } " variable as needed and compiled."
-{ $subsection compile-queue }
+{ $subsections compile-queue }
"Once compiled, a word is added to the assoc stored in the " { $link compiled } " variable. When compilation is complete, this assoc is passed to " { $link modify-code-heap } "."
$nl
"The " { $link compile-word } " word performs the actual task of compiling an individual word. The process proceeds as follows:"
"The optimizing compiler also trades off compile time for performance of generated code, so loading certain vocabularies might take a while. Saving the image after loading vocabularies can save you a lot of time that you would spend waiting for the same code to load in every coding session; see " { $link "images" } " for information."
$nl
"Most code you write will run with the optimizing compiler. Sometimes, the non-optimizing compiler is used, for example for listener interactions, or for running the quotation passed to " { $link POSTPONE: call( } "."
-{ $subsection "compiler-errors" }
-{ $subsection "hints" }
-{ $subsection "compiler-usage" }
-{ $subsection "compiler-impl" } ;
+{ $subsections
+ "compiler-errors"
+ "hints"
+ "compiler-usage"
+ "compiler-impl"
+} ;
ABOUT: "compiler"
$nl
"Implements both the TIFF and GIF variations of the LZW algorithm."
{ $heading "Decompression" }
-{ $subsection tiff-lzw-uncompress }
-{ $subsection gif-lzw-uncompress }
+{ $subsections
+ tiff-lzw-uncompress
+ gif-lzw-uncompress
+}
{ $heading "Compression" }
"Compression has not yet been implemented."
$nl
"Implementation details:"
-{ $subsection "compression.lzw.differences" }
+{ $subsections "compression.lzw.differences" }
;
ABOUT: "compression.lzw"
"The " { $vocab-link "concurrency.combinators" } " vocabulary provides concurrent variants of various combinators."\r
$nl\r
"Concurrent sequence combinators:"\r
-{ $subsection parallel-each }\r
-{ $subsection 2parallel-each }\r
-{ $subsection parallel-map }\r
-{ $subsection 2parallel-map }\r
-{ $subsection parallel-filter }\r
+{ $subsections\r
+ parallel-each\r
+ 2parallel-each\r
+ parallel-map\r
+ 2parallel-map\r
+ parallel-filter\r
+}\r
"Concurrent cleave combinators:"\r
-{ $subsection parallel-cleave }\r
-{ $subsection parallel-spread }\r
-{ $subsection parallel-napply } ;\r
+{ $subsections\r
+ parallel-cleave\r
+ parallel-spread\r
+ parallel-napply\r
+} ;\r
\r
ABOUT: "concurrency.combinators"\r
\r
ARTICLE: "concurrency.count-downs" "Count-down latches"\r
"The " { $vocab-link "concurrency.count-downs" } " vocabulary implements the " { $emphasis "count-down latch" } " data type, whichis a wrapper for a non-negative integer value which tends towards zero. A thread can either decrement the value, or wait for it to become zero."\r
-{ $subsection <count-down> }\r
-{ $subsection count-down }\r
-{ $subsection await }\r
+{ $subsections\r
+ <count-down>\r
+ count-down\r
+ await\r
+}\r
"The vocabulary was modelled after a similar feature in Java's " { $snippet "java.util.concurrent" } " library." ;\r
\r
ABOUT: "concurrency.count-downs"\r
ARTICLE: "concurrency.distributed" "Distributed message passing"
"The " { $vocab-link "concurrency.distributed" } " implements transparent distributed message passing, inspired by Erlang and Termite."
-{ $subsection start-node }
+{ $subsections start-node }
"Instances of " { $link thread } " can be sent to remote processes, at which point they are converted to objects holding the thread ID and the current node's host name:"
-{ $subsection remote-process }
+{ $subsections remote-process }
"The " { $vocab-link "serialize" } " vocabulary is used to convert Factor objects to byte arrays for transfer over a socket." ;
ABOUT: "concurrency.distributed"
\r
ARTICLE: "concurrency.exchangers" "Object exchange points"\r
"The " { $vocab-link "concurrency.exchangers" } " vocabulary implements " { $emphasis "object exchange points" } ", which are rendezvous points where two threads can exchange objects."\r
-{ $subsection exchanger }\r
-{ $subsection <exchanger> }\r
-{ $subsection exchange }\r
+{ $subsections\r
+ exchanger\r
+ <exchanger>\r
+ exchange\r
+}\r
"One use-case is two threads, where one thread reads data into a buffer and another thread processes the data. The reader thread can begin by reading the data, then passing the buffer through an exchanger, then recursing. The processing thread can begin by creating an empty buffer, and exchanging it through the exchanger. It then processes the result and recurses."\r
$nl\r
"The vocabulary was modelled after a similar feature in Java's " { $snippet "java.util.concurrent" } " library." ;\r
"The flag can be raised at any time; raising a raised flag does nothing. Lowering a flag if it has not been raised yet will wait for another thread to raise the flag."
$nl
"Essentially, a flag can be thought of as a counting semaphore where the count never goes above one."
-{ $subsection flag }
-{ $subsection flag? }
+{ $subsections
+ flag
+ flag?
+}
"Waiting for a flag to be raised:"
-{ $subsection raise-flag }
-{ $subsection wait-for-flag }
-{ $subsection lower-flag } ;
+{ $subsections
+ raise-flag
+ wait-for-flag
+ lower-flag
+} ;
ABOUT: "concurrency.flags"
\r
ARTICLE: "concurrency.futures" "Futures"\r
"The " { $vocab-link "concurrency.futures" } " vocabulary implements " { $emphasis "futures" } ", which are deferred computations performed in a background thread. A thread may create a future, then proceed to perform other tasks, then later wait for the future to complete."\r
-{ $subsection future }\r
-{ $subsection ?future }\r
-{ $subsection ?future-timeout } ;\r
+{ $subsections\r
+ future\r
+ ?future\r
+ ?future-timeout\r
+} ;\r
\r
ABOUT: "concurrency.futures"\r
"A mutual-exclusion lock ensures that only one thread executes with the lock held at a time. They are used to protect critical sections so that certain operations appear to be atomic to other threads."\r
$nl\r
"There are two varieties of locks: non-reentrant and reentrant. The latter may be acquired recursively by the same thread. Attempting to do so with the former will deadlock."\r
-{ $subsection lock }\r
-{ $subsection <lock> }\r
-{ $subsection <reentrant-lock> }\r
-{ $subsection with-lock }\r
-{ $subsection with-lock-timeout } ;\r
+{ $subsections\r
+ lock\r
+ <lock>\r
+ <reentrant-lock>\r
+ with-lock\r
+ with-lock-timeout\r
+} ;\r
\r
HELP: rw-lock\r
{ $class-description "The class of reader/writer locks." } ;\r
"Read/write locks allow any number of threads to hold the read lock simulateneously, however attempting to acquire a write lock blocks until all other threads release read locks and write locks."\r
$nl\r
"Read/write locks are reentrant. A thread holding a write lock may acquire a read lock or a write lock without blocking. However a thread holding a read lock may not acquire a write lock recursively since that could break invariants assumed by the code executing with the read lock held."\r
-{ $subsection rw-lock }\r
-{ $subsection <rw-lock> }\r
-{ $subsection with-read-lock }\r
-{ $subsection with-write-lock }\r
+{ $subsections\r
+ rw-lock\r
+ <rw-lock>\r
+ with-read-lock\r
+ with-write-lock\r
+}\r
"Versions of the above that take a timeout duration:"\r
-{ $subsection with-read-lock-timeout }\r
-{ $subsection with-write-lock-timeout } ;\r
+{ $subsections\r
+ with-read-lock-timeout\r
+ with-write-lock-timeout\r
+} ;\r
\r
ARTICLE: "concurrency.locks" "Locks"\r
"A " { $emphasis "lock" } " is an object protecting a critical region of code, enforcing a particular mutual-exclusion policy. The " { $vocab-link "concurrency.locks" } " vocabulary implements two types of locks:"\r
-{ $subsection "concurrency.locks.mutex" }\r
-{ $subsection "concurrency.locks.rw" } ;\r
+{ $subsections\r
+ "concurrency.locks.mutex"\r
+ "concurrency.locks.rw"\r
+} ;\r
\r
ABOUT: "concurrency.locks"\r
\r
ARTICLE: "concurrency.mailboxes" "Mailboxes"\r
"A " { $emphasis "mailbox" } " is a first-in-first-out queue where the operation of removing an element blocks if the queue is empty. Mailboxes are implemented in the " { $vocab-link "concurrency.mailboxes" } " vocabulary."\r
-{ $subsection mailbox }\r
-{ $subsection <mailbox> }\r
+{ $subsections\r
+ mailbox\r
+ <mailbox>\r
+}\r
"Removing the first element:"\r
-{ $subsection mailbox-get }\r
-{ $subsection mailbox-get-timeout }\r
+{ $subsections\r
+ mailbox-get\r
+ mailbox-get-timeout\r
+}\r
"Removing the first element matching a predicate:"\r
-{ $subsection mailbox-get? }\r
-{ $subsection mailbox-get-timeout? }\r
+{ $subsections\r
+ mailbox-get?\r
+ mailbox-get-timeout?\r
+}\r
"Emptying out a mailbox:"\r
-{ $subsection mailbox-get-all }\r
+{ $subsections mailbox-get-all }\r
"Adding an element:"\r
-{ $subsection mailbox-put }\r
+{ $subsections mailbox-put }\r
"Testing if a mailbox is empty:"\r
-{ $subsection mailbox-empty? }\r
-{ $subsection while-mailbox-empty } ;\r
+{ $subsections\r
+ mailbox-empty?\r
+ while-mailbox-empty\r
+} ;\r
\r
ABOUT: "concurrency.mailboxes"\r
"The messages that are sent from thread to thread are any Factor value. Factor tuples are ideal for this sort of thing as you can send a tuple to a thread and the generic word dispatch mechanism can be used to perform actions depending on what the type of the tuple is."
$nl
"The " { $link spawn } " word pushes the newly-created thread on the calling thread's stack; this thread object can then be sent messages:"
-{ $subsection send }
+{ $subsections send }
"A thread can get a message from its queue:"
-{ $subsection receive }
-{ $subsection receive-timeout }
-{ $subsection receive-if }
-{ $subsection receive-if-timeout }
+{ $subsections
+ receive
+ receive-timeout
+ receive-if
+ receive-if-timeout
+}
{ $see-also "concurrency.mailboxes" } ;
ARTICLE: { "concurrency" "synchronous-sends" } "Synchronous sends"
"The " { $link send } " word sends a message asynchronously, and the sending thread continues immediately. It is also possible to send a message to a thread and block until a response is received:"
-{ $subsection send-synchronous }
+{ $subsections send-synchronous }
"To reply to a synchronous message:"
-{ $subsection reply-synchronous }
+{ $subsections reply-synchronous }
"An example:"
{ $example
"USING: concurrency.messaging threads ;"
"A thread can handle exceptions using the standard Factor exception handling mechanism. If an exception is uncaught the thread will terminate. For example:"
{ $code "[ 1 0 / \"This will not print\" print ] \"division-by-zero\" spawn" }
"Processes can be linked so that a parent thread can receive the exception that caused the child thread to terminate. In this way 'supervisor' threads can be created that are notified when child threads terminate and possibly restart them."
-{ $subsection spawn-linked }
+{ $subsections spawn-linked }
"This will create a unidirectional link, such that if an uncaught exception causes the child to terminate, the parent thread can catch it:"
{ $code "["
" [ 1 0 / \"This will not print\" print ] \"linked-division\" spawn-linked drop"
"A concurrency-oriented program is one in which multiple threads run simultaneously in a single Factor image or across multiple running Factor instances. The threads can communicate with each other by asynchronous message sends."
$nl
"Although threads can share data via Factor's mutable data structures it is not recommended to mix shared state with message passing as it can lead to confusing code."
-{ $subsection { "concurrency" "messaging" } }
-{ $subsection { "concurrency" "synchronous-sends" } }
-{ $subsection { "concurrency" "exceptions" } } ;
+{ $subsections
+ { "concurrency" "messaging" }
+ { "concurrency" "synchronous-sends" }
+ { "concurrency" "exceptions" }
+} ;
ABOUT: "concurrency.messaging"
\r
ARTICLE: "concurrency.promises" "Promises"\r
"The " { $vocab-link "concurrency.promises" } " vocabulary implements " { $emphasis "promises" } ", which are thread-safe write-once variables. Once a promise is created, threads may block waiting for it to be " { $emphasis "fulfilled" } "; at some point in the future, another thread may provide a value at which point all waiting threads are notified."\r
-{ $subsection promise }\r
-{ $subsection <promise> }\r
-{ $subsection fulfill }\r
-{ $subsection ?promise }\r
-{ $subsection ?promise-timeout } ;\r
+{ $subsections\r
+ promise\r
+ <promise>\r
+ fulfill\r
+ ?promise\r
+ ?promise-timeout\r
+} ;\r
\r
ABOUT: "concurrency.promises"\r
"] parallel-map"\r
}\r
"Creating semaphores:"\r
-{ $subsection semaphore }\r
-{ $subsection <semaphore> }\r
+{ $subsections\r
+ semaphore\r
+ <semaphore>\r
+}\r
"Unlike locks, where acquisition and release are always paired by a combinator, semaphores expose these operations directly and there is no requirement that they be performed in the same thread:"\r
-{ $subsection acquire }\r
-{ $subsection acquire-timeout }\r
-{ $subsection release }\r
+{ $subsections\r
+ acquire\r
+ acquire-timeout\r
+ release\r
+}\r
"Combinators which pair acquisition and release:"\r
-{ $subsection with-semaphore }\r
-{ $subsection with-semaphore-timeout } ;\r
+{ $subsections\r
+ with-semaphore\r
+ with-semaphore-timeout\r
+} ;\r
\r
ABOUT: "concurrency.semaphores"\r
"CGSize"
}
"Some words for working with the above:"
-{ $subsection <CGRect> }
-{ $subsection <CGPoint> }
-{ $subsection <CGSize> } ;
+{ $subsections
+ <CGRect>
+ <CGPoint>
+ <CGSize>
+} ;
IN: core-graphics.types
ABOUT: "core-graphics.types"
ARTICLE: "csv" "Comma-separated-values parsing and writing"
"The " { $vocab-link "csv" } " vocabulary can read and write CSV (comma-separated-value) files." $nl
"Reading a csv file:"
-{ $subsection file>csv }
+{ $subsections file>csv }
"Writing a csv file:"
-{ $subsection csv>file }
+{ $subsections csv>file }
"Changing the delimiter from a comma:"
-{ $subsection with-delimiter }
+{ $subsections with-delimiter }
"Reading from a stream:"
-{ $subsection csv }
+{ $subsections csv }
"Writing to a stream:"
-{ $subsection write-csv } ;
+{ $subsections write-csv } ;
ABOUT: "csv"
HELP: result-set
{ $description "An object encapsulating a raw SQL result object. There are two ways in which a result set can be accessed, but they are specific to the database backend in use."
- { $subsection "db-random-access-result-set" }
- { $subsection "db-sequential-result-set" }
+{ $subsections
+ "db-random-access-result-set"
+ "db-sequential-result-set"
+}
} ;
HELP: new-result-set
ARTICLE: "db" "Database library"
"Accessing a database:"
-{ $subsection "db-custom-database-combinators" }
+{ $subsections "db-custom-database-combinators" }
"Higher-level database help:"
{ $vocab-subsection "Database types" "db.types" }
{ $vocab-subsection "High-level tuple/database integration" "db.tuples" }
"Low-level database help:"
-{ $subsection "db-protocol" }
-{ $subsection "db-result-sets" }
-{ $subsection "db-lowlevel-tutorial" }
+{ $subsections
+ "db-protocol"
+ "db-result-sets"
+ "db-lowlevel-tutorial"
+}
"Supported database backends:"
{ $vocab-subsection "SQLite" "db.sqlite" }
{ $vocab-subsection "PostgreSQL" "db.postgresql" } ;
"Random-access result sets do not have to be traversed in order. For instance, PostgreSQL's result set object can be accessed as a matrix with i,j coordinates."
$nl
"Databases which work in this way must provide methods for the following traversal words:"
-{ $subsection #rows }
-{ $subsection #columns }
-{ $subsection row-column }
-{ $subsection row-column-typed } ;
+{ $subsections
+ #rows
+ #columns
+ row-column
+ row-column-typed
+} ;
ARTICLE: "db-sequential-result-set" "Sequential result sets"
"Sequential result sets can be iterated one element after the next. SQLite's result sets offer this method of traversal."
$nl
"Databases which work in this way must provide methods for the following traversal words:"
-{ $subsection more-rows? }
-{ $subsection advance-row }
-{ $subsection row-column }
-{ $subsection row-column-typed } ;
+{ $subsections
+ more-rows?
+ advance-row
+ row-column
+ row-column-typed
+} ;
ARTICLE: "db-result-sets" "Result sets"
"Result sets are the encapsulated, database-specific results from a SQL query."
$nl
"Two possible protocols for iterating over result sets exist:"
-{ $subsection "db-random-access-result-set" }
-{ $subsection "db-sequential-result-set" }
+{ $subsections
+ "db-random-access-result-set"
+ "db-sequential-result-set"
+}
"Query the number of rows or columns:"
-{ $subsection #rows }
-{ $subsection #columns }
+{ $subsections
+ #rows
+ #columns
+}
"Traversing a result set:"
-{ $subsection advance-row }
-{ $subsection more-rows? }
+{ $subsections
+ advance-row
+ more-rows?
+}
"Pulling out a single row of results:"
-{ $subsection row-column }
-{ $subsection row-column-typed } ;
+{ $subsections
+ row-column
+ row-column-typed
+} ;
ARTICLE: "db-protocol" "Low-level database protocol"
"The high-level protocol (see " { $vocab-link "db.tuples" } ") uses this low-level protocol for executing statements and queries." $nl
"Opening a database:"
-{ $subsection db-open }
+{ $subsections db-open }
"Closing a database:"
-{ $subsection db-close }
+{ $subsections db-close }
"Creating statements:"
-{ $subsection <simple-statement> }
-{ $subsection <prepared-statement> }
+{ $subsections
+ <simple-statement>
+ <prepared-statement>
+}
"Using statements with the database:"
-{ $subsection prepare-statement }
-{ $subsection bind-statement* }
-{ $subsection low-level-bind }
+{ $subsections
+ prepare-statement
+ bind-statement*
+ low-level-bind
+}
"Performing a query:"
-{ $subsection query-results }
+{ $subsections query-results }
"Handling query results:"
-{ $subsection "db-result-sets" }
+{ $subsections "db-result-sets" }
;
! { $subsection bind-tuple }
ARTICLE: "db-lowlevel-tutorial" "Low-level database tutorial"
"Although Factor makes integrating a database with its object system easy (see " { $vocab-link "db.tuples" } "), sometimes you may want to write SQL directly and get the results back as arrays of strings, for instance, when interfacing with a legacy database that doesn't easily map to " { $snippet "tuples" } "." $nl
"Executing a SQL command:"
-{ $subsection sql-command }
+{ $subsections sql-command }
"Executing a query directly:"
-{ $subsection sql-query }
+{ $subsections sql-query }
"Here's an example usage where we'll make a book table, insert some objects, and query them." $nl
"First, let's set up a custom combinator for using our database. See " { $link "db-custom-database-combinators" } " for more details."
{ $code """
ARTICLE: "db-tuples" "High-level tuple/database integration"
"Start with a tutorial:"
-{ $subsection "db-tuples-tutorial" }
+{ $subsections "db-tuples-tutorial" }
"Database types supported:"
-{ $subsection "db.types" }
+{ $subsections "db.types" }
"Useful words:"
-{ $subsection "db-tuples-words" }
+{ $subsections "db-tuples-words" }
"For porting db.tuples to other databases:"
-{ $subsection "db-tuples-protocol" }
+{ $subsections "db-tuples-protocol" }
;
ARTICLE: "db-tuples-words" "High-level tuple/database words"
"Making tuples work with a database:"
-{ $subsection define-persistent }
+{ $subsections define-persistent }
"Creating tables:"
-{ $subsection create-table }
-{ $subsection ensure-table }
-{ $subsection ensure-tables }
-{ $subsection recreate-table }
+{ $subsections
+ create-table
+ ensure-table
+ ensure-tables
+ recreate-table
+}
"Dropping tables:"
-{ $subsection drop-table }
+{ $subsections drop-table }
"Inserting a tuple:"
-{ $subsection insert-tuple }
+{ $subsections insert-tuple }
"Updating a tuple:"
-{ $subsection update-tuple }
+{ $subsections update-tuple }
"Deleting tuples:"
-{ $subsection delete-tuples }
+{ $subsections delete-tuples }
"Querying tuples:"
-{ $subsection select-tuple }
-{ $subsection select-tuples }
-{ $subsection count-tuples } ;
+{ $subsections
+ select-tuple
+ select-tuples
+ count-tuples
+} ;
ARTICLE: "db-tuples-protocol" "Tuple database protocol"
"Creating a table:"
-{ $subsection create-sql-statement }
+{ $subsections create-sql-statement }
"Dropping a table:"
-{ $subsection drop-sql-statement }
+{ $subsections drop-sql-statement }
"Inserting a tuple:"
-{ $subsection <insert-db-assigned-statement> }
-{ $subsection <insert-user-assigned-statement> }
+{ $subsections
+ <insert-db-assigned-statement>
+ <insert-user-assigned-statement>
+}
"Updating a tuple:"
-{ $subsection <update-tuple-statement> }
+{ $subsections <update-tuple-statement> }
"Deleting tuples:"
-{ $subsection <delete-tuples-statement> }
+{ $subsections <delete-tuples-statement> }
"Selecting tuples:"
-{ $subsection <select-by-slots-statement> }
+{ $subsections <select-by-slots-statement> }
"Counting tuples:"
-{ $subsection <count-statement> } ;
+{ $subsections <count-statement> } ;
ARTICLE: "db-tuples-tutorial" "Tuple database tutorial"
"Let's make a tuple and store it in a database. To follow along, click on each code example and run it in the listener. If you forget to run an example, just start at the top and run them all again in order." $nl
ARTICLE: "db.types" "Database types"
"The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types." $nl
"Primary keys:"
-{ $subsection +db-assigned-id+ }
-{ $subsection +user-assigned-id+ }
-{ $subsection +random-id+ }
+{ $subsections
+ +db-assigned-id+
+ +user-assigned-id+
+ +random-id+
+}
"Null and boolean types:"
-{ $subsection NULL }
-{ $subsection BOOLEAN }
+{ $subsections
+ NULL
+ BOOLEAN
+}
"Text types:"
-{ $subsection VARCHAR }
-{ $subsection TEXT }
+{ $subsections
+ VARCHAR
+ TEXT
+}
"Number types:"
-{ $subsection INTEGER }
-{ $subsection BIG-INTEGER }
-{ $subsection SIGNED-BIG-INTEGER }
-{ $subsection UNSIGNED-BIG-INTEGER }
-{ $subsection DOUBLE }
-{ $subsection REAL }
+{ $subsections
+ INTEGER
+ BIG-INTEGER
+ SIGNED-BIG-INTEGER
+ UNSIGNED-BIG-INTEGER
+ DOUBLE
+ REAL
+}
"Calendar types:"
-{ $subsection DATE }
-{ $subsection DATETIME }
-{ $subsection TIME }
-{ $subsection TIMESTAMP }
+{ $subsections
+ DATE
+ DATETIME
+ TIME
+ TIMESTAMP
+}
"Factor byte-arrays:"
-{ $subsection BLOB }
+{ $subsections BLOB }
"Arbitrary Factor objects:"
-{ $subsection FACTOR-BLOB }
+{ $subsections FACTOR-BLOB }
"Factor URLs:"
-{ $subsection URL } ;
+{ $subsections URL } ;
ABOUT: "db.types"
ARTICLE: "debugger" "The debugger"
"Caught errors can be logged in human-readable form:"
-{ $subsection print-error }
-{ $subsection try }
+{ $subsections
+ print-error
+ try
+}
"User-defined errors can have customized printed representation by implementing a generic word:"
-{ $subsection error. }
+{ $subsections error. }
"A number of words facilitate interactive debugging of errors:"
-{ $subsection :error }
-{ $subsection :s }
-{ $subsection :r }
-{ $subsection :c }
-{ $subsection :get }
+{ $subsections
+ :error
+ :s
+ :r
+ :c
+ :get
+}
"Most types of errors are documented, and the documentation is instantly accessible:"
-{ $subsection :help }
+{ $subsections :help }
"If the error was restartable, a list of restarts is also printed, and a numbered restart can be invoked:"
-{ $subsection :1 }
-{ $subsection :2 }
-{ $subsection :3 }
-{ $subsection :res }
+{ $subsections
+ :1
+ :2
+ :3
+ :res
+}
"You can read more about error handling in " { $link "errors" } "."
$nl
"Note that in Factor, the debugger is a tool for printing and inspecting errors, not for walking through code. For the latter, see " { $link "ui-walker" } "." ;
"The " { $vocab-link "definitions.icons" } " vocabulary associates common definition types with icons."
{ $definition-icons }
"Looking up the icon associated with a definition:"
-{ $subsection definition-icon }
+{ $subsections definition-icon }
"Defining new icons:"
-{ $subsection POSTPONE: ICON: } ;
+{ $subsections POSTPONE: ICON: } ;
ABOUT: "definitions.icons"
\ No newline at end of file
"Unlike " { $link "tuple-subclassing" } ", which expresses " { $emphasis "is-a" } " relationships by statically including the methods and slots of the superclass in all subclasses, consultation forwards generic word calls to another distinct object."
$nl
"Defining new protocols:"
-{ $subsection POSTPONE: PROTOCOL: }
-{ $subsection define-protocol }
+{ $subsections
+ POSTPONE: PROTOCOL:
+ define-protocol
+}
"Defining new protocols consisting of slot accessors:"
-{ $subsection POSTPONE: SLOT-PROTOCOL: }
+{ $subsections POSTPONE: SLOT-PROTOCOL: }
"Defining consultation:"
-{ $subsection POSTPONE: CONSULT: }
-{ $subsection define-consult }
+{ $subsections
+ POSTPONE: CONSULT:
+ define-consult
+}
"Every tuple class has an associated protocol consisting of all of its slot accessor methods. The " { $vocab-link "delegate.protocols" } " vocabulary defines formal protocols for the various informal protocols used in the Factor core, such as " { $link "sequence-protocol" } ", " { $link "assocs-protocol" } " or " { $link "stream-protocol" } ;
ABOUT: "delegate"
"The " { $vocab-link "deques" } " vocabulary implements the deque data structure which has constant-time insertion and removal of elements at both ends."
$nl
"Deques must be instances of a mixin class:"
-{ $subsection deque }
+{ $subsections deque }
"Deques must implement a protocol."
$nl
"Querying the deque:"
-{ $subsection peek-front }
-{ $subsection peek-back }
-{ $subsection deque-empty? }
-{ $subsection deque-member? }
+{ $subsections
+ peek-front
+ peek-back
+ deque-empty?
+ deque-member?
+}
"Adding and removing elements:"
-{ $subsection push-front* }
-{ $subsection push-back* }
-{ $subsection pop-front* }
-{ $subsection pop-back* }
-{ $subsection clear-deque }
+{ $subsections
+ push-front*
+ push-back*
+ pop-front*
+ pop-back*
+ clear-deque
+}
"Working with node objects output by " { $link push-front* } " and " { $link push-back* } ":"
-{ $subsection delete-node }
-{ $subsection node-value }
+{ $subsections
+ delete-node
+ node-value
+}
"Utility operations built in terms of the above:"
-{ $subsection push-front }
-{ $subsection push-all-front }
-{ $subsection push-back }
-{ $subsection push-all-back }
-{ $subsection pop-front }
-{ $subsection pop-back }
-{ $subsection slurp-deque }
+{ $subsections
+ push-front
+ push-all-front
+ push-back
+ push-all-back
+ pop-front
+ pop-back
+ slurp-deque
+}
"When using a deque as a queue, the convention is to queue elements with " { $link push-front } " and deque them with " { $link pop-back } "." ;
ABOUT: "deques"
"The two main supported operations are equating two elements, which joins their equivalence classes, and checking if two elements belong to the same equivalence class. Both operations have the time complexity of the inverse Ackermann function, which for all intents and purposes is constant time."
$nl
"The class of disjoint sets:"
-{ $subsection disjoint-set }
+{ $subsections disjoint-set }
"Creating new disjoint sets:"
-{ $subsection <disjoint-set> }
-{ $subsection assoc>disjoint-set }
+{ $subsections
+ <disjoint-set>
+ assoc>disjoint-set
+}
"Queries:"
-{ $subsection equiv? }
-{ $subsection equiv-set-size }
+{ $subsections
+ equiv?
+ equiv-set-size
+}
"Adding elements:"
-{ $subsection add-atom }
+{ $subsections add-atom }
"Equating elements:"
-{ $subsection equate }
+{ $subsections equate }
"Additionally, disjoint sets implement the " { $link clone } " generic word." ;
ABOUT: "disjoint-sets"
"A double-linked list is the canonical implementation of a " { $link deque } "."
$nl
"Double-linked lists form a class:"
-{ $subsection dlist }
-{ $subsection dlist? }
+{ $subsections
+ dlist
+ dlist?
+}
"Constructing a double-linked list:"
-{ $subsection <dlist> }
+{ $subsection
s <dlist> }
"Double-linked lists support all the operations of the deque protocol (" { $link "deques" } ") as well as the following."
$nl
"Iterating over elements:"
-{ $subsection dlist-each }
-{ $subsection dlist-find }
-{ $subsection dlist-filter }
-{ $subsection dlist-any? }
+{ $subsections
+ dlist-each
+ dlist-find
+ dlist-filter
+ dlist-any?
+}
"Deleting a node matching a predicate:"
-{ $subsection delete-node-if* }
-{ $subsection delete-node-if }
+{ $subsections
+ delete-node-if*
+ delete-node-if
+}
"Search deque implementation:"
-{ $subsection <hashed-dlist> } ;
+{ $subsections <hashed-dlist> } ;
ABOUT: "dlists"
ARTICLE: "documents" "Documents"
"The " { $vocab-link "documents" } " vocabulary implements " { $emphasis "documents" } ", which are models storing a passage of text as a sequence of lines. Operations are defined for operating on subranges of the text, and " { $link "ui.gadgets.editors" } " can display these models."
-{ $subsection document }
-{ $subsection <document> }
+{ $subsections
+ document
+ <document>
+}
"Getting and setting the contents of the entire document:"
-{ $subsection doc-string }
-{ $subsection set-doc-string }
-{ $subsection clear-doc }
+{ $subsections
+ doc-string
+ set-doc-string
+ clear-doc
+}
"Getting and setting subranges:"
-{ $subsection doc-line }
-{ $subsection doc-lines }
-{ $subsection doc-range }
-{ $subsection set-doc-range }
-{ $subsection remove-doc-range }
+{ $subsections
+ doc-line
+ doc-lines
+ doc-range
+ set-doc-range
+ remove-doc-range
+}
"A combinator:"
-{ $subsection each-line }
-{ $subsection "document-locs" }
-{ $subsection "documents.elements" }
+{ $subsections each-line }
+"More info:"
+{ $subsections
+ "document-locs"
+ "documents.elements"
+}
{ $see-also "ui.gadgets.editors" } ;
ARTICLE: "document-locs" "Document locations"
"Locations in the document are represented as a line/column number pair, with both indices being zero-based. There are some words for manipulating locations:"
-{ $subsection +col }
-{ $subsection +line }
-{ $subsection =col }
-{ $subsection =line }
+{ $subsections
+ +col
+ +line
+ =col
+ =line
+}
"Miscellaneous words for working with locations:"
-{ $subsection lines-equal? }
-{ $subsection validate-loc } ;
+{ $subsections
+ lines-equal?
+ validate-loc
+} ;
ABOUT: "documents"
"Document elements, defined in the " { $vocab-link "documents.elements" } " vocabulary, overlay a hierarchy of structure on top of the flat sequence of characters presented by the document."
$nl
"The different types of document elements correspond to the standard editing taxonomy:"
-{ $subsection char-elt }
-{ $subsection one-word-elt }
-{ $subsection word-elt }
-{ $subsection one-line-elt }
-{ $subsection line-elt }
-{ $subsection doc-elt }
+{ $subsections
+ char-elt
+ one-word-elt
+ word-elt
+ one-line-elt
+ line-elt
+ doc-elt
+}
"New locations can be created out of existing ones by finding the start or end of a document element nearest to a given location."
-{ $subsection prev-elt }
-{ $subsection next-elt } ;
+{ $subsections
+ prev-elt
+ next-elt
+} ;
ABOUT: "documents.elements"
\ No newline at end of file
ARTICLE: "editor" "Editor integration"
"Factor development is best done with one of the supported editors; this allows you to quickly jump to definitions from the Factor environment."
-{ $subsection edit }
+{ $subsections edit }
"Depending on the editor you are using, you must load one of the child vocabularies of the " { $vocab-link "editors" } " vocabulary, for example " { $vocab-link "editors.emacs" } ":"
{ $code "USE: editors.emacs" }
"If you intend to always use the same editor, it helps to have it load during stage 2 bootstrap. Place the code to load and possibly configure it in the " { $link "factor-boot-rc" } "."
$nl
"Editor integration vocabularies store a quotation in a global variable when loaded:"
-{ $subsection edit-hook }
+{ $subsections edit-hook }
"If a syntax error was thrown while loading a source file, you can jump to the location of the error in your editor:"
-{ $subsection :edit } ;
+{ $subsections :edit } ;
ABOUT: "editor"
"The " { $vocab-link "environment" } " vocabulary interfaces to the platform-dependent mechanism for setting environment variables." $nl
"Windows CE has no concept of environment variables, so these words are undefined on that platform." $nl
"Reading environment variables:"
-{ $subsection os-env }
-{ $subsection os-envs }
+{ $subsections
+ os-env
+ os-envs
+}
"Writing environment variables:"
-{ $subsection set-os-env }
-{ $subsection unset-os-env }
-{ $subsection set-os-envs } ;
+{ $subsections
+ set-os-env
+ unset-os-env
+ set-os-envs
+} ;
ABOUT: "environment"
ARTICLE: "eval" "Evaluating strings at runtime"
"The " { $vocab-link "eval" } " vocabulary implements support for evaluating strings at runtime."
-{ $subsection POSTPONE: eval( }
-{ $subsection eval>string } ;
+{ $subsections
+ POSTPONE: eval(
+ eval>string
+} ;
ABOUT: "eval"
ARTICLE: "farkup-ast" "Farkup syntax tree nodes"
"The " { $link parse-farkup } " word outputs a tree of nodes corresponding to the Farkup syntax of the input string. This tree can be programatically traversed and mutated before being passed on to " { $link write-farkup } "."
-{ $subsection heading1 }
-{ $subsection heading2 }
-{ $subsection heading3 }
-{ $subsection heading4 }
-{ $subsection strong }
-{ $subsection emphasis }
-{ $subsection superscript }
-{ $subsection subscript }
-{ $subsection inline-code }
-{ $subsection paragraph }
-{ $subsection list-item }
-{ $subsection unordered-list }
-{ $subsection ordered-list }
-{ $subsection table }
-{ $subsection table-row }
-{ $subsection link }
-{ $subsection image }
-{ $subsection code } ;
+{ $subsections
+ heading1
+ heading2
+ heading3
+ heading4
+ strong
+ emphasis
+ superscript
+ subscript
+ inline-code
+ paragraph
+ list-item
+ unordered-list
+ ordered-list
+ table
+ table-row
+ link
+ image
+ code
+} ;
ARTICLE: "farkup" "Farkup"
"The " { $vocab-link "farkup" } " vocabulary implements Farkup (Factor mARKUP), a simple markup language. Farkup was loosely based on the markup languages employed by MediaWiki and " { $url "http://reddit.com" } "."
$nl
"The main entry points for converting Farkup to HTML:"
-{ $subsection convert-farkup }
-{ $subsection write-farkup }
+{ $subsections
+ convert-farkup
+ write-farkup
+}
"The syntax tree of a piece of Farkup can also be inspected and modified:"
-{ $subsection parse-farkup }
-{ $subsection (write-farkup) }
-{ $subsection "farkup-ast" } ;
+{ $subsections
+ parse-farkup
+ (write-farkup)
+ "farkup-ast"
+} ;
ABOUT: "farkup"
ARTICLE: "fonts" "Fonts"
"The " { $vocab-link "fonts" } " vocabulary implements a data type for fonts that other vocabularies, for example " { $link "ui" } ", can use. A font combines a font name, size, style, and color information into a single object."
-{ $subsection font }
-{ $subsection <font> }
+{ $subsections
+ font
+ <font>
+}
"Modifying fonts:"
-{ $subsection font-with-foreground }
-{ $subsection font-with-background }
+{ $subsections
+ font-with-foreground
+ font-with-background
+}
"Useful constants:"
-{ $subsection monospace-font }
-{ $subsection sans-serif-font }
-{ $subsection serif-font }
+{ $subsections
+ monospace-font
+ sans-serif-font
+ serif-font
+}
"A data type for font metrics. The " { $vocab-link "fonts" } " vocabulary does not provide any means of computing font metrics, it simply defines a common data type that other vocabularies, such as " { $vocab-link "ui.text" } " may use:"
-{ $subsection metrics } ;
+{ $subsections metrics } ;
ABOUT: "fonts"
ARTICLE: "formatting" "Formatted printing"
"The " { $vocab-link "formatting" } " vocabulary is used for formatted printing."
-{ $subsection printf }
-{ $subsection sprintf }
-{ $subsection strftime }
-;
+{ $subsections
+ printf
+ sprintf
+ strftime
+} ;
ABOUT: "formatting"
"The " { $vocab-link "fry" } " vocabulary implements " { $emphasis "fried quotation" } ". Conceptually, fried quotations are quotations with “holes” (more formally, " { $emphasis "fry specifiers" } "), and the holes are filled in when the fried quotation is pushed on the stack."\r
$nl\r
"Fried quotations are started by a special parsing word:"\r
-{ $subsection POSTPONE: '[ }\r
+{ $subsections POSTPONE: '[ }\r
"There are two types of fry specifiers; the first can hold a value, and the second “splices” a quotation, as if it were inserted without surrounding brackets:"\r
-{ $subsection _ }\r
-{ $subsection @ }\r
+{ $subsections\r
+ _\r
+ @\r
+}\r
"The holes are filled in with the top of stack going in the rightmost hole, the second item on the stack going in the second hole from the right, and so on."\r
-{ $subsection "fry.examples" }\r
-{ $subsection "fry.philosophy" }\r
+{ $subsections\r
+ "fry.examples"\r
+ "fry.philosophy"\r
+}\r
"Fry is implemented as a parsing word which reads a quotation and scans for occurrences of " { $link _ } " and " { $link @ } "; these words are not actually executed, and doing so raises an error (this can happen if they're accidentally used outside of a fry)."\r
$nl\r
"Fried quotations can also be constructed without using a parsing word; this is useful when meta-programming:"\r
-{ $subsection fry }\r
+{ $subsections fry }\r
"Fried quotations are an abstraction on top of the " { $link "compositional-combinators" } "; their use is encouraged over the combinators, because often the fry form is shorter and clearer than the combinator form." ;\r
\r
ABOUT: "fry"\r
ARTICLE: "furnace.actions.page" "Furnace page actions"
"Page actions implement the common case of an action that simply serves a Chloe template in response to a GET request."
-{ $subsection page-action }
-{ $subsection <page-action> }
+{ $subsections
+ page-action
+ <page-action>
+}
"When using a page action, instead of setting the " { $slot "display" } " slot, the " { $slot "template" } " slot is set instead. The " { $slot "init" } ", " { $slot "authorize" } ", " { $slot "validate" } " and " { $slot "submit" } " slots can still be set as usual."
$nl
"The " { $slot "template" } " slot of a " { $link page-action } " contains a pair with shape " { $snippet "{ responder name }" } ", where " { $snippet "responder" } " is a responder class, usually a subclass of " { $link dispatcher } ", and " { $snippet "name" } " is the name of a template file, without the " { $snippet ".xml" } " extension, relative to the directory containing the responder's vocabulary source file."
-{ $subsection "furnace.actions.page.example" } ;
+{ $subsections "furnace.actions.page.example" } ;
ARTICLE: "furnace.actions.config" "Furnace action configuration"
"Actions have the following slots:"
"The action code is set up so that the " { $slot "init" } " quotation can validate query parameters, and the " { $slot "validate" } " quotation can validate POST parameters."
$nl
"A word to validate parameters and make them available as HTML form values (see " { $link "html.forms.values" } "); typically this word is invoked from the " { $slot "init" } " and " { $slot "validate" } " quotations:"
-{ $subsection validate-params }
+{ $subsections validate-params }
"The above word expects an association list mapping parameter names to validator quotations; validator quotations can use the words in the "
"Custom validation logic can invoke a word when validation fails; " { $link validate-params } " invokes this word for you:"
-{ $subsection validation-failed }
+{ $subsections validation-failed }
"If validation fails, no more action code is executed, and the client is redirected back to the originating page, where validation errors can be displayed. Note that validation errors are rendered automatically by the " { $link "html.components" } " words, and in particular, " { $link "html.templates.chloe" } " use these words." ;
ARTICLE: "furnace.actions.lifecycle" "Furnace action lifecycle"
ARTICLE: "furnace.actions.impl" "Furnace actions implementation"
"The following parametrized constructor should be called from constructors for subclasses of " { $link action } ":"
-{ $subsection new-action } ;
+{ $subsections new-action } ;
ARTICLE: "furnace.actions" "Furnace actions"
"The " { $vocab-link "furnace.actions" } " vocabulary implements a type of responder, called an " { $emphasis "action" } ", which handles the form validation lifecycle."
"Other than form validation capability, actions are also often simpler to use than implementing new responders directly, since creating a new class is not required, and the action dispatches on the request type (GET, HEAD, or POST)."
$nl
"The class of actions:"
-{ $subsection action }
+{ $subsections action }
"Creating a new action:"
-{ $subsection <action> }
+{ $subsection
s <action> }
"Once created, an action needs to be configured; typically the creation and configuration of an action is encapsulated into a single word:"
-{ $subsection "furnace.actions.config" }
+{ $subsections "furnace.actions.config" }
"Validating forms with actions:"
-{ $subsection "furnace.actions.validation" }
+{ $subsections "furnace.actions.validation" }
"More about the form validation lifecycle:"
-{ $subsection "furnace.actions.lifecycle" }
+{ $subsections "furnace.actions.lifecycle" }
"A convenience class:"
-{ $subsection "furnace.actions.page" }
+{ $subsections "furnace.actions.page" }
"Low-level features:"
-{ $subsection "furnace.actions.impl" } ;
+{ $subsections "furnace.actions.impl" } ;
ABOUT: "furnace.actions"
{ $link "furnace.db" }
}
"A word to wrap a responder in an alloy:"
-{ $subsection <alloy> }
+{ $subsection
s <alloy> }
"Initializing database tables for asides, conversations and sessions:"
-{ $subsection init-furnace-tables }
+{ $subsections init-furnace-tables }
"Start a timer to expire asides, conversations and sessions:"
-{ $subsection start-expiring } ;
+{ $subsections start-expiring } ;
ABOUT: "furnace.alloy"
"The " { $vocab-link "furnace.asides" } " vocabulary provides support for sending a user to a page which can then return to the former location."
$nl
"To use asides, wrap your responder in an aside responder:"
-{ $subsection <asides> }
+{ $subsection
s <asides> }
"The asides responder must be wrapped inside a session responder (" { $link <sessions> } "), which in turn must be wrapped inside a database persistence responder (" { $link <db-persistence> } "). The " { $vocab-link "furnace.alloy" } " vocabulary combines all of these responders into one."
$nl
"Saving the current page in an aside which propagates through " { $link <redirect> } " responses:"
-{ $subsection begin-aside }
+{ $subsections begin-aside }
"Returning from an aside:"
-{ $subsection end-aside }
+{ $subsections end-aside }
"Asides are used by " { $vocab-link "furnace.auth.login" } "; when the client requests a protected page, an aside begins and the client is redirected to a login page. Upon a successful login, the aside ends and the client returns to the protected page. If the client directly visits the login page and logs in, there is no current aside, so the client is sent to the default URL passed to " { $link end-aside } ", which in the case of login is the root URL." ;
ABOUT: "furnace.asides"
"Every user in the authentication framework has a set of associated capabilities."
$nl
"Defining new capabilities:"
-{ $subsection define-capability }
+{ $subsections define-capability }
"Capabilities are stored in a global variable:"
-{ $subsection capabilities }
+{ $subsections capabilities }
"Protected resources can be restricted to users possessing certain capabilities only by storing a sequence of capabilities in the " { $slot "capabilities" } " slot of a " { $link protected } " instance." ;
ARTICLE: "furnace.auth.protected" "Protected resources"
"To restrict access to authenticated clients only, wrap a responder in a protected responder."
-{ $subsection protected }
-{ $subsection <protected> }
+{ $subsections
+ protected
+ <protected>
+}
"Protected responders have the following two slots which may be set:"
{ $table
{ { $slot "description" } "A string identifying the protected resource for user interface purposes" }
"The " { $vocab-link "furnace.auth" } " framework looks up users using an authentication provider. Different authentication providers can be swapped in to implement various authentication strategies."
$nl
"Each authentication realm has a provider stored in the " { $slot "users" } " slot. The default provider is " { $link users-in-db } "."
-{ $subsection "furnace.auth.providers.protocol" }
-{ $subsection "furnace.auth.providers.null" }
-{ $subsection "furnace.auth.providers.assoc" }
-{ $subsection "furnace.auth.providers.db" } ;
+{ $subsections
+ "furnace.auth.providers.protocol"
+ "furnace.auth.providers.null"
+ "furnace.auth.providers.assoc"
+ "furnace.auth.providers.db"
+} ;
ARTICLE: "furnace.auth.features" "Optional authentication features"
"Vocabularies having names prefixed by " { $code "furnace.auth.features" } " implement optional features which can be enabled by calling special words. These words define new actions on an authentication realm."
-{ $subsection "furnace.auth.features.deactivate-user" }
-{ $subsection "furnace.auth.features.edit-profile" }
-{ $subsection "furnace.auth.features.recover-password" }
-{ $subsection "furnace.auth.features.registration" } ;
+{ $subsections
+ "furnace.auth.features.deactivate-user"
+ "furnace.auth.features.edit-profile"
+ "furnace.auth.features.recover-password"
+ "furnace.auth.features.registration"
+} ;
ARTICLE: "furnace.auth.realms" "Authentication realms"
"The superclass of authentication realms:"
-{ $subsection realm }
+{ $subsections realm }
"There are two concrete implementations:"
-{ $subsection "furnace.auth.basic" }
-{ $subsection "furnace.auth.login" }
+{ $subsections
+ "furnace.auth.basic"
+ "furnace.auth.login"
+}
"Authentication realms need to be configured after construction."
-{ $subsection "furnace.auth.realm-config" } ;
+{ $subsections "furnace.auth.realm-config" } ;
ARTICLE: "furnace.auth.users" "User profiles"
"A responder wrapped in an authentication realm may access the currently logged-in user,"
-{ $subsection logged-in-user }
+{ $subsections logged-in-user }
"as well as the logged-in username:"
-{ $subsection username }
+{ $subsections username }
"Values can also be stored in user profile variables:"
-{ $subsection uget }
-{ $subsection uset }
-{ $subsection uchange }
+{ $subsections
+ uget
+ uset
+ uchange
+}
"User profile variables have the same restrictions on their values as session variables; see " { $link "furnace.sessions.serialize" } " for a discussion." ;
ARTICLE: "furnace.auth.example" "Furnace authentication example"
"The " { $vocab-link "furnace.auth" } " vocabulary implements a pluggable authentication framework."
$nl
"Usernames and passwords are verified using an " { $emphasis "authentication provider" } "."
-{ $subsection "furnace.auth.providers" }
+{ $subsections "furnace.auth.providers" }
"Users have capabilities assigned to them."
-{ $subsection "furnace.auth.capabilities" }
+{ $subsections "furnace.auth.capabilities" }
"An " { $emphasis "authentication realm" } " is a responder which manages access to protected resources."
-{ $subsection "furnace.auth.realms" }
+{ $subsections "furnace.auth.realms" }
"Actions contained inside an authentication realm can be protected by wrapping them with a responder."
-{ $subsection "furnace.auth.protected" }
+{ $subsections "furnace.auth.protected" }
"Actions contained inside an authentication realm can access the currently logged-in user profile."
-{ $subsection "furnace.auth.users" }
+{ $subsections "furnace.auth.users" }
"Authentication realms can be adorned with additional functionality."
-{ $subsection "furnace.auth.features" }
+{ $subsections "furnace.auth.features" }
"An administration tool."
-{ $subsection "furnace.auth.user-admin" }
+{ $subsections "furnace.auth.user-admin" }
"A concrete example."
-{ $subsection "furnace.auth.example" } ;
+{ $subsections "furnace.auth.example" } ;
ABOUT: "furnace.auth"
ARTICLE: "furnace.auth.basic" "Basic authentication"
"The " { $vocab-link "furnace.auth.basic" } " vocabulary implements HTTP basic authentication."
-{ $subsection basic-auth-realm }
-{ $subsection <basic-auth-realm> } ;
+{ $subsections
+ basic-auth-realm
+ <basic-auth-realm>
+} ;
ABOUT: "furnace.auth.basic"
"The " { $vocab-link "furnace.auth.features.deactivate-user" } " vocabulary implements an authentication feature for user profile deactivation, allowing users to voluntarily deactivate their account."
$nl
"To enable this feature, call the following word on an authentication realm:"
-{ $subsection allow-deactivation }
+{ $subsections allow-deactivation }
"To check if deactivation is enabled:"
-{ $subsection allow-deactivation? }
+{ $subsections allow-deactivation? }
"This feature adds a " { $snippet "deactivate-user" } " action to the realm, and a link to this action can be inserted in Chloe templates using the following XML snippet:"
{ $code
"<t:if t:code=\"furnace.auth.features.deactivate-user:allow-deactivation?\">"
"The " { $vocab-link "furnace.auth.features.edit-profile" } " vocabulary implements an authentication feature for user profile editing, allowing users to change some details of their account."
$nl
"To enable this feature, call the following word on an authentication realm:"
-{ $subsection allow-edit-profile }
+{ $subsections allow-edit-profile }
"To check if profile editing is enabled:"
-{ $subsection allow-edit-profile? }
+{ $subsections allow-edit-profile? }
"This feature adds an " { $snippet "edit-profile" } " action to the realm, and a link to this action can be inserted in Chloe templates using the following XML snippet:"
{ $code
"<t:if t:code=\"furnace.auth.features.edit-profile:allow-edit-profile?\">"
" vocabulary implements an authentication feature for user password recovery, allowing users to get a new password e-mailed to them in the event they forget their current one."
$nl
"To enable this feature, first call the following word on an authentication realm,"
-{ $subsection allow-password-recovery }
+{ $subsections allow-password-recovery }
"Then set a global configuration variable:"
-{ $subsection lost-password-from }
+{ $subsections lost-password-from }
"In addition, the " { $link "smtp" } " may need to be configured as well."
$nl
"To check if password recovery is enabled:"
-{ $subsection allow-password-recovery? }
+{ $subsections allow-password-recovery? }
"This feature adds a " { $snippet "recover-password" } " action to the realm, and a link to this action can be inserted in Chloe templates using the following XML snippet:"
{ $code
"<t:if t:code=\"furnace.auth.features.recover-password:allow-password-recovery?\">"
"The " { $vocab-link "furnace.auth.features.registration" } " vocabulary implements an authentication feature for user registration, allowing new users to create accounts."
$nl
"To enable this feature, call the following word on an authentication realm:"
-{ $subsection allow-registration }
+{ $subsections allow-registration }
"To check if user registration is enabled:"
-{ $subsection allow-registration? }
+{ $subsections allow-registration? }
"This feature adds a " { $snippet "register" } " action to the realm. A link to this action is inserted on the login page if the " { $vocab-link "furnace.auth.login" } " authentication realm is used. Links to this action can be inserted from other pages using the following Chloe XML snippet:"
{ $code
"<t:if t:code=\"furnace.auth.features.registration:allow-registration?\">"
ARTICLE: "furnace.auth.login" "Login authentication"
"The " { $vocab-link "furnace.auth.login" } " vocabulary implements an authentication realm which displays a login page with a username and password field."
-{ $subsection login-realm }
-{ $subsection <login-realm> }
+{ $subsections
+ login-realm
+ <login-realm>
+}
"The " { $snippet "logout" } " action logs the user out of the realm, and a link to this action can be inserted in Chloe templates using the following XML snippet:"
{ $code
"<t:button t:action=\"$login-realm/logout\">Logout</t:button>"
ARTICLE: "furnace.auth.providers.assoc" "In-memory authentication provider"
"The " { $vocab-link "furnace.auth.providers.assoc" } " vocabulary implements an authentication provider which looks up usernames and passwords in an associative mapping."
-{ $subsection users-in-memory }
-{ $subsection <users-in-memory> }
+{ $subsections
+ users-in-memory
+ <users-in-memory>
+}
"The " { $slot "assoc" } " slot of the " { $link users-in-memory } " tuple maps usernames to checksums of passwords." ;
ABOUT: "furnace.auth.providers.assoc"
"The " { $vocab-link "furnace.auth.providers.db" } " vocabulary implements an authentication provider which looks up authentication requests in the " { $snippet "USERS" } " table of the current database. The database schema is Factor-specific, and the table should be initialized by calling"
{ $code "users create-table" }
"The authentication provider class:"
-{ $subsection users-in-db } ;
+{ $subsections users-in-db } ;
ABOUT: "furnace.auth.providers.db"
"The " { $vocab-link "furnace.auth.providers" } " vocabulary implements a protocol for persistence and authentication of users."
$nl
"The class of users:"
-{ $subsection user }
+{ $subsections user }
"Generic protocol:"
-{ $subsection get-user }
-{ $subsection new-user }
-{ $subsection update-user } ;
+{ $subsections
+ get-user
+ new-user
+ update-user
+} ;
ABOUT: "furnace.auth.providers.protocol"
ARTICLE: "furnace.boilerplate" "Furnace boilerplate support"
"The " { $vocab-link "furnace.boilerplate" } " vocabulary implements a facility for sharing a common header and footer between different pages on a web site. It builds on top of " { $link "html.templates.boilerplate" } "."
-{ $subsection <boilerplate> }
-{ $subsection "furnace.boilerplate.config" }
-{ $subsection "furnace.boilerplate.example" }
+{ $subsections
+ <boilerplate>
+ "furnace.boilerplate.config"
+ "furnace.boilerplate.example"
+}
{ $see-also "html.templates.chloe.tags.boilerplate" } ;
ABOUT: "furnace.boilerplate"
"Conversation scope is used by form validation to pass validation errors between requests."
$nl
"To use conversation scope, wrap your responder in an conversation responder:"
-{ $subsection <conversations> }
+{ $subsections <conversations> }
"The conversations responder must be wrapped inside a session responder (" { $link <sessions> } "), which in turn must be wrapped inside a database persistence responder (" { $link <db-persistence> } "). The " { $vocab-link "furnace.alloy" } " vocabulary combines all of these responders into one."
$nl
"Managing conversation scopes:"
-{ $subsection begin-conversation }
-{ $subsection end-conversation }
-{ $subsection <continue-conversation> }
+{ $subsections
+ begin-conversation
+ end-conversation
+ <continue-conversation>
+}
"Reading and writing conversation variables:"
-{ $subsection cget }
-{ $subsection cset }
-{ $subsection cchange }
+{ $subsections
+ cget
+ cset
+ cchange
+}
"Note that conversation scope is serialized as part of the session, which means that only serializable objects can be stored there. See " { $link "furnace.sessions.serialize" } " for details." ;
ABOUT: "furnace.conversations"
ARTICLE: "furnace.db" "Furnace database support"
"The " { $vocab-link "furnace.db" } " vocabulary implements a responder which maintains a database connection pool and runs each request in a " { $link with-db } " scope."
-{ $subsection <db-persistence> }
+{ $subsections <db-persistence> }
"The " { $vocab-link "furnace.alloy" } " vocabulary combines database persistence with several other features." ;
ABOUT: "furnace.db"
IN: furnace
ARTICLE: "furnace.persistence" "Furnace persistence layer"
-{ $subsection "furnace.db" }
+{ $subsections "furnace.db" }
"Server-side state:"
-{ $subsection "furnace.sessions" }
-{ $subsection "furnace.conversations" }
-{ $subsection "furnace.asides" }
-{ $subsection "furnace.presentation" } ;
+{ $subsections
+ "furnace.sessions"
+ "furnace.conversations"
+ "furnace.asides"
+ "furnace.presentation"
+} ;
ARTICLE: "furnace.presentation" "Furnace presentation layer"
"HTML components:"
-{ $subsection "html.components" }
-{ $subsection "html.forms" }
+{ $subsections
+ "html.components"
+ "html.forms"
+}
"Content templates:"
-{ $subsection "html.templates" }
-{ $subsection "html.templates.chloe" }
-{ $subsection "html.templates.fhtml" }
-{ $subsection "furnace.boilerplate" }
+{ $subsections
+ "html.templates"
+ "html.templates.chloe"
+ "html.templates.fhtml"
+ "furnace.boilerplate"
+}
"Other types of content:"
-{ $subsection "furnace.syndication" }
-{ $subsection "furnace.json" } ;
+{ $subsections
+ "furnace.syndication"
+ "furnace.json"
+} ;
ARTICLE: "furnace.load-balancing" "Load balancing and fail-over with Furnace"
"The Furnace session manager persists sessions to a database. This means that HTTP requests can be transparently distributed between multiple Factor HTTP server instances, running the same web app on top of the same database, as long as the web applications do not use mutable global state, such as global variables. The Furnace framework itself does not use any mutable global state." ;
"Conversation scope and asides for complex page flow"
}
"Major functionality:"
-{ $subsection "furnace.actions" }
-{ $subsection "furnace.alloy" }
-{ $subsection "furnace.persistence" }
-{ $subsection "furnace.presentation" }
-{ $subsection "furnace.auth" }
-{ $subsection "furnace.load-balancing" }
+{ $subsections
+ "furnace.actions"
+ "furnace.alloy"
+ "furnace.persistence"
+ "furnace.presentation"
+ "furnace.auth"
+ "furnace.load-balancing"
+}
"Utilities:"
-{ $subsection "furnace.referrer" }
-{ $subsection "furnace.redirection" }
-{ $subsection "furnace.extension-points" }
-{ $subsection "furnace.misc" }
+{ $subsections
+ "furnace.referrer"
+ "furnace.redirection"
+ "furnace.extension-points"
+ "furnace.misc"
+}
"Related frameworks:"
-{ $subsection "db" }
-{ $subsection "xml" }
-{ $subsection "http.server" }
-{ $subsection "logging" }
-{ $subsection "urls" } ;
+{ $subsections
+ "db"
+ "xml"
+ "http.server"
+ "logging"
+ "urls"
+} ;
ABOUT: "furnace"
ARTICLE: "furnace.json" "Furnace JSON support"
"The " { $vocab-link "furnace.json" } " vocabulary provides a utility word for serving HTTP responses with JSON content."
-{ $subsection <json-content> } ;
+{ $subsections <json-content> } ;
ABOUT: "furnace.json"
"The recaptcha responder is a " { $link filter-responder } " that wraps another responder. Set the " { $slot "domain" } ", " { $slot "public-key" } ", and " { $slot "private-key" } " slots of this responder to your Recaptcha account information." $nl
"Wrapping a responder with Recaptcha:"
-{ $subsection <recaptcha> }
+{ $subsections <recaptcha> }
"Validating recaptcha:"
-{ $subsection validate-recaptcha }
+{ $subsections validate-recaptcha }
"Symbols set after validation:"
-{ $subsection recaptcha-valid? }
-{ $subsection recaptcha-error }
-{ $subsection "recaptcha-example" } ;
+{ $subsections
+ recaptcha-valid?
+ recaptcha-error
+ "recaptcha-example"
+} ;
ABOUT: "furnace.recaptcha"
"The words in this section help with implementing sites which require SSL/TLS for additional security."
$nl
"Converting a HTTP URL into an HTTPS URL:"
-{ $subsection >secure-url }
+{ $subsections >secure-url }
"Redirecting the client to an HTTPS URL:"
-{ $subsection <secure-redirect> }
+{ $subsections <secure-redirect> }
"Tools for writing responders which require SSL/TLS connections:"
-{ $subsection if-secure }
-{ $subsection <secure-only> } ;
+{ $subsections
+ if-secure
+ <secure-only>
+} ;
ARTICLE: "furnace.redirection" "Furnace redirection support"
"The " { $vocab-link "furnace.redirection" } " vocabulary builds additional functionality on top of " { $vocab-link "http.server.redirection" } ", and integrates with various Furnace features such as " { $link "furnace.asides" } " and " { $link "furnace.conversations" } "."
$nl
"A redirection response which takes asides and conversations into account:"
-{ $subsection <redirect> }
+{ $subsections <redirect> }
"A responder which unconditionally redirects the client to another URL:"
-{ $subsection <redirect-responder> }
-{ $subsection "furnace.redirection.secure" } ;
+{ $subsections
+ <redirect-responder>
+ "furnace.redirection.secure"
+} ;
ABOUT: "furnace.redirection"
ARTICLE: "furnace.referrer" "Form submission referrer checking"
"The " { $vocab-link "furnace.referrer" } " implements a simple security measure which can be used to thwart cross-site scripting attacks."
-{ $subsection <check-form-submissions> }
+{ $subsections <check-form-submissions> }
"Explicit referrer checking:"
-{ $subsection referrer }
-{ $subsection same-host? } ;
+{ $subsections
+ referrer
+ same-host?
+} ;
ABOUT: "furnace.referrer"
"The " { $vocab-link "furnace.sessions" } " vocabulary implements session management, which allows state to be maintained between HTTP requests. The session state is stored on the server; the client receives an opaque ID which is saved in a cookie (for GET requests) or a hidden form field (for POST requests)."
$nl
"To use session management, wrap your responder in an session manager:"
-{ $subsection <sessions> }
+{ $subsections <sessions> }
"The sessions responder must be wrapped inside a database persistence responder (" { $link <db-persistence> } "). The " { $vocab-link "furnace.alloy" } " vocabulary combines all of these responders into one."
$nl
"Reading and writing session variables from a request:"
-{ $subsection sget }
-{ $subsection sset }
-{ $subsection schange }
+{ $subsections
+ sget
+ sset
+ schange
+}
"Additional topics:"
-{ $subsection "furnace.sessions.config" }
-{ $subsection "furnace.sessions.serialize" } ;
+{ $subsections
+ "furnace.sessions.config"
+ "furnace.sessions.serialize"
+} ;
ABOUT: "furnace.sessions"
ARTICLE: "furnace.syndication.protocol" "Atom feed entry protocol"
"An Atom feed action takes a sequence of objects and converts them into Atom feed entries. The objects must implement a protocol consisting of either a single generic word:"
-{ $subsection >entry }
+{ $subsections >entry }
"Or a series of generic words, called by the default implementation of " { $link >entry } ":"
-{ $subsection feed-entry-title }
-{ $subsection feed-entry-description }
-{ $subsection feed-entry-date }
-{ $subsection feed-entry-url } ;
+{ $subsections
+ feed-entry-title
+ feed-entry-description
+ feed-entry-date
+ feed-entry-url
+} ;
ARTICLE: "furnace.syndication" "Furnace Atom syndication support"
"The " { $vocab-link "furnace.syndication" } " vocabulary builds on the " { $link "syndication" } " library by providing easy support for generating Atom feeds from " { $link "furnace.actions" } "."
-{ $subsection <feed-action> }
-{ $subsection "furnace.syndication.config" }
-{ $subsection "furnace.syndication.protocol" } ;
+{ $subsections
+ <feed-action>
+ "furnace.syndication.config"
+ "furnace.syndication.protocol"
+} ;
ABOUT: "furnace.syndication"
"Furnace features such as session management, conversation scope and asides need to modify URLs in links and redirects, and insert hidden form fields, to implement state on top of the stateless HTTP protocol. In order to decouple the server-side state management code from the HTML templating code, a series of hooks are used."
$nl
"Responders can implement methods on the following generic words:"
-{ $subsection modify-query }
-{ $subsection modify-redirect-query }
-{ $subsection link-attr }
-{ $subsection modify-form }
+{ $subsections
+ modify-query
+ modify-redirect-query
+ link-attr
+ modify-form
+}
"Presentation-level code can call the following words:"
-{ $subsection adjust-url }
-{ $subsection adjust-redirect-url } ;
+{ $subsections
+ adjust-url
+ adjust-redirect-url
+} ;
ARTICLE: "furnace.misc" "Miscellaneous Furnace features"
"Inspecting the chain of responders handling the current request:"
-{ $subsection nested-responders }
-{ $subsection each-responder }
-{ $subsection resolve-base-path }
+{ $subsections
+ nested-responders
+ each-responder
+ resolve-base-path
+}
"Vocabulary root-relative resources:"
-{ $subsection vocab-path }
-{ $subsection resolve-template-path }
+{ $subsections
+ vocab-path
+ resolve-template-path
+}
"Early return from a responder:"
-{ $subsection with-exit-continuation }
-{ $subsection exit-with }
+{ $subsections
+ with-exit-continuation
+ exit-with
+}
"Other useful words:"
-{ $subsection hidden-form-field }
-{ $subsection client-state }
-{ $subsection user-agent } ;
+{ $subsections
+ hidden-form-field
+ client-state
+ user-agent
+} ;
ARTICLE: "game-input" "Game controller input"
"The " { $vocab-link "game-input" } " vocabulary provides cross-platform access to game controller devices such as joysticks and gamepads. It also provides an interface for polling raw keyboard and mouse input." $nl
"The game input interface must be initialized before being used:"
-{ $subsection open-game-input }
-{ $subsection close-game-input }
-{ $subsection with-game-input }
+{ $subsections
+ open-game-input
+ close-game-input
+ with-game-input
+}
"Once the game input interface is open, connected controller devices can be enumerated:"
-{ $subsection get-controllers }
-{ $subsection find-controller-products }
-{ $subsection find-controller-instance }
+{ $subsections
+ get-controllers
+ find-controller-products
+ find-controller-instance
+}
"These " { $link controller } " objects can be queried of their identity:"
-{ $subsection product-string }
-{ $subsection product-id }
-{ $subsection instance-id }
+{ $subsections
+ product-string
+ product-id
+ instance-id
+}
"A hook is provided for invoking the system calibration tool:"
-{ $subsection calibrate-controller }
+{ $subsections calibrate-controller }
"The current state of a controller, the keyboard, and the mouse can be read:"
-{ $subsection read-controller }
-{ $subsection read-keyboard }
-{ $subsection read-mouse }
-{ $subsection controller-state }
-{ $subsection keyboard-state }
-{ $subsection mouse-state } ;
+{ $subsections
+ read-controller
+ read-keyboard
+ read-mouse
+ controller-state
+ keyboard-state
+ mouse-state
+} ;
HELP: open-game-input
{ $description "Initializes the game input interface. An exception will be thrown if the initialization fails. Calls to open-game-input are reference counted; each call to open-game-input needs a corresponding call to close-game-input to close the game input interface." } ;
{ $description "A generalization of " { $link tuck } " that can work for any stack depth. The top item will be copied and placed " { $snippet "n" } " items down on the stack." } ;\r
\r
ARTICLE: "sequence-generalizations" "Generalized sequence operations"\r
-{ $subsection narray }\r
-{ $subsection nsequence }\r
-{ $subsection firstn }\r
-{ $subsection nappend }\r
-{ $subsection nappend-as } ;\r
+{ $subsections\r
+ narray\r
+ nsequence\r
+ firstn\r
+ nappend\r
+ nappend-as\r
+} ;\r
\r
ARTICLE: "shuffle-generalizations" "Generalized shuffle words"\r
-{ $subsection ndup }\r
-{ $subsection npick }\r
-{ $subsection nrot }\r
-{ $subsection -nrot }\r
-{ $subsection nnip }\r
-{ $subsection ndrop }\r
-{ $subsection ntuck }\r
-{ $subsection mnswap }\r
-{ $subsection nweave } ;\r
+{ $subsections\r
+ ndup\r
+ npick\r
+ nrot\r
+ -nrot\r
+ nnip\r
+ ndrop\r
+ ntuck\r
+ mnswap\r
+ nweave\r
+} ;\r
\r
ARTICLE: "combinator-generalizations" "Generalized combinators"\r
-{ $subsection ndip }\r
-{ $subsection nkeep }\r
-{ $subsection napply }\r
-{ $subsection ncleave }\r
-{ $subsection nspread } ;\r
+{ $subsections\r
+ ndip\r
+ nkeep\r
+ napply\r
+ ncleave\r
+ nspread\r
+} ;\r
\r
ARTICLE: "other-generalizations" "Additional generalizations"\r
-{ $subsection ncurry } \r
-{ $subsection nwith }\r
-{ $subsection nsum } ;\r
+{ $subsections\r
+ ncurry\r
+ nwith\r
+ nsum\r
+} ;\r
\r
ARTICLE: "generalizations" "Generalized shuffle words and combinators"\r
"The " { $vocab-link "generalizations" } " vocabulary defines a number of stack shuffling words and combinators for use in "\r
"macros where the arity of the input quotations depends on an "\r
"input parameter."\r
-{ $subsection "sequence-generalizations" }\r
-{ $subsection "shuffle-generalizations" }\r
-{ $subsection "combinator-generalizations" }\r
-{ $subsection "other-generalizations" } ;\r
+{ $subsections\r
+ "sequence-generalizations"\r
+ "shuffle-generalizations"\r
+ "combinator-generalizations"\r
+ "other-generalizations"\r
+} ;\r
\r
ABOUT: "generalizations"\r
ARTICLE: { "hash2" "intro" } "Hash2"
"The hash2 vocabulary specifies a simple minimal datastructure for hash tables with two integers as keys. These hash tables are fixed size and do not conform to the associative mapping protocol. Words used in creating and manipulating these hash tables include:"
-{ $subsection <hash2> }
-{ $subsection hash2 }
-{ $subsection set-hash2 }
-{ $subsection alist>hash2 } ;
+{ $subsections
+ <hash2>
+ hash2
+ set-hash2
+ alist>hash2
+} ;
HELP: <hash2>
{ $values { "size" "size of the underlying array" } { "hash2" hash2 } }
"Heap elements are key/value pairs and are compared using the " { $link <=> } " generic word on the first element of the pair."
$nl
"There are two classes of heaps. Min-heaps sort their elements so that the minimum element is first:"
-{ $subsection min-heap }
-{ $subsection min-heap? }
-{ $subsection <min-heap> }
+{ $subsections
+ min-heap
+ min-heap?
+ <min-heap>
+}
"Max-heaps sort their elements so that the maximum element is first:"
-{ $subsection max-heap }
-{ $subsection max-heap? }
-{ $subsection <max-heap> }
+{ $subsections
+ max-heap
+ max-heap?
+ <max-heap>
+}
"Both obey a protocol."
$nl
"Queries:"
-{ $subsection heap-empty? }
-{ $subsection heap-size }
-{ $subsection heap-peek }
+{ $subsections
+ heap-empty?
+ heap-size
+ heap-peek
+}
"Insertion:"
-{ $subsection heap-push }
-{ $subsection heap-push* }
-{ $subsection heap-push-all }
+{ $subsections
+ heap-push
+ heap-push*
+ heap-push-all
+}
"Removal:"
-{ $subsection heap-pop* }
-{ $subsection heap-pop }
-{ $subsection heap-delete }
+{ $subsections
+ heap-pop*
+ heap-pop
+ heap-delete
+}
"Processing heaps:"
-{ $subsection slurp-heap } ;
+{ $subsections slurp-heap } ;
ABOUT: "heaps"
ARTICLE: "cookbook" "Factor cookbook"
"The Factor cookbook is a high-level overview of the most important concepts required to program in Factor."
-{ $subsection "cookbook-syntax" }
-{ $subsection "cookbook-colon-defs" }
-{ $subsection "cookbook-combinators" }
-{ $subsection "cookbook-variables" }
-{ $subsection "cookbook-vocabs" }
-{ $subsection "cookbook-application" }
-{ $subsection "cookbook-scripts" }
-{ $subsection "cookbook-philosophy" }
-{ $subsection "cookbook-pitfalls" }
-{ $subsection "cookbook-next" } ;
+{ $subsections
+ "cookbook-syntax"
+ "cookbook-colon-defs"
+ "cookbook-combinators"
+ "cookbook-variables"
+ "cookbook-vocabs"
+ "cookbook-application"
+ "cookbook-scripts"
+ "cookbook-philosophy"
+ "cookbook-pitfalls"
+ "cookbook-next"
+} ;
ABOUT: "cookbook"
{ "a " { $link wrapper } " - the wrapped object is pushed on the data stack. Wrappers are used to push word objects directly on the stack when they would otherwise execute. See the " { $link POSTPONE: \ } " parsing word." }
{ "All other types of objects are pushed on the data stack." }
}
-{ $subsection "tail-call-opt" }
+{ $subsections "tail-call-opt" }
{ $see-also "compiler" } ;
ARTICLE: "objects" "Objects"
"An " { $emphasis "object" } " is any datum which may be identified. All values are objects in Factor. Each object carries type information, and types are checked at runtime; Factor is dynamically typed."
-{ $subsection "equality" }
-{ $subsection "math.order" }
-{ $subsection "classes" }
-{ $subsection "tuples" }
-{ $subsection "generic" }
+{ $subsections
+ "equality"
+ "math.order"
+ "classes"
+ "tuples"
+ "generic"
+}
"Advanced features:"
-{ $subsection "delegate" }
-{ $subsection "mirrors" }
-{ $subsection "slots" } ;
+{ $subsections
+ "delegate"
+ "mirrors"
+ "slots"
+} ;
ARTICLE: "numbers" "Numbers"
-{ $subsection "arithmetic" }
-{ $subsection "math-constants" }
-{ $subsection "math-functions" }
-{ $subsection "number-strings" }
+{ $subsections
+ "arithmetic"
+ "math-constants"
+ "math-functions"
+ "number-strings"
+}
"Number implementations:"
-{ $subsection "integers" }
-{ $subsection "rationals" }
-{ $subsection "floats" }
-{ $subsection "complex-numbers" }
+{ $subsections
+ "integers"
+ "rationals"
+ "floats"
+ "complex-numbers"
+}
"Advanced features:"
-{ $subsection "math-vectors" }
-{ $subsection "math-intervals" } ;
+{ $subsections
+ "math-vectors"
+ "math-intervals"
+} ;
USE: io.buffers
ARTICLE: "collections" "Collections"
{ $heading "Sequences" }
-{ $subsection "sequences" }
-{ $subsection "virtual-sequences" }
-{ $subsection "namespaces-make" }
+{ $subsections
+ "sequences"
+ "virtual-sequences"
+ "namespaces-make"
+}
"Fixed-length sequences:"
-{ $subsection "arrays" }
-{ $subsection "quotations" }
-{ $subsection "strings" }
-{ $subsection "byte-arrays" }
-{ $subsection "specialized-arrays" }
+{ $subsections
+ "arrays"
+ "quotations"
+ "strings"
+ "byte-arrays"
+ "specialized-arrays"
+}
"Resizable sequences:"
-{ $subsection "vectors" }
-{ $subsection "byte-vectors" }
-{ $subsection "sbufs" }
-{ $subsection "growable" }
+{ $subsections
+ "vectors"
+ "byte-vectors"
+ "sbufs"
+ "growable"
+}
{ $heading "Associative mappings" }
-{ $subsection "assocs" }
-{ $subsection "linked-assocs" }
-{ $subsection "biassocs" }
-{ $subsection "refs" }
+{ $subsections
+ "assocs"
+ "linked-assocs"
+ "biassocs"
+ "refs"
+}
"Implementations:"
-{ $subsection "hashtables" }
-{ $subsection "alists" }
-{ $subsection "enums" }
+{ $subsections
+ "hashtables"
+ "alists"
+ "enums"
+}
{ $heading "Double-ended queues" }
-{ $subsection "deques" }
+{ $subsections "deques" }
"Implementations:"
-{ $subsection "dlists" }
-{ $subsection "search-deques" }
+{ $subsections
+ "dlists"
+ "search-deques"
+}
{ $heading "Other collections" }
-{ $subsection "lists" }
-{ $subsection "disjoint-sets" }
-{ $subsection "interval-maps" }
-{ $subsection "heaps" }
-{ $subsection "boxes" }
-{ $subsection "graphs" }
-{ $subsection "buffers" }
+{ $subsections
+ "lists"
+ "disjoint-sets"
+ "interval-maps"
+ "heaps"
+ "boxes"
+ "graphs"
+ "buffers"
+}
"There are also many other vocabularies tagged " { $link T{ vocab-tag { name "collections" } } } " in the library." ;
USING: io.encodings.utf8 io.encodings.binary io.files ;
ARTICLE: "io" "Input and output"
{ $heading "Streams" }
-{ $subsection "streams" }
-{ $subsection "io.files" }
+{ $subsections
+ "streams"
+ "io.files"
+}
{ $heading "The file system" }
-{ $subsection "io.pathnames" }
-{ $subsection "io.files.info" }
-{ $subsection "io.files.links" }
-{ $subsection "io.directories" }
+{ $subsections
+ "io.pathnames"
+ "io.files.info"
+ "io.files.links"
+ "io.directories"
+}
{ $heading "Encodings" }
-{ $subsection "encodings-introduction" }
-{ $subsection "io.encodings" }
+{ $subsections
+ "encodings-introduction"
+ "io.encodings"
+}
{ $heading "Wrapper streams" }
-{ $subsection "io.streams.duplex" }
-{ $subsection "io.streams.plain" }
-{ $subsection "io.streams.string" }
-{ $subsection "io.streams.byte-array" }
+{ $subsections
+ "io.streams.duplex"
+ "io.streams.plain"
+ "io.streams.string"
+ "io.streams.byte-array"
+}
{ $heading "Utilities" }
-{ $subsection "stream-binary" }
-{ $subsection "io.styles" }
-{ $subsection "checksums" }
+{ $subsections
+ "stream-binary"
+ "io.styles"
+ "checksums"
+}
{ $heading "Implementation" }
-{ $subsection "io.streams.c" }
-{ $subsection "io.ports" }
+{ $subsections
+ "io.streams.c"
+ "io.ports"
+}
{ $see-also "destructors" } ;
ARTICLE: "article-index" "Article index"
ARTICLE: "handbook-language-reference" "The language"
{ $heading "Fundamentals" }
-{ $subsection "conventions" }
-{ $subsection "syntax" }
+{ $subsections
+ "conventions"
+ "syntax"
+}
{ $heading "The stack" }
-{ $subsection "evaluator" }
-{ $subsection "effects" }
-{ $subsection "inference" }
+{ $subsections
+ "evaluator"
+ "effects"
+ "inference"
+}
{ $heading "Basic data types" }
-{ $subsection "booleans" }
-{ $subsection "numbers" }
-{ $subsection "collections" }
+{ $subsections
+ "booleans"
+ "numbers"
+ "collections"
+}
{ $heading "Evaluation" }
-{ $subsection "words" }
-{ $subsection "shuffle-words" }
-{ $subsection "combinators" }
-{ $subsection "threads" }
+{ $subsections
+ "words"
+ "shuffle-words"
+ "combinators"
+ "threads"
+}
{ $heading "Named values" }
-{ $subsection "locals" }
-{ $subsection "namespaces" }
-{ $subsection "namespaces-global" }
-{ $subsection "values" }
+{ $subsections
+ "locals"
+ "namespaces"
+ "namespaces-global"
+ "values"
+}
{ $heading "Abstractions" }
-{ $subsection "fry" }
-{ $subsection "objects" }
-{ $subsection "errors" }
-{ $subsection "destructors" }
-{ $subsection "memoize" }
-{ $subsection "parsing-words" }
-{ $subsection "macros" }
-{ $subsection "continuations" }
+{ $subsections
+ "fry"
+ "objects"
+ "errors"
+ "destructors"
+ "memoize"
+ "parsing-words"
+ "macros"
+ "continuations"
+}
{ $heading "Program organization" }
-{ $subsection "vocabs.loader" }
+{ $subsections "vocabs.loader" }
"Vocabularies tagged " { $link T{ vocab-tag { name "extensions" } } } " implement various additional language abstractions." ;
ARTICLE: "handbook-system-reference" "The implementation"
{ $heading "Parse time and compile time" }
-{ $subsection "parser" }
-{ $subsection "definitions" }
-{ $subsection "vocabularies" }
-{ $subsection "source-files" }
-{ $subsection "compiler" }
-{ $subsection "tools.errors" }
+{ $subsections
+ "parser"
+ "definitions"
+ "vocabularies"
+ "source-files"
+ "compiler"
+ "tools.errors"
+}
{ $heading "Virtual machine" }
-{ $subsection "images" }
-{ $subsection "cli" }
-{ $subsection "rc-files" }
-{ $subsection "init" }
-{ $subsection "system" }
-{ $subsection "layouts" } ;
+{ $subsections
+ "images"
+ "cli"
+ "rc-files"
+ "init"
+ "system"
+ "layouts"
+} ;
ARTICLE: "handbook-tools-reference" "Developer tools"
"The below tools are text-based. " { $link "ui-tools" } " are documented separately."
{ $heading "Workflow" }
-{ $subsection "listener" }
-{ $subsection "editor" }
-{ $subsection "vocabs.refresh" }
-{ $subsection "tools.test" }
-{ $subsection "help" }
+{ $subsections
+ "listener"
+ "editor"
+ "vocabs.refresh"
+ "tools.test"
+ "help"
+}
{ $heading "Debugging" }
-{ $subsection "prettyprint" }
-{ $subsection "inspector" }
-{ $subsection "tools.inference" }
-{ $subsection "tools.annotations" }
-{ $subsection "tools.deprecation" }
+{ $subsections
+ "prettyprint"
+ "inspector"
+ "tools.inference"
+ "tools.annotations"
+ "tools.deprecation"
+}
{ $heading "Browsing" }
-{ $subsection "see" }
-{ $subsection "tools.crossref" }
-{ $subsection "vocabs.hierarchy" }
+{ $subsections
+ "see"
+ "tools.crossref"
+ "vocabs.hierarchy"
+}
{ $heading "Performance" }
-{ $subsection "timing" }
-{ $subsection "profiling" }
-{ $subsection "tools.memory" }
-{ $subsection "tools.threads" }
-{ $subsection "tools.destructors" }
-{ $subsection "tools.disassembler" }
+{ $subsections
+ "timing"
+ "profiling"
+ "tools.memory"
+ "tools.threads"
+ "tools.destructors"
+ "tools.disassembler"
+}
{ $heading "Deployment" }
-{ $subsection "tools.deploy" } ;
+{ $subsections "tools.deploy" } ;
ARTICLE: "handbook-library-reference" "Libraries"
"This index lists articles from loaded vocabularies which are not subsections of any other article. To explore more vocabularies, see " { $link "vocab-index" } "."
{ $index [ orphan-articles { "help.home" "handbook" } diff ] } ;
ARTICLE: "handbook" "Factor handbook"
-"Learn the language:"
-{ $subsection "cookbook" }
-{ $subsection "first-program" }
-"Reference material:"
-{ $subsection "handbook-language-reference" }
-{ $subsection "io" }
-{ $subsection "ui" }
-{ $subsection "handbook-system-reference" }
-{ $subsection "handbook-tools-reference" }
-{ $subsection "ui-tools" }
-{ $subsection "alien" }
-{ $subsection "handbook-library-reference" }
-"Explore loaded libraries:"
-{ $subsection "article-index" }
-{ $subsection "primitive-index" }
-{ $subsection "error-index" }
-{ $subsection "type-index" }
-{ $subsection "class-index" }
-"Explore the code base:"
-{ $subsection "vocab-index" } ;
+{ $heading "Getting Started" }
+{ $subsections
+ "cookbook"
+ "first-program"
+}
+{ $heading "Reference" }
+{ $subsections
+ "handbook-language-reference"
+ "io"
+ "ui"
+ "handbook-system-reference"
+ "handbook-tools-reference"
+ "ui-tools"
+ "alien"
+ "handbook-library-reference"
+}
+{ $heading "Explore loaded libraries" }
+{ $subsections
+ "article-index"
+ "primitive-index"
+ "error-index"
+ "type-index"
+ "class-index"
+}
+{ $heading "Explore the code base" }
+{ $subsections "vocab-index" } ;
ABOUT: "handbook"
ARTICLE: "printing-elements" "Printing markup elements"
"When writing documentation, it is useful to be able to print markup elements for testing purposes. Markup elements which are strings or arrays of elements are printed in the obvious way. Markup elements of the form " { $snippet "{ $directive content... }" } " are printed by executing the " { $snippet "$directive" } " word with the element content on the stack."
-{ $subsection print-element }
-{ $subsection print-content } ;
+{ $subsections
+ print-element
+ print-content
+} ;
ARTICLE: "span-elements" "Span elements"
-{ $subsection $emphasis }
-{ $subsection $strong }
-{ $subsection $link }
-{ $subsection $vocab-link }
-{ $subsection $snippet }
-{ $subsection $slot }
-{ $subsection $url } ;
+{ $subsections
+ $emphasis
+ $strong
+ $link
+ $vocab-link
+ $snippet
+ $slot
+ $url
+} ;
ARTICLE: "block-elements" "Block elements"
"Paragraph break:"
-{ $subsection $nl }
+{ $subsections $nl }
"Standard headings for word documentation:"
-{ $subsection $values }
-{ $subsection $description }
-{ $subsection $class-description }
-{ $subsection $error-description }
-{ $subsection $var-description }
-{ $subsection $contract }
-{ $subsection $examples }
-{ $subsection $warning }
-{ $subsection $notes }
-{ $subsection $side-effects }
-{ $subsection $errors }
-{ $subsection $see-also }
+{ $subsections
+ $values
+ $description
+ $class-description
+ $error-description
+ $var-description
+ $contract
+ $examples
+ $warning
+ $notes
+ $side-effects
+ $errors
+ $see-also
+}
"Elements used in " { $link $values } " forms:"
-{ $subsection $instance }
-{ $subsection $maybe }
-{ $subsection $or }
-{ $subsection $quotation }
+{ $subsections
+ $instance
+ $maybe
+ $or
+ $quotation
+}
"Boilerplate paragraphs:"
-{ $subsection $low-level-note }
-{ $subsection $io-error }
+{ $subsections
+ $low-level-note
+ $io-error
+}
"Some additional elements:"
-{ $subsection $code }
-{ $subsection $curious }
-{ $subsection $example }
-{ $subsection $heading }
-{ $subsection $links }
-{ $subsection $list }
-{ $subsection $markup-example }
-{ $subsection $references }
-{ $subsection $see }
-{ $subsection $subsection }
-{ $subsection $table } ;
+{ $subsections
+ $code
+ $curious
+ $example
+ $heading
+ $links
+ $list
+ $markup-example
+ $references
+ $see
+ $subsection
+ $table
+} ;
ARTICLE: "markup-utils" "Markup element utilities"
"Utility words to assist in defining new elements:"
-{ $subsection simple-element }
-{ $subsection ($span) }
-{ $subsection ($block) } ;
+{ $subsections
+ simple-element
+ ($span)
+ ($block)
+} ;
ARTICLE: "element-types" "Element types"
"Markup elements can be classified into two broad categories, block elements and span elements. Block elements are inset with newlines before and after, whereas span elements flow with the paragraph text."
-{ $subsection "span-elements" }
-{ $subsection "block-elements" }
-{ $subsection "markup-utils" } ;
+{ $subsections
+ "span-elements"
+ "block-elements"
+ "markup-utils"
+} ;
IN: help.markup
ABOUT: "element-types"
"By convention, documentation is written in files whose names end with " { $snippet "-docs.factor" } ". Vocabulary documentation should be placed in the same directory as the vocabulary source code; see " { $link "vocabs.loader" } "."
$nl
"A pair of parsing words are used to define free-standing articles and to associate documentation with words:"
-{ $subsection POSTPONE: ARTICLE: }
-{ $subsection POSTPONE: HELP: }
+{ $subsections
+ POSTPONE: ARTICLE:
+ POSTPONE: HELP:
+}
"A parsing word defines the main help article for a vocabulary:"
-{ $subsection POSTPONE: ABOUT: }
+{ $subsections POSTPONE: ABOUT: }
"The " { $emphasis "content" } " in both cases is a " { $emphasis "markup element" } ", a recursive structure taking one of the following forms:"
{ $list
{ "a string," }
"<simple-element> ::== { <element>* }"
"<fancy-element> ::== { <type> <element> }"
}
-{ $subsection "element-types" }
-{ $subsection "printing-elements" }
+{ $subsections
+ "element-types"
+ "printing-elements"
+}
"Related words can be cross-referenced:"
-{ $subsection related-words }
+{ $subsections related-words }
{ $see-also "help.lint" } ;
ARTICLE: "help-impl" "Help system implementation"
"Help topic protocol:"
-{ $subsection article-name }
-{ $subsection article-title }
-{ $subsection article-content }
-{ $subsection article-parent }
-{ $subsection set-article-parent }
+{ $subsections
+ article-name
+ article-title
+ article-content
+ article-parent
+ set-article-parent
+}
"Boilerplate word help can be automatically generated (for example, slot accessor help):"
-{ $subsection word-help }
-{ $subsection word-help* }
+{ $subsections
+ word-help
+ word-help*
+}
"Help article implementation:"
-{ $subsection article }
-{ $subsection articles }
+{ $subsections
+ article
+ articles
+}
"Links:"
-{ $subsection link }
-{ $subsection >link }
+{ $subsections
+ link
+ >link
+}
"Utilities for traversing markup element trees:"
-{ $subsection elements }
-{ $subsection collect-elements }
+{ $subsections
+ elements
+ collect-elements
+}
"Links and " { $link article } " instances implement the definition protocol; refer to " { $link "definitions" } "." ;
ARTICLE: "help" "Help system"
"The help system maintains documentation written in a simple markup language, along with cross-referencing and search. Documentation can either exist as free-standing " { $emphasis "articles" } " or be associated with words."
-{ $subsection "browsing-help" }
-{ $subsection "writing-help" }
-{ $subsection "help.lint" }
-{ $subsection "tips-of-the-day" }
-{ $subsection "help-impl" } ;
+{ $subsections
+ "browsing-help"
+ "writing-help"
+ "help.lint"
+ "tips-of-the-day"
+ "help-impl"
+} ;
IN: help
ABOUT: "help"
{ $values { "element" "a markup element of the form " { $snippet "{ topic }" } } }
{ $description "Prints a large clickable link to the help topic named by the first item in " { $snippet "element" } ". The link is printed along with its associated definition icon." }
{ $examples
- { $markup-example { $subsection "sequences" } }
- { $markup-example { $subsection nth } }
- { $markup-example { $subsection each } }
+ { $markup-example { $subsections "sequences" } }
+ { $markup-example { $subsections nth } }
+ { $markup-example { $subsections each } }
} ;
HELP: $subsections
"The " { $vocab-link "help.lint" } " vocabulary implements a tool to check documentation in an automated fashion. You should use this tool to check any documentation that you write."
$nl
"To run help lint, use one of the following two words:"
-{ $subsection help-lint }
-{ $subsection help-lint-all }
+{ $subsections
+ help-lint
+ help-lint-all
+}
"Once a help lint run completes, failures can be listed:"
-{ $subsection :lint-failures }
+{ $subsections :lint-failures }
"Help lint failures are also shown in the " { $link "ui.tools.error-list" } "."
$nl
"Help lint performs the following checks:"
ARTICLE: "tips-of-the-day" "Tips of the day"
"The " { $vocab-link "help.tips" } " vocabulary provides a facility for displaying tips of the day in the " { $link "ui-listener" } ". Tips are defined with a parsing word:"
-{ $subsection POSTPONE: TIP: }
+{ $subsections POSTPONE: TIP: }
"All tips defined so far:"
-{ $subsection "all-tips-of-the-day" } ;
+{ $subsections "all-tips-of-the-day" } ;
ABOUT: "tips-of-the-day"
\ No newline at end of file
"In this tutorial, we will write a simple Factor program which prompts the user to enter a word, and tests if it is a palindrome (that is, the word is spelled the same backwards and forwards)."
$nl
"In this tutorial, you will learn about basic Factor development tools."
-{ $subsection "first-program-start" }
-{ $subsection "first-program-logic" }
-{ $subsection "first-program-test" }
-{ $subsection "first-program-extend" } ;
+{ $subsections
+ "first-program-start"
+ "first-program-logic"
+ "first-program-test"
+ "first-program-extend"
+} ;
ABOUT: "first-program"
{ $all-authors } ;
ARTICLE: "vocab-index" "Vocabulary index"
-{ $subsection "vocab-tags" }
-{ $subsection "vocab-authors" }
+{ $subsections
+ "vocab-tags"
+ "vocab-authors"
+}
{ $vocab "" } ;
HELP: words.
ARTICLE: "browsing-help" "Browsing documentation"
"Help topics are instances of a mixin:"
-{ $subsection topic }
+{ $subsections topic }
"Most commonly, topics are article name strings, or words. You can display a specific help topic:"
-{ $subsection help }
+{ $subsections help }
"You can also display the help for a vocabulary:"
-{ $subsection about }
+{ $subsections about }
"To list a vocabulary's words only:"
-{ $subsection words. }
+{ $subsections words. }
{ $examples
{ $code "\"evaluator\" help" }
{ $code "\\ + help" }
"In some cases, specialization will not help at all, and can make generated code slower from the increase in code size. The compiler is capable of inferring enough static type information to generate efficient code in many cases without explicit help from the programmer. Specializers should be used as a last resort, after profiling shows that a critical loop makes a lot of repeated calls to generic words which dispatch on the same class."
$nl
"Type hints are declared with a parsing word:"
-{ $subsection POSTPONE: HINTS: }
+{ $subsections POSTPONE: HINTS: }
"The specialized version of a word which will be compiled by the compiler can be inspected:"
-{ $subsection specialized-def } ;
+{ $subsections specialized-def } ;
HELP: specialized-def
{ $values { "word" word } { "quot" quotation } }
ARTICLE: "html.components.links" "Link components"
"Link components render a link to an object."
-{ $subsection link }
+{ $subsections link }
"The link title and URL are determined by passing the object to a pair of generic words:"
-{ $subsection link-title }
-{ $subsection link-href }
+{ $subsections
+ link-title
+ link-href
+}
"The generic words provide methods on the " { $link string } " and " { $link url } " classes which treat the object as a URL. New methods can be defined for rendering links to custom data types." ;
HELP: comparison
"Most web applications can use the " { $vocab-link "html.templates.chloe" } " templating framework instead of using this vocabulary directly. Where maximum flexibility is required, this vocabulary can be used together with the " { $vocab-link "html.templates.fhtml" } " templating framework."
$nl
"Rendering components:"
-{ $subsection render }
+{ $subsections render }
"Components render a named value, and the name of the value is passed in every time the component is rendered, rather than being associated with the component itself. Named values are taken from the current HTML form (see " { $link "html.forms" } ")."
$nl
"Component come in two varieties: singletons and tuples. Components with no configuration are singletons; they do not have to instantiated, rather the class word represents the component. Tuple components have to be instantiated and offer configuration options."
$nl
"Singleton components:"
-{ $subsection hidden }
-{ $subsection link }
-{ $subsection inspector }
-{ $subsection comparison }
-{ $subsection html }
-{ $subsection xml }
+{ $subsections
+ hidden
+ link
+ inspector
+ comparison
+ html
+ xml
+}
"Tuple components:"
-{ $subsection field }
-{ $subsection password }
-{ $subsection textarea }
-{ $subsection choice }
-{ $subsection checkbox }
-{ $subsection code }
-{ $subsection farkup }
+{ $subsections
+ field
+ password
+ textarea
+ choice
+ checkbox
+ code
+ farkup
+}
"Creating custom components:"
-{ $subsection render* }
+{ $subsections render* }
"Custom components can emit HTML using the " { $vocab-link "xml.syntax" } " vocabulary." ;
ABOUT: "html.components"
"The below words are used to implement the " { $vocab-link "furnace.actions" } " vocabulary. Calling them directly is rarely necessary."
$nl
"Creating a new form:"
-{ $subsection <form> }
+{ $subsections <form> }
"Variable holding current form:"
-{ $subsection form }
+{ $subsections form }
"Working with forms:"
-{ $subsection with-form }
-{ $subsection begin-form }
+{ $subsections
+ with-form
+ begin-form
+}
"Validation:"
-{ $subsection validation-error }
-{ $subsection validation-failed? }
-{ $subsection validate-values } ;
+{ $subsections
+ validation-error
+ validation-failed?
+ validate-values
+} ;
ARTICLE: "html.forms.values" "HTML form values"
"Form values are a central concept in the Furnace framework. Web actions primarily concern themselves with validating values, marshalling values to a database, and setting values for display in a form."
$nl
"Getting and setting values:"
-{ $subsection value }
-{ $subsection set-value }
-{ $subsection from-object }
-{ $subsection to-object }
+{ $subsections
+ value
+ set-value
+ from-object
+ to-object
+}
"Iterating over values; these words are used by " { $vocab-link "html.templates.chloe" } " to implement the " { $snippet "t:each" } " and " { $snippet "t:bind-each" } " tags:"
-{ $subsection with-each-value }
-{ $subsection with-each-object }
+{ $subsections
+ with-each-value
+ with-each-object
+}
"Nesting a form inside another form as a value:"
-{ $subsection nest-form } ;
+{ $subsections nest-form } ;
ARTICLE: "html.forms" "HTML forms"
"The " { $vocab-link "html.forms" } " vocabulary implements support for rendering and validating HTML forms. The definition of a " { $emphasis "form" } " is a bit more general than the content of an " { $snippet "<form>" } " tag. Namely, a page which displays a database record without offering any editing capability is considered a form too; it consists entirely of read-only components."
"This vocabulary is an integral part of the " { $vocab-link "furnace" } " web framework. The " { $vocab-link "html.templates.chloe" } " vocabulary uses the HTML form words to implement various template tags. The words are also often used directly from web action implementations."
$nl
"This vocabulary can be used without either the Furnace framework or the HTTP server; for example, as part of a static HTML generation tool."
-{ $subsection "html.forms.forms" }
-{ $subsection "html.forms.values" } ;
+{ $subsections
+ "html.forms.forms"
+ "html.forms.values"
+} ;
ABOUT: "html.forms"
ARTICLE: "html.streams" "HTML streams"
"The " { $vocab-link "html.streams" } " vocabulary provides a stream which implements " { $link "io.styles" } " by constructing HTML markup in the form of " { $vocab-link "xml.data" } " types."
-{ $subsection html-writer }
-{ $subsection <html-writer> }
-{ $subsection with-html-writer } ;
+{ $subsections
+ html-writer
+ <html-writer>
+ with-html-writer
+} ;
ABOUT: "html.streams"
" ..."
"</t:chloe>"
}
-{ $subsection "html.templates.chloe.tags.component" }
-{ $subsection "html.templates.chloe.tags.boilerplate" }
-{ $subsection "html.templates.chloe.tags.control" }
-{ $subsection "html.templates.chloe.tags.form" } ;
+{ $subsections
+ "html.templates.chloe.tags.component"
+ "html.templates.chloe.tags.boilerplate"
+ "html.templates.chloe.tags.control"
+ "html.templates.chloe.tags.form"
+} ;
ARTICLE: "html.templates.chloe.extend" "Extending Chloe"
"The " { $vocab-link "html.templates.chloe.syntax" } " and " { $vocab-link "html.templates.chloe.compiler" } " vocabularies contain the heart of the Chloe implementation."
"Chloe is implemented as a compiler which converts XML templates into Factor quotations. The template only has to be parsed and compiled once, and not on every HTTP request. This helps improve performance and memory usage."
$nl
"These vocabularies provide various hooks by which Chloe can be extended. First of all, new " { $link "html.components" } " can be wired in. If further flexibility is needed, entirely new tags can be defined by hooking into the Chloe compiler."
-{ $subsection "html.templates.chloe.extend.components" }
-{ $subsection "html.templates.chloe.extend.tags" } ;
+{ $subsections
+ "html.templates.chloe.extend.components"
+ "html.templates.chloe.extend.tags"
+} ;
ARTICLE: "html.templates.chloe.extend.tags" "Extending Chloe with custom tags"
"Syntax for defining custom tags:"
-{ $subsection POSTPONE: CHLOE: }
+{ $subsections POSTPONE: CHLOE: }
"A number of compiler words can be used from the " { $link POSTPONE: CHLOE: } " body to emit compiled template code."
$nl
"Extracting attributes from the XML tag:"
-{ $subsection required-attr }
-{ $subsection optional-attr }
-{ $subsection compile-attr }
+{ $subsections
+ required-attr
+ optional-attr
+ compile-attr
+}
"Examining tag nesting:"
-{ $subsection tag-stack }
+{ $subsections tag-stack }
"Generating code for printing strings and calling quotations:"
-{ $subsection [write] }
-{ $subsection [code] }
+{ $subsections
+ [write]
+ [code]
+}
"Generating code from child elements:"
-{ $subsection process-children }
-{ $subsection compile-children>string }
-{ $subsection compile-with-scope }
+{ $subsections
+ process-children
+ compile-children>string
+ compile-with-scope
+}
"Examples which illustrate some of the above:"
-{ $subsection "html.templates.chloe.extend.tags.example" } ;
+{ $subsections "html.templates.chloe.extend.tags.example" } ;
ARTICLE: "html.templates.chloe.extend.tags.example" "Examples of custom Chloe tags"
"As a first example, let's develop a custom Chloe tag which simply renders a random number. The tag will be used as follows:"
ARTICLE: "html.templates.chloe.extend.components" "Extending Chloe with custom components"
"Custom HTML components implementing the " { $link render* } " word can be wired up with Chloe using the following syntax from " { $vocab-link "html.templates.chloe.components" } ":"
-{ $subsection POSTPONE: COMPONENT: }
-{ $subsection "html.templates.chloe.extend.components.example" } ;
+{ $subsections
+ POSTPONE: COMPONENT:
+ "html.templates.chloe.extend.components.example"
+} ;
ARTICLE: "html.templates.chloe" "Chloe templates"
"The " { $vocab-link "html.templates.chloe" } " vocabulary implements an XHTML templating engine. Unlike " { $vocab-link "html.templates.fhtml" } ", Chloe templates are always well-formed XML, and no Factor code can be embedded in them, enforcing proper separation of concerns. Chloe templates can be edited using standard XML editing tools; they are less flexible than FHTML, but often simpler as a result."
-{ $subsection <chloe> }
-{ $subsection reset-cache }
-{ $subsection "html.templates.chloe.tags" }
-{ $subsection "html.templates.chloe.extend" } ;
+{ $subsections
+ <chloe>
+ reset-cache
+ "html.templates.chloe.tags"
+ "html.templates.chloe.extend"
+} ;
ABOUT: "html.templates.chloe"
"FHTML provides an alternative to " { $vocab-link "html.templates.chloe" } " for situations where complex logic must be embedded in the presentation layer of a web application. While this is discouraged for larger applications, it is useful for prototyping as well as simpler applications."
$nl
"The entire syntax of an FHTML template can be summarized as thus: text outside of " { $snippet "<%" } " and " { $snippet "%>" } " is rendered literally. Text inside " { $snippet "<%" } " and " { $snippet "%>" } " is interpreted as Factor source code."
-{ $subsection <fhtml> } ;
+{ $subsections <fhtml> } ;
ABOUT: "html.templates.fhtml"
"The following words define the interface between a templating engine and the " { $vocab-link "furnace.boilerplate" } " vocabulary."
$nl
"The master/child template interface follows a pattern where for each concept there is a word called by the child to store an entity, and another word to write the entity out; this solves the problem where certain HTML tags, such as " { $snippet "<title>" } " and " { $snippet "<link>" } " must appear inside the " { $snippet "<head>" } " tag, even though those tags are usually precisely those that the child template will want to set."
-{ $subsection set-title }
-{ $subsection write-title }
-{ $subsection add-style }
-{ $subsection write-style }
-{ $subsection add-atom-feed }
-{ $subsection write-atom-feeds }
+{ $subsections
+ set-title
+ write-title
+ add-style
+ write-style
+ add-atom-feed
+ write-atom-feeds
+}
"Processing a master template with a child:"
-{ $subsection with-boilerplate }
-{ $subsection call-next-template } ;
+{ $subsections
+ with-boilerplate
+ call-next-template
+} ;
ARTICLE: "html.templates" "HTML template interface"
"The " { $vocab-link "html.templates" } " vocabulary implements an abstract interface to HTML templating engines. The " { $vocab-link "html.templates.fhtml" } " and " { $vocab-link "html.templates.chloe" } " vocabularies are two implementations of this."
$nl
"An HTML template is an instance of a mixin:"
-{ $subsection template }
+{ $subsections template }
"HTML templates must also implement a method on a generic word:"
-{ $subsection call-template* }
+{ $subsections call-template* }
"Calling an HTML template:"
-{ $subsection call-template }
+{ $subsections call-template }
"Usually HTML templates are invoked dynamically by the Furnace web framework and HTTP server. They can also be used in static HTML generation tools:"
-{ $subsection template-convert }
-{ $subsection "html.templates.boilerplate" } ;
+{ $subsections
+ template-convert
+ "html.templates.boilerplate"
+} ;
ABOUT: "html.templates"
ARTICLE: "http.client.get" "GET requests with the HTTP client"
"Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
-{ $subsection http-get }
+{ $subsections http-get }
"Utilities to retrieve a " { $link url } " and save the contents to a file:"
-{ $subsection download }
-{ $subsection download-to }
+{ $subsections
+ download
+ download-to
+}
"Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
-{ $subsection <get-request> }
-{ $subsection http-request }
+{ $subsections
+ <get-request>
+ http-request
+}
"The " { $link http-get } " and " { $link http-request } " words output sequences. This is undesirable if the response data may be large. Another pair of words take a quotation instead, and pass the quotation chunks of data incrementally:"
-{ $subsection with-http-get }
-{ $subsection with-http-request } ;
+{ $subsections
+ with-http-get
+ with-http-request
+} ;
ARTICLE: "http.client.post-data" "HTTP client post data"
"HTTP POST and PUT request words take a post data parameter, which can be one of the following:"
"[ URL\" http://www.my-company.com/web-service\" http-post ] with-disposal"
}
"An internal word used to convert objects to " { $link post-data } " instances:"
-{ $subsection >post-data } ;
+{ $subsections >post-data } ;
ARTICLE: "http.client.post" "POST requests with the HTTP client"
"Basic usage involves passing post data and a " { $link url } ", and getting a " { $link response } " and data back:"
-{ $subsection http-post }
+{ $subsections http-post }
"Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
-{ $subsection <post-request> }
+{ $subsection
s <post-request> }
"Both words take a post data parameter; see " { $link "http.client.post-data" } "." ;
ARTICLE: "http.client.put" "PUT requests with the HTTP client"
"Basic usage involves passing post data and a " { $link url } ", and getting a " { $link response } " and data back:"
-{ $subsection http-post }
+{ $subsections http-post }
"Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
-{ $subsection <post-request> }
+{ $subsection
s <post-request> }
"Both words take a post data parameter; see " { $link "http.client.post-data" } "." ;
ARTICLE: "http.client.encoding" "Character encodings and the HTTP client"
ARTICLE: "http.client.errors" "HTTP client errors"
"HTTP operations may fail for one of two reasons. The first is an I/O error resulting from a network problem; a name server lookup failure, or a refused connection. The second is a protocol-level error returned by the server. There are two such errors:"
-{ $subsection download-failed }
-{ $subsection too-many-redirects } ;
+{ $subsections
+ download-failed
+ too-many-redirects
+} ;
ARTICLE: "http.client" "HTTP client"
"The " { $vocab-link "http.client" } " vocabulary implements an HTTP and HTTPS client on top of " { $link "http" } "."
"For HTTPS support, you must load the " { $vocab-link "urls.secure" } " vocab first. If you don't need HTTPS support, don't load " { $vocab-link "urls.secure" } "; this will reduce the size of images generated by " { $vocab-link "tools.deploy" } "."
$nl
"There are two primary usage patterns, data retrieval with GET requests and form submission with POST requests:"
-{ $subsection "http.client.get" }
-{ $subsection "http.client.post" }
-{ $subsection "http.client.put" }
+{ $subsections
+ "http.client.get"
+ "http.client.post"
+ "http.client.put"
+}
"Submission data for POST and PUT requests:"
-{ $subsection "http.client.post-data" }
+{ $subsections "http.client.post-data" }
"More esoteric use-cases, for example HTTP methods other than the above, are accomodated by constructing an empty request object with " { $link <request> } " and filling everything in by hand."
-{ $subsection "http.client.encoding" }
-{ $subsection "http.client.errors" }
+{ $subsections
+ "http.client.encoding"
+ "http.client.errors"
+}
{ $see-also "urls" } ;
ABOUT: "http.client"
"The " { $vocab-link "furnace.sessions" } " vocabulary implements session management using cookies, thus the most common use case can be taken care of without working with cookies directly."
$nl
"The class of cookies:"
-{ $subsection cookie }
+{ $subsections cookie }
"Creating cookies:"
-{ $subsection <cookie> }
+{ $subsections <cookie> }
"Getting, adding, and deleting cookies in " { $link request } " and " { $link response } " objects:"
-{ $subsection get-cookie }
-{ $subsection put-cookie }
-{ $subsection delete-cookie } ;
+{ $subsections
+ get-cookie
+ put-cookie
+ delete-cookie
+} ;
ARTICLE: "http.headers" "HTTP headers"
"Every " { $link request } " and " { $link response } " has a set of HTTP headers stored in the " { $slot "header" } " slot. Header names are normalized to lower-case when a request or response is being parsed."
-{ $subsection header }
-{ $subsection set-header } ;
+{ $subsections
+ header
+ set-header
+} ;
ARTICLE: "http.post-data" "HTTP post data"
"Every " { $link request } " where the " { $slot "method" } " slot is " { $snippet "POST" } " can contain post data."
-{ $subsection post-data }
-{ $subsection <post-data> } ;
+{ $subsections
+ post-data
+ <post-data>
+} ;
ARTICLE: "http.requests" "HTTP requests"
"HTTP requests:"
-{ $subsection request }
-{ $subsection <request> }
+{ $subsections
+ request
+ <request>
+}
"Requests can contain form submissions:"
-{ $subsection "http.post-data" } ;
+{ $subsections "http.post-data" } ;
ARTICLE: "http.responses" "HTTP responses"
"HTTP responses:"
-{ $subsection response }
-{ $subsection <response> }
+{ $subsections
+ response
+ <response>
+}
"Raw responses only contain a status line, with no header. They are used by webapps which need full control over the HTTP response, for example " { $vocab-link "http.server.cgi" } ":"
-{ $subsection raw-response }
-{ $subsection <raw-response> } ;
+{ $subsections
+ raw-response
+ <raw-response>
+} ;
ARTICLE: "http" "HTTP protocol objects"
"The " { $vocab-link "http" } " vocabulary contains data types shared by " { $vocab-link "http.client" } " and " { $vocab-link "http.server" } "."
$nl
"The HTTP client sends an HTTP request to the server and receives an HTTP response back. The HTTP server receives HTTP requests from clients and sends HTTP responses back."
-{ $subsection "http.requests" }
-{ $subsection "http.responses" }
+{ $subsections
+ "http.requests"
+ "http.responses"
+}
"Both requests and responses support some common functionality:"
-{ $subsection "http.headers" }
-{ $subsection "http.cookies" }
+{ $subsections
+ "http.headers"
+ "http.cookies"
+}
{ $see-also "urls" } ;
ABOUT: "http"
ARTICLE: "http.server.cgi" "Serving CGI scripts"
"The " { $vocab-link "http.server.cgi" } " implements CGI support. It is used in conjunction with a " { $link <static> } " responder."
-{ $subsection enable-cgi } ;
+{ $subsections enable-cgi } ;
ARTICLE: "http.server.dispatchers" "HTTP dispatchers and virtual hosting"
"The " { $vocab-link "http.server.dispatchers" } " vocabulary implements two responders which route HTTP requests to one or more child responders."
-{ $subsection "http.server.dispatchers.example" }
+{ $subsections "http.server.dispatchers.example" }
"Pathname dispatchers implement a directory hierarchy where each subdirectory is its own responder:"
-{ $subsection dispatcher }
-{ $subsection <dispatcher> }
+{ $subsections
+ dispatcher
+ <dispatcher>
+}
"Virtual host dispatchers dispatch each virtual host to a different responder:"
-{ $subsection vhost-dispatcher }
-{ $subsection <vhost-dispatcher> }
+{ $subsections
+ vhost-dispatcher
+ <vhost-dispatcher>
+}
"Adding responders to dispatchers:"
-{ $subsection add-responder }
+{ $subsections add-responder }
"The " { $slot "default" } " slot holds a responder which receives all unrecognized URLs. By default, it responds with 404 messages." ;
ABOUT: "http.server.dispatchers"
ARTICLE: "http.server.filters" "HTTP responder filters"
"The " { $vocab-link "http.server.filters" } " vocabulary implements the common pattern where one responder wraps another, doing some processing before calling the wrapped responder."
-{ $subsection filter-responder }
+{ $subsections filter-responder }
"To use it, simply subclass " { $link filter-responder } ", and call " { $link POSTPONE: call-next-method } " from your " { $link call-responder* } " method to pass control to the wrapped responder." ;
ABOUT: "http.server.filters"
ARTICLE: "http.server.redirection" "HTTP responder redirection"
"The " { $vocab-link "http.server.redirection" } " defines some " { $link response } " types which redirect the user's client to a new page."
-{ $subsection <permanent-redirect> }
-{ $subsection <temporary-redirect> }
+{ $subsections
+ <permanent-redirect>
+ <temporary-redirect>
+}
"A utility used by the above:"
-{ $subsection relative-to-request }
+{ $subsections relative-to-request }
"The " { $vocab-link "furnace.redirection" } " vocabulary provides a higher-level implementation of this. The " { $vocab-link "furnace.conversations" } " vocabulary allows state to be maintained between redirects." ;
ABOUT: "http.server.redirection"
"However, the HTTP server is unaware of the forwarding, and still believes that it is listening on port 8080 and 8443, respectively. This can be a problem if a responder wishes to redirect the user to a secure page; they will be sent to port 8443 and not 443 as one would expect."
$nl
"The " { $vocab-link "http.server.remapping" } " vocabulary defines a variable which may store an assoc of port mappings:"
-{ $subsection port-remapping }
+{ $subsections port-remapping }
"For example, with the above setup, we would set it as follows:"
{ $code
"{ { 8080 80 } { 8443 443 } } port-remapping set-global"
ARTICLE: "http.server.responses" "Canned HTTP responses"
"The " { $vocab-link "http.server.responses" } " vocabulary provides constructors for a few useful " { $link response } " objects."
-{ $subsection <content> }
-{ $subsection <304> }
-{ $subsection <403> }
-{ $subsection <400> }
-{ $subsection <404> }
+{ $subsections
+ <content>
+ <304>
+ <403>
+ <400>
+ <404>
+}
"New error responses like the above can be created for other error codes too:"
-{ $subsection <trivial-response> } ;
+{ $subsections <trivial-response> } ;
ABOUT: "http.server.responses"
ARTICLE: "http.server.rewrite" "URL rewrite responders"
"The " { $vocab-link "http.server.rewrite" } " vocabulary defines two responder types which can help make website URLs more human-friendly."
-{ $subsection "http.server.rewrite.overview" }
+{ $subsections "http.server.rewrite.overview" }
"Directory rewrite responders:"
-{ $subsection rewrite }
-{ $subsection <rewrite> }
+{ $subsections
+ rewrite
+ <rewrite>
+}
"Virtual host rewrite responders -- these chop off the value in the " { $snippet "suffix" } " slot from the tail of the host name, and use the rest as the parameter value:"
-{ $subsection vhost-rewrite }
-{ $subsection <vhost-rewrite> } ;
+{ $subsections
+ vhost-rewrite
+ <vhost-rewrite>
+} ;
ABOUT: "http.server.rewrite"
\ No newline at end of file
ARTICLE: "http.server.requests" "HTTP request variables"
"The following variables are set by the HTTP server at the beginning of a request."
-{ $subsection request }
-{ $subsection url }
-{ $subsection post-request? }
-{ $subsection responder-nesting }
-{ $subsection params }
+{ $subsections
+ request
+ url
+ post-request?
+ responder-nesting
+ params
+}
"Utility words:"
-{ $subsection param }
-{ $subsection set-param }
-{ $subsection request-params }
+{ $subsections
+ param
+ set-param
+ request-params
+}
"Additional vocabularies may be set by vocabularies such as " { $vocab-link "html.forms" } " and " { $vocab-link "furnace.sessions" } "." ;
ARTICLE: "http.server.responders" "HTTP server responders"
"The HTTP server dispatches requests to a main responder:"
-{ $subsection main-responder }
+{ $subsections main-responder }
"The main responder may in turn dispatch it a subordinate dispatcher, and so on."
$nl
"Responders process requests and output " { $link "http.responses" } "; concretely are instances of classes which implement a generic word:"
-{ $subsection call-responder* }
+{ $subsections call-responder* }
"To actually call a subordinate responder, use the following word instead:"
-{ $subsection call-responder }
+{ $subsections call-responder }
"A simple implementation of a responder which always outputs the same response:"
-{ $subsection trivial-responder }
-{ $subsection <trivial-responder> }
+{ $subsections
+ trivial-responder
+ <trivial-responder>
+}
{ $vocab-subsection "Furnace actions" "furnace.actions" }
"In particular, writing new responders by hand is rarely necessary, because in most cases it is easier to use " { $vocab-link "furnace.actions" } " instead." ;
ARTICLE: "http.server.variables" "HTTP server variables"
"The following global variables control the behavior of the HTTP server. Both are off by default."
-{ $subsection development? }
-{ $subsection benchmark? } ;
+{ $subsections
+ development?
+ benchmark?
+} ;
ARTICLE: "http.server" "HTTP server"
"The " { $vocab-link "http.server" } " vocabulary implements an HTTP and HTTPS server on top of " { $vocab-link "io.servers.connection" } "."
-{ $subsection "http.server.responders" }
-{ $subsection "http.server.requests" }
+{ $subsections
+ "http.server.responders"
+ "http.server.requests"
+}
"Various types of responders are defined in other vocabularies:"
-{ $subsection "http.server.dispatchers" }
-{ $subsection "http.server.filters" }
+{ $subsections
+ "http.server.dispatchers"
+ "http.server.filters"
+}
"Useful canned responses:"
-{ $subsection "http.server.responses" }
-{ $subsection "http.server.redirection" }
+{ $subsections
+ "http.server.responses"
+ "http.server.redirection"
+}
"Configuration:"
-{ $subsection "http.server.variables" }
-{ $subsection "http.server.remapping" }
+{ $subsections
+ "http.server.variables"
+ "http.server.remapping"
+}
"Features:"
-{ $subsection "http.server.static" }
-{ $subsection "http.server.cgi" }
+{ $subsections
+ "http.server.static"
+ "http.server.cgi"
+}
"The " { $vocab-link "furnace" } " framework implements high-level abstractions which make developing web applications much easier than writing responders by hand." ;
ABOUT: "http.server"
"The static responder can be extended for dynamic content by associating quotations with MIME types in the hashtable stored in the " { $slot "special" } " slot. The quotations have stack effect " { $snippet "( path -- response )" } "."
$nl
"A utility word uses the above feature to enable server-side " { $snippet ".fhtml" } " scripts, allowing a development style much like PHP:"
-{ $subsection enable-fhtml }
+{ $subsections enable-fhtml }
"This feature is also used by " { $vocab-link "http.server.cgi" } " to run " { $snippet ".cgi" } " files."
$nl
"It is also possible to override the hook used when serving static files to the client:"
-{ $subsection <file-responder> }
+{ $subsections <file-responder> }
"The default just sends the file's contents with the request; " { $vocab-link "xmode.code2html.responder" } " provides an alternate hook which sends a syntax-highlighted version of the file." ;
ARTICLE: "http.server.static" "Serving static content"
"The " { $vocab-link "http.server.static" } " vocabulary implements a responder for serving static files."
-{ $subsection <static> }
+{ $subsections <static> }
"The static responder does not serve directory listings by default, as a security measure. Directory listings can be enabled by storing a true value in the " { $slot "allow-listings" } " slot."
$nl
"If all you want to do is serve files from a directory, the following phrase does the trick:"
"\"/var/www/mysite.com/\" <static> main-responder set"
"8080 httpd"
}
-{ $subsection "http.server.static.extend" } ;
+{ $subsections "http.server.static.extend" } ;
ABOUT: "http.server.static"
"The inspector displays a tabular view of an object and adds navigation and editing features. Inspector words are found in the " { $vocab-link "inspector" } " vocabulary."
$nl
"Starting the inspector:"
-{ $subsection inspect }
+{ $subsections inspect }
"The inspector supports a number of commands which operate on the most recently inspected object:"
-{ $subsection &push }
-{ $subsection &back }
-{ $subsection &at }
-{ $subsection &put }
-{ $subsection &add }
-{ $subsection &rename }
-{ $subsection &delete }
+{ $subsections
+ &push
+ &back
+ &at
+ &put
+ &add
+ &rename
+ &delete
+}
"A variable holding the current object:"
-{ $subsection me }
+{ $subsections me }
"A description of an object can be printed without starting the inspector:"
-{ $subsection describe } ;
+{ $subsections describe } ;
ABOUT: "inspector"
"The " { $vocab-link "interval-maps" } " vocabulary implements a data structure, similar to assocs, where a set of closed intervals of keys are associated with values. As such, interval maps do not conform to the assoc protocol, because intervals of floats, for example, can be used, and it is impossible to get a list of keys in between."\r
$nl\r
"The following operations are used to query interval maps:"\r
-{ $subsection interval-at* }\r
-{ $subsection interval-at }\r
-{ $subsection interval-key? }\r
-{ $subsection interval-values }\r
+{ $subsections\r
+ interval-at*\r
+ interval-at\r
+ interval-key?\r
+ interval-values\r
+}\r
"Use the following to construct interval maps"\r
-{ $subsection <interval-map> }\r
-{ $subsection coalesce } ;\r
+{ $subsections\r
+ <interval-map>\r
+ coalesce\r
+} ;\r
\r
ABOUT: "interval-maps"\r
ARTICLE: { "inverse" "intro" } "Invertible quotations"
"The inverse vocab defines a way to 'undo' quotations, and builds a pattern matching framework on that basis. A quotation can be inverted by reversing it and inverting each word. To define the inverse for particular word, use"
-{ $subsection define-inverse }
-{ $subsection define-pop-inverse }
+{ $subsections
+ define-inverse
+ define-pop-inverse
+}
"To build an inverse quotation"
-{ $subsection [undo] }
+{ $subsections [undo] }
"To use the inverse quotation for pattern matching"
-{ $subsection undo }
-{ $subsection matches? }
-{ $subsection switch } ;
+{ $subsections
+ undo
+ matches?
+ switch
+} ;
IN: inverse
ABOUT: { "inverse" "intro" }
"Buffers are used to implement native I/O backends."
$nl
"Buffer words are found in the " { $vocab-link "io.buffers" } " vocabulary."
-{ $subsection buffer }
-{ $subsection <buffer> }
+{ $subsections
+ buffer
+ <buffer>
+}
"Buffers must be manually deallocated by calling " { $link dispose } "."
$nl
"Buffer operations:"
-{ $subsection buffer-reset }
-{ $subsection buffer-length }
-{ $subsection buffer-empty? }
-{ $subsection buffer-capacity }
-{ $subsection buffer@ }
+{ $subsections
+ buffer-reset
+ buffer-length
+ buffer-empty?
+ buffer-capacity
+ buffer@
+}
"Reading from the buffer:"
-{ $subsection buffer-peek }
-{ $subsection buffer-pop }
-{ $subsection buffer-read }
+{ $subsections
+ buffer-peek
+ buffer-pop
+ buffer-read
+}
"Writing to the buffer:"
-{ $subsection byte>buffer }
-{ $subsection >buffer }
-{ $subsection n>buffer } ;
+{ $subsections
+ byte>buffer
+ >buffer
+ n>buffer
+} ;
ABOUT: "buffers"
ARTICLE: "current-directory" "Current working directory"
"File system I/O operations use the value of a variable to resolve relative pathnames:"
-{ $subsection current-directory }
+{ $subsections current-directory }
"This variable can be changed with a pair of words:"
-{ $subsection set-current-directory }
-{ $subsection with-directory }
+{ $subsections
+ set-current-directory
+ with-directory
+}
"This variable is independent of the operating system notion of “current working directory”. While all Factor I/O operations use the variable and not the operating system's value, care must be taken when making FFI calls which expect a pathname. The first option is to resolve relative paths:"
-{ $subsection (normalize-path) }
+{ $subsections (normalize-path) }
"The second is to change the working directory of the current process:"
-{ $subsection cd }
-{ $subsection cwd } ;
+{ $subsections
+ cd
+ cwd
+} ;
ARTICLE: "io.directories.listing" "Directory listing"
"Directory listing:"
-{ $subsection directory-entries }
-{ $subsection directory-files }
-{ $subsection with-directory-entries }
-{ $subsection with-directory-files } ;
+{ $subsections
+ directory-entries
+ directory-files
+ with-directory-entries
+ with-directory-files
+} ;
ARTICLE: "io.directories.create" "Creating directories"
-{ $subsection make-directory }
-{ $subsection make-directories } ;
+{ $subsections
+ make-directory
+ make-directories
+} ;
ARTICLE: "delete-move-copy" "Deleting, moving, and copying files"
"Operations for deleting and copying files come in two forms:"
"Since both of the above lists apply to copying files, that this means that there are a total of six variations on copying a file."
$nl
"Deleting files:"
-{ $subsection delete-file }
-{ $subsection delete-directory }
+{ $subsections
+ delete-file
+ delete-directory
+}
"Moving files:"
-{ $subsection move-file }
-{ $subsection move-file-into }
-{ $subsection move-files-into }
+{ $subsections
+ move-file
+ move-file-into
+ move-files-into
+}
"Copying files:"
-{ $subsection copy-file }
-{ $subsection copy-file-into }
-{ $subsection copy-files-into }
+{ $subsections
+ copy-file
+ copy-file-into
+ copy-files-into
+}
"On most operating systems, files can only be moved within the same file system. To move files between file systems, use " { $link copy-file } " followed by " { $link delete-file } " on the old name." ;
ARTICLE: "io.directories" "Directory manipulation"
"The " { $vocab-link "io.directories" } " vocabulary defines words for inspecting and manipulating directory trees."
-{ $subsection home }
-{ $subsection "current-directory" }
-{ $subsection "io.directories.listing" }
-{ $subsection "io.directories.create" }
-{ $subsection "delete-move-copy" }
-{ $subsection "io.directories.hierarchy" } ;
+{ $subsections
+ home
+ "current-directory"
+ "io.directories.listing"
+ "io.directories.create"
+ "delete-move-copy"
+ "io.directories.hierarchy"
+} ;
ABOUT: "io.directories"
"The " { $vocab-link "io.directories.hierarchy" } " vocabulary defines words for operating on directory hierarchies recursively."
$nl
"Deleting directory trees recursively:"
-{ $subsection delete-tree }
+{ $subsections delete-tree }
"Copying directory trees recursively:"
-{ $subsection copy-tree }
-{ $subsection copy-tree-into }
-{ $subsection copy-trees-into } ;
+{ $subsections
+ copy-tree
+ copy-tree-into
+ copy-trees-into
+} ;
ABOUT: "io.directories.hierarchy"
ARTICLE: "io.directories.search" "Searching directories"
"The " { $vocab-link "io.directories.search" } " vocabulary contains words used for recursively iterating over a directory and for finding files in a directory tree." $nl
"Traversing directories:"
-{ $subsection recursive-directory-files }
-{ $subsection recursive-directory-entries }
-{ $subsection each-file }
+{ $subsections
+ recursive-directory-files
+ recursive-directory-entries
+ each-file
+}
"Finding files by name:"
-{ $subsection find-file }
-{ $subsection find-all-files }
-{ $subsection find-in-directories }
-{ $subsection find-all-in-directories }
+{ $subsections
+ find-file
+ find-all-files
+ find-in-directories
+ find-all-in-directories
+}
"Finding files by extension:"
-{ $subsection find-by-extension }
-{ $subsection find-by-extensions } ;
+{ $subsections
+ find-by-extension
+ find-by-extensions
+} ;
ABOUT: "io.directories.search"
ARTICLE: "io.encodings.8-bit" "Legacy 8-bit encodings"
"Many encodings are a simple mapping of bytes onto characters. The " { $vocab-link "io.encodings.8-bit" } " vocabulary implements these generically using existing resource files. These encodings should be used with extreme caution, as fully general Unicode encodings like UTF-8 are nearly always more appropriate. The following 8-bit encodings are already defined:"
-{ $subsection latin1 }
-{ $subsection latin2 }
-{ $subsection latin3 }
-{ $subsection latin4 }
-{ $subsection latin/cyrillic }
-{ $subsection latin/arabic }
-{ $subsection latin/greek }
-{ $subsection latin/hebrew }
-{ $subsection latin5 }
-{ $subsection latin6 }
-{ $subsection latin/thai }
-{ $subsection latin7 }
-{ $subsection latin8 }
-{ $subsection latin9 }
-{ $subsection latin10 }
-{ $subsection koi8-r }
-{ $subsection windows-1252 }
-{ $subsection ebcdic }
-{ $subsection mac-roman } ;
+{ $subsections
+ latin1
+ latin2
+ latin3
+ latin4
+ latin/cyrillic
+ latin/arabic
+ latin/greek
+ latin/hebrew
+ latin5
+ latin6
+ latin/thai
+ latin7
+ latin8
+ latin9
+ latin10
+ koi8-r
+ windows-1252
+ ebcdic
+ mac-roman
+} ;
ABOUT: "io.encodings.8-bit"
ARTICLE: "io.encodings.ascii" "ASCII encoding"
"By default, if there's a non-ASCII character in an input stream, it will be replaced with a replacement character (U+FFFD), and if a non-ASCII character is used in output, an exception is thrown."
-{ $subsection ascii } ;
+{ $subsections ascii } ;
ABOUT: "io.encodings.ascii"
ARTICLE: "io.encodings.binary" "Binary encoding"
"Making an encoded stream with the binary encoding is a no-op; streams with this encoding deal with byte-arrays, not strings."
-{ $subsection binary } ;
+{ $subsections binary } ;
ABOUT: "io.encodings.binary"
{ $see-also "encodings-introduction" } ;
ARTICLE: "io.encodings.euc-kr" "EUC-KR encoding"
-{ $subsection euc-kr } ;
+{ $subsections euc-kr } ;
ABOUT: "io.encodings.euc-kr"
\ No newline at end of file
ARTICLE: "io.encodings.gb18030" "GB 18030"
"The " { $vocab-link "io.encodings.gb18030" } " vocabulary implements GB18030, a commonly used encoding for Chinese text besides the standard UTF encodings for Unicode strings."
-{ $subsection gb18030 } ;
+{ $subsections gb18030 } ;
ABOUT: "io.encodings.gb18030"
ARTICLE: "io.encodings.iana" "IANA-registered encoding names"
"The " { $vocab-link "io.encodings.iana" } " vocabulary provides words for accessing the names of encodings and the encoding descriptors corresponding to names." $nl
"Most text encodings in common use have been registered with IANA. There is a standard set of names for each encoding. Simple conversion functions:"
-{ $subsection name>encoding }
-{ $subsection encoding>name }
+{ $subsections
+ name>encoding
+ encoding>name
+}
"To let a new encoding be used with the above words, use the following:"
-{ $subsection register-encoding } ;
+{ $subsections register-encoding } ;
HELP: name>encoding
{ $values { "name" "an encoding name" } { "encoding" "an encoding descriptor" } }
{ $see-also "encodings-introduction" } ;
ARTICLE: "io.encodings.iso2022" "ISO 2022-JP-1 encoding"
-{ $subsection iso2022 } ;
+{ $subsections iso2022 } ;
ABOUT: "io.encodings.iso2022"
{ $class-description "Korean Johab encoding (KSC5601-1992). This encoding is not commonly used anymore." } ;
ARTICLE: "io.encodings.johab" "Korean Johab encoding"
-{ $subsection johab } ;
+{ $subsections johab } ;
ABOUT: "io.encodings.johab"
\ No newline at end of file
ARTICLE: "io.encodings.shift-jis" "Shift JIS"
"Shift JIS is a text encoding for Japanese. There are multiple versions, depending on whether the offical standard or the modified Microsoft version is required."
-{ $subsection shift-jis }
-{ $subsection windows-31j } ;
+{ $subsections
+ shift-jis
+ windows-31j
+} ;
ABOUT: "io.encodings.shift-jis"
ARTICLE: "io.encodings.string" "Encoding and decoding strings"
"Strings can be encoded or decoded to and from byte arrays through an encoding by passing "
{ $link "encodings-descriptors" } " to the following words:"
-{ $subsection encode }
-{ $subsection decode } ;
+{ $subsections
+ encode
+ decode
+} ;
HELP: decode
{ $values { "byte-array" byte-array } { "encoding" "an encoding descriptor" }
ARTICLE: "io.encodings.utf32" "UTF-32 encoding"
"The UTF-32 encoding is a fixed-width encoding. Unicode code points are encoded as 4 byte sequences. There are three encoding descriptor classes for working with UTF-32, depending on endianness or the presence of a BOM:"
-{ $subsection utf32 }
-{ $subsection utf32le }
-{ $subsection utf32be } ;
+{ $subsections
+ utf32
+ utf32le
+ utf32be
+} ;
ABOUT: "io.encodings.utf32"
ARTICLE: "io.files.info" "File system meta-data"
"File meta-data:"
-{ $subsection file-info }
-{ $subsection link-info }
-{ $subsection exists? }
-{ $subsection directory? }
+{ $subsections
+ file-info
+ link-info
+ exists?
+ directory?
+}
"File types:"
-{ $subsection "file-types" }
+{ $subsections "file-types" }
"File system meta-data:"
-{ $subsection file-system-info }
-{ $subsection file-systems } ;
+{ $subsections
+ file-system-info
+ file-systems
+} ;
ABOUT: "io.files.info"
ARTICLE: "unix-file-permissions" "Unix file permissions"
"Reading all file permissions:"
-{ $subsection file-permissions }
+{ $subsections file-permissions }
"Reading individual file permissions:"
-{ $subsection uid? }
-{ $subsection gid? }
-{ $subsection sticky? }
-{ $subsection user-read? }
-{ $subsection user-write? }
-{ $subsection user-execute? }
-{ $subsection group-read? }
-{ $subsection group-write? }
-{ $subsection group-execute? }
-{ $subsection other-read? }
-{ $subsection other-write? }
-{ $subsection other-execute? }
+{ $subsections
+ uid?
+ gid?
+ sticky?
+ user-read?
+ user-write?
+ user-execute?
+ group-read?
+ group-write?
+ group-execute?
+ other-read?
+ other-write?
+ other-execute?
+}
"Writing all file permissions:"
-{ $subsection set-file-permissions }
+{ $subsections set-file-permissions }
"Writing individual file permissions:"
-{ $subsection set-uid }
-{ $subsection set-gid }
-{ $subsection set-sticky }
-{ $subsection set-user-read }
-{ $subsection set-user-write }
-{ $subsection set-user-execute }
-{ $subsection set-group-read }
-{ $subsection set-group-write }
-{ $subsection set-group-execute }
-{ $subsection set-other-read }
-{ $subsection set-other-write }
-{ $subsection set-other-execute } ;
+{ $subsections
+ set-uid
+ set-gid
+ set-sticky
+ set-user-read
+ set-user-write
+ set-user-execute
+ set-group-read
+ set-group-write
+ set-group-execute
+ set-other-read
+ set-other-write
+ set-other-execute
+} ;
ARTICLE: "unix-file-timestamps" "Unix file timestamps"
"To read file times, use the accessors on the object returned by the " { $link file-info } " word." $nl
"Setting multiple file times:"
-{ $subsection set-file-times }
+{ $subsections set-file-times }
"Setting just the last access time:"
-{ $subsection set-file-access-time }
+{ $subsections set-file-access-time }
"Setting just the last modified time:"
-{ $subsection set-file-modified-time } ;
+{ $subsections set-file-modified-time } ;
ARTICLE: "unix-file-ids" "Unix file user and group ids"
"Reading file user data:"
-{ $subsection file-user-id }
-{ $subsection file-user-name }
+{ $subsections
+ file-user-id
+ file-user-name
+}
"Setting file user data:"
-{ $subsection set-file-user }
+{ $subsections set-file-user }
"Reading file group data:"
-{ $subsection file-group-id }
-{ $subsection file-group-name }
+{ $subsections
+ file-group-id
+ file-group-name
+}
"Setting file group data:"
-{ $subsection set-file-group } ;
+{ $subsections set-file-group } ;
ARTICLE: "io.files.info.unix" "Unix file attributes"
"The " { $vocab-link "io.files.info.unix" } " vocabulary implements a high-level way to set Unix-specific permissions, timestamps, and user and group IDs for files."
-{ $subsection "unix-file-permissions" }
-{ $subsection "unix-file-timestamps" }
-{ $subsection "unix-file-ids" } ;
+{ $subsections
+ "unix-file-permissions"
+ "unix-file-timestamps"
+ "unix-file-ids"
+} ;
ABOUT: "io.files.info.unix"
ARTICLE: "io.files.links" "Symbolic links"
"Reading links:"
-{ $subsection read-link }
-{ $subsection follow-link }
-{ $subsection follow-links }
+{ $subsections
+ read-link
+ follow-link
+ follow-links
+}
"Creating links:"
-{ $subsection make-link }
+{ $subsections make-link }
"Copying links:"
-{ $subsection copy-link }
+{ $subsections copy-link }
"Not all operating systems support symbolic links."
{ $see-also link-info } ;
ARTICLE: "io.files.temp" "Temporary files"
"Pathnames relative to Factor's temporary files directory:"
-{ $subsection temp-directory }
-{ $subsection temp-file } ;
+{ $subsections
+ temp-directory
+ temp-file
+} ;
ABOUT: "io.files.temp"
ARTICLE: "file-types" "File types"
"Platform-independent types:"
-{ $subsection +regular-file+ }
-{ $subsection +directory+ }
+{ $subsections
+ +regular-file+
+ +directory+
+}
"Platform-specific types:"
-{ $subsection +character-device+ }
-{ $subsection +block-device+ }
-{ $subsection +fifo+ }
-{ $subsection +symbolic-link+ }
-{ $subsection +socket+ }
-{ $subsection +unknown+ } ;
+{ $subsections
+ +character-device+
+ +block-device+
+ +fifo+
+ +symbolic-link+
+ +socket+
+ +unknown+
+} ;
ABOUT: "file-types"
ARTICLE: "io.files.unique" "Unique files"
"The " { $vocab-link "io.files.unique" } " vocabulary implements cross-platform unique file creation in temporary directories in a high-level and secure way." $nl
"Changing the temporary path:"
-{ $subsection current-temporary-directory }
+{ $subsections current-temporary-directory }
"Creating unique files:"
-{ $subsection unique-file }
-{ $subsection cleanup-unique-file }
-{ $subsection make-unique-file }
+{ $subsections
+ unique-file
+ cleanup-unique-file
+ make-unique-file
+}
"Creating unique directories:"
-{ $subsection unique-directory }
-{ $subsection with-unique-directory }
-{ $subsection cleanup-unique-directory }
+{ $subsections
+ unique-directory
+ with-unique-directory
+ cleanup-unique-directory
+}
"Default temporary directory:"
-{ $subsection default-temporary-directory } ;
+{ $subsections default-temporary-directory } ;
ABOUT: "io.files.unique"
ARTICLE: "io.launcher.detached" "Running processes in the background"
"By default, " { $link run-process } " waits for the process to complete. To run a process without waiting for it to finish, set the " { $snippet "detached" } " slot of a " { $link process } ", or use the following word:"
-{ $subsection run-detached } ;
+{ $subsections run-detached } ;
ARTICLE: "io.launcher.environment" "Setting environment variables"
"The " { $snippet "environment" } " slot of a " { $link process } " contains an association mapping environment variable names to values. The interpretation of environment variables is operating system-specific."
$nl
"The " { $snippet "environment-mode" } " slot controls how the environment of the current Factor instance is composed with the value of the " { $snippet "environment" } " slot:"
-{ $subsection +prepend-environment+ }
-{ $subsection +replace-environment+ }
-{ $subsection +append-environment+ }
+{ $subsections
+ +prepend-environment+
+ +replace-environment+
+ +append-environment+
+}
"The default value is " { $link +append-environment+ } "." ;
ARTICLE: "io.launcher.redirection" "Input/output redirection"
ARTICLE: "io.launcher.lifecycle" "The process lifecycle"
"A freshly instantiated " { $link process } " represents a set of launch parameters."
-{ $subsection process }
-{ $subsection <process> }
+{ $subsections
+ process
+ <process>
+}
"Words for launching processes take a fresh process which has never been started before as input, and output a copy as output."
-{ $subsection process-started? }
+{ $subsections process-started? }
"The " { $link process } " instance output by launching words contains all original slot values in addition to the " { $snippet "handle" } " slot, which indicates the process is currently running."
-{ $subsection process-running? }
+{ $subsections process-running? }
"It is possible to wait for a process to exit:"
-{ $subsection wait-for-process }
+{ $subsections wait-for-process }
"A running process can also be killed:"
-{ $subsection kill-process } ;
+{ $subsections kill-process } ;
ARTICLE: "io.launcher.launch" "Launching processes"
"Launching processes:"
-{ $subsection run-process }
-{ $subsection try-process }
-{ $subsection run-detached }
+{ $subsections
+ run-process
+ try-process
+ run-detached
+}
"Redirecting standard input and output to a pipe:"
-{ $subsection <process-reader> }
-{ $subsection <process-writer> }
-{ $subsection <process-stream> }
+{ $subsections
+ <process-reader>
+ <process-writer>
+ <process-stream>
+}
"Combinators built on top of the above:"
-{ $subsection with-process-reader }
-{ $subsection with-process-writer }
-{ $subsection with-process-stream } ;
+{ $subsections
+ with-process-reader
+ with-process-writer
+ with-process-stream
+} ;
ARTICLE: "io.launcher.examples" "Launcher examples"
"Starting a command and waiting for it to finish:"
ARTICLE: "io.launcher" "Operating system processes"
"The " { $vocab-link "io.launcher" } " vocabulary implements cross-platform process launching."
-{ $subsection "io.launcher.examples" }
-{ $subsection "io.launcher.descriptors" }
-{ $subsection "io.launcher.launch" }
+{ $subsections
+ "io.launcher.examples"
+ "io.launcher.descriptors"
+ "io.launcher.launch"
+}
"Advanced topics:"
-{ $subsection "io.launcher.lifecycle" }
-{ $subsection "io.launcher.command" }
-{ $subsection "io.launcher.detached" }
-{ $subsection "io.launcher.environment" }
-{ $subsection "io.launcher.redirection" }
-{ $subsection "io.launcher.priority" }
-{ $subsection "io.launcher.timeouts" } ;
+{ $subsections
+ "io.launcher.lifecycle"
+ "io.launcher.command"
+ "io.launcher.detached"
+ "io.launcher.environment"
+ "io.launcher.redirection"
+ "io.launcher.priority"
+ "io.launcher.timeouts"
+} ;
ABOUT: "io.launcher"
ARTICLE: "io.mmap.arrays" "Working with memory-mapped data"
"The " { $link <mapped-file> } " word returns an instance of " { $link mapped-file } ", which doesn't directly support the sequence protocol. Instead, it needs to be wrapped in a specialized array of the appropriate C type:"
-{ $subsection <mapped-array> }
+{ $subsections <mapped-array> }
"The appropriate specialized array type must first be generated with " { $link POSTPONE: SPECIALIZED-ARRAY: } "."
$nl
"Data can also be read and written from the " { $link mapped-file } " by applying low-level alien words to the " { $slot "address" } " slot. This approach is not recommended, though, since in most cases the compiler will generate efficient code for specialized array usage. See " { $link "reading-writing-memory" } " for a description of low-level memory access primitives." ;
ARTICLE: "io.mmap" "Memory-mapped files"
"The " { $vocab-link "io.mmap" } " vocabulary implements support for memory-mapped files."
-{ $subsection <mapped-file> }
+{ $subsections <mapped-file> }
"Memory-mapped files are disposable and can be closed with " { $link dispose } " or " { $link with-disposal } ". A utility combinator which wraps the above:"
-{ $subsection with-mapped-file }
+{ $subsections with-mapped-file }
"Instances of " { $link mapped-file } " don't support any interesting operations in themselves. There are two facilities for accessing their contents:"
-{ $subsection "io.mmap.arrays" }
-{ $subsection "io.mmap.examples" } ;
+{ $subsections
+ "io.mmap.arrays"
+ "io.mmap.examples"
+} ;
ABOUT: "io.mmap"
\r
ARTICLE: "io.monitors.descriptors" "File system change descriptors"\r
"The " { $link next-change } " word outputs instances of a class:"\r
-{ $subsection file-change }\r
+{ $subsections file-change }\r
"The " { $slot "changed" } " slot holds a sequence which may contain any of the following symbols:"\r
-{ $subsection +add-file+ }\r
-{ $subsection +remove-file+ }\r
-{ $subsection +modify-file+ }\r
-{ $subsection +rename-file-old+ }\r
-{ $subsection +rename-file-new+ }\r
-{ $subsection +rename-file+ } ;\r
+{ $subsections\r
+ +add-file+\r
+ +remove-file+\r
+ +modify-file+\r
+ +rename-file-old+\r
+ +rename-file-new+\r
+ +rename-file+\r
+} ;\r
\r
ARTICLE: "io.monitors.platforms" "Monitors on different platforms"\r
"Whether the " { $slot "path" } " slot of a " { $link file-change } " contains an absolute path or a path relative to the path given to " { $link <monitor> } " is unspecified, and may even vary on the same platform. User code should not assume either case."\r
"File system change monitors listen for changes to file names, attributes and contents under a specified directory. They can optionally be recursive, in which case subdirectories are also monitored."\r
$nl\r
"Monitoring operations must be wrapped in a combinator:"\r
-{ $subsection with-monitors }\r
+{ $subsections with-monitors }\r
"Creating a file system change monitor and listening for changes:"\r
-{ $subsection <monitor> }\r
-{ $subsection next-change }\r
+{ $subsections\r
+ <monitor>\r
+ next-change\r
+}\r
"An alternative programming style is where instead of having a thread listen for changes on a monitor, change notifications are posted to a mailbox:"\r
-{ $subsection (monitor) }\r
-{ $subsection "io.monitors.descriptors" }\r
-{ $subsection "io.monitors.platforms" } \r
+{ $subsections\r
+ (monitor)\r
+ "io.monitors.descriptors"\r
+ "io.monitors.platforms"\r
+}\r
"Monitors are closed by calling " { $link dispose } " or " { $link with-disposal } ". An easy way to pair construction with disposal is to use a combinator:"\r
-{ $subsection with-monitor }\r
+{ $subsections with-monitor }\r
"Monitors support the " { $link "io.timeouts" } "."\r
$nl\r
"An example which watches a directory for changes:"\r
"A " { $emphasis "pipe" } " is a unidirectional channel for transfer of bytes. Data written to one end of the pipe can be read from the other. Pipes can be used to pass data between processes; they can also be used within a single process to implement communication between coroutines."
$nl
"Low-level pipes:"
-{ $subsection pipe }
-{ $subsection (pipe) }
+{ $subsections
+ pipe
+ (pipe)
+}
"High-level pipe streams:"
-{ $subsection <pipe> }
"Pipelines of coroutines and processes:"
-{ $subsection run-pipeline } ;
+{ $subsections run-pipeline } ;
ABOUT: "io.pipes"
"Connection pools are implemented in the " { $snippet "io.pools" } " vocabulary. They are used to reuse sockets and connections which may be potentially expensive to create and destroy."
$nl
"The class of connection pools:"
-{ $subsection pool }
+{ $subsections pool }
"Creating connection pools:"
-{ $subsection <pool> }
"A utility combinator:"
-{ $subsection with-pool }
+{ $subsections with-pool }
"Acquiring and returning connections, and a utility combinator:"
-{ $subsection acquire-connection }
-{ $subsection return-connection }
-{ $subsection with-pooled-connection }
+{ $subsections
+ acquire-connection
+ return-connection
+ with-pooled-connection
+}
"Pools are not created directly, instead one uses subclasses which implement a generic word:"
-{ $subsection make-connection }
+{ $subsections make-connection }
"One example is a datagram socket pool:"
-{ $subsection datagram-pool }
-{ $subsection <datagram-pool> } ;
+{ $subsections
+ datagram-pool
+ <datagram-pool>
+} ;
ABOUT: "io.pools"
"On Windows and Unix, Factor implements blocking file and network streams on top of a non-blocking I/O substrate, ensuring that Factor threads will yield when performing I/O. This substrate is implemented in the " { $vocab-link "io.ports" } " vocabulary."
$nl
"A " { $emphasis "port" } " is a stream using non-blocking I/O substrate:"
-{ $subsection port }
-{ $subsection <port> }
-{ $subsection <buffered-port> }
+{ $subsections
+ port
+ <port>
+ <buffered-port>
+}
"Input ports:"
-{ $subsection input-port }
-{ $subsection <input-port> }
+{ $subsections
+ input-port
+ <input-port>
+}
"Output ports:"
-{ $subsection output-port }
-{ $subsection <output-port> }
+{ $subsections
+ output-port
+ <output-port>
+}
"Global native I/O protocol:"
-{ $subsection io-backend }
-{ $subsection init-io }
-{ $subsection init-stdio }
-{ $subsection io-multiplex }
+{ $subsections
+ io-backend
+ init-io
+ init-stdio
+ io-multiplex
+}
"Per-port native I/O protocol:"
-{ $subsection (wait-to-read) }
-{ $subsection (wait-to-write) }
+{ $subsections
+ (wait-to-read)
+ (wait-to-write)
+}
"Additionally, the I/O backend must provide an implementation of the " { $link dispose } " generic word." ;
ABOUT: "io.ports"
ARTICLE: "server-config" "Threaded server configuration"
"The " { $link threaded-server } " tuple has a variety of slots which can be set before starting the server with " { $link start-server } " or " { $link start-server* } "."
-{ $subsection "server-config-logging" }
-{ $subsection "server-config-listen" }
-{ $subsection "server-config-limit" }
-{ $subsection "server-config-stream" }
-{ $subsection "server-config-handler" } ;
+{ $subsections
+ "server-config-logging"
+ "server-config-listen"
+ "server-config-limit"
+ "server-config-stream"
+ "server-config-handler"
+} ;
ARTICLE: "server-config-logging" "Logging connections"
"The " { $snippet "name" } " slot of a threaded server instance should be set to a string naming the logging service name to use. See " { $link "logging" } " for details." ;
"The " { $snippet "secure" } " slot of a threaded server instance is interpreted in the same manner as the " { $snippet "insecure" } " slot, except that secure encrypted connections are then allowed. If this slot is set, the " { $snippet "secure-config" } " slot should also be set to a " { $link secure-config } " instance containing SSL server configuration. See " { $link "ssl-config" } " for details."
$nl
"Two utility words for producing address specifiers:"
-{ $subsection local-server }
-{ $subsection internet-server } ;
+{ $subsections
+ local-server
+ internet-server
+} ;
ARTICLE: "server-config-limit" "Limiting connections"
"The " { $snippet "max-connections" } " slot is initially set to " { $link f } ", which disables connection limiting, but can be set to an integer specifying the maximum number of simultaneous connections."
ARTICLE: "io.servers.connection" "Threaded servers"
"The " { $vocab-link "io.servers.connection" } " vocabulary implements a generic server abstraction for " { $link "network-connection" } ". A set of threads listen for connections, and additional threads are spawned for each client connection. In addition to this basic functionality, it provides some advanced features such as logging, connection limits and secure socket support."
-{ $subsection "server-examples" }
+{ $subsections "server-examples" }
"Creating threaded servers with client handler quotations:"
-{ $subsection <threaded-server> }
+{ $subsections <threaded-server> }
"Client handlers can also be implemented by subclassing a threaded server; see " { $link "server-config-handler" } " for details:"
-{ $subsection threaded-server }
-{ $subsection new-threaded-server }
-{ $subsection handle-client* }
+{ $subsections
+ threaded-server
+ new-threaded-server
+ handle-client*
+}
"The server must be configured before it can be started."
-{ $subsection "server-config" }
+{ $subsections "server-config" }
"Starting the server:"
-{ $subsection start-server }
-{ $subsection start-server* }
-{ $subsection wait-for-server }
+{ $subsections
+ start-server
+ start-server*
+ wait-for-server
+}
"Stopping the server:"
-{ $subsection stop-server }
+{ $subsections stop-server }
"From within the dynamic scope of a client handler, several words can be used to interact with the threaded server:"
-{ $subsection stop-this-server }
-{ $subsection secure-port }
-{ $subsection insecure-port }
+{ $subsections
+ stop-this-server
+ secure-port
+ insecure-port
+}
"Additionally, the " { $link local-address } " and "
-{ $subsection remote-address } " variables are set, as in " { $link with-client } "." ;
+{ $subsections remote-address } " variables are set, as in " { $link with-client } "." ;
ABOUT: "io.servers.connection"
ARTICLE: "ssl-methods" "SSL/TLS methods"
"The " { $snippet "method" } " slot of a " { $link secure-config } " can be set to one of the following values:"
-{ $subsection SSLv2 }
-{ $subsection SSLv23 }
-{ $subsection SSLv3 }
-{ $subsection TLSv1 }
+{ $subsections
+ SSLv2
+ SSLv23
+ SSLv3
+ TLSv1
+}
"The default value is " { $link SSLv23 } "." ;
HELP: secure-config
ARTICLE: "ssl-config" "Secure socket configuration"
"Secure sockets require some configuration, particularly for server sockets. A class represents secure socket configuration parameters:"
-{ $subsection secure-config }
+{ $subsections secure-config }
"Creating new instances:"
-{ $subsection <secure-config> }
+{ $subsections <secure-config> }
"Configuration parameters:"
-{ $subsection "ssl-methods" }
-{ $subsection "ssl-key-file" }
-{ $subsection "ssl-ca-file" }
-{ $subsection "ssl-dh-file" }
-{ $subsection "ssl-ephemeral-rsa" } ;
+{ $subsections
+ "ssl-methods"
+ "ssl-key-file"
+ "ssl-ca-file"
+ "ssl-dh-file"
+ "ssl-ephemeral-rsa"
+} ;
HELP: <secure-context>
{ $values { "config" secure-config } { "context" secure-context } }
ARTICLE: "ssl-contexts" "Secure socket contexts"
"All secure socket operations must be performed in a secure socket context. A context is created from a secure socket configuration. An implicit context with the default configuration is always available, however server sockets require a certificate to be set together with other parameters, and the default configuration is insufficient, so a context must be explicitly created in that case."
-{ $subsection with-secure-context } ;
+{ $subsections with-secure-context } ;
HELP: secure
{ $class-description "The class of secure socket addresses." } ;
"Secure socket connections are established by passing a secure socket address to " { $link <client> } " or " { $link <server> } "."
$nl
"Secure socket addresses form a class:"
-{ $subsection secure }
+{ $subsections secure }
"Constructing secure socket addresses:"
-{ $subsection <secure> }
+{ $subsections <secure> }
"Instances of this class can wrap an " { $link inet } ", " { $link inet4 } " or an " { $link inet6 } ", although note that certificate validation is only performed for instances of " { $link inet } " since otherwise the host name is not available." ;
HELP: send-secure-handshake
"Some protocols, such as HTTPS, require that the connection be established as an SSL/TLS connection. Others, such as secure SMTP and POP3 require that the client and server initiate an SSL/TLS handshake upon the client sending a plain-text request. The latter use-case is accomodated by a pair of words."
$nl
"Upgrading a connection to a secure socket by initiating an SSL/TLS handshake with the server:"
-{ $subsection send-secure-handshake }
+{ $subsections send-secure-handshake }
"Upgrading a connection to a secure socket by waiting for an SSL/TLS handshake from the client:"
-{ $subsection accept-secure-handshake } ;
+{ $subsections accept-secure-handshake } ;
HELP: premature-close
{ $error-description "Thrown if an SSL connection is closed without the proper " { $snippet "close_notify" } " sequence. This error is never reported for " { $link SSLv2 } " connections because there is no distinction between expected and unexpected connection closure in that case." } ;
ARTICLE: "ssl-errors" "Secure socket errors"
"Secure sockets can throw one of several errors in addition to the usual I/O errors:"
-{ $subsection premature-close }
-{ $subsection certificate-verify-error }
-{ $subsection common-name-verify-error }
+{ $subsections
+ premature-close
+ certificate-verify-error
+ common-name-verify-error
+}
"The " { $link send-secure-handshake } " word can throw one of two errors:"
-{ $subsection upgrade-on-non-socket }
-{ $subsection upgrade-buffers-full } ;
+{ $subsections
+ upgrade-on-non-socket
+ upgrade-buffers-full
+} ;
ARTICLE: "io.sockets.secure" "Secure sockets (SSL, TLS)"
"The " { $vocab-link "io.sockets.secure" } " vocabulary implements secure, encrypted sockets using the OpenSSL library."
"At present, this vocabulary only works on Unix, and not on Windows."
$nl
"This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (" { $url "http://www.openssl.org/" } "), cryptographic software written by Eric Young (eay@cryptsoft.com) and software written by Tim Hudson (tjh@cryptsoft.com)."
-{ $subsection "ssl-config" }
-{ $subsection "ssl-contexts" }
-{ $subsection "ssl-addresses" }
-{ $subsection "ssl-upgrade" }
-{ $subsection "ssl-errors" } ;
+{ $subsections
+ "ssl-config"
+ "ssl-contexts"
+ "ssl-addresses"
+ "ssl-upgrade"
+ "ssl-errors"
+} ;
ABOUT: "io.sockets.secure"
"The networking words are quite general and work with " { $emphasis "address specifiers" } " rather than concrete concepts such as host names. There are four types of address specifiers."
$nl
"Unix domain sockets:"
-{ $subsection local }
-{ $subsection <local> }
+{ $subsections
+ local
+ <local>
+}
"Internet host name/port number pairs; the host name is resolved to an IPv4 or IPv6 address using the operating system's resolver:"
-{ $subsection inet }
-{ $subsection <inet> }
+{ $subsections
+ inet
+ <inet>
+}
"IPv4 addresses, with no host name resolution:"
-{ $subsection inet4 }
-{ $subsection <inet4> }
+{ $subsections
+ inet4
+ <inet4>
+}
"IPv6 addresses, with no host name resolution:"
-{ $subsection inet6 }
-{ $subsection <inet6> }
+{ $subsections
+ inet6
+ <inet6>
+}
"While the " { $link inet } " addressing specifier is capable of performing name lookups when passed to " { $link <client> } ", sometimes it is necessary to look up a host name without making a connection:"
-{ $subsection resolve-host } ;
+{ $subsections resolve-host } ;
ARTICLE: "network-connection" "Connection-oriented networking"
"Network connections can be established with this word:"
-{ $subsection <client> }
-{ $subsection with-client }
+{ $subsections
+ <client>
+ with-client
+}
"Connection-oriented network servers are implemented by first opening a server socket, then waiting for connections:"
-{ $subsection <server> }
-{ $subsection accept }
+{ $subsections
+ <server>
+ accept
+}
"Server sockets are closed by calling " { $link dispose } "."
$nl
"Address specifiers have the following interpretation with connection-oriented networking words:"
ARTICLE: "network-packet" "Packet-oriented networking"
"A packet-oriented socket can be opened with this word:"
-{ $subsection <datagram> }
+{ $subsections <datagram> }
"Packets can be sent and received with a pair of words:"
-{ $subsection send }
-{ $subsection receive }
+{ $subsections
+ send
+ receive
+}
"Packet-oriented sockets are closed by calling " { $link dispose } "."
$nl
"Address specifiers have the following interpretation with packet-oriented networking words:"
"TCP/IP and UDP/IP, over IPv4 and IPv6"
"Unix domain sockets (Unix only)"
}
-{ $subsection "network-examples" }
-{ $subsection "network-addressing" }
-{ $subsection "network-connection" }
-{ $subsection "network-packet" }
+{ $subsections
+ "network-examples"
+ "network-addressing"
+ "network-connection"
+ "network-packet"
+}
{ $vocab-subsection "Secure sockets (SSL, TLS)" "io.sockets.secure" }
{ $see-also "io.pipes" } ;
ARTICLE: "io.streams.duplex" "Duplex streams"
"Duplex streams combine an input stream and an output stream into a bidirectional stream."
-{ $subsection duplex-stream }
-{ $subsection <duplex-stream> }
+{ $subsections
+ duplex-stream
+ <duplex-stream>
+}
"A pair of combinators for rebinding both default streams at once:"
-{ $subsection with-stream }
-{ $subsection with-stream* } ;
+{ $subsections
+ with-stream
+ with-stream*
+} ;
ABOUT: "io.streams.duplex"
ARTICLE: "io.streams.limited" "Limited input streams"
"The " { $vocab-link "io.streams.limited" } " vocabulary wraps a stream to behave as if it had only a limited number of bytes, either throwing an error or returning " { $link f } " upon reaching the end." $nl
"Wrap a stream in a limited stream:"
-{ $subsection limit }
+{ $subsections limit }
"Wrap the current " { $link input-stream } " in a limited stream:"
-{ $subsection limit-input }
+{ $subsections limit-input }
"Unlimits a limited stream:"
-{ $subsection unlimited }
+{ $subsections unlimited }
"Unlimits the current " { $link input-stream } ":"
-{ $subsection unlimited-input }
+{ $subsections unlimited-input }
"Make a limited stream throw an exception on exhaustion:"
-{ $subsection stream-throws }
+{ $subsections stream-throws }
"Make a limited stream return " { $link f } " on exhaustion:"
-{ $subsection stream-eofs } ;
+{ $subsections stream-eofs } ;
ABOUT: "io.streams.limited"
"The " { $vocab-link "io.streams.null" } " vocabulary implements a pair of streams which are useful for testing. The null reader always yields EOF and the null writer ignores all output. Conceptually, they are similar to " { $snippet "/dev/null" } " on a Unix system."
$nl
"Null readers:"
-{ $subsection null-reader }
-{ $subsection with-null-writer }
+{ $subsections
+ null-reader
+ with-null-writer
+}
"Null writers:"
-{ $subsection null-writer }
-{ $subsection with-null-reader } ;
+{ $subsections
+ null-writer
+ with-null-reader
+} ;
ABOUT: "io.streams.null"
\ No newline at end of file
ARTICLE: "io.streams.string" "String streams"
"String streams:"
-{ $subsection <string-reader> }
-{ $subsection <string-writer> }
+{ $subsections
+ <string-reader>
+ <string-writer>
+}
"Utility combinators:"
-{ $subsection with-string-reader }
-{ $subsection with-string-writer } ;
+{ $subsections
+ with-string-reader
+ with-string-writer
+} ;
ABOUT: "io.streams.string"
ARTICLE: "formatted-stream-protocol" "Formatted stream protocol"
"The " { $vocab-link "io.styles" } " vocabulary defines a protocol for output streams that support rich text."
-{ $subsection stream-format }
-{ $subsection make-span-stream }
-{ $subsection make-block-stream }
-{ $subsection make-cell-stream }
-{ $subsection stream-write-table } ;
+{ $subsections
+ stream-format
+ make-span-stream
+ make-block-stream
+ make-cell-stream
+ stream-write-table
+} ;
ARTICLE: "formatted-stdout" "Formatted output on the default stream"
"The below words perform formatted output on " { $link output-stream } "."
$nl
"Formatted output:"
-{ $subsection format }
-{ $subsection with-style }
-{ $subsection with-nesting }
+{ $subsections
+ format
+ with-style
+ with-nesting
+}
"Tabular output:"
-{ $subsection tabular-output }
-{ $subsection with-row }
-{ $subsection with-cell }
-{ $subsection write-cell } ;
+{ $subsections
+ tabular-output
+ with-row
+ with-cell
+ write-cell
+} ;
HELP: href
{ $description "Character style. A URL string that the text links to." } ;
ARTICLE: "character-styles" "Character styles"
"Character styles for " { $link stream-format } " and " { $link with-style } ":"
-{ $subsection foreground }
-{ $subsection background }
-{ $subsection font-name }
-{ $subsection font-size }
-{ $subsection font-style }
+{ $subsections
+ foreground
+ background
+ font-name
+ font-size
+ font-style
+}
"Special styles:"
-{ $subsection href }
-{ $subsection image }
+{ $subsections
+ href
+ image
+}
{ $see-also "presentations" } ;
ARTICLE: "paragraph-styles" "Paragraph styles"
"Paragraph styles for " { $link with-nesting } ":"
-{ $subsection page-color }
-{ $subsection border-color }
-{ $subsection inset }
-{ $subsection wrap-margin }
-{ $subsection presented } ;
+{ $subsections
+ page-color
+ border-color
+ inset
+ wrap-margin
+ presented
+} ;
ARTICLE: "table-styles" "Table styles"
"Table styles for " { $link tabular-output } ":"
-{ $subsection table-gap }
-{ $subsection table-border } ;
+{ $subsections
+ table-gap
+ table-border
+} ;
HELP: write-object
{ $values { "str" string } { "obj" "an object" } }
ARTICLE: "presentations" "Presentations"
"A special style for " { $link format } " and " { $link with-nesting } ":"
-{ $subsection presented }
+{ $subsections presented }
"The " { $link presented } " style can be used to emit clickable objects. A utility word for outputting this style:"
-{ $subsection write-object } ;
+{ $subsections write-object } ;
ARTICLE: "styles" "Text styles"
"The " { $link stream-format } ", " { $link with-style } ", " { $link with-nesting } " and " { $link tabular-output } " words take a hashtable of style attributes. Output stream implementations are free to ignore style information."
$nl
"Style hashtables are keyed by symbols from the " { $vocab-link "io.styles" } " vocabulary."
-{ $subsection "character-styles" }
-{ $subsection "paragraph-styles" }
-{ $subsection "table-styles" }
-{ $subsection "presentations" } ;
+{ $subsections
+ "character-styles"
+ "paragraph-styles"
+ "table-styles"
+ "presentations"
+} ;
ARTICLE: "io.styles" "Formatted output"
"The " { $vocab-link "io.styles" } " vocabulary defines a protocol for formatted output. This is used by the prettyprinter, help system, and various developer tools. Implementations include " { $vocab-link "ui.gadgets.panes" } ", " { $vocab-link "html.streams" } ", and " { $vocab-link "io.streams.plain" } "."
-{ $subsection "formatted-stream-protocol" }
-{ $subsection "formatted-stdout" }
-{ $subsection "styles" } ;
+{ $subsections
+ "formatted-stream-protocol"
+ "formatted-stdout"
+ "styles"
+} ;
ABOUT: "io.styles"
{ $link make-span-stream } ", "
{ $link make-block-stream } " and "
{ $link make-cell-stream } "."
-{ $subsection plain-writer } ;
\ No newline at end of file
+{ $subsections plain-writer } ;
\ No newline at end of file
\r
ARTICLE: "io.timeouts" "I/O timeout protocol"\r
"Streams, processes and monitors support optional timeouts, which impose an upper bound on the length of time for which an operation on these objects can block. Timeouts are used in network servers to prevent malicious clients from holding onto connections forever, and to ensure that runaway processes get killed."\r
-{ $subsection timeout }\r
-{ $subsection set-timeout }\r
+{ $subsections\r
+ timeout\r
+ set-timeout\r
+}\r
"The I/O timeout protocol can be implemented by any class wishing to support timeouts on blocking operations."\r
-{ $subsection cancel-operation }\r
+{ $subsections cancel-operation }\r
"A combinator to be used in operations which can time out:"\r
-{ $subsection with-timeout }\r
+{ $subsections with-timeout }\r
{ $see-also "stream-protocol" "io.launcher" "io.monitors" } ;\r
\r
ABOUT: "io.timeouts"\r
USING: help.markup help.syntax ;
ARTICLE: "json" "JSON serialization"
-{ $subsection "json.reader" }
-{ $subsection "json.writer" } ;
+{ $subsections
+ "json.reader"
+ "json.writer"
+} ;
ABOUT: "json"
ARTICLE: "json.reader" "JSON reader"
"The " { $vocab-link "json.reader" } " vocabulary defines a word for parsing strings in JSON format."
-{ $subsection json> } ;
+{ $subsections json> } ;
ABOUT: "json.reader"
ARTICLE: "json.writer" "JSON writer"
"The " { $vocab-link "json.writer" } " vocabulary defines words for converting objects to JSON format."
-{ $subsection >json }
-{ $subsection json-print } ;
+{ $subsections
+ >json
+ json-print
+} ;
ABOUT: "json.writer"
\r
ARTICLE: "lcs" "LCS, diffing and distance"\r
"This vocabulary provides words for three apparently unrelated but in fact very similar problems: finding a longest common subsequence between two sequences, getting a minimal edit script (diff) between two sequences, and calculating the Levenshtein distance between two sequences. The implementations of these algorithms are very closely related, and all running times are O(nm), where n and m are the lengths of the input sequences."\r
-{ $subsection lcs }\r
-{ $subsection diff }\r
-{ $subsection levenshtein }\r
+{ $subsections\r
+ lcs\r
+ diff\r
+ levenshtein\r
+}\r
"The " { $link diff } " word returns a sequence of tuples of the following classes. They all hold their contents in the 'item' slot."\r
-{ $subsection insert }\r
-{ $subsection delete }\r
-{ $subsection retain } ;\r
+{ $subsections\r
+ insert\r
+ delete\r
+ retain\r
+} ;\r
\r
ABOUT: "lcs"\r
"A " { $emphasis "linked assoc" } " is an assoc which combines an underlying assoc with a dlist to form a structure which has the insertion and retrieval characteristics of the underlying assoc (typically a hashtable), but with the ability to get the entries in insertion order by calling " { $link >alist } "."
$nl
"Linked assocs are implemented in the " { $vocab-link "linked-assocs" } " vocabulary."
-{ $subsection linked-assoc }
-{ $subsection <linked-hash> }
-{ $subsection <linked-assoc> } ;
+{ $subsections
+ linked-assoc
+ <linked-hash>
+ <linked-assoc>
+} ;
ABOUT: "linked-assocs"
\ No newline at end of file
ARTICLE: "listener-watch" "Watching variables in the listener"
"The listener prints the concepts of the data and retain stacks after every expression. It can also print values of dynamic variables which are added to a watch list:"
-{ $subsection visible-vars }
+{ $subsections visible-vars }
"To add or remove a single variable:"
-{ $subsection show-var }
-{ $subsection hide-var }
+{ $subsections
+ show-var
+ hide-var
+}
"To add and remove multiple variables:"
-{ $subsection show-vars }
-{ $subsection hide-vars }
+{ $subsections
+ show-vars
+ hide-vars
+}
"Hiding all visible variables:"
-{ $subsection hide-all-vars } ;
+{ $subsections hide-all-vars } ;
HELP: only-use-vocabs
{ $values { "vocabs" "a sequence of vocabulary specifiers" } }
"Multi-line expressions are supported:"
{ $example "{ 1 2 3 } [\n .\n] each" "1\n2\n3" }
"The listener knows when to expect more input by looking at the height of the stack. Parsing words such as " { $link POSTPONE: { } " leave elements on the parser stack, and corresponding words such as " { $link POSTPONE: } } " pop them."
-{ $subsection "listener-watch" }
+{ $subsections "listener-watch" }
"To start a nested listener:"
-{ $subsection listener }
+{ $subsections listener }
"To exit the listener, invoke the " { $link return } " word."
$nl
"Multi-line quotations can be read independently of the rest of the listener:"
-{ $subsection read-quot } ;
+{ $subsections read-quot } ;
ABOUT: "listener"
ARTICLE: "lists.lazy" "Lazy lists"
"The " { $vocab-link "lists.lazy" } " vocabulary implements lazy lists and standard operations to manipulate them."
-{ $subsection { "lists.lazy" "construction" } }
-{ $subsection { "lists.lazy" "manipulation" } }
-{ $subsection { "lists.lazy" "combinators" } }
-{ $subsection { "lists.lazy" "io" } } ;
+{ $subsections
+ { "lists.lazy" "construction" }
+ { "lists.lazy" "manipulation" }
+ { "lists.lazy" "combinators" }
+ { "lists.lazy" "io" }
+} ;
ARTICLE: { "lists.lazy" "combinators" } "Combinators for manipulating lazy lists"
"The following combinators create lazy lists from other lazy lists:"
-{ $subsection lazy-map }
-{ $subsection lfilter }
-{ $subsection luntil }
-{ $subsection lwhile }
-{ $subsection lfrom-by }
-{ $subsection lcomp }
-{ $subsection lcomp* } ;
+{ $subsections
+ lazy-map
+ lfilter
+ luntil
+ lwhile
+ lfrom-by
+ lcomp
+ lcomp*
+} ;
ARTICLE: { "lists.lazy" "io" } "Lazy list I/O"
"Input from a stream can be read through a lazy list, using the following words:"
-{ $subsection lcontents }
-{ $subsection llines } ;
+{ $subsections
+ lcontents
+ llines
+} ;
ARTICLE: { "lists.lazy" "construction" } "Constructing lazy lists"
"Words for constructing lazy lists:"
-{ $subsection lazy-cons }
-{ $subsection 1lazy-list }
-{ $subsection 2lazy-list }
-{ $subsection 3lazy-list }
-{ $subsection sequence-tail>list }
-{ $subsection >list }
-{ $subsection lfrom } ;
+{ $subsections
+ lazy-cons
+ 1lazy-list
+ 2lazy-list
+ 3lazy-list
+ sequence-tail>list
+ >list
+ lfrom
+} ;
ARTICLE: { "lists.lazy" "manipulation" } "Manipulating lazy lists"
"To make new lazy lists from old ones:"
-{ $subsection <memoized-cons> }
-{ $subsection lappend }
-{ $subsection lconcat }
-{ $subsection lcartesian-product }
-{ $subsection lcartesian-product* }
-{ $subsection lmerge }
-{ $subsection ltake } ;
+{ $subsections
+ <memoized-cons>
+ lappend
+ lconcat
+ lcartesian-product
+ lcartesian-product*
+ lmerge
+ ltake
+} ;
HELP: lazy-cons
{ $values { "car" { $quotation "( -- elt )" } } { "cdr" { $quotation "( -- cons )" } } { "promise" "the resulting cons object" } }
ARTICLE: "lists" "Lists"
"The " { $vocab-link "lists" } " vocabulary implements linked lists. There are simple strict linked lists, but a generic list protocol allows the implementation of lazy lists as well."
-{ $subsection { "lists" "protocol" } }
-{ $subsection { "lists" "strict" } }
-{ $subsection { "lists" "manipulation" } }
-{ $subsection { "lists" "combinators" } }
+{ $subsections
+ { "lists" "protocol" }
+ { "lists" "strict" }
+ { "lists" "manipulation" }
+ { "lists" "combinators" }
+}
{ $vocab-subsection "Lazy lists" "lists.lazy" } ;
ARTICLE: { "lists" "protocol" } "The list protocol"
"Lists are instances of a mixin class:"
-{ $subsection list }
+{ $subsections list }
"Instances of the mixin must implement the following words:"
-{ $subsection car }
-{ $subsection cdr }
-{ $subsection nil? } ;
+{ $subsections
+ car
+ cdr
+ nil?
+} ;
ARTICLE: { "lists" "strict" } "Constructing strict lists"
"Strict lists are simply cons cells where the car and cdr have already been evaluated. These are the lists of Lisp. To construct a strict list, the following words are provided:"
-{ $subsection cons }
-{ $subsection swons }
-{ $subsection sequence>list }
-{ $subsection 1list }
-{ $subsection 2list }
-{ $subsection 3list } ;
+{ $subsections
+ cons
+ swons
+ sequence>list
+ 1list
+ 2list
+ 3list
+} ;
ARTICLE: { "lists" "combinators" } "Combinators for lists"
"Several combinators exist for list traversal."
-{ $subsection leach }
-{ $subsection lmap }
-{ $subsection foldl }
-{ $subsection foldr }
-{ $subsection lmap>array }
-{ $subsection traverse } ;
+{ $subsections
+ leach
+ lmap
+ foldl
+ foldr
+ lmap>array
+ traverse
+} ;
ARTICLE: { "lists" "manipulation" } "Manipulating lists"
"To get at the contents of a list:"
-{ $subsection uncons }
-{ $subsection unswons }
-{ $subsection lnth }
-{ $subsection cadr }
-{ $subsection llength }
+{ $subsections
+ uncons
+ unswons
+ lnth
+ cadr
+ llength
+}
"To get a new list from an old one:"
-{ $subsection lreverse }
-{ $subsection lappend }
-{ $subsection lcut } ;
+{ $subsections
+ lreverse
+ lappend
+ lcut
+} ;
HELP: cons
{ $values { "car" "the head of the list cell" } { "cdr" "the tail of the list cell" } { "cons" list } }
CONSTANT: five 5
{ $ five $[ five dup 1 + dup 2 + ] } .
""" "{ 5 5 6 8 }" }
-{ $subsection POSTPONE: $ }
-{ $subsection POSTPONE: $[ }
-{ $subsection POSTPONE: ${ }
-;
+{ $subsections
+ POSTPONE: $
+ POSTPONE: $[
+ POSTPONE: ${
+} ;
ABOUT: "literals"
"Compile-time transformation is used to compile local variables to efficient code; prettyprinter extensions are defined so that " { $link see } " can display original word definitions with local variables and not the closure-converted concatenative code which results."
$nl
"Applicative word definitions where the inputs are named local variables:"
-{ $subsection POSTPONE: :: }
-{ $subsection POSTPONE: M:: }
-{ $subsection POSTPONE: MEMO:: }
-{ $subsection POSTPONE: MACRO:: }
+{ $subsections
+ POSTPONE: ::
+ POSTPONE: M::
+ POSTPONE: MEMO::
+ POSTPONE: MACRO::
+}
"Lexical binding forms:"
-{ $subsection POSTPONE: [let }
-{ $subsection POSTPONE: [let* }
-{ $subsection POSTPONE: [wlet }
+{ $subsections
+ POSTPONE: [let
+ POSTPONE: [let*
+ POSTPONE: [wlet
+}
"Lambda abstractions:"
-{ $subsection POSTPONE: [| }
+{ $subsections POSTPONE: [| }
"Lightweight binding form:"
-{ $subsection POSTPONE: :> }
+{ $subsections POSTPONE: :> }
"Additional topics:"
-{ $subsection "locals-literals" }
-{ $subsection "locals-mutable" }
-{ $subsection "locals-fry" }
-{ $subsection "locals-limitations" }
+{ $subsections
+ "locals-literals"
+ "locals-mutable"
+ "locals-fry"
+ "locals-limitations"
+}
"Locals complement dynamically scoped variables implemented in the " { $vocab-link "namespaces" } " vocabulary." ;
ABOUT: "locals"
"The " { $vocab-link "logging.analysis" } " vocabulary builds on the " { $vocab-link "logging.parser" } " vocabulary. It parses log files and produces formatted summary reports. It is used by the " { $vocab-link "logging.insomniac" } " vocabulary to e-mail daily reports."
$nl
"Print log file summary:"
-{ $subsection analyze-log }
+{ $subsections analyze-log }
"Factors:"
-{ $subsection analyze-entries }
-{ $subsection analysis. } ;
+{ $subsections
+ analyze-entries
+ analysis.
+} ;
ABOUT: "logging.analysis"
"The " { $vocab-link "logging.insomniac" } " vocabulary builds on the " { $vocab-link "logging.analysis" } " vocabulary. It provides support for e-mailing log reports and rotating logs on a daily basis. E-mails are sent using the " { $vocab-link "smtp" } " vocabulary."
$nl
"Required configuration parameters:"
-{ $subsection insomniac-sender }
-{ $subsection insomniac-recipients }
+{ $subsections
+ insomniac-sender
+ insomniac-recipients
+}
"E-mailing a one-off report:"
-{ $subsection email-log-report }
+{ $subsections email-log-report }
"E-mailing reports and rotating logs on a daily basis:"
-{ $subsection schedule-insomniac } ;
+{ $subsections schedule-insomniac } ;
ABOUT: "logging.insomniac"
ARTICLE: "logging.levels" "Log levels"
"Several log levels are supported, from lowest to highest:"
-{ $subsection DEBUG }
-{ $subsection NOTICE }
-{ $subsection WARNING }
-{ $subsection ERROR }
-{ $subsection CRITICAL } ;
+{ $subsections
+ DEBUG
+ NOTICE
+ WARNING
+ ERROR
+ CRITICAL
+} ;
ARTICLE: "logging.files" "Log files"
"Each application that wishes to use logging must choose a log service name; the following combinator should wrap the top level of the application:"
-{ $subsection with-logging }
+{ $subsections with-logging }
"Log messages are written to " { $snippet "log-root/service/1.log" } ", where"
{ $list
{ { $snippet "log-root" } " is the Factor source directory by default, but can be overriden with the " { $link log-root } " variable" }
{ { $snippet "service" } " is the service name" }
}
"You can get the log path for a service:"
-{ $subsection log-path }
-{ $subsection log# }
+{ $subsections
+ log-path
+ log#
+}
"New log entries are always sent to " { $snippet "1.log" } " but " { $link "logging.rotation" } " moves " { $snippet "1.log" } " to " { $snippet "2.log" } ", " { $snippet "2.log" } " to " { $snippet "3.log" } ", and so on." ;
HELP: log-message
ARTICLE: "logging.messages" "Logging messages"
"Logging messages explicitly:"
-{ $subsection log-message }
-{ $subsection log-error }
-{ $subsection log-critical }
+{ $subsections
+ log-message
+ log-error
+ log-critical
+}
"A utility for defining words which just log and do nothing else:"
-{ $subsection POSTPONE: LOG: }
+{ $subsections POSTPONE: LOG: }
"Annotating words to log; this uses the " { $link "tools.annotations" } " feature:"
-{ $subsection add-input-logging }
-{ $subsection add-output-logging }
-{ $subsection add-error-logging } ;
+{ $subsections
+ add-input-logging
+ add-output-logging
+ add-error-logging
+} ;
HELP: rotate-logs
{ $description "Rotates all logs. The highest numbered log file in each log directory is deleted, and each file is renamed so that its number increments by one. Subsequent logging calls will create a new #1 log file. This keeps log files from getting too large and makes them easier to search." } ;
ARTICLE: "logging.rotation" "Log rotation"
"Log files should be rotated periodically to prevent unbounded growth."
-{ $subsection rotate-logs }
-{ $subsection close-logs }
+{ $subsections
+ rotate-logs
+ close-logs
+}
"The " { $vocab-link "logging.insomniac" } " vocabulary automates log rotation." ;
ARTICLE: "logging.server" "Log implementation"
"The " { $vocab-link "logging.server" } " vocabulary implements a concurrent log server using " { $vocab-link "concurrency.messaging" } ". User code never interacts with the server directly, instead it uses the words in the " { $link "logging" } " vocabulary. The server is used to synchronize access to log files and ensure that log rotation can proceed in an orderly fashion."
$nl
"The " { $link log-message } " word sends a message to the server which results in the server executing an internal word:"
-{ $subsection (log-message) }
+{ $subsections (log-message) }
"The " { $link rotate-logs } " word sends a message to the server which results in the server executing an internal word:"
-{ $subsection (rotate-logs) }
+{ $subsections (rotate-logs) }
"The " { $link close-logs } " word sends a message to the server which results in the server executing an internal word:"
-{ $subsection (close-logs) } ;
+{ $subsections (close-logs) } ;
ARTICLE: "logging" "Logging framework"
"The " { $vocab-link "logging" } " vocabulary implements a comprehensive logging framework suitable for server-side production applications."
-{ $subsection "logging.files" }
-{ $subsection "logging.levels" }
-{ $subsection "logging.messages" }
-{ $subsection "logging.rotation" }
-{ $subsection "logging.parser" }
-{ $subsection "logging.analysis" }
-{ $subsection "logging.server" } ;
+{ $subsections
+ "logging.files"
+ "logging.levels"
+ "logging.messages"
+ "logging.rotation"
+ "logging.parser"
+ "logging.analysis"
+ "logging.server"
+} ;
ABOUT: "logging"
"The " { $vocab-link "logging.parser" } " vocabulary parses log files output by the " { $vocab-link "logging" } " vocabulary. It is used by " { $link "logging.analysis" } " and " { $vocab-link "logging.insomniac" } " to analyze logs."
$nl
"There is only one primary entry point:"
-{ $subsection parse-log } ;
+{ $subsections parse-log } ;
ABOUT: "logging.parser"
"Factor macros are similar to Lisp macros; they are not like C preprocessor macros."
$nl
"Defining new macros:"
-{ $subsection POSTPONE: MACRO: }
+{ $subsections POSTPONE: MACRO: }
"A slightly lower-level facility, " { $emphasis "compiler transforms" } ", allows an ordinary word definition to co-exist with a version that performs compile-time expansion."
-{ $subsection define-transform }
+{ $subsections define-transform }
"An example is the " { $link member? } " word. If the input sequence is a literal, the compile transform kicks in and converts the " { $link member? } " call into a series of conditionals. Otherwise, if the input sequence is not literal, a call to the definition of " { $link member? } " is generated."
{ $see-also "generalizations" "fry" } ;
"The " { $vocab-link "match" } " vocabulary implements ML-style pattern matching."
$nl
"Variables used for pattern matching must be explicitly defined first:"
-{ $subsection POSTPONE: MATCH-VARS: }
+{ $subsections POSTPONE: MATCH-VARS: }
"A basic pattern match:"
-{ $subsection match }
+{ $subsections match }
"A conditional form analogous to " { $link cond } ":"
-{ $subsection match-cond }
+{ $subsections match-cond }
"Pattern replacement:"
-{ $subsection match-replace } ;
+{ $subsections match-replace } ;
ABOUT: "match"
ARTICLE: "math.bits" "Number bits virtual sequence"
"The " { $vocab-link "math.bits" } " vocabulary implements a virtual sequence which presents an integer as a sequence of bits, with the first element of the sequence being the least significant bit of the integer."
-{ $subsection bits }
-{ $subsection <bits> }
-{ $subsection make-bits } ;
+{ $subsections
+ bits
+ <bits>
+ make-bits
+} ;
HELP: bits
{ $class-description "Virtual sequence class of bits of a number. The first bit is the least significant bit. This can be constructed with " { $link <bits> } " or " { $link make-bits } "." } ;
} ;
HELP: flags
-{ $values
- { "values" sequence }
-}
+{ $values { "values" sequence } }
{ $description "Constructs a constant flag value from a sequence of integers or words that output integers. The resulting constant is computed at compile-time, which makes this word as efficient as using a literal integer." }
{ $examples
{ $example "USING: math.bitwise kernel prettyprint ;"
ARTICLE: "math-bitfields" "Constructing bit fields"
"Some applications, such as binary communication protocols and assemblers, need to construct integers from elaborate bit field specifications. Hand-coding this using " { $link shift } " and " { $link bitor } " results in repetitive code. A higher-level facility exists to factor out this repetition:"
-{ $subsection bitfield } ;
+{ $subsections bitfield } ;
ARTICLE: "math.bitwise" "Additional bitwise arithmetic"
"The " { $vocab-link "math.bitwise" } " vocabulary provides bitwise arithmetic words extending " { $link "bitwise-arithmetic" } ". They are useful for efficiency, low-level programming, and interfacing with C libraries."
$nl
"Setting and clearing bits:"
-{ $subsection set-bit }
-{ $subsection clear-bit }
+{ $subsections
+ set-bit
+ clear-bit
+}
"Testing if bits are set or clear:"
-{ $subsection bit? }
-{ $subsection bit-clear? }
+{ $subsections
+ bit?
+ bit-clear?
+}
"Operations with bitmasks:"
-{ $subsection mask }
-{ $subsection unmask }
-{ $subsection mask? }
-{ $subsection unmask? }
+{ $subsections
+ mask
+ unmask
+ mask?
+ unmask?
+}
"Generating an integer with n set bits:"
-{ $subsection on-bits }
+{ $subsections on-bits }
"Counting the number of set bits:"
-{ $subsection bit-count }
+{ $subsections bit-count }
"More efficient modding by powers of two:"
-{ $subsection wrap }
+{ $subsections wrap }
"Bit-rolling:"
-{ $subsection bitroll }
-{ $subsection bitroll-32 }
-{ $subsection bitroll-64 }
+{ $subsections
+ bitroll
+ bitroll-32
+ bitroll-64
+}
"32-bit arithmetic:"
-{ $subsection w+ }
-{ $subsection w- }
-{ $subsection w* }
+{ $subsections
+ w+
+ w-
+ w*
+}
"Bitfields:"
-{ $subsection flags }
-{ $subsection "math-bitfields" } ;
+{ $subsections
+ flags
+ "math-bitfields"
+} ;
ABOUT: "math.bitwise"
ARTICLE: "math.blas.config" "Configuring the BLAS interface"
"The " { $link "math.blas-summary" } " chooses the underlying BLAS interface to use based on the values of the following global variables:"
-{ $subsection blas-library }
-{ $subsection blas-fortran-abi }
+{ $subsections
+ blas-library
+ blas-fortran-abi
+}
"The interface attempts to set default values based on the ones encountered on the Factor project's build machines. If these settings don't work with your system's BLAS, or you wish to use a commercial BLAS, you may change the global values of those variables in your " { $link "factor-rc" } ". For example, to use AMD's ACML library on Windows with " { $snippet "math.blas" } ", your " { $snippet "factor-rc" } " would look like this:"
{ $code """
USING: math.blas.config namespaces ;
ARTICLE: "math.blas-summary" "Basic Linear Algebra Subroutines (BLAS) interface"
"Factor provides an interface to high-performance vector and matrix math routines available in implementations of the BLAS math library. A set of specialized types are provided for handling packed, unboxed vector data:"
-{ $subsection "math.blas-types" }
+{ $subsections "math.blas-types" }
"Scalar-vector and vector-vector operations are available in the " { $vocab-link "math.blas.vectors" } " vocabulary:"
-{ $subsection "math.blas.vectors" }
+{ $subsections "math.blas.vectors" }
"Vector-matrix and matrix-matrix operations are available in the " { $vocab-link "math.blas.matrices" } " vocabulary:"
-{ $subsection "math.blas.matrices" }
+{ $subsections "math.blas.matrices" }
"The low-level BLAS Fortran interface can be accessed directly through the " { $vocab-link "math.blas.ffi" } " vocabulary. The BLAS interface can be configured to use different underlying BLAS implementations:"
-{ $subsection "math.blas.config" } ;
+{ $subsections "math.blas.config" } ;
ARTICLE: "math.blas-types" "BLAS interface types"
"BLAS vectors come in single- and double-precision, real and complex flavors:"
-{ $subsection float-blas-vector }
-{ $subsection double-blas-vector }
-{ $subsection complex-float-blas-vector }
-{ $subsection complex-double-blas-vector }
+{ $subsections
+ float-blas-vector
+ double-blas-vector
+ complex-float-blas-vector
+ complex-double-blas-vector
+}
"These vector types all follow the " { $link sequence } " protocol. In addition, there are corresponding types for matrix data:"
-{ $subsection float-blas-matrix }
-{ $subsection double-blas-matrix }
-{ $subsection complex-float-blas-matrix }
-{ $subsection complex-double-blas-matrix }
+{ $subsections
+ float-blas-matrix
+ double-blas-matrix
+ complex-float-blas-matrix
+ complex-double-blas-matrix
+}
"There are BOA constructors for all vector and matrix types, which provide the most flexibility in specifying memory layout:"
-{ $subsection <float-blas-vector> }
-{ $subsection <double-blas-vector> }
-{ $subsection <complex-float-blas-vector> }
-{ $subsection <complex-double-blas-vector> }
-{ $subsection <float-blas-matrix> }
-{ $subsection <double-blas-matrix> }
-{ $subsection <complex-float-blas-matrix> }
-{ $subsection <complex-double-blas-matrix> }
+{ $subsections
+ <float-blas-vector>
+ <double-blas-vector>
+ <complex-float-blas-vector>
+ <complex-double-blas-vector>
+ <float-blas-matrix>
+ <double-blas-matrix>
+ <complex-float-blas-matrix>
+ <complex-double-blas-matrix>
+}
"For the simple case of creating a dense, zero-filled vector or matrix, simple empty object constructors are provided:"
-{ $subsection <empty-vector> }
-{ $subsection <empty-matrix> }
+{ $subsections
+ <empty-vector>
+ <empty-matrix>
+}
"BLAS vectors and matrices can also be constructed from other Factor sequences:"
-{ $subsection >float-blas-vector }
-{ $subsection >double-blas-vector }
-{ $subsection >complex-float-blas-vector }
-{ $subsection >complex-double-blas-vector }
-{ $subsection >float-blas-matrix }
-{ $subsection >double-blas-matrix }
-{ $subsection >complex-float-blas-matrix }
-{ $subsection >complex-double-blas-matrix } ;
+{ $subsections
+ >float-blas-vector
+ >double-blas-vector
+ >complex-float-blas-vector
+ >complex-double-blas-vector
+ >float-blas-matrix
+ >double-blas-matrix
+ >complex-float-blas-matrix
+ >complex-double-blas-matrix
+} ;
ARTICLE: "math.blas.matrices" "BLAS interface matrix operations"
"Transposing and slicing matrices:"
-{ $subsection Mtranspose }
-{ $subsection Mrows }
-{ $subsection Mcols }
-{ $subsection Msub }
+{ $subsections
+ Mtranspose
+ Mrows
+ Mcols
+ Msub
+}
"Matrix-vector products:"
-{ $subsection n*M.V+n*V! }
-{ $subsection n*M.V+n*V }
-{ $subsection n*M.V }
-{ $subsection M.V }
+{ $subsections
+ n*M.V+n*V!
+ n*M.V+n*V
+ n*M.V
+ M.V
+}
"Vector outer products:"
-{ $subsection n*V(*)V+M! }
-{ $subsection n*V(*)Vconj+M! }
-{ $subsection n*V(*)V+M }
-{ $subsection n*V(*)Vconj+M }
-{ $subsection n*V(*)V }
-{ $subsection n*V(*)Vconj }
-{ $subsection V(*) }
-{ $subsection V(*)conj }
+{ $subsections
+ n*V(*)V+M!
+ n*V(*)Vconj+M!
+ n*V(*)V+M
+ n*V(*)Vconj+M
+ n*V(*)V
+ n*V(*)Vconj
+ V(*)
+ V(*)conj
+}
"Matrix products:"
-{ $subsection n*M.M+n*M! }
-{ $subsection n*M.M+n*M }
-{ $subsection n*M.M }
-{ $subsection M. }
+{ $subsections
+ n*M.M+n*M!
+ n*M.M+n*M
+ n*M.M
+ M.
+}
"Scalar-matrix products:"
-{ $subsection n*M! }
-{ $subsection n*M }
-{ $subsection M*n }
-{ $subsection M/n }
+{ $subsections
+ n*M!
+ n*M
+ M*n
+ M/n
+}
"Literal syntax:"
-{ $subsection POSTPONE: smatrix{ }
-{ $subsection POSTPONE: dmatrix{ }
-{ $subsection POSTPONE: cmatrix{ }
-{ $subsection POSTPONE: zmatrix{ } ;
+{ $subsections
+ POSTPONE: smatrix{
+ POSTPONE: dmatrix{
+ POSTPONE: cmatrix{
+ POSTPONE: zmatrix{
+} ;
ABOUT: "math.blas.matrices"
ARTICLE: "math.blas.vectors" "BLAS interface vector operations"
"Slicing vectors:"
-{ $subsection Vsub }
+{ $subsections Vsub }
"Taking the norm (magnitude) of a vector:"
-{ $subsection Vnorm }
+{ $subsections Vnorm }
"Summing and taking the maximum of elements:"
-{ $subsection Vasum }
-{ $subsection Viamax }
-{ $subsection Vamax }
+{ $subsections
+ Vasum
+ Viamax
+ Vamax
+}
"Scalar-vector products:"
-{ $subsection n*V! }
-{ $subsection n*V }
-{ $subsection V*n }
-{ $subsection V/n }
-{ $subsection Vneg }
+{ $subsections
+ n*V!
+ n*V
+ V*n
+ V/n
+ Vneg
+}
"Vector addition:"
-{ $subsection n*V+V! }
-{ $subsection n*V+V }
-{ $subsection V+ }
-{ $subsection V- }
+{ $subsections
+ n*V+V!
+ n*V+V
+ V+
+ V-
+}
"Vector inner products:"
-{ $subsection V. }
-{ $subsection V.conj }
+{ $subsections
+ V.
+ V.conj
+}
"Literal syntax:"
-{ $subsection POSTPONE: svector{ }
-{ $subsection POSTPONE: dvector{ }
-{ $subsection POSTPONE: cvector{ }
-{ $subsection POSTPONE: zvector{ } ;
+{ $subsections
+ POSTPONE: svector{
+ POSTPONE: dvector{
+ POSTPONE: cvector{
+ POSTPONE: zvector{
+} ;
ABOUT: "math.blas.vectors"
"Unlike math, where all real numbers are also complex numbers, Factor only considers a number to be a complex number if its imaginary part is non-zero. However, complex number operations are fully supported for real numbers; they are treated as having an imaginary part of zero." ;
ARTICLE: "complex-numbers" "Complex numbers"
-{ $subsection complex }
+{ $subsections complex }
"Complex numbers arise as solutions to quadratic equations whose graph does not intersect the " { $emphasis "x" } " axis. Their literal syntax is covered in " { $link "syntax-complex-numbers" } "."
$nl
"Complex numbers can be taken apart:"
-{ $subsection real-part }
-{ $subsection imaginary-part }
-{ $subsection >rect }
+{ $subsections
+ real-part
+ imaginary-part
+ >rect
+}
"Complex numbers can be constructed from real numbers:"
-{ $subsection rect> }
-{ $subsection "complex-numbers-zero" }
+{ $subsections
+ rect>
+ "complex-numbers-zero"
+}
{ $see-also "syntax-complex-numbers" } ;
HELP: complex
{ $class-description "The class of complex numbers with non-zero imaginary part." } ;
ARTICLE: "math-constants" "Constants"
"Standard mathematical constants:"
-{ $subsection e }
-{ $subsection euler }
-{ $subsection phi }
-{ $subsection pi }
-{ $subsection epsilon }
-{ $subsection single-epsilon } ;
+{ $subsections
+ e
+ euler
+ phi
+ pi
+ epsilon
+ single-epsilon
+} ;
ABOUT: "math-constants"
"The " { $vocab-link "math.floats.env" } " vocabulary contains words for querying and controlling the floating-point environment."
$nl
"Querying and setting exception flags:"
-{ $subsection fp-exception-flags }
-{ $subsection set-fp-exception-flags }
-{ $subsection clear-fp-exception-flags }
-{ $subsection collect-fp-exceptions }
+{ $subsections
+ fp-exception-flags
+ set-fp-exception-flags
+ clear-fp-exception-flags
+ collect-fp-exceptions
+}
"Querying and controlling processor traps for floating-point exceptions:"
-{ $subsection fp-traps }
-{ $subsection with-fp-traps }
-{ $subsection without-fp-traps }
+{ $subsections
+ fp-traps
+ with-fp-traps
+ without-fp-traps
+}
"Getting the floating-point exception state from errors raised by enabled traps:"
-{ $subsection vm-error>exception-flags }
-{ $subsection vm-error-exception-flag? }
+{ $subsections
+ vm-error>exception-flags
+ vm-error-exception-flag?
+}
"Querying and controlling the rounding mode and treatment of denormals:"
-{ $subsection rounding-mode }
-{ $subsection with-rounding-mode }
-{ $subsection denormal-mode }
-{ $subsection with-denormal-mode } ;
+{ $subsections
+ rounding-mode
+ with-rounding-mode
+ denormal-mode
+ with-denormal-mode
+} ;
ABOUT: "math.floats.env"
"Exponential and natural logarithm:"
{ $subsections exp cis log }
"Other logarithms:"
-{ $subsection log1+ log10 }
+{ $subsections log1+ log10 }
"Raising a number to a power:"
{ $subsections ^ 10^ }
"Converting between rectangular and polar form:"
ARTICLE: "math-intervals-new" "Creating intervals"
"Standard constructors:"
-{ $subsection [a,b] }
-{ $subsection (a,b) }
-{ $subsection [a,b) }
-{ $subsection (a,b] }
+{ $subsections
+ [a,b]
+ (a,b)
+ [a,b)
+ (a,b]
+}
"One-point interval constructor:"
-{ $subsection [a,a] }
+{ $subsections [a,a] }
"Open-ended interval constructors:"
-{ $subsection [-inf,a] }
-{ $subsection [-inf,a) }
-{ $subsection [a,inf] }
-{ $subsection (a,inf] }
+{ $subsections
+ [-inf,a]
+ [-inf,a)
+ [a,inf]
+ (a,inf]
+}
"The set of all real numbers with infinities:"
-{ $subsection [-inf,inf] }
+{ $subsections [-inf,inf] }
"The empty set:"
-{ $subsection empty-interval }
+{ $subsections empty-interval }
"Another constructor:"
-{ $subsection points>interval } ;
+{ $subsections points>interval } ;
ARTICLE: "math-intervals-arithmetic" "Interval arithmetic"
"Binary operations on intervals:"
-{ $subsection interval+ }
-{ $subsection interval- }
-{ $subsection interval* }
-{ $subsection interval/ }
-{ $subsection interval/i }
-{ $subsection interval-mod }
-{ $subsection interval-rem }
-{ $subsection interval-min }
-{ $subsection interval-max }
+{ $subsections
+ interval+
+ interval-
+ interval*
+ interval/
+ interval/i
+ interval-mod
+ interval-rem
+ interval-min
+ interval-max
+}
"Bitwise operations on intervals:"
-{ $subsection interval-shift }
-{ $subsection interval-bitand }
-{ $subsection interval-bitor }
-{ $subsection interval-bitxor }
+{ $subsections
+ interval-shift
+ interval-bitand
+ interval-bitor
+ interval-bitxor
+}
"Unary operations on intervals:"
-{ $subsection interval-1+ }
-{ $subsection interval-1- }
-{ $subsection interval-neg }
-{ $subsection interval-bitnot }
-{ $subsection interval-recip }
-{ $subsection interval-2/ }
-{ $subsection interval-abs }
-{ $subsection interval-log2 } ;
+{ $subsections
+ interval-1+
+ interval-1-
+ interval-neg
+ interval-bitnot
+ interval-recip
+ interval-2/
+ interval-abs
+ interval-log2
+} ;
ARTICLE: "math-intervals-sets" "Set-theoretic operations on intervals"
-{ $subsection interval-contains? }
-{ $subsection interval-subset? }
-{ $subsection interval-intersect }
-{ $subsection interval-union }
-{ $subsection interval-closure }
-{ $subsection integral-closure } ;
+{ $subsections
+ interval-contains?
+ interval-subset?
+ interval-intersect
+ interval-union
+ interval-closure
+ integral-closure
+} ;
ARTICLE: "math-intervals-compare" "Comparing intervals"
-{ $subsection interval< }
-{ $subsection interval<= }
-{ $subsection interval> }
-{ $subsection interval>= }
-{ $subsection assume< }
-{ $subsection assume<= }
-{ $subsection assume> }
-{ $subsection assume>= } ;
+{ $subsections
+ interval<
+ interval<=
+ interval>
+ interval>=
+ assume<
+ assume<=
+ assume>
+ assume>=
+} ;
ARTICLE: "math-interval-properties" "Properties of interval arithmetic"
"For some operations, interval arithmetic yields inaccurate results, either because the result of lifting some operations to intervals does not result in intervals (bitwise operations, for example) or for the sake of simplicity of implementation."
ARTICLE: "math-intervals" "Intervals"
"Interval arithmetic is performed on ranges of real numbers, rather than exact values. It is used by the Factor compiler to convert arbitrary-precision arithmetic to machine arithmetic, by inferring bounds for integer calculations."
-{ $subsection "math-interval-properties" }
+{ $subsections "math-interval-properties" }
"The class of intervals:"
-{ $subsection interval }
-{ $subsection interval? }
+{ $subsections
+ interval
+ interval?
+}
"Interval operations:"
-{ $subsection "math-intervals-new" }
-{ $subsection "math-intervals-arithmetic" }
-{ $subsection "math-intervals-sets" }
-{ $subsection "math-intervals-compare" } ;
+{ $subsections
+ "math-intervals-new"
+ "math-intervals-arithmetic"
+ "math-intervals-sets"
+ "math-intervals-compare"
+} ;
ABOUT: "math-intervals"
{ $example "USE: math.functions" "2.0 acos ." "C{ 0.0 1.316957896924817 }" }
{ $unchecked-example "USE: math.libm" "2.0 facos ." "0/0." } }
"Trigonometric functions:"
-{ $subsection fcos }
-{ $subsection fsin }
-{ $subsection facos }
-{ $subsection fasin }
-{ $subsection fatan }
-{ $subsection fatan2 }
+{ $subsections
+ fcos
+ fsin
+ facos
+ fasin
+ fatan
+ fatan2
+}
"Hyperbolic functions:"
-{ $subsection fcosh }
-{ $subsection fsinh }
+{ $subsections
+ fcosh
+ fsinh
+}
"Exponentials and logarithms:"
-{ $subsection fexp }
-{ $subsection flog }
-{ $subsection flog10 }
+{ $subsections
+ fexp
+ flog
+ flog10
+}
"Powers:"
-{ $subsection fpow }
-{ $subsection fsqrt } ;
+{ $subsections
+ fpow
+ fsqrt
+} ;
ABOUT: "math.libm"
"A polynomial is a vector with the highest powers on the right:"
{ $code "{ 1 1 0 1 } -> 1 + x + x^3" "{ } -> 0" }
"Numerous words are defined to help with polynomial arithmetic:"
-{ $subsection p= }
-{ $subsection p+ }
-{ $subsection p- }
-{ $subsection p* }
-{ $subsection p-sq }
-{ $subsection powers }
-{ $subsection n*p }
-{ $subsection p/mod }
-{ $subsection pgcd }
-{ $subsection polyval }
-{ $subsection pdiff }
-{ $subsection pextend-conv }
-{ $subsection ptrim }
-{ $subsection 2ptrim } ;
+{ $subsections
+ p=
+ p+
+ p-
+ p*
+ p-sq
+ powers
+ n*p
+ p/mod
+ pgcd
+ polyval
+ pdiff
+ pextend-conv
+ ptrim
+ 2ptrim
+} ;
ABOUT: "polynomials"
ARTICLE: "math.primes.lucas-lehmer" "Lucas-Lehmer Mersenne Primality test"
"The " { $vocab-link "math.primes.lucas-lehmer" } " vocabulary tests numbers of the form " { $snippet "(2 ^ p) - 1" } " for primality, where " { $snippet "p" } " is prime." $nl
"Run the Lucas-Lehmer test:"
-{ $subsection lucas-lehmer } ;
+{ $subsections lucas-lehmer } ;
ABOUT: "math.primes.lucas-lehmer"
ARTICLE: "math.primes.miller-rabin" "Miller-Rabin probabilistic primality test"
"The " { $vocab-link "math.primes.miller-rabin" } " vocabulary implements the Miller-Rabin probabilistic primality test and utility words that use it in order to generate random prime numbers." $nl
"The Miller-Rabin probabilistic primality test:"
-{ $subsection miller-rabin }
-{ $subsection miller-rabin* } ;
+{ $subsections
+ miller-rabin
+ miller-rabin*
+} ;
ABOUT: "math.primes.miller-rabin"
ARTICLE: "math.primes" "Prime numbers"
"The " { $vocab-link "math.primes" } " vocabulary implements words related to prime numbers. Serveral useful vocabularies exist for testing primality. The Sieve of Eratosthenes in " { $vocab-link "math.primes.erato" } " is useful for testing primality below five million. For larger integers, " { $vocab-link "math.primes.miller-rabin" } " is a fast probabilstic primality test. The " { $vocab-link "math.primes.lucas-lehmer" } " vocabulary implements an algorithm for finding huge Mersenne prime numbers." $nl
"Testing if a number is prime:"
-{ $subsection prime? }
+{ $subsections prime? }
"Generating prime numbers:"
-{ $subsection next-prime }
-{ $subsection primes-upto }
-{ $subsection primes-between }
-{ $subsection random-prime }
+{ $subsections
+ next-prime
+ primes-upto
+ primes-between
+ random-prime
+}
"Generating relative prime numbers:"
-{ $subsection find-relative-prime }
-{ $subsection find-relative-prime* }
+{ $subsections
+ find-relative-prime
+ find-relative-prime*
+}
"Make a sequence of random prime numbers:"
-{ $subsection unique-primes } ;
+{ $subsections unique-primes } ;
ABOUT: "math.primes"
"The " { $vocab-link "math.primes.safe" } " vocabulary implements words to calculate safe prime numbers. Safe primes are of the form p = 2q + 1, where p,q are prime. Safe primes have desirable qualities for cryptographic applications." $nl
"Testing if a number is a safe prime:"
-{ $subsection safe-prime? }
+{ $subsections safe-prime? }
"Generating safe prime numbers:"
-{ $subsection next-safe-prime }
-{ $subsection random-safe-prime } ;
+{ $subsections
+ next-safe-prime
+ random-safe-prime
+} ;
ABOUT: "math.primes.safe"
"ranging from " { $emphasis "a" } " to " { $emphasis "b" } " by " { $emphasis "step" } ". Ascending as well as descending ranges are supported."
$nl
"The class of ranges:"
-{ $subsection range }
+{ $subsections range }
"Creating ranges with integer end-points. The standard mathematical convention is used, where " { $snippet "(" } " or " { $snippet ")" } " denotes that the end-point itself " { $emphasis "is not" } " part of the range; " { $snippet "[" } " or " { $snippet "]" } " denotes that the end-point " { $emphasis "is" } " part of the range:"
-{ $subsection [a,b] }
-{ $subsection (a,b] }
-{ $subsection [a,b) }
-{ $subsection (a,b) }
-{ $subsection [0,b] }
-{ $subsection [1,b] }
-{ $subsection [0,b) }
+{ $subsections
+ [a,b]
+ (a,b]
+ [a,b)
+ (a,b)
+ [0,b]
+ [1,b]
+ [0,b)
+}
"Creating general ranges:"
-{ $subsection <range> }
+{ $subsections <range> }
"Ranges are most frequently used with sequence combinators as a means of iterating over integers. For example,"
{ $code "3 10 [a,b] [ sqrt ] map" }
"Computing the factorial of 100 with a descending range:"
IN: math.ratios
ARTICLE: "rationals" "Rational numbers"
-{ $subsection ratio }
+{ $subsections ratio }
"When we add, subtract or multiply any two integers, the result is always an integer. However, dividing a numerator by a denominator that is not an integral divisor of the denominator yields a ratio:"
{ $example "1210 11 / ." "110" }
{ $example "100 330 / ." "10/33" }
{ $example "1/2 1/3 + ." "5/6" }
{ $example "100 6 / 3 * ." "50" }
"Ratios can be taken apart:"
-{ $subsection numerator }
-{ $subsection denominator }
-{ $subsection >fraction }
+{ $subsections
+ numerator
+ denominator
+ >fraction
+}
{ $see-also "syntax-ratios" } ;
ABOUT: "rationals"
ARTICLE: "math.rectangles" "Rectangles"
"The " { $vocab-link "math.rectangles" } " vocabulary defines a rectangle data type and operations on them."
-{ $subsection rect }
+{ $subsections rect }
"Rectangles can be taken apart:"
-{ $subsection rect-bounds }
-{ $subsection rect-extent }
+{ $subsections
+ rect-bounds
+ rect-extent
+}
"New rectangles can be created:"
-{ $subsection <zero-rect> }
-{ $subsection <rect> }
-{ $subsection <extent-rect> }
+{ $subsections
+ <zero-rect>
+ <rect>
+ <extent-rect>
+}
"Set-theoretic operations on rectangles:"
-{ $subsection rect-intersect }
-{ $subsection rect-union }
-{ $subsection contains-rect? }
-{ $subsection contains-point? }
+{ $subsections
+ rect-intersect
+ rect-union
+ contains-rect?
+ contains-point?
+}
"A utility word:"
-{ $subsection offset-rect } ;
+{ $subsections offset-rect } ;
ABOUT: "math.rectangles"
"Each SIMD vector type is named " { $snippet "scalar-count" } ", where " { $snippet "scalar" } " is a scalar C type and " { $snippet "count" } " is a vector dimension."
$nl
"To use a SIMD vector type, a parsing word is used to generate the relevant code and bring it into the vocabulary search path; this is the same idea as with " { $link "specialized-arrays" } ":"
-{ $subsection POSTPONE: SIMD: }
+{ $subsections POSTPONE: SIMD: }
"The following vector types are supported:"
{ $code
"char-16"
"It is best to avoid calling SIMD primitives directly. To write efficient high-level code that compiles down to primitives and avoids memory allocation, see " { $link "math.vectors.simd.efficiency" } "."
$nl
"There are two primitives which are used to implement accessing SIMD vector fields of " { $link "classes.struct" } ":"
-{ $subsection alien-vector }
-{ $subsection set-alien-vector }
+{ $subsections
+ alien-vector
+ set-alien-vector
+}
"For the most part, the above primitives correspond directly to vector arithmetic words. They take a representation parameter, which is one of the singleton members of the " { $link vector-rep } " union in the " { $vocab-link "cpu.architecture" } " vocabulary." ;
ARTICLE: "math.vectors.simd.alien" "SIMD data in struct classes"
ARTICLE: "math.vectors.simd" "Hardware vector arithmetic (SIMD)"
"The " { $vocab-link "math.vectors.simd" } " vocabulary extends the " { $vocab-link "math.vectors" } " vocabulary to support efficient vector arithmetic on small, fixed-size vectors."
-{ $subsection "math.vectors.simd.intro" }
-{ $subsection "math.vectors.simd.types" }
-{ $subsection "math.vectors.simd.words" }
-{ $subsection "math.vectors.simd.support" }
-{ $subsection "math.vectors.simd.accuracy" }
-{ $subsection "math.vectors.simd.efficiency" }
-{ $subsection "math.vectors.simd.alien" }
-{ $subsection "math.vectors.simd.intrinsics" } ;
+{ $subsections
+ "math.vectors.simd.intro"
+ "math.vectors.simd.types"
+ "math.vectors.simd.words"
+ "math.vectors.simd.support"
+ "math.vectors.simd.accuracy"
+ "math.vectors.simd.efficiency"
+ "math.vectors.simd.alien"
+ "math.vectors.simd.intrinsics"
+} ;
HELP: SIMD:
{ $syntax "SIMD: type" }
ARTICLE: "math-vectors-arithmetic" "Vector arithmetic"
"Vector/vector binary operations:"
-{ $subsection v+ }
-{ $subsection v- }
-{ $subsection v+- }
-{ $subsection v* }
-{ $subsection v/ }
+{ $subsections
+ v+
+ v-
+ v+-
+ v*
+ v/
+}
"Vector unary operations:"
-{ $subsection vneg }
-{ $subsection vabs }
-{ $subsection vsqrt }
-{ $subsection vfloor }
-{ $subsection vceiling }
-{ $subsection vtruncate }
+{ $subsections
+ vneg
+ vabs
+ vsqrt
+ vfloor
+ vceiling
+ vtruncate
+}
"Vector/scalar and scalar/vector binary operations:"
-{ $subsection vneg }
-{ $subsection v*n }
-{ $subsection n*v }
-{ $subsection v/n }
-{ $subsection n/v }
-{ $subsection v+n }
-{ $subsection n+v }
-{ $subsection v-n }
-{ $subsection n-v }
+{ $subsections
+ vneg
+ v*n
+ n*v
+ v/n
+ n/v
+ v+n
+ n+v
+ v-n
+ n-v
+}
"Saturated arithmetic (only on " { $link "specialized-arrays" } "):"
-{ $subsection vs+ }
-{ $subsection vs- }
-{ $subsection vs* }
+{ $subsections
+ vs+
+ vs-
+ vs*
+}
"Inner product and norm:"
-{ $subsection v. }
-{ $subsection norm }
-{ $subsection norm-sq }
-{ $subsection normalize }
+{ $subsections
+ v.
+ norm
+ norm-sq
+ normalize
+}
"Comparing entire vectors:"
-{ $subsection distance }
-{ $subsection v~ } ;
+{ $subsections
+ distance
+ v~
+} ;
ARTICLE: "math-vectors-logic" "Vector componentwise logic"
"Element comparisons:"
-{ $subsection v< }
-{ $subsection v<= }
-{ $subsection v= }
-{ $subsection v>= }
-{ $subsection v> }
-{ $subsection vunordered? }
-{ $subsection vmax }
-{ $subsection vmin }
-{ $subsection vsupremum }
-{ $subsection vinfimum }
+{ $subsections
+ v<
+ v<=
+ v=
+ v>=
+ v>
+ vunordered?
+ vmax
+ vmin
+ vsupremum
+ vinfimum
+}
"Bitwise operations:"
-{ $subsection vbitand }
-{ $subsection vbitandn }
-{ $subsection vbitor }
-{ $subsection vbitxor }
-{ $subsection vlshift }
-{ $subsection vrshift }
+{ $subsections
+ vbitand
+ vbitandn
+ vbitor
+ vbitxor
+ vlshift
+ vrshift
+}
"Element logical operations:"
-{ $subsection vand }
-{ $subsection vor }
-{ $subsection vxor }
-{ $subsection vmask }
-{ $subsection v? }
+{ $subsections
+ vand
+ vor
+ vxor
+ vmask
+ v?
+}
"Element shuffling:"
-{ $subsection vshuffle } ;
+{ $subsections vshuffle } ;
ARTICLE: "math-vectors-misc" "Miscellaneous vector functions"
-{ $subsection trilerp }
-{ $subsection bilerp }
-{ $subsection vlerp }
-{ $subsection vnlerp }
-{ $subsection vbilerp } ;
+{ $subsections
+ trilerp
+ bilerp
+ vlerp
+ vnlerp
+ vbilerp
+} ;
ARTICLE: "math-vectors" "Vector operations"
"Any Factor sequence can be used to represent a mathematical vector, however for best performance, the sequences defined by the " { $vocab-link "specialized-arrays" } " and " { $vocab-link "math.vectors.simd" } " vocabularies should be used."
-{ $subsection "math-vectors-arithmetic" }
-{ $subsection "math-vectors-logic" }
-{ $subsection "math-vectors-misc" } ;
+{ $subsections
+ "math-vectors-arithmetic"
+ "math-vectors-logic"
+ "math-vectors-misc"
+} ;
ABOUT: "math-vectors"
"Memoization is useful in situations where the set of possible inputs is small, but the results are expensive to compute and should be cached. Memoized words should not have any side effects."
$nl
"Defining a memoized word at parse time:"
-{ $subsection POSTPONE: MEMO: }
+{ $subsections POSTPONE: MEMO: }
"Defining a memoized word at run time:"
-{ $subsection define-memoized }
+{ $subsections define-memoized }
"Clearing memoized results:"
-{ $subsection reset-memoized } ;
+{ $subsections reset-memoized } ;
ABOUT: "memoize"
ARTICLE: "mime.types" "MIME types"
"The " { $vocab-link "mime.types" } " vocabulary loads a file of MIME types and provides a word to look up the MIME type based on a file extension." $nl
"Looking up a MIME type:"
-{ $subsection mime-type } ;
+{ $subsections mime-type } ;
ABOUT: "mime.types"
"The " { $vocab-link "mirrors" } " vocabulary defines data types which present an object's slots and slot values as an associative structure. This enables idioms such as iteration over all slots in a tuple, or editing of tuples, sequences and assocs in a generic fashion. This functionality is used by developer tools and meta-programming utilities."
$nl
"A mirror provides such a view of a tuple:"
-{ $subsection mirror }
-{ $subsection <mirror> }
+{ $subsections
+ mirror
+ <mirror>
+}
"Utility word used by developer tools which inspect objects:"
-{ $subsection make-mirror }
+{ $subsections make-mirror }
{ $see-also "slots" } ;
ABOUT: "mirrors"
\r
ARTICLE: "models.arrow" "Arrow models"\r
"Arrow model values are computed by applying a quotation to the value of another model."\r
-{ $subsection arrow }\r
-{ $subsection <arrow> } ;\r
+{ $subsections\r
+ arrow\r
+ <arrow>\r
+} ;\r
\r
ABOUT: "models.arrow"\r
ARTICLE: "models.arrow.smart" "Smart arrow models"
"The " { $vocab-link "models.arrow.smart" } " vocabulary generalizes arrows to arbitrary input arity. They're called “smart” because they resemble " { $link "combinators.smart" } "."
-{ $subsection <smart-arrow> } ;
+{ $subsections <smart-arrow> } ;
ABOUT: "models.arrow.smart"
\ No newline at end of file
\r
ARTICLE: "models-delay" "Delay models"\r
"Delay models are used to implement delayed updating of gadgets in response to user input."\r
-{ $subsection delay }\r
-{ $subsection <delay> } ;\r
+{ $subsections\r
+ delay\r
+ <delay>\r
+} ;\r
\r
ABOUT: "models-delay"\r
"The " { $vocab-link "models" } " vocabulary provides basic support for dataflow programming. A model is an observable value. Changing a model's value notifies other objects which depend on the model automatically, and models may depend on each other's values."
$nl
"The class of models:"
-{ $subsection model }
+{ $subsections model }
"Creating models:"
-{ $subsection <model> }
+{ $subsections <model> }
"Adding and removing connections:"
-{ $subsection add-connection }
-{ $subsection remove-connection }
+{ $subsections
+ add-connection
+ remove-connection
+}
"Generic word called on model connections when the model value changes:"
-{ $subsection model-changed }
+{ $subsections model-changed }
"When using models which are not associated with controls (or when unit testing controls), you must activate and deactivate models manually:"
-{ $subsection activate-model }
-{ $subsection deactivate-model }
-{ $subsection "models-impl" }
-{ $subsection "models.arrow" }
-{ $subsection "models.product" }
-{ $subsection "models-range" }
-{ $subsection "models-delay" } ;
+{ $subsections
+ activate-model
+ deactivate-model
+ "models-impl"
+ "models.arrow"
+ "models.product"
+ "models-range"
+ "models-delay"
+} ;
ARTICLE: "models-impl" "Implementing models"
"New types of models can be defined, for example see " { $vocab-link "models.arrow" } "."
$nl
"Models can execute hooks when activated:"
-{ $subsection model-activated }
+{ $subsections model-activated }
"Models can override requests to change their value, for example to perform validation:"
-{ $subsection set-model } ;
+{ $subsections set-model } ;
ABOUT: "models"
\r
ARTICLE: "models.product" "Product models"\r
"Product model values are computed by collecting the values from a sequence of underlying models into a new sequence."\r
-{ $subsection product }\r
-{ $subsection <product> } ;\r
+{ $subsections\r
+ product\r
+ <product>\r
+} ;\r
\r
ABOUT: "models.product"\r
\r
ARTICLE: "models-range" "Range models"\r
"Range models ensure their value is a real number within a fixed range."\r
-{ $subsection range }\r
-{ $subsection <range> }\r
+{ $subsections\r
+ range\r
+ <range>\r
+}\r
"Range models conform to a protocol for getting and setting the current value, as well as the endpoints of the range."\r
-{ $subsection "range-model-protocol" } ;\r
+{ $subsections "range-model-protocol" } ;\r
\r
ARTICLE: "range-model-protocol" "Range model protocol"\r
"The range model protocol is implemented by the " { $link range } " and " { $link compose } " classes. User-defined models may implement it too."\r
-{ $subsection range-value }\r
-{ $subsection range-page-value } \r
-{ $subsection range-min-value } \r
-{ $subsection range-max-value } \r
-{ $subsection range-max-value* } \r
-{ $subsection set-range-value } \r
-{ $subsection set-range-page-value } \r
-{ $subsection set-range-min-value } \r
-{ $subsection set-range-max-value } ;\r
+{ $subsections\r
+ range-value\r
+ range-page-value\r
+ range-min-value\r
+ range-max-value\r
+ range-max-value*\r
+ set-range-value\r
+ set-range-page-value\r
+ set-range-min-value \r
+ set-range-max-value \r
+} ;\r
\r
ABOUT: "models-range"\r
ARTICLE: "multiline" "Multiline"
"Multiline strings:"
-{ $subsection POSTPONE: STRING: }
-{ $subsection POSTPONE: HEREDOC: }
-{ $subsection POSTPONE: DELIMITED: }
+{ $subsections
+ POSTPONE: STRING:
+ POSTPONE: HEREDOC:
+ POSTPONE: DELIMITED:
+}
"Multiline comments:"
-{ $subsection POSTPONE: /* }
+{ $subsections POSTPONE: /* }
"Writing new multiline parsing words:"
-{ $subsection parse-multiline-string }
+{ $subsections parse-multiline-string }
;
ABOUT: "multiline"
ARTICLE: "opengl.annotations" "OpenGL error reporting"
"The " { $vocab-link "opengl.annotations" } " vocabulary provides some tools for tracking down GL errors:"
-{ $subsection throw-gl-errors }
-{ $subsection log-gl-errors }
-{ $subsection clear-gl-error-log }
-{ $subsection reset-gl-functions } ;
+{ $subsections
+ throw-gl-errors
+ log-gl-errors
+ clear-gl-error-log
+ reset-gl-functions
+} ;
ABOUT: "opengl.annotations"
\ No newline at end of file
ARTICLE: "opengl.debug" "Interactive debugging of OpenGL applications"
"The " { $vocab-link "opengl.debug" } " vocabulary provides words to assist with interactive debugging of OpenGL applications in the Factor UI."
-{ $subsection G-world }
-{ $subsection G }
-{ $subsection F }
-{ $subsection GB }
-{ $subsection gl-break } ;
+{ $subsections
+ G-world
+ G
+ F
+ GB
+ gl-break
+} ;
ABOUT: "opengl.debug"
IN: opengl.gl
ARTICLE: "opengl-low-level" "OpenGL binding"
- { $subsection "opengl-specifying-vertices" }
- { $subsection "opengl-geometric-primitives" }
- { $subsection "opengl-modeling-transformations" } ;
+{ $subsections
+ "opengl-specifying-vertices"
+ "opengl-geometric-primitives"
+ "opengl-modeling-transformations"
+} ;
ARTICLE: "opengl-specifying-vertices" "Specifying vertices"
+{ $subsections
+ glVertex2d
+ glVertex2f
+ glVertex2i
+ glVertex2s
+ glVertex3d
+ glVertex3f
+ glVertex3i
+ glVertex3s
+ glVertex4d
+ glVertex4f
+ glVertex4i
+ glVertex4s
+ glVertex2dv
+ glVertex2fv
+ glVertex2iv
+ glVertex2sv
+ glVertex3dv
+ glVertex3fv
+ glVertex3iv
+ glVertex3sv
+ glVertex4dv
+ glVertex4fv
+ glVertex4iv
+ glVertex4sv
+} ;
- { $subsection glVertex2d }
- { $subsection glVertex2f }
- { $subsection glVertex2i }
- { $subsection glVertex2s }
- { $subsection glVertex3d }
- { $subsection glVertex3f }
- { $subsection glVertex3i }
- { $subsection glVertex3s }
- { $subsection glVertex4d }
- { $subsection glVertex4f }
- { $subsection glVertex4i }
- { $subsection glVertex4s }
- { $subsection glVertex2dv }
- { $subsection glVertex2fv }
- { $subsection glVertex2iv }
- { $subsection glVertex2sv }
- { $subsection glVertex3dv }
- { $subsection glVertex3fv }
- { $subsection glVertex3iv }
- { $subsection glVertex3sv }
- { $subsection glVertex4dv }
- { $subsection glVertex4fv }
- { $subsection glVertex4iv }
- { $subsection glVertex4sv } ;
ARTICLE: "opengl-geometric-primitives" "OpenGL geometric primitives"
{ $link GL_FILL } } } } } ;
ARTICLE: "opengl-modeling-transformations" "Modeling transformations"
- { $subsection glTranslatef }
- { $subsection glTranslated }
- { $subsection glRotatef }
- { $subsection glRotated }
- { $subsection glScalef }
- { $subsection glScaled } ;
+{ $subsections
+ glTranslatef
+ glTranslated
+ glRotatef
+ glRotated
+ glScalef
+ glScaled
+} ;
{ glTranslatef glTranslated glRotatef glRotated glScalef glScaled }
"The " { $vocab-link "opengl" } " vocabulary implements some utility words to give OpenGL a more Factor-like feel."
$nl
"The " { $vocab-link "opengl.gl" } " and " { $vocab-link "opengl.glu" } " vocabularies have the actual OpenGL bindings."
-{ $subsection "opengl-low-level" }
+{ $subsections "opengl-low-level" }
"Error reporting:"
-{ $subsection gl-error }
+{ $subsections gl-error }
"Wrappers:"
-{ $subsection gl-color }
-{ $subsection gl-translate }
-{ $subsection bind-texture-unit }
+{ $subsections
+ gl-color
+ gl-translate
+ bind-texture-unit
+}
"Combinators:"
-{ $subsection do-enabled }
-{ $subsection do-attribs }
-{ $subsection do-matrix }
-{ $subsection with-translation }
-{ $subsection make-dlist }
+{ $subsections
+ do-enabled
+ do-attribs
+ do-matrix
+ with-translation
+ make-dlist
+}
"Rendering geometric shapes:"
-{ $subsection gl-line }
-{ $subsection gl-fill-rect }
-{ $subsection gl-rect }
-;
+{ $subsections
+ gl-line
+ gl-fill-rect
+ gl-rect
+} ;
ABOUT: "gl-utilities"
"This vocabulary provides a deque implementation which is persistent and purely functional: old versions of deques are not modified by operations. Instead, each push and pop operation creates a new deque based off the old one."
$nl
"The class of persistent deques:"
-{ $subsection deque }
+{ $subsections deque }
"To create a deque:"
-{ $subsection <deque> }
-{ $subsection sequence>deque }
+{ $subsections
+ <deque>
+ sequence>deque
+}
"To test if a deque is empty:"
-{ $subsection deque-empty? }
+{ $subsections deque-empty? }
"To manipulate deques:"
-{ $subsection push-front }
-{ $subsection push-back }
-{ $subsection pop-front }
-{ $subsection pop-back }
-{ $subsection deque>sequence } ;
+{ $subsections
+ push-front
+ push-back
+ pop-front
+ pop-back
+ deque>sequence
+} ;
HELP: deque
{ $class-description "This is the class of persistent (functional) double-ended queues. All deque operations can be done in O(1) amortized time for single-threaded access while maintaining the old version. For more information, see " { $link "persistent.deques" } "." } ;
ARTICLE: "persistent-heaps" "Persistent heaps"
"This vocabulary implements persistent minheaps, aka priority queues. They are purely functional and support efficient O(log n) operations of pushing and popping, with O(1) time access to the minimum element. To create heaps, use the following words:"
-{ $subsection <persistent-heap> }
-{ $subsection <singleton-heap> }
+{ $subsections
+ <persistent-heap>
+ <singleton-heap>
+}
"To manipulate them:"
-{ $subsection pheap-peek }
-{ $subsection pheap-push }
-{ $subsection pheap-pop }
-{ $subsection pheap-pop* }
-{ $subsection pheap-empty? }
-{ $subsection assoc>pheap }
-{ $subsection pheap>alist }
-{ $subsection pheap>values } ;
+{ $subsections
+ pheap-peek
+ pheap-push
+ pheap-pop
+ pheap-pop*
+ pheap-empty?
+ assoc>pheap
+ pheap>alist
+ pheap>values
+} ;
ABOUT: "persistent-heaps"
ARTICLE: "persistent.sequences" "Persistent sequence protocol"
"The persistent sequence protocol consists of the non-mutating sequence protocol words, such as " { $link length } " and " { $link nth } ", together with the following operations:"
-{ $subsection new-nth }
-{ $subsection ppush }
-{ $subsection ppop }
+{ $subsections
+ new-nth
+ ppush
+ ppop
+}
"The default implementations of the above run in " { $snippet "O(n)" } " time; the " { $vocab-link "persistent.vectors" } " vocabulary provides an implementation of these operations in " { $snippet "O(1)" } " time." ;
ABOUT: "persistent.sequences"
"A " { $emphasis "persistent vector" } " differs from an ordinary vector (" { $link "vectors" } ") in that it is immutable, and all operations yield new persistent vectors instead of modifying inputs. Unlike immutable operations on ordinary sequences, persistent vector operations are efficient and run in sub-linear time."
$nl
"The class of persistent vectors:"
-{ $subsection persistent-vector }
+{ $subsections persistent-vector }
"Converting a sequence into a persistent vector:"
-{ $subsection >persistent-vector }
+{ $subsections >persistent-vector }
"Persistent vectors have a literal syntax:"
-{ $subsection POSTPONE: PV{ }
+{ $subsections POSTPONE: PV{ }
"The empty persistent vector, written " { $snippet "PV{ }" } ", is used for building up all other persistent vectors."
$nl
"This implementation of persistent vectors is based on the " { $snippet "clojure.lang.PersistentVector" } " class from Rich Hickey's Clojure language for the JVM (" { $url "http://clojure.org" } ")." ;
"A detailed description of the algorithm, along with implementations in various languages, can be at in " { $url "http://www.tartarus.org/~martin/PorterStemmer" } "."
$nl
"The main word of the algorithm takes an English word as input and outputs its stem:"
-{ $subsection stem }
+{ $subsections stem }
"The algorithm consists of a number of steps:"
-{ $subsection step1a }
-{ $subsection step1b }
-{ $subsection step1c }
-{ $subsection step2 }
-{ $subsection step3 }
-{ $subsection step4 }
-{ $subsection step5 } ;
+{ $subsections
+ step1a
+ step1b
+ step1c
+ step2
+ step3
+ step4
+ step5
+} ;
ABOUT: "porter-stemmer"
ARTICLE: "present" "Converting objects to human-readable strings"
"A word for converting an object into a human-readable string:"
-{ $subsection present } ;
+{ $subsections present } ;
HELP: present
{ $values { "object" object } { "string" string } }
ARTICLE: "prettyprint-numbers" "Prettyprinting numbers"
"The " { $link . } " word prints numbers in decimal. A set of words in the " { $vocab-link "prettyprint" } " vocabulary is provided to print integers using another base."
-{ $subsection .b }
-{ $subsection .o }
-{ $subsection .h } ;
+{ $subsections
+ .b
+ .o
+ .h
+} ;
ARTICLE: "prettyprint-stacks" "Prettyprinting stacks"
"Prettyprinting the current data, retain, call stacks:"
-{ $subsection .s }
-{ $subsection .r }
-{ $subsection .c }
+{ $subsections
+ .s
+ .r
+ .c
+}
"Prettyprinting any stack:"
-{ $subsection stack. }
+{ $subsections stack. }
"Prettyprinting any call stack:"
-{ $subsection callstack. }
+{ $subsections callstack. }
"Note that calls to " { $link .s } " can also be included inside words as a debugging aid, however a more convenient way to achieve this is to use the annotation facility. See " { $link "tools.annotations" } "." ;
ARTICLE: "prettyprint-variables" "Prettyprint control variables"
"The following variables affect the " { $link . } " and " { $link pprint } " words if set in the current dynamic scope:"
-{ $subsection tab-size }
-{ $subsection margin }
-{ $subsection nesting-limit }
-{ $subsection length-limit }
-{ $subsection line-limit }
-{ $subsection number-base }
-{ $subsection string-limit? }
-{ $subsection boa-tuples? }
-{ $subsection c-object-pointers? }
+{ $subsections
+ tab-size
+ margin
+ nesting-limit
+ length-limit
+ line-limit
+ number-base
+ string-limit?
+ boa-tuples?
+ c-object-pointers?
+}
"Note that the " { $link short. } " and " { $link pprint-short } " variables override some of these variables."
{
$warning "Treat the global variables as essentially being constants. Only ever rebind them in a nested scope."
"Prettyprinter sections must subclass " { $link section } ", and they must also obey a protocol."
$nl
"Layout queries:"
-{ $subsection section-fits? }
-{ $subsection indent-section? }
-{ $subsection unindent-first-line? }
-{ $subsection newline-after? }
-{ $subsection short-section? }
+{ $subsections
+ section-fits?
+ indent-section?
+ unindent-first-line?
+ newline-after?
+ short-section?
+}
"Printing sections:"
-{ $subsection short-section }
-{ $subsection long-section }
+{ $subsections
+ short-section
+ long-section
+}
"Utilities to use when implementing sections:"
-{ $subsection new-section }
-{ $subsection new-block }
-{ $subsection add-section } ;
+{ $subsections
+ new-section
+ new-block
+ add-section
+} ;
ARTICLE: "prettyprint-sections" "Prettyprinter sections"
"The prettyprinter's formatting engine can be used directly:"
-{ $subsection with-pprint }
+{ $subsections with-pprint }
"Code in a " { $link with-pprint } " block or a method on " { $link pprint* } " can build up a tree of " { $emphasis "sections" } ". A section is either a text node or a " { $emphasis "block" } " which itself consists of sections."
$nl
"Once the output sections have been generated, the tree of sections is traversed and intelligent decisions are made about indentation and line breaks. Finally, text is output."
-{ $subsection section }
+{ $subsections section }
"Adding leaf sections:"
-{ $subsection line-break }
-{ $subsection text }
-{ $subsection styled-text }
+{ $subsections
+ line-break
+ text
+ styled-text
+}
"Nesting and denesting sections:"
-{ $subsection <object }
-{ $subsection <block }
-{ $subsection <inset }
-{ $subsection <flow }
-{ $subsection <colon }
-{ $subsection block> }
+{ $subsections
+ <object
+ <block
+ <inset
+ <flow
+ <colon
+ block>
+}
"New types of sections can be defined."
-{ $subsection "prettyprint-section-protocol" } ;
+{ $subsections "prettyprint-section-protocol" } ;
ARTICLE: "prettyprint-literal" "Literal prettyprinting protocol"
"Most custom data types have a literal syntax which resembles a sequence. An easy way to define such a syntax is to add a method to the " { $link pprint* } " generic word which calls " { $link pprint-object } ", and then to provide methods on two other generic words:"
-{ $subsection pprint-delims }
-{ $subsection >pprint-sequence }
+{ $subsections
+ pprint-delims
+ >pprint-sequence
+}
"For example, consider the following data type, together with a parsing word for creating literals:"
{ $code
"TUPLE: rect w h ;"
ARTICLE: "prettyprint-literal-more" "Prettyprinting more complex literals"
"If the " { $link "prettyprint-literal" } " is insufficient, a method can be defined to control prettyprinting directly:"
-{ $subsection pprint* }
+{ $subsections pprint* }
"Some utilities which can be called from methods on " { $link pprint* } ":"
-{ $subsection pprint-object }
-{ $subsection pprint-word }
-{ $subsection pprint-elements }
-{ $subsection pprint-string }
-{ $subsection pprint-prefix }
+{ $subsections
+ pprint-object
+ pprint-word
+ pprint-elements
+ pprint-string
+ pprint-prefix
+}
"Custom methods defined on " { $link pprint* } " do not perform I/O directly, instead they call prettyprinter words to construct " { $emphasis "sections" } " of output. See " { $link "prettyprint-sections" } "." ;
ARTICLE: "prettyprint-extension" "Extending the prettyprinter"
"One can define literal syntax for a new class using the " { $link "parser" } " together with corresponding prettyprinting methods which print instances of the class using this syntax."
-{ $subsection "prettyprint-literal" }
-{ $subsection "prettyprint-literal-more" }
+{ $subsections
+ "prettyprint-literal"
+ "prettyprint-literal-more"
+}
"The prettyprinter actually exposes a general source code output engine and is not limited to printing object structure."
-{ $subsection "prettyprint-sections" } ;
+{ $subsections "prettyprint-sections" } ;
ARTICLE: "prettyprint" "The prettyprinter"
"One of Factor's key features is the ability to print almost any object as a valid source literal expression. This greatly aids debugging and provides the building blocks for light-weight object serialization facilities."
"Prettyprinter words are found in the " { $vocab-link "prettyprint" } " vocabulary."
$nl
"The key words to print an object to " { $link output-stream } "; the first two emit a trailing newline, the second two do not:"
-{ $subsection . }
-{ $subsection short. }
-{ $subsection pprint }
-{ $subsection pprint-short }
-{ $subsection pprint-use }
+{ $subsections
+ .
+ short.
+ pprint
+ pprint-short
+ pprint-use
+}
"The string representation of an object can be requested:"
-{ $subsection unparse }
-{ $subsection unparse-use }
+{ $subsections
+ unparse
+ unparse-use
+}
"Utility for tabular output:"
-{ $subsection pprint-cell }
+{ $subsections pprint-cell }
"More prettyprinter usage:"
-{ $subsection "prettyprint-numbers" }
-{ $subsection "prettyprint-stacks" }
+{ $subsections
+ "prettyprint-numbers"
+ "prettyprint-stacks"
+}
"Prettyprinter customization:"
-{ $subsection "prettyprint-variables" }
-{ $subsection "prettyprint-extension" }
-{ $subsection "prettyprint-limitations" }
+{ $subsections
+ "prettyprint-variables"
+ "prettyprint-extension"
+ "prettyprint-limitations"
+}
{ $see-also "number-strings" "see" } ;
ABOUT: "prettyprint"
{ $vocab-link "prettyprint.stylesheet" }
$nl
"Control the way that the prettyprinter formats output based on object type. These hooks form a basic \"syntax\" highlighting system."
-{ $subsection word-style }
-{ $subsection string-style }
-{ $subsection vocab-style }
-{ $subsection effect-style }
+{ $subsections
+ word-style
+ string-style
+ vocab-style
+ effect-style
+}
;
ABOUT: "prettyprint.stylesheet"
ARTICLE: "quoted-printable" "Quoted printable encoding"
"The " { $vocab-link "quoted-printable" } " vocabulary implements RFC 2045 part 6.7, providing words for reading and generating quotable printed text."
-{ $subsection >quoted }
-{ $subsection >quoted-lines }
-{ $subsection quoted> } ;
+{ $subsections
+ >quoted
+ >quoted-lines
+ quoted>
+} ;
HELP: >quoted
{ $values { "byte-array" byte-array } { "string" string } }
ARTICLE: "random-protocol" "Random protocol"
"A random number generator must implement one of these two words:"
-{ $subsection random-32* }
-{ $subsection random-bytes* }
+{ $subsections
+ random-32*
+ random-bytes*
+}
"Optional, to seed a random number generator:"
-{ $subsection seed-random } ;
+{ $subsections seed-random } ;
ARTICLE: "random" "Generating random integers"
"The " { $vocab-link "random" } " vocabulary contains a protocol for generating random or pseudorandom numbers."
"The “Mersenne Twister” pseudorandom number generator algorithm is the default generator stored in " { $link random-generator } "."
$nl
"Generate a random object:"
-{ $subsection random }
+{ $subsections random }
"Efficient 32-bit random numbers:"
-{ $subsection random-32 }
+{ $subsections random-32 }
"Combinators to change the random number generator:"
-{ $subsection with-random }
-{ $subsection with-system-random }
-{ $subsection with-secure-random }
+{ $subsections
+ with-random
+ with-system-random
+ with-secure-random
+}
"Implementation:"
-{ $subsection "random-protocol" }
+{ $subsections "random-protocol" }
"Randomizing a sequence:"
-{ $subsection randomize }
+{ $subsections randomize }
"Sampling a sequences:"
-{ $subsection sample }
+{ $subsections sample }
"Deleting a random element from a sequence:"
-{ $subsection delete-random }
+{ $subsections delete-random }
"Random numbers with " { $snippet "n" } " bits:"
-{ $subsection random-bits }
-{ $subsection random-bits* } ;
+{ $subsections
+ random-bits
+ random-bits*
+} ;
ABOUT: "random"
ARTICLE: "refs" "References"
"References provide a uniform way of accessing and changing values. Some examples of referenced values are variables, tuple slots, and keys or values of assocs. References can be read, written, and deleted. References are defined in the " { $vocab-link "refs" } " vocabulary, and new reference types can be made by implementing a protocol."
-{ $subsection "refs-protocol" }
-{ $subsection "refs-impls" }
-{ $subsection "refs-utils" }
+{ $subsections
+ "refs-protocol"
+ "refs-impls"
+ "refs-utils"
+}
"References are used by the " { $link "ui-inspector" } "." ;
ABOUT: "refs"
ARTICLE: "refs-impls" "Reference implementations"
"References to objects:"
-{ $subsection obj-ref }
-{ $subsection <obj-ref> }
+{ $subsections
+ obj-ref
+ <obj-ref>
+}
"References to assoc keys:"
-{ $subsection key-ref }
-{ $subsection <key-ref> }
+{ $subsections
+ key-ref
+ <key-ref>
+}
"References to assoc values:"
-{ $subsection value-ref }
-{ $subsection <value-ref> }
+{ $subsections
+ value-ref
+ <value-ref>
+}
"References to variables:"
-{ $subsection var-ref }
-{ $subsection <var-ref> }
-{ $subsection global-var-ref }
-{ $subsection <global-var-ref> }
+{ $subsections
+ var-ref
+ <var-ref>
+ global-var-ref
+ <global-var-ref>
+}
"References to tuple slots:"
-{ $subsection slot-ref }
-{ $subsection <slot-ref> }
+{ $subsections
+ slot-ref
+ <slot-ref>
+}
"Using boxes as references:"
-{ $subsection "box-refs" } ;
+{ $subsections "box-refs" } ;
ARTICLE: "refs-utils" "Reference utilities"
-{ $subsection ref-on }
-{ $subsection ref-off }
-{ $subsection ref-inc }
-{ $subsection ref-dec }
-{ $subsection set-ref* } ;
+{ $subsections
+ ref-on
+ ref-off
+ ref-inc
+ ref-dec
+ set-ref*
+} ;
ARTICLE: "refs-protocol" "Reference protocol"
"To use a class of objects as references you must implement the reference protocol for that class, and mark your class as an instance of the " { $link ref } " mixin class. All references must implement these two words:"
-{ $subsection get-ref }
-{ $subsection set-ref }
+{ $subsections
+ get-ref
+ set-ref
+}
"References may also implement:"
-{ $subsection delete-ref } ;
+{ $subsections delete-ref } ;
ARTICLE: "box-refs" "Boxes as references"
{ $link "boxes" } " are elements of the " { $link ref } " mixin class, so any box may be used as a reference. Bear in mind that boxes will still throw an error if you call " { $link get-ref } " on an empty box." ;
ARTICLE: "roman" "Roman numerals"
"The " { $vocab-link "roman" } " vocabulary can convert numbers to and from the Roman numeral system and can perform arithmetic given Roman numerals as input." $nl
"A parsing word for literal Roman numerals:"
-{ $subsection POSTPONE: ROMAN: }
+{ $subsections POSTPONE: ROMAN: }
"Converting to Roman numerals:"
-{ $subsection >roman }
-{ $subsection >ROMAN }
+{ $subsections
+ >roman
+ >ROMAN
+}
"Converting Roman numerals to integers:"
-{ $subsection roman> }
+{ $subsections roman> }
"Roman numeral arithmetic:"
-{ $subsection roman+ }
-{ $subsection roman- }
-{ $subsection roman* }
-{ $subsection roman/i }
-{ $subsection roman/mod } ;
+{ $subsections
+ roman+
+ roman-
+ roman*
+ roman/i
+ roman/mod
+} ;
ABOUT: "roman"
"A search deque is a data structure with constant-time insertion and removal of elements at both ends, and constant-time membership tests. Inserting an element more than once has no effect. Search deques implement all deque operations in terms of an underlying deque, and membership testing with " { $link deque-member? } " is implemented with an underlying assoc. Search deques are defined in the " { $vocab-link "search-deques" } " vocabulary."
$nl
"Creating a search deque:"
-{ $subsection <search-deque> } ;
+{ $subsections <search-deque> } ;
ABOUT: "search-deques"
"The " { $vocab-link "see" } " vocabulary implements support for printing out " { $link "definitions" } " in the image."
$nl
"Printing a definition:"
-{ $subsection see }
+{ $subsections see }
"Printing the methods defined on a generic word or class (see " { $link "objects" } "):"
-{ $subsection see-methods }
+{ $subsections see-methods }
"Definition specifiers implementing the " { $link "definition-protocol" } " should also implement the " { $emphasis "see protocol" } ":"
-{ $subsection see* }
-{ $subsection synopsis* } ;
+{ $subsections
+ see*
+ synopsis*
+} ;
ABOUT: "see"
\ No newline at end of file
ARTICLE: "sequences.complex-components" "Complex component virtual sequences"
"The " { $link complex-components } " class wraps a sequence of " { $link complex } " number values, presenting a sequence of " { $link real } " values made by interleaving the real and imaginary parts of the complex values in the original sequence."
-{ $subsection complex-components }
-{ $subsection <complex-components> } ;
+{ $subsections
+ complex-components
+ <complex-components>
+} ;
ABOUT: "sequences.complex-components"
ARTICLE: "sequences.complex" "Complex virtual sequences"
"The " { $link complex-sequence } " class wraps a sequence of " { $link real } " number values, presenting a sequence of " { $link complex } " values made by treating the underlying sequence as pairs of alternating real and imaginary values."
-{ $subsection complex-sequence }
-{ $subsection <complex-sequence> } ;
+{ $subsections
+ complex-sequence
+ <complex-sequence>
+} ;
ABOUT: "sequences.complex"
ARTICLE: "sequences.deep" "Deep sequence combinators"
"The combinators in the " { $vocab-link "sequences.deep" } " vocabulary are variants of standard sequence combinators which traverse nested subsequences."
-{ $subsection deep-each }
-{ $subsection deep-map }
-{ $subsection deep-filter }
-{ $subsection deep-find }
-{ $subsection deep-any? }
-{ $subsection deep-change-each }
+{ $subsections
+ deep-each
+ deep-map
+ deep-filter
+ deep-find
+ deep-any?
+ deep-change-each
+}
"A utility word to collapse nested subsequences:"
-{ $subsection flatten } ;
+{ $subsections flatten } ;
ABOUT: "sequences.deep"
"The " { $vocab-link "serialize" } " vocabulary implements binary serialization for all Factor data types except for continuations. Unlike the prettyprinter, shared structure and circularity is preserved."
$nl
"Storing objects on streams:"
-{ $subsection serialize }
-{ $subsection deserialize }
+{ $subsections
+ serialize
+ deserialize
+}
"Storing objects as byte arrays:"
-{ $subsection object>bytes }
-{ $subsection bytes>object } ;
+{ $subsections
+ object>bytes
+ bytes>object
+} ;
ABOUT: "serialize"
ARTICLE: "simple-flat-file" "Parsing simple flat files"
"The " { $vocab-link "simple-flat-file" } " vocabulary provides words for loading and parsing simple flat files in a particular format which is common for encoding and Unicode tasks."
-{ $subsection flat-file>biassoc }
-{ $subsection load-interval-file }
-{ $subsection data } ;
+{ $subsections
+ flat-file>biassoc
+ load-interval-file
+ data
+} ;
HELP: load-interval-file
{ $values { "filename" string } { "table" "an interval map" } }
"The " { $vocab-link "smtp" } " vocabulary sends e-mail via an SMTP server."
$nl
"This library is configured by a set of dynamically-scoped variables:"
-{ $subsection smtp-server }
-{ $subsection smtp-tls? }
-{ $subsection smtp-read-timeout }
-{ $subsection smtp-domain }
-{ $subsection smtp-auth }
+{ $subsections
+ smtp-server
+ smtp-tls?
+ smtp-read-timeout
+ smtp-domain
+ smtp-auth
+}
"The latter is set to an instance of one of the following:"
-{ $subsection no-auth }
-{ $subsection plain-auth }
+{ $subsections
+ no-auth
+ plain-auth
+}
"Constructing an e-mail:"
-{ $subsection email }
-{ $subsection <email> }
+{ $subsections
+ email
+ <email>
+}
"Sending an email:"
-{ $subsection send-email }
+{ $subsections send-email }
"More topics:"
-{ $subsection "smtp-gmail" } ;
+{ $subsections "smtp-gmail" } ;
ABOUT: "smtp"
ARTICLE: "sorting.human" "Human-friendly sorting"
"The " { $vocab-link "sorting.human" } " vocabulary sorts by numbers as a human would -- by comparing their magnitudes -- rather than in a lexicographic way. For example, sorting a1, a10, a03, a2 with human sort returns a1, a2, a03, a10, while sorting with natural sort returns a03, a1, a10, a2." $nl
"Comparing two objects:"
-{ $subsection human<=> }
-{ $subsection human>=< }
+{ $subsections
+ human<=>
+ human>=<
+}
"Splitting a string into substrings and integers:"
-{ $subsection find-numbers } ;
+{ $subsections find-numbers } ;
ABOUT: "sorting.human"
ARTICLE: "sorting.slots" "Sorting by slots"
"The " { $vocab-link "sorting.slots" } " vocabulary can sort tuples by slot in ascending or descending order, using subsequent slots as tie-breakers." $nl
"Comparing two objects by a sequence of slots:"
-{ $subsection compare-slots }
+{ $subsections compare-slots }
"Sorting a sequence of tuples by a slot/comparator pairs:"
-{ $subsection sort-by }
-{ $subsection sort-keys-by }
-{ $subsection sort-values-by } ;
+{ $subsections
+ sort-by
+ sort-keys-by
+ sort-values-by
+} ;
ABOUT: "sorting.slots"
"The " { $vocab-link "specialized-arrays" } " vocabulary implements fixed-length sequence types for storing machine values in a space-efficient manner without boxing."
$nl
"A specialized array type needs to be generated for each element type. This is done with a parsing word:"
-{ $subsection POSTPONE: SPECIALIZED-ARRAY: }
+{ $subsections POSTPONE: SPECIALIZED-ARRAY: }
"This parsing word adds new words to the search path, documented in the next section."
-{ $subsection "specialized-array-words" }
-{ $subsection "specialized-array-c" }
-{ $subsection "specialized-array-math" }
-{ $subsection "specialized-array-examples" }
+{ $subsections
+ "specialized-array-words"
+ "specialized-array-c"
+ "specialized-array-math"
+ "specialized-array-examples"
+}
"The " { $vocab-link "specialized-vectors" } " vocabulary provides a resizable version of this abstraction." ;
ABOUT: "specialized-arrays"
ARTICLE: "specialized-vectors" "Specialized vectors"
"The " { $vocab-link "specialized-vectors" } " vocabulary implements resizable sequence types for storing machine values in a space-efficient manner without boxing."
-{ $subsection "specialized-vector-words" }
-{ $subsection "specialized-vector-c" }
+{ $subsections
+ "specialized-vector-words"
+ "specialized-vector-c"
+}
"The " { $vocab-link "specialized-arrays" } " vocabulary provides a fixed-length version of this abstraction." ;
ABOUT: "specialized-vectors"
ARTICLE: "splitting.monotonic" "Splitting trending sequences"
"The " { $vocab-link "splitting.monotonic" } " vocabulary splits sequences that are trending downwards, upwards, or stably." $nl
"Splitting into sequences:"
-{ $subsection monotonic-split }
+{ $subsections monotonic-split }
"Splitting into slices:"
-{ $subsection monotonic-slice }
+{ $subsections monotonic-slice }
"Trending:"
-{ $subsection downward-slices }
-{ $subsection stable-slices }
-{ $subsection upward-slices }
-{ $subsection trends } ;
+{ $subsections
+ downward-slices
+ stable-slices
+ upward-slices
+ trends
+} ;
ABOUT: "splitting.monotonic"
{ "The " { $link "compiler" } " reports them via " { $link "tools.errors" } }
}
"Errors thrown when insufficient information is available to calculate the stack effect of a call to a combinator or macro (see " { $link "inference-combinators" } "):"
-{ $subsection do-not-compile }
-{ $subsection literal-expected }
+{ $subsections
+ do-not-compile
+ literal-expected
+}
"Error thrown when a word's stack effect declaration does not match the composition of the stack effects of its factors:"
-{ $subsection effect-error }
+{ $subsections effect-error }
"Error thrown when branches have incompatible stack effects (see " { $link "inference-branches" } "):"
-{ $subsection unbalanced-branches-error }
+{ $subsections unbalanced-branches-error }
"Inference errors for inline recursive words (see " { $link "inference-recursive-combinators" } "):"
-{ $subsection undeclared-recursion-error }
-{ $subsection diverging-recursion-error }
-{ $subsection unbalanced-recursion-error }
-{ $subsection inconsistent-recursive-call-error }
+{ $subsections
+ undeclared-recursion-error
+ diverging-recursion-error
+ unbalanced-recursion-error
+ inconsistent-recursive-call-error
+}
"More obscure errors that are unlikely to arise in ordinary code:"
-{ $subsection recursive-quotation-error }
-{ $subsection too-many->r }
-{ $subsection too-many-r> }
-{ $subsection missing-effect } ;
+{ $subsections
+ recursive-quotation-error
+ too-many->r
+ too-many-r>
+ missing-effect
+} ;
ABOUT: "inference-errors"
ARTICLE: "tools.inference" "Stack effect tools"
{ $link "inference" } " can be used interactively to print stack effects of quotations without running them. It can also be used from " { $link "combinators.smart" } "."
-{ $subsection infer }
-{ $subsection infer. }
+{ $subsections
+ infer
+ infer.
+}
"There are also some words for working with " { $link effect } " instances. Getting a word's declared stack effect:"
-{ $subsection stack-effect }
+{ $subsections stack-effect }
"Converting a stack effect to a string form:"
-{ $subsection effect>string }
+{ $subsections effect>string }
"Comparing effects:"
-{ $subsection effect-height }
-{ $subsection effect<= }
-{ $subsection effect= }
+{ $subsections
+ effect-height
+ effect<=
+ effect=
+}
"The class of stack effects:"
-{ $subsection effect }
-{ $subsection effect? } ;
+{ $subsections
+ effect
+ effect?
+} ;
ARTICLE: "inference-escape" "Stack effect checking escape hatches"
"In a static checking regime, sometimes it is necessary to step outside the boundaries and run some code which cannot be statically checked; perhaps this code is constructed at run-time. There are two ways to get around the static stack checker."
"If the stack effect of a word or quotation is known, but the word or quotation itself is not, " { $link POSTPONE: execute( } " or " { $link POSTPONE: call( } " can be used. See " { $link "call" } " for details."
$nl
"If the stack effect is not known, the code being called cannot manipulate the datastack directly. Instead, it must reflect the datastack into an array:"
-{ $subsection with-datastack }
+{ $subsections with-datastack }
"The surrounding code has a static stack effect since " { $link with-datastack } " has one. However, the array passed in as input may be transformed arbitrarily by calling this combinator." ;
ARTICLE: "inference" "Stack effect checking"
"If a word's stack effect cannot be inferred, a compile error is reported. See " { $link "compiler-errors" } "."
$nl
"The following articles describe how different control structures are handled by the stack checker."
-{ $subsection "inference-simple" }
-{ $subsection "inference-combinators" }
-{ $subsection "inference-recursive-combinators" }
-{ $subsection "inference-branches" }
+{ $subsections
+ "inference-simple"
+ "inference-combinators"
+ "inference-recursive-combinators"
+ "inference-branches"
+}
"Stack checking catches several classes of errors."
-{ $subsection "inference-errors" }
+{ $subsections "inference-errors" }
"Sometimes code with a dynamic stack effect has to be run."
-{ $subsection "inference-escape" }
+{ $subsections "inference-escape" }
{ $see-also "effects" "tools.inference" "tools.errors" } ;
ABOUT: "inference"
"The " { $vocab-link "suffix-arrays" } " vocabulary implements the suffix array data structure for efficient lookup of subsequences. This suffix array implementation is a sorted array of suffixes. Querying it for matches uses binary search for efficiency." $nl
"Creating new suffix arrays:"
-{ $subsection >suffix-array }
+{ $subsections >suffix-array }
"Literal suffix arrays:"
-{ $subsection POSTPONE: SA{ }
+{ $subsections POSTPONE: SA{ }
"Querying suffix arrays:"
-{ $subsection query } ;
+{ $subsections query } ;
ABOUT: "suffix-arrays"
ARTICLE: "summary" "Converting objects to summary strings"
"A word for getting very brief descriptions of words and general objects:"
-{ $subsection summary } ;
+{ $subsections summary } ;
HELP: summary
{ $values { "object" object } { "string" string } }
"The " { $vocab-link "syndication" } " vocabulary implements support for reading Atom and RSS feeds, and writing Atom feeds."
$nl
"Data types:"
-{ $subsection feed }
-{ $subsection <feed> }
-{ $subsection entry }
-{ $subsection <entry> }
+{ $subsections
+ feed
+ <feed>
+ entry
+ <entry>
+}
"Reading feeds:"
-{ $subsection download-feed }
-{ $subsection parse-feed }
-{ $subsection xml>feed }
+{ $subsections
+ download-feed
+ parse-feed
+ xml>feed
+}
"Writing feeds:"
-{ $subsection feed>xml }
+{ $subsections feed>xml }
"The " { $vocab-link "furnace.syndication" } " vocabulary builds on top of this vocabulary to enable easy generation of Atom feeds from web applications. The " { $vocab-link "webapps.planet" } " vocabulary is a complete example of a web application which reads and exports feeds."
{ $see-also "urls" } ;
ARTICLE: "threads-start/stop" "Starting and stopping threads"
"Spawning new threads:"
-{ $subsection spawn }
-{ $subsection spawn-server }
+{ $subsections
+ spawn
+ spawn-server
+}
"Creating and spawning a thread can be factored out into two separate steps:"
-{ $subsection <thread> }
-{ $subsection (spawn) }
+{ $subsections
+ <thread>
+ (spawn)
+}
"Threads stop either when the quotation given to " { $link spawn } " returns, or when the following word is called:"
-{ $subsection stop }
+{ $subsections stop }
"If the image is saved and started again, all runnable threads are stopped. Vocabularies wishing to have a background thread always running should use " { $link add-init-hook } "." ;
ARTICLE: "threads-yield" "Yielding and suspending threads"
"Yielding to other threads:"
-{ $subsection yield }
+{ $subsections yield }
"Sleeping for a period of time:"
-{ $subsection sleep }
+{ $subsections sleep }
"Interrupting sleep:"
-{ $subsection interrupt }
+{ $subsections interrupt }
"Threads can be suspended and woken up at some point in the future when a condition is satisfied:"
-{ $subsection suspend }
-{ $subsection resume }
-{ $subsection resume-with } ;
+{ $subsections
+ suspend
+ resume
+ resume-with
+} ;
ARTICLE: "thread-state" "Thread-local state and variables"
"Threads form a class of objects:"
-{ $subsection thread }
+{ $subsections thread }
"The current thread:"
-{ $subsection self }
+{ $subsections self }
"Thread-local variables:"
-{ $subsection tnamespace }
-{ $subsection tget }
-{ $subsection tset }
-{ $subsection tchange }
+{ $subsections
+ tnamespace
+ tget
+ tset
+ tchange
+}
"Each thread has its own independent set of thread-local variables and newly-spawned threads begin with an empty set."
$nl
"Global hashtable of all threads, keyed by " { $snippet "id" } ":"
-{ $subsection threads }
+{ $subsections threads }
"Threads have an identity independent of continuations. If a continuation is refied in one thread and then resumed in another thread, the code running in that continuation will observe a change in the value output by " { $link self } "." ;
ARTICLE: "thread-impl" "Thread implementation"
"Thread implementation:"
-{ $subsection run-queue }
-{ $subsection sleep-queue } ;
+{ $subsections
+ run-queue
+ sleep-queue
+} ;
ARTICLE: "threads" "Lightweight co-operative threads"
"Factor supports lightweight co-operative threads implemented on top of " { $link "continuations" } ". A thread will yield while waiting for input/output operations to complete, or when a yield has been explicitly requested."
"Factor threads are very lightweight. Each thread can take as little as 900 bytes of memory. This library has been tested running hundreds of thousands of simple threads."
$nl
"Words for working with threads are in the " { $vocab-link "threads" } " vocabulary."
-{ $subsection "threads-start/stop" }
-{ $subsection "threads-yield" }
-{ $subsection "thread-state" }
-{ $subsection "thread-impl" } ;
+{ $subsections
+ "threads-start/stop"
+ "threads-yield"
+ "thread-state"
+ "thread-impl"
+} ;
ABOUT: "threads"
"The word annotation feature modifies word definitions to add debugging code. You can restore the old definition by calling " { $link reset } " on the word in question."
$nl
"Printing messages when a word is called or returns:"
-{ $subsection watch }
-{ $subsection watch-vars }
+{ $subsections
+ watch
+ watch-vars
+}
"Timing words:"
-{ $subsection reset-word-timing }
-{ $subsection add-timing }
-{ $subsection word-timing. }
+{ $subsections
+ reset-word-timing
+ add-timing
+ word-timing.
+}
"All of the above words are implemented using a single combinator which applies a quotation to a word definition to yield a new definition:"
-{ $subsection annotate }
+{ $subsections annotate }
{ $warning
"Certain internal words, such as words in the " { $vocab-link "math" } ", " { $vocab-link "sequences" } " and UI vocabularies, cannot be annotated, since the annotated code may end up recursively invoking the word in question. This may crash or hang Factor. It is safest to only define annotations on your own words."
} ;
"Various developer tools make use of a general-purpose fuzzy completion algorithm."
$nl
"The main entry point:"
-{ $subsection completions }
+{ $subsections completions }
"The words used to implement the algorithm can be called as well, for finer control over fuzzy matching:"
-{ $subsection fuzzy }
-{ $subsection runs }
-{ $subsection score }
-{ $subsection complete }
-{ $subsection rank-completions } ;
+{ $subsections
+ fuzzy
+ runs
+ score
+ complete
+ rank-completions
+} ;
ABOUT: "tools.completion"
ARTICLE: "tools.crossref" "Definition cross referencing"
"Definitions can answer a sequence of definitions they directly depend on:"
-{ $subsection uses }
+{ $subsections uses }
"An inverted index of the above:"
-{ $subsection get-crossref }
+{ $subsections get-crossref }
"Words to access it:"
-{ $subsection usage }
-{ $subsection smart-usage }
+{ $subsections
+ usage
+ smart-usage
+}
"Tools for interactive use:"
-{ $subsection usage. }
-{ $subsection vocab-uses. }
-{ $subsection vocab-usage. }
+{ $subsections
+ usage.
+ vocab-uses.
+ vocab-usage.
+}
{ $see-also "definitions" "words" "see" } ;
ABOUT: "tools.crossref"
ARTICLE: "deploy-flags" "Deployment flags"
"There are two sets of deployment flags. The first set controls the major subsystems which are to be included in the deployment image:"
-{ $subsection deploy-math? }
-{ $subsection deploy-unicode? }
-{ $subsection deploy-threads? }
-{ $subsection deploy-ui? }
+{ $subsections
+ deploy-math?
+ deploy-unicode?
+ deploy-threads?
+ deploy-ui?
+}
"The second set of flags controls the level of stripping to be performed on the deployment image; there is a trade-off between image size, and retaining functionality which is required by the application:"
-{ $subsection deploy-io }
-{ $subsection deploy-reflection }
-{ $subsection deploy-word-props? }
-{ $subsection deploy-c-types? } ;
+{ $subsections
+ deploy-io
+ deploy-reflection
+ deploy-word-props?
+ deploy-c-types?
+} ;
ABOUT: "deploy-flags"
ARTICLE: "deploy-config" "Deployment configuration"
"The deployment configuration is a key/value mapping stored in the " { $snippet "deploy.factor" } " file in the vocabulary's directory. If this file does not exist, the default deployment configuration is used:"
-{ $subsection default-config }
+{ $subsections default-config }
"The deployment configuration can be read and written with a pair of words:"
-{ $subsection deploy-config }
-{ $subsection set-deploy-config }
+{ $subsections
+ deploy-config
+ set-deploy-config
+}
"A utility word is provided to load the configuration, change a flag, and store it back to disk:"
-{ $subsection set-deploy-flag }
+{ $subsections set-deploy-flag }
"The " { $link "ui.tools.deploy" } " provides a graphical way of editing the configuration." ;
HELP: deploy-config
ARTICLE: "prepare-deploy" "Preparing to deploy an application"
"In order to deploy an application as a stand-alone image, the application's vocabulary must first be given a " { $link POSTPONE: MAIN: } " hook. Then, a " { $emphasis "deployment configuration" } " must be created."
-{ $subsection "deploy-config" }
-{ $subsection "deploy-flags" } ;
+{ $subsections
+ "deploy-config"
+ "deploy-flags"
+} ;
ARTICLE: "tools.deploy.usage" "Deploy tool usage"
"Once the necessary deployment flags have been set, the application can be deployed:"
-{ $subsection deploy }
+{ $subsections deploy }
"For example, you can deploy the " { $vocab-link "hello-ui" } " demo which comes with Factor. Note that this demo already has a deployment configuration, so nothing needs to be configured:"
{ $code "\"hello-ui\" deploy" }
{ $list
"Most of the time, the words in the " { $vocab-link "tools.deploy" } " vocabulary should not be used directly; instead, use " { $link "ui.tools.deploy" } "."
$nl
"You must explicitly specify major subsystems which are required, as well as the level of reflection support needed. This is done by modifying the deployment configuration prior to deployment."
-{ $subsection "prepare-deploy" }
-{ $subsection "tools.deploy.usage" }
-{ $subsection "tools.deploy.impl" }
-{ $subsection "tools.deploy.caveats" } ;
+{ $subsections
+ "prepare-deploy"
+ "tools.deploy.usage"
+ "tools.deploy.impl"
+ "tools.deploy.caveats"
+} ;
ABOUT: "tools.deploy"
ARTICLE: "tools.deprecation" "Deprecation tracking"
"Factor's core syntax defines a " { $link POSTPONE: deprecated } " word that can be applied to words to mark them as deprecated. When the " { $vocab-link "tools.deprecation" } " vocabulary is loaded, notes will be collected and reported by the " { $link "tools.errors" } " mechanism when deprecated words are used to define other words."
-{ $subsection POSTPONE: deprecated }
-{ $subsection :deprecations } ;
+{ $subsections
+ POSTPONE: deprecated
+ :deprecations
+} ;
ABOUT: "tools.deprecation"
ARTICLE: "tools.destructors" "Destructor tools"
"The " { $vocab-link "tools.destructors" } " vocabulary provides words for tracking down resource leaks."
-{ $subsection debug-leaks? }
-{ $subsection disposables. }
-{ $subsection leaks }
+{ $subsections
+ debug-leaks?
+ disposables.
+ leaks
+}
{ $see-also "destructors" } ;
ABOUT: "tools.destructors"
\r
ARTICLE: "tools.disassembler" "Disassembling words"\r
"The " { $vocab-link "tools.disassembler" } " vocabulary provides support for disassembling compiled word definitions. It uses the " { $snippet "libudis86" } " library on x86-32 and x86-64, and " { $snippet "gdb" } " on PowerPC."\r
-{ $subsection disassemble } ;\r
+{ $subsections disassemble } ;\r
\r
ABOUT: "tools.disassembler"\r
"This indicates that some words did not pass the stack checker. Stack checker error conditions are documented in " { $link "inference-errors" } ", and the stack checker itself in " { $link "inference" } "."
$nl
"Words to view errors:"
-{ $subsection :errors }
-{ $subsection :linkage }
+{ $subsections
+ :errors
+ :linkage
+}
"Compiler errors are reported using the " { $link "tools.errors" } " mechanism, and as a result, they are also are shown in the " { $link "ui.tools.error-list" } "." ;
HELP: compiler-error
"Some tools, such as the " { $link "compiler" } ", " { $link "tools.test" } " and " { $link "help.lint" } " need to report multiple errors at a time. Each error is associated with a source file, line number, and optionally, a definition. " { $link "errors" } " cannot be used for this purpose, so the " { $vocab-link "source-files.errors" } " vocabulary provides an alternative mechanism. Note that the words in this vocabulary are used for implementation only; to actually list errors, consult the documentation for the relevant tools."
$nl
"Source file errors inherit from a class:"
-{ $subsection source-file-error }
+{ $subsections source-file-error }
"Printing an error summary:"
-{ $subsection error-summary }
+{ $subsections error-summary }
"Printing a list of errors:"
-{ $subsection errors. }
+{ $subsections errors. }
"Batch errors are reported in the " { $link "ui.tools.error-list" } "." ;
ABOUT: "tools.errors"
\ No newline at end of file
ARTICLE: "tools.files" "Files tools"
"The " { $vocab-link "tools.files" } " vocabulary implements directory files and file-systems listing in a cross-platform way." $nl
"Listing a directory:"
-{ $subsection directory. } ;
+{ $subsections directory. } ;
ABOUT: "tools.files"
ARTICLE: "tools.hexdump" "Hexdump"
"The " { $vocab-link "tools.hexdump" } " vocabulary provides a traditional hexdump view of a sequence." $nl
"Write hexdump to string:"
-{ $subsection hexdump }
+{ $subsections hexdump }
"Write the hexdump to the output stream:"
-{ $subsection hexdump. } ;
+{ $subsections hexdump. } ;
ABOUT: "tools.hexdump"
ARTICLE: "tools.memory" "Object memory tools"
"You can print object heap status information:"
-{ $subsection room. }
-{ $subsection heap-stats. }
-{ $subsection heap-stats }
+{ $subsections
+ room.
+ heap-stats.
+ heap-stats
+}
"You can query memory status:"
-{ $subsection data-room }
-{ $subsection code-room }
+{ $subsections
+ data-room
+ code-room
+}
"There are a pair of combinators, analogous to " { $link each } " and " { $link filter } ", which operate on the entire collection of objects in the object heap:"
-{ $subsection each-object }
-{ $subsection instances }
+{ $subsections
+ each-object
+ instances
+}
"You can check an object's the heap memory usage:"
-{ $subsection size }
+{ $subsections size }
"The garbage collector can be invoked manually:"
-{ $subsection gc }
+{ $subsections gc }
{ $see-also "images" } ;
ABOUT: "tools.memory"
"The " { $vocab-link "tools.profiler" } " vocabulary implements a simple call counting profiler."
$nl
"Quotations can be passed to a combinator which calls them with the profiler enabled:"
-{ $subsection profile }
+{ $subsections profile }
"After a quotation has been profiled, call counts can be presented in various ways:"
-{ $subsection profile. }
-{ $subsection vocab-profile. }
-{ $subsection usage-profile. }
-{ $subsection vocabs-profile. }
-{ $subsection method-profile. }
-{ $subsection "profiler-limitations" }
+{ $subsections
+ profile.
+ vocab-profile.
+ usage-profile.
+ vocabs-profile.
+ method-profile.
+ "profiler-limitations"
+}
{ $see-also "ui.tools.profiler" } ;
ABOUT: "profiling"
ARTICLE: "tools.scaffold" "Scaffold tool"
"Scaffold setup:"
-{ $subsection developer-name }
+{ $subsections developer-name }
"Generate new vocabs:"
-{ $subsection scaffold-vocab }
+{ $subsections scaffold-vocab }
"Generate help scaffolding:"
-{ $subsection scaffold-help }
-{ $subsection scaffold-undocumented }
-{ $subsection help. }
+{ $subsections
+ scaffold-help
+ scaffold-undocumented
+ help.
+}
"Types that are unrecognized by the scaffold generator will be of type " { $link null } ". The developer should change these to strings that describe the stack effect names instead." $nl
"Scaffolding a configuration file:"
-{ $subsection scaffold-rc }
-{ $subsection scaffold-factor-boot-rc }
-{ $subsection scaffold-factor-rc }
-{ $subsection scaffold-emacs }
+{ $subsections
+ scaffold-rc
+ scaffold-factor-boot-rc
+ scaffold-factor-rc
+ scaffold-emacs
+}
;
ABOUT: "tools.scaffold"
ARTICLE: "tools.test.write" "Writing unit tests"
"Assert that a quotation outputs a specific set of values:"
-{ $subsection POSTPONE: unit-test }
+{ $subsections POSTPONE: unit-test }
"Assert that a quotation throws an error:"
-{ $subsection POSTPONE: must-fail }
-{ $subsection POSTPONE: must-fail-with }
+{ $subsections
+ POSTPONE: must-fail
+ POSTPONE: must-fail-with
+}
"Assert that a quotation or word has a specific static stack effect (see " { $link "inference" } "):"
-{ $subsection POSTPONE: must-infer }
-{ $subsection POSTPONE: must-infer-as }
+{ $subsections
+ POSTPONE: must-infer
+ POSTPONE: must-infer-as
+}
"All of the above are used like ordinary words but are actually parsing words. This ensures that parse-time state, namely the line number, can be associated with the test in question, and reported in test failures." ;
ARTICLE: "tools.test.run" "Running unit tests"
"The following words run test harness files; any test failures are collected and printed at the end:"
-{ $subsection test }
-{ $subsection test-all }
+{ $subsections
+ test
+ test-all
+}
"The following word prints failures:"
-{ $subsection :test-failures }
+{ $subsections :test-failures }
"Test failures are reported using the " { $link "tools.errors" } " mechanism and are shown in the " { $link "ui.tools.error-list" } "."
$nl
"Unit test failures are instances of a class, and are stored in a global variable:"
-{ $subsection test-failure }
-{ $subsection test-failures } ;
+{ $subsections
+ test-failure
+ test-failures
+} ;
ARTICLE: "tools.test" "Unit testing"
"A unit test is a piece of code which starts with known input values, then compares the output of a word with an expected output, where the expected output is defined by the word's contract."
"The latter is used for vocabularies with more extensive test suites."
$nl
"If the test harness needs to define words, they should be placed in a vocabulary named " { $snippet { $emphasis "vocab" } ".tests" } " where " { $emphasis "vocab" } " is the vocab being tested."
-{ $subsection "tools.test.write" }
-{ $subsection "tools.test.run" } ;
+{ $subsections
+ "tools.test.write"
+ "tools.test.run"
+} ;
ABOUT: "tools.test"
ARTICLE: "tools.threads" "Listing threads"
"Printing a list of running threads:"
-{ $subsection threads. } ;
+{ $subsections threads. } ;
ABOUT: "tools.threads"
ARTICLE: "timing" "Timing code"
"You can time the execution of a quotation in the listener:"
-{ $subsection time }
+{ $subsections time }
"A lower-level word puts timings on the stack, intead of printing:"
-{ $subsection benchmark }
+{ $subsections benchmark }
"You can also read the system clock and garbage collection statistics directly:"
-{ $subsection micros }
-{ $subsection gc-stats }
+{ $subsections
+ micros
+ gc-stats
+}
{ $see-also "profiling" } ;
ABOUT: "timing"
"In addition to invoking the walker explicitly through the UI, it is possible to set breakpoints on words using words in the " { $vocab-link "tools.walker" } " vocabulary."
$nl
"Annotating a word with a breakpoint (see " { $link "tools.annotations" } "):"
-{ $subsection breakpoint }
-{ $subsection breakpoint-if }
+{ $subsections
+ breakpoint
+ breakpoint-if
+}
"Breakpoints can be inserted directly into code:"
-{ $subsection break }
-{ $subsection POSTPONE: B }
+{ $subsections
+ break
+ POSTPONE: B
+}
"Note that because the walker calls various core library and UI words while rendering its own user interface, setting a breakpoint on a word such as " { $link append } " or " { $link + } " will hang the UI." ;
ABOUT: "breakpoints"
"Since value semantics differ from reference semantics, it is best to use tuple arrays with tuples where all slots are declared " { $link read-only } "."
$nl
"Tuple arrays should not be used with inheritance; storing an instance of a subclass in a tuple array will slice off the subclass slots, and getting the same value out again will yield an instance of the superclass. Also, tuple arrays do not get updated if tuples are redefined to add or remove slots, so caution should be exercised when doing interactive development on code that uses tuple arrays."
-{ $subsection POSTPONE: TUPLE-ARRAY: }
+{ $subsections POSTPONE: TUPLE-ARRAY: }
"An example:"
{ $example
"USE: tuple-arrays"
ARTICLE: "clipboard-protocol" "Clipboard protocol"
"Custom gadgets that wish to interact with the clipboard must use the following two generic words to read and write clipboard contents:"
-{ $subsection paste-clipboard }
-{ $subsection copy-clipboard }
+{ $subsections
+ paste-clipboard
+ copy-clipboard
+}
"UI backends can either implement the above two words in the case of an asynchronous clipboard model (for example, X11). If direct access to the clipboard is provided (Windows, Mac OS X), the following two generic words may be implemented instead:"
-{ $subsection clipboard-contents }
-{ $subsection set-clipboard-contents }
+{ $subsections
+ clipboard-contents
+ set-clipboard-contents
+}
"However, gadgets should not call these words, since they will fail if only the asynchronous method of clipboard access is supported by the backend in use."
$nl
"Access to two clipboards is provided:"
-{ $subsection clipboard }
-{ $subsection selection }
+{ $subsections
+ clipboard
+ selection
+}
"These variables may contain clipboard protocol implementations which transfer data to and from the native system clipboard. However an UI backend may leave one or both of these variables in their default state, which is a trivial clipboard implementation internal to the Factor UI." ;
ABOUT: "clipboard-protocol"
ARTICLE: "ui-commands" "Commands"
"Commands are an abstraction layered on top of gestures. Their main advantage is that they are identified by words and can be organized into " { $emphasis "command maps" } ". This allows easy construction of buttons and tool bars for invoking commands."
-{ $subsection define-command }
+{ $subsections define-command }
"Command groups are defined on gadget classes:"
-{ $subsection define-command-map }
+{ $subsections define-command-map }
"Commands can be introspected and invoked:"
-{ $subsection commands }
-{ $subsection command-map }
-{ $subsection invoke-command }
+{ $subsections
+ commands
+ command-map
+ invoke-command
+}
"Gadgets for invoking commands are documented in " { $link "ui.gadgets.buttons" } "."
$nl
"When documenting gadgets, command documentation can be automatically generated:"
-{ $subsection $command-map }
-{ $subsection $command } ;
+{ $subsections
+ $command-map
+ $command
+} ;
ABOUT: "ui-commands"
ARTICLE: "ui-book-layout" "Book layouts"
"Books can contain any number of children, and display one child at a time. The currently visible child is determined by the value of the model, which must be an integer."
-{ $subsection book }
-{ $subsection <book> }
-{ $subsection <empty-book> } ;
+{ $subsections
+ book
+ <book>
+ <empty-book>
+} ;
ABOUT: "ui-book-layout"
ARTICLE: "ui.gadgets.borders" "Border gadgets"
"The " { $vocab-link "ui.gadgets.borders" } " vocabulary implements border gadgets, which add empty space around a child gadget."
-{ $subsection border }
-{ $subsection <border> } ;
+{ $subsections
+ border
+ <border>
+} ;
ABOUT: "ui.gadgets.borders"
ARTICLE: "ui.gadgets.buttons" "Button gadgets"
"The " { $vocab-link "ui.gadgets.buttons" } " vocabulary implements buttons. Buttons respond to mouse clicks by invoking a quotation."
-{ $subsection button }
+{ $subsections button }
"There are many ways to create a new button:"
-{ $subsection <button> }
-{ $subsection <roll-button> }
-{ $subsection <border-button> }
-{ $subsection <repeat-button> }
+{ $subsections
+ <button>
+ <roll-button>
+ <border-button>
+ <repeat-button>
+}
"Gadgets for invoking commands:"
-{ $subsection <command-button> }
-{ $subsection <toolbar> }
+{ $subsections
+ <command-button>
+ <toolbar>
+}
"Button appearance can be customized:"
-{ $subsection button-pen }
+{ $subsections button-pen }
"Button constructors take " { $emphasis "label specifiers" } " as input. A label specifier is either a string, an array of strings, a gadget or " { $link f } "."
{ $see-also <command-button> "ui-commands" } ;
ARTICLE: "gadgets-editors-selection" "The caret and mark"
"If there is no selection, the caret and the mark are at the same location; otherwise the mark delimits the end-point of the selection opposite the caret."
-{ $subsection editor-caret }
-{ $subsection editor-mark }
-{ $subsection change-caret }
-{ $subsection change-caret&mark }
-{ $subsection mark>caret }
+{ $subsections
+ editor-caret
+ editor-mark
+ change-caret
+ change-caret&mark
+ mark>caret
+}
"Getting the selected text:"
-{ $subsection gadget-selection? }
-{ $subsection gadget-selection }
+{ $subsections
+ gadget-selection?
+ gadget-selection
+}
"Removing selected text:"
-{ $subsection remove-selection }
+{ $subsections remove-selection }
"Scrolling to the caret location:"
-{ $subsection scroll>caret }
+{ $subsections scroll>caret }
"Use " { $link user-input* } " to change selected text." ;
ARTICLE: "gadgets-editors-contents" "Getting and setting editor contents"
-{ $subsection editor-string }
-{ $subsection set-editor-string }
-{ $subsection clear-editor } ;
+{ $subsections
+ editor-string
+ set-editor-string
+ clear-editor
+} ;
ARTICLE: "gadgets-editors-commands" "Editor gadget commands"
{ $command-map editor "editing" }
ARTICLE: "ui.gadgets.editors" "Editor gadgets"
"The " { $vocab-link "ui.gadgets.editors" } " vocabulary implements editor gadgets. An editor edits a passage of text. Editors display a " { $link document } ". Editors are built from and inherit all features of " { $link "ui.gadgets.line-support" } "."
-{ $subsection "gadgets-editors-commands" }
+{ $subsections "gadgets-editors-commands" }
"Editors:"
-{ $subsection editor }
-{ $subsection <editor> }
-{ $subsection "gadgets-editors-contents" }
-{ $subsection "gadgets-editors-selection" }
+{ $subsections
+ editor
+ <editor>
+ "gadgets-editors-contents"
+ "gadgets-editors-selection"
+}
"Multiline editors:"
-{ $subsection <multiline-editor> }
+{ $subsections <multiline-editor> }
"Fields:"
-{ $subsection <model-field> }
-{ $subsection <action-field> }
+{ $subsections
+ <model-field>
+ <action-field>
+}
"Editors edit " { $emphasis "documents" } ":"
-{ $subsection "documents" } ;
+{ $subsections "documents" } ;
TIP: "Editor gadgets support undo and redo; press " { $command editor "editing" com-undo } " and " { $command editor "editing" com-redo } "." ;
"The filled cell's column/row pair is stored in the frame gadget's " { $slot "filled-cell" } " slot. If the actual dimensions of a frame exceed it preferred dimensions, then the fill slot is resized appropriately, together with its row and column."
$nl
"Because frames inherit from grids, grid layout words can be used to add and remove children."
-{ $subsection frame }
+{ $subsections frame }
"Creating empty frames:"
-{ $subsection <frame> } ;
+{ $subsections <frame> } ;
HELP: frame
{ $class-description "A frame is a gadget which lays out its children in a grid, and assigns all remaining space to a distinguished filled cell. The " { $slot "filled-cell" } " slot stores a pair with shape " { $snippet "{ col row }" } "."
"A " { $emphasis "control" } " is a gadget which is linked to an underlying " { $link model } " by having its " { $snippet "model" } " slot set to a " { $link model } " instance."
$nl
"Some utility words useful in control implementations:"
-{ $subsection control-value }
-{ $subsection set-control-value }
+{ $subsections
+ control-value
+ set-control-value
+}
{ $see-also "models" } ;
"This feature is used for completion popups and " { $link "ui.gadgets.menus" } " in the " { $link "ui-tools" } "."
$nl
"Displaying a gadget in a glass layer:"
-{ $subsection show-glass }
+{ $subsections show-glass }
"Hiding a gadget in a glass layer:"
-{ $subsection hide-glass }
+{ $subsections hide-glass }
"Callback generic invoked on the gadget when its glass layer is hidden:"
-{ $subsection hide-glass-hook }
+{ $subsections hide-glass-hook }
"Popup gadgets add support for forwarding keyboard gestures from an owner gadget to the glass layer:"
-{ $subsection show-popup }
-{ $subsection pass-to-popup } ;
+{ $subsections
+ show-popup
+ pass-to-popup
+} ;
ABOUT: "ui.gadgets.glass"
\ No newline at end of file
{ $description "Creates a new " { $link grid-lines } "." } ;
ARTICLE: "ui.gadgets.grid-lines" "Grid lines"
-{ $subsection grid-lines }
-{ $subsection <grid-lines> } ;
+{ $subsections
+ grid-lines
+ <grid-lines>
+} ;
ABOUT: "ui.gadgets.grid-lines"
\ No newline at end of file
ARTICLE: "ui-grid-layout" "Grid layouts"
"Grid gadgets layout their children in a rectangular grid."
-{ $subsection grid }
+{ $subsections grid }
"Creating grids from a fixed set of gadgets:"
-{ $subsection <grid> }
+{ $subsections <grid> }
"Managing children:"
-{ $subsection grid-add }
-{ $subsection grid-remove }
-{ $subsection grid-child }
+{ $subsections
+ grid-add
+ grid-remove
+ grid-child
+}
"Grid lines:"
-{ $subsection "ui.gadgets.grid-lines" } ;
+{ $subsections "ui.gadgets.grid-lines" } ;
HELP: grid
{ $class-description "A grid gadget lays out its children so that all gadgets in a column have equal width and all gadgets in a row have equal height."
"Incremental layout is used by " { $link "ui.gadgets.panes" } " to ensure that new lines of output does not take longer to display when the pane already has previous output."
$nl
"Incremental layouts are not a general replacement for " { $link "ui-pack-layout" } " and there are some limitations to be aware of."
-{ $subsection incremental }
-{ $subsection <incremental> }
+{ $subsections
+ incremental
+ <incremental>
+}
"Children are added and removed with a special set of words which perform necessary relayout immediately:"
-{ $subsection add-incremental }
-{ $subsection clear-incremental }
+{ $subsections
+ add-incremental
+ clear-incremental
+}
"Calling " { $link unparent } " to remove a child of an incremental layout is permitted, however the relayout following the removal will not be performed in constant time, because all gadgets following the removed gadget need to be moved." ;
ABOUT: "ui-incremental-layout"
ARTICLE: "ui.gadgets.labeled" "Labeled gadgets"
"The " { $vocab-link "ui.gadgets.labeled" } " vocabulary implements labeled borders around child gadgets."
-{ $subsection labeled-gadget }
-{ $subsection <labeled-gadget> } ;
+{ $subsections
+ labeled-gadget
+ <labeled-gadget>
+} ;
ABOUT: "ui.gadgets.labeled"
ARTICLE: "ui.gadgets.labels" "Label gadgets"
"The " { $vocab-link "ui.gadgets.labels" } " vocabulary implements labels. A label displays a piece of text, which is either a single line string or an array of line strings."
-{ $subsection label }
-{ $subsection <label> }
-{ $subsection <label-control> }
+{ $subsections
+ label
+ <label>
+ <label-control>
+}
"Labels have a virtual slot named " { $slot "string" } " which contains the displayed text. The " { $slot "text" } " slot should not be set directly."
$nl
"Label specifiers are used by buttons, checkboxes and radio buttons:"
-{ $subsection >label } ;
+{ $subsections >label } ;
ABOUT: "ui.gadgets.labels"
"The " { $vocab-link "ui.gadgets.line-support" } " vocabulary provides common code shared by gadgets which display a sequence of lines of text. Currently, the two gadgets that use it are " { $link "ui.gadgets.editors" } " and " { $link "ui.gadgets.tables" } "."
$nl
"The class of line gadgets:"
-{ $subsection line-gadget }
-{ $subsection line-gadget? }
+{ $subsections
+ line-gadget
+ line-gadget?
+}
"Line gadgets are backed by a model which must be a sequence. The number of lines in the gadget is the length of the sequence."
$nl
"Line gadgets cannot be created and used directly, instead a subclass must be defined:"
-{ $subsection new-line-gadget }
+{ $subsections new-line-gadget }
"Subclasses must implement a generic word:"
-{ $subsection draw-line }
+{ $subsections draw-line }
"Two optional generic words may be implemented; if they are not implemented in the subclass, a default implementation based on font metrics will be used:"
-{ $subsection line-height }
-{ $subsection line-leading }
+{ $subsections
+ line-height
+ line-leading
+}
"Validating line numbers:"
-{ $subsection validate-line }
+{ $subsections validate-line }
"Working with visible lines:"
-{ $subsection visible-lines }
-{ $subsection first-visible-line }
-{ $subsection last-visible-line }
+{ $subsections
+ visible-lines
+ first-visible-line
+ last-visible-line
+}
"Converting y co-ordinates to line numbers, and vice versa:"
-{ $subsection line>y }
-{ $subsection y>line } ;
+{ $subsections
+ line>y
+ y>line
+} ;
ABOUT: "ui.gadgets.line-support"
\ No newline at end of file
ARTICLE: "ui.gadgets.menus" "Popup menus"
"The " { $vocab-link "ui.gadgets.menus" } " vocabulary displays popup menus in " { $link "ui.gadgets.glass" } "."
-{ $subsection <commands-menu> }
-{ $subsection show-menu }
-{ $subsection show-commands-menu } ;
+{ $subsections
+ <commands-menu>
+ show-menu
+ show-commands-menu
+} ;
ABOUT: "ui.gadgets.menus"
ARTICLE: "ui-pack-layout" "Pack layouts"
"Pack gadgets layout their children along a single axis."
-{ $subsection pack }
+{ $subsections pack }
"Creating empty packs:"
-{ $subsection <pack> }
-{ $subsection <pile> }
-{ $subsection <shelf> }
+{ $subsections
+ <pack>
+ <pile>
+ <shelf>
+}
"For more control, custom layouts can reuse portions of pack layout logic:"
-{ $subsection pack-pref-dim }
-{ $subsection pack-layout } ;
+{ $subsections
+ pack-pref-dim
+ pack-layout
+} ;
HELP: pack
{ $class-description "A gadget which lays out its children along a single axis stored in the " { $snippet "orientation" } " slot. Can be constructed with one of the following words:"
ARTICLE: "ui.gadgets.panes" "Pane gadgets"
"The " { $vocab-link "ui.gadgets.panes" } " vocabulary implements panes, which display formatted text."
-{ $subsection pane }
-{ $subsection <pane> }
-{ $subsection <pane-control> }
+{ $subsections
+ pane
+ <pane>
+ <pane-control>
+}
"Panes are written to by creating a special output stream:"
-{ $subsection pane-stream }
-{ $subsection <pane-stream> }
+{ $subsections
+ pane-stream
+ <pane-stream>
+}
"In addition to the stream output words (" { $link "stream-protocol" } ", pane streams can have gadgets written to them:"
-{ $subsection write-gadget }
-{ $subsection print-gadget }
-{ $subsection gadget. }
+{ $subsections
+ write-gadget
+ print-gadget
+ gadget.
+}
"The " { $link gadget. } " word is useful for interactive debugging of gadgets in the listener."
$nl
"There are a few combinators for working with panes:"
-{ $subsection with-pane }
-{ $subsection make-pane } ;
+{ $subsections
+ with-pane
+ make-pane
+} ;
ABOUT: "ui.gadgets.panes"
"The " { $vocab-link "ui.gadgets.presentations" } " vocabulary implements presentations, which are graphical representations of an object, associated with the object itself (see " { $link "ui-operations" } ")."
$nl
"Clicking a presentation with the left mouse button invokes the object's primary operation, and clicking with the right mouse button displays a menu of all applicable operations. Presentations are usually not constructed directly, and instead are written to " { $link "ui.gadgets.panes" } " with formatted stream output words (see " { $link "presentations" } ")."
-{ $subsection presentation }
-{ $subsection <presentation> } ;
+{ $subsections
+ presentation
+ <presentation>
+} ;
ABOUT: "ui.gadgets.presentations"
ARTICLE: "ui.gadgets.scrollers" "Scroller gadgets"
"The " { $vocab-link "ui.gadgets.scrollers" } " vocabulary implements scroller gadgets. A scroller displays a gadget which is larger than the visible area."
-{ $subsection scroller }
-{ $subsection <scroller> }
+{ $subsections
+ scroller
+ <scroller>
+}
"Getting and setting the scroll position:"
-{ $subsection scroll-position }
-{ $subsection set-scroll-position }
+{ $subsections
+ scroll-position
+ set-scroll-position
+}
"Writing scrolling-aware gadgets:"
-{ $subsection scroll>bottom }
-{ $subsection scroll>top }
-{ $subsection scroll>rect }
-{ $subsection find-scroller } ;
+{ $subsections
+ scroll>bottom
+ scroll>top
+ scroll>rect
+ find-scroller
+} ;
ABOUT: "ui.gadgets.scrollers"
ARTICLE: "ui.gadgets.sliders" "Slider gadgets"
"The " { $vocab-link "ui.gadgets.sliders" } " vocabulary implements slider gadgets. A slider allows the user to graphically manipulate a value by moving a thumb back and forth."
-{ $subsection slider }
-{ $subsection <slider> }
+{ $subsections
+ slider
+ <slider>
+}
"Changing slider values:"
-{ $subsection slide-by }
-{ $subsection slide-by-line }
-{ $subsection slide-by-page }
+{ $subsections
+ slide-by
+ slide-by-line
+ slide-by-page
+}
"Since sliders are controls the value can be get and set by via the " { $snippet "model" } " slot. " ;
ABOUT: "ui.gadgets.sliders"
ARTICLE: "ui.gadgets.status-bar" "Status bars and mouse-over help"
"The " { $vocab-link "ui.gadgets.status-bar" } " vocabulary implements a word to display windows with a status bar."
-{ $subsection open-status-window }
+{ $subsections open-status-window }
"Gadgets can use a pair of words to show and hide status bar messages. These words will work in any gadget, but will have no effect unless the gadget is displayed inside a window with a status bar."
-{ $subsection show-status }
-{ $subsection hide-status }
+{ $subsections
+ show-status
+ hide-status
+}
{ $link "ui.gadgets.presentations" } " use the status bar to display object summary." ;
ABOUT: "ui.gadgets.status-bar"
"Table gadgets use a row renderer to display rows and do a few other things."
$nl
"Renderers are usually instances of singleton classes, since they don't need any state of their own. Renderers are required to implement a single generic word:"
-{ $subsection row-columns }
+{ $subsections row-columns }
"Renderers can also implement the following optional generic words for additional row information:"
-{ $subsection row-value }
-{ $subsection row-color }
+{ $subsections
+ row-value
+ row-color
+}
"The following optional generic words allow the renderer to provide some information about the display of all rows:"
-{ $subsection prototype-row }
-{ $subsection column-alignment }
-{ $subsection filled-column }
-{ $subsection column-titles } ;
+{ $subsections
+ prototype-row
+ column-alignment
+ filled-column
+ column-titles
+} ;
ARTICLE: "ui.gadgets.tables.selection" "Table row selection"
"A few slots in the table gadget concern row selection:"
{ { $slot "multiple-selection?" } { " - if set to a true value, users are allowed to select more than one value." } }
}
"Some words for row selection:"
-{ $subsection selected-rows }
-{ $subsection (selected-rows) }
-{ $subsection selected } ;
+{ $subsections
+ selected-rows
+ (selected-rows)
+ selected
+} ;
ARTICLE: "ui.gadgets.tables.actions" "Table row actions"
"When the user double-clicks on a row, or presses " { $command table "row" row-action } " while a row is selected, optional action and hook quotations are invoked. The action receives the row value and the hook receives the table gadget itself. These quotations are stored in the " { $slot "action" } " and " { $snippet "hook" } " slots of a table, respectively."
"If the " { $slot "single-click?" } " slot is set to a true value, then single-clicking on a row will invoke the row action. The default value is " { $link f } "."
$nl
"The row action can also be invoked programmatically:"
-{ $subsection row-action } ;
+{ $subsections row-action } ;
ARTICLE: "ui.gadgets.tables.config" "Table gadget configuration"
"Various slots in the table gadget can be set to change the appearance and behavior of the table gadget."
"Tables display a model as a series of rows. The model must be a sequence, and a " { $emphasis "renderer" } " creates a sequence of columns for each row. Tables are built from and inherit all features of " { $link "ui.gadgets.line-support" } "."
{ $command-map table "row" }
"The class of tables:"
-{ $subsection table }
-{ $subsection table? }
+{ $subsections
+ table
+ table?
+}
"Creating new tables:"
-{ $subsection <table> }
-{ $subsection "ui.gadgets.tables.renderers" }
-{ $subsection "ui.gadgets.tables.selection" }
-{ $subsection "ui.gadgets.tables.actions" }
-{ $subsection "ui.gadgets.tables.example" } ;
+{ $subsections
+ <table>
+ "ui.gadgets.tables.renderers"
+ "ui.gadgets.tables.selection"
+ "ui.gadgets.tables.actions"
+ "ui.gadgets.tables.example"
+} ;
ABOUT: "ui.gadgets.tables"
\ No newline at end of file
ARTICLE: "ui-track-layout" "Track layouts"
"Track gadgets are like " { $link "ui-pack-layout" } " except each child is resized to a fixed multiple of the track's dimension."
-{ $subsection track }
+{ $subsections track }
"Creating empty tracks:"
-{ $subsection <track> }
+{ $subsections <track> }
"Adding children:"
-{ $subsection track-add } ;
+{ $subsections track-add } ;
HELP: track
{ $class-description "A track is like a " { $link pack } " except each child is resized to a fixed multiple of the track's dimension in the direction of " { $snippet "orientation" } ". Tracks are created by calling " { $link <track> } "." } ;
ARTICLE: "ui.gadgets.worlds-subclassing" "Subclassing worlds"
"The " { $link world } " gadget can be subclassed, giving Factor code full control of the window's OpenGL context. The following generic words can be overridden to replace standard UI behavior:"
-{ $subsection begin-world }
-{ $subsection end-world }
-{ $subsection resize-world }
-{ $subsection draw-world* }
+{ $subsections
+ begin-world
+ end-world
+ resize-world
+ draw-world*
+}
"See the " { $vocab-link "spheres" } " and " { $vocab-link "bunny" } " demos for examples." ;
ARTICLE: "ui-paint-custom" "Implementing custom drawing logic"
"The UI uses OpenGL to render gadgets. Custom rendering logic can be plugged in with the " { $link "ui-pen-protocol" } ", or by implementing a generic word:"
-{ $subsection draw-gadget* }
+{ $subsections draw-gadget* }
"Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary."
$nl
"Gadgets which need to allocate and deallocate OpenGL resources such as textures, display lists, and so on, should perform the allocation in the " { $link graft* } " method, and the deallocation in the " { $link ungraft* } " method. Since those words are not necessarily called with the gadget's OpenGL context active, a utility word can be used to find and make the correct OpenGL context current:"
-{ $subsection find-gl-context }
+{ $subsections find-gl-context }
"OpenGL state must not be altered as a result of drawing a gadget, so any flags which were enabled should be disabled, and vice versa. To take full control of the OpenGL context, see " { $link "ui.gadgets.worlds-subclassing" } "."
-{ $subsection "ui-paint-coord" }
-{ $subsection "ui.gadgets.worlds-subclassing" }
-{ $subsection "gl-utilities" }
-{ $subsection "text-rendering" } ;
+{ $subsections
+ "ui-paint-coord"
+ "ui.gadgets.worlds-subclassing"
+ "gl-utilities"
+ "text-rendering"
+} ;
"User actions such as keyboard input and mouse button clicks deliver " { $emphasis "gestures" } " to gadgets. If the direct receiver of the gesture does not handle it, the gesture is passed on to the receiver's parent, and this way it travels up the gadget hierarchy. Gestures which are not handled at some point are ignored."
$nl
"There are two ways to define gesture handling logic. The simplest way is to associate a fixed set of gestures with a class:"
-{ $subsection set-gestures }
+{ $subsections set-gestures }
"Another way is to define a generic word on a class which handles all gestures sent to gadgets of that class:"
-{ $subsection handle-gesture }
+{ $subsections handle-gesture }
"Sometimes a gesture needs to be presented to the user:"
-{ $subsection gesture>string }
+{ $subsections gesture>string }
"Keyboard input:"
-{ $subsection "ui-focus" }
-{ $subsection "keyboard-gestures" }
-{ $subsection "action-gestures" }
-{ $subsection "ui-user-input" }
+{ $subsections
+ "ui-focus"
+ "keyboard-gestures"
+ "action-gestures"
+ "ui-user-input"
+}
"Mouse input:"
-{ $subsection "mouse-gestures" }
-{ $subsection "multitouch-gestures" }
+{ $subsections
+ "mouse-gestures"
+ "multitouch-gestures"
+}
"Guidelines for cross-platform applications:"
-{ $subsection "gesture-differences" }
+{ $subsections "gesture-differences" }
"Abstractions built on top of gestures:"
-{ $subsection "ui-commands" }
-{ $subsection "ui-operations" } ;
+{ $subsections
+ "ui-commands"
+ "ui-operations"
+} ;
ARTICLE: "ui-focus" "Keyboard focus"
"The gadget with keyboard focus is the current receiver of keyboard gestures and user input. Gadgets that wish to receive keyboard input should request focus when clicked:"
-{ $subsection request-focus }
+{ $subsections request-focus }
"The following example demonstrates defining a handler for a mouse click gesture which requests focus:"
{ $code
"my-gadget H{"
"} set-gestures"
}
"To nominate a single child as the default focusable child, implement a method on a generic word:"
-{ $subsection focusable-child* }
+{ $subsections focusable-child* }
"Gestures are sent to a gadget when it gains or loses focus; this can be used to change the gadget's appearance, for example by displaying a border:"
-{ $subsection gain-focus }
-{ $subsection lose-focus } ;
+{ $subsections
+ gain-focus
+ lose-focus
+} ;
ARTICLE: "keyboard-gestures" "Keyboard gestures"
"There are two types of keyboard gestures:"
-{ $subsection key-down }
-{ $subsection key-up }
+{ $subsections
+ key-down
+ key-up
+}
"Each keyboard gesture has a set of modifiers and a key symbol. The set modifiers is denoted by an array which must either be " { $link f } ", or an order-preserving subsequence of the following:"
{ $code "{ S+ C+ A+ M+ }" }
-{ $subsection S+ }
-{ $subsection C+ }
-{ $subsection A+ }
-{ $subsection M+ }
+{ $subsections
+ S+
+ C+
+ A+
+ M+
+}
"A key symbol is either a single-character string denoting literal input, or one of the following strings:"
{ $list
{ $snippet "CLEAR" }
ARTICLE: "ui-user-input" "Free-form keyboard input"
"Whereas keyboard gestures are intended to be used for keyboard shortcuts, certain gadgets such as text fields need to accept free-form keyboard input. This can be done by implementing a generic word:"
-{ $subsection user-input* } ;
+{ $subsections user-input* } ;
ARTICLE: "mouse-gestures" "Mouse gestures"
"There are two types of mouse gestures indicating button clicks:"
-{ $subsection button-down }
-{ $subsection button-up }
+{ $subsections
+ button-down
+ button-up
+}
"When a mouse button is pressed or released, two gestures are sent. The first gesture indicates the specific button number, and if this gesture is not handled, the second has a button number set to " { $link f } ":"
{ $code "T{ button-down f 1 }" "T{ button-down f f }" }
"Because tuple literals fill unspecified slots with " { $link f } ", the last gesture can be written as " { $snippet "T{ button-down }" } "."
$nl
"Gestures to indicate mouse motion, depending on whenever a button is held down or not:"
-{ $subsection motion }
-{ $subsection drag }
+{ $subsections
+ motion
+ drag
+}
"Gestures to indicate that the mouse has crossed gadget boundaries:"
-{ $subsection mouse-enter }
-{ $subsection mouse-leave }
+{ $subsections
+ mouse-enter
+ mouse-leave
+}
"A number of global variables are set after a mouse gesture is sent. These variables can be read to obtain additional information about the gesture."
-{ $subsection hand-gadget }
-{ $subsection hand-world }
-{ $subsection hand-loc }
-{ $subsection hand-buttons }
-{ $subsection hand-clicked }
-{ $subsection hand-click-loc }
-{ $subsection hand-click# }
+{ $subsections
+ hand-gadget
+ hand-world
+ hand-loc
+ hand-buttons
+ hand-clicked
+ hand-click-loc
+ hand-click#
+}
"There are some utility words for working with click locations:"
-{ $subsection hand-rel }
-{ $subsection hand-click-rel }
-{ $subsection drag-loc }
+{ $subsections
+ hand-rel
+ hand-click-rel
+ drag-loc
+}
"Mouse scroll wheel gesture:"
-{ $subsection mouse-scroll }
+{ $subsections mouse-scroll }
"Global variable set when a mouse scroll wheel gesture is sent:"
-{ $subsection scroll-direction } ;
+{ $subsections scroll-direction } ;
ARTICLE: "multitouch-gestures" "Multi-touch gestures"
"Multi-touch gestures are only supported on Mac OS X with newer MacBook and MacBook Pro models."
$nl
"Three-finger swipe:"
-{ $subsection left-action }
-{ $subsection right-action }
-{ $subsection up-action }
-{ $subsection down-action }
+{ $subsections
+ left-action
+ right-action
+ up-action
+ down-action
+}
"Two-finger pinch:"
-{ $subsection zoom-in-action }
-{ $subsection zoom-out-action } ;
+{ $subsections
+ zoom-in-action
+ zoom-out-action
+} ;
ARTICLE: "action-gestures" "Action gestures"
"Action gestures exist to keep keyboard shortcuts for common application operations consistent."
-{ $subsection undo-action }
-{ $subsection redo-action }
-{ $subsection cut-action }
-{ $subsection copy-action }
-{ $subsection paste-action }
-{ $subsection delete-action }
-{ $subsection select-all-action }
-{ $subsection new-action }
-{ $subsection open-action }
-{ $subsection save-action }
-{ $subsection save-as-action }
-{ $subsection revert-action }
-{ $subsection close-action }
+{ $subsections
+ undo-action
+ redo-action
+ cut-action
+ copy-action
+ paste-action
+ delete-action
+ select-all-action
+ new-action
+ open-action
+ save-action
+ save-as-action
+ revert-action
+ close-action
+}
"The following keyboard gestures, if not handled directly, send action gestures:"
{ $table
{ { $strong "Keyboard gesture" } { $strong "Action gesture" } }
ARTICLE: "ui-operations" "Operations"
"Operations are commands performed on presentations."
-{ $subsection operation }
-{ $subsection define-operation }
-{ $subsection primary-operation }
-{ $subsection secondary-operation }
-{ $subsection define-operation-map }
+{ $subsections
+ operation
+ define-operation
+ primary-operation
+ secondary-operation
+ define-operation-map
+}
"When documenting gadgets, operation documentation can be automatically generated:"
-{ $subsection $operations }
-{ $subsection $operation } ;
+{ $subsections
+ $operations
+ $operation
+} ;
ABOUT: "ui-operations"
ARTICLE: "ui-pen-protocol" "UI pen protocol"
"The " { $snippet "interior" } " and " { $snippet "boundary" } " slots of a gadget facilitate easy factoring and sharing of drawing logic. Objects stored in these slots must implement the pen protocol:"
-{ $subsection draw-interior }
-{ $subsection draw-boundary }
+{ $subsections
+ draw-interior
+ draw-boundary
+}
"The default value of these slots is the " { $link f } " singleton, which implements the above protocol by doing nothing."
$nl
"Some other pre-defined implementations:"
ARTICLE: "ui.pixel-formats-attributes" "Pixel format attributes"
"The following pixel format attributes can be requested and queried of " { $link pixel-format } "s. Binary attributes are represented by the presence of a symbol in an attribute sequence:"
-{ $subsection double-buffered }
-{ $subsection stereo }
-{ $subsection offscreen }
-{ $subsection fullscreen }
-{ $subsection windowed }
-{ $subsection accelerated }
-{ $subsection software-rendered }
-{ $subsection backing-store }
-{ $subsection multisampled }
-{ $subsection supersampled }
-{ $subsection sample-alpha }
-{ $subsection color-float }
+{ $subsections
+ double-buffered
+ stereo
+ offscreen
+ fullscreen
+ windowed
+ accelerated
+ software-rendered
+ backing-store
+ multisampled
+ supersampled
+ sample-alpha
+ color-float
+}
"Integer attributes are represented by a " { $link tuple } " with a single " { $snippet "value" } "slot:"
-{ $subsection color-bits }
-{ $subsection red-bits }
-{ $subsection green-bits }
-{ $subsection blue-bits }
-{ $subsection alpha-bits }
-{ $subsection accum-bits }
-{ $subsection accum-red-bits }
-{ $subsection accum-green-bits }
-{ $subsection accum-blue-bits }
-{ $subsection accum-alpha-bits }
-{ $subsection depth-bits }
-{ $subsection stencil-bits }
-{ $subsection aux-buffers }
-{ $subsection sample-buffers }
-{ $subsection samples }
+{ $subsections
+ color-bits
+ red-bits
+ green-bits
+ blue-bits
+ alpha-bits
+ accum-bits
+ accum-red-bits
+ accum-green-bits
+ accum-blue-bits
+ accum-alpha-bits
+ depth-bits
+ stencil-bits
+ aux-buffers
+ sample-buffers
+ samples
+}
{ $examples
"The following " { $link world } " subclass will request a double-buffered window with minimum 24-bit color and depth buffers, and will throw an error if the requirements aren't met:"
{ $code """
ARTICLE: "ui.pixel-formats" "Pixel formats"
"The UI allows you to control the window system's OpenGL interface with a cross-platform set of pixel format specifiers:"
-{ $subsection "ui.pixel-formats-attributes" }
+{ $subsections "ui.pixel-formats-attributes" }
"Pixel formats can be requested using these attributes:"
-{ $subsection pixel-format }
-{ $subsection <pixel-format> }
-{ $subsection pixel-format-attribute }
+{ $subsections
+ pixel-format
+ <pixel-format>
+ pixel-format-attribute
+}
"If a request for a set of pixel format attributes cannot be satisfied, an error is thrown:"
-{ $subsection invalid-pixel-format-attributes }
+{ $subsections invalid-pixel-format-attributes }
"Pixel formats are requested as part of opening a window for a " { $link world } ". These generics can be overridden on " { $snippet "world" } " subclasses to control pixel format selection:"
-{ $subsection world-pixel-format-attributes }
-{ $subsection check-world-pixel-format }
+{ $subsections
+ world-pixel-format-attributes
+ check-world-pixel-format
+}
;
ABOUT: "ui.pixel-formats"
{ "The " { $link draw-boundary } " generic word is called on the value of the " { $snippet "boundary" } " slot." }
}
"Now, each one of these steps will be covered in detail."
-{ $subsection "ui-pen-protocol" }
-{ $subsection "ui-paint-custom" } ;
+{ $subsections
+ "ui-pen-protocol"
+ "ui-paint-custom"
+} ;
ARTICLE: "ui-paint-coord" "The UI co-ordinate system"
"The UI uses a co-ordinate system where the y axis is oriented down. The OpenGL " { $link GL_MODELVIEW } " matrix is saved or restored when rendering a gadget, and the origin is translated to the gadget's origin within the window. The current origin is stored in a variable:"
-{ $subsection origin }
+{ $subsections origin }
"Gadgets must not draw outside of their bounding box, however clipping is not enforced by default, for performance reasons. This can be changed by setting the " { $slot "clipped?" } " slot to " { $link t } " in the gadget's constructor." ;
ABOUT: "ui-paint"
ARTICLE: "text-rendering" "Rendering text"
"The " { $vocab-link "ui.text" } " vocabulary provides a cross-platform interface to the operating system's native font rendering engine. Currently, it uses Core Text on Mac OS X and FreeType on Windows and X11."
-{ $subsection "fonts" }
+{ $subsections "fonts" }
"Measuring text:"
-{ $subsection text-dim }
-{ $subsection text-width }
-{ $subsection text-height }
-{ $subsection line-metrics }
+{ $subsections
+ text-dim
+ text-width
+ text-height
+ line-metrics
+}
"Converting screen locations to string offsets, and vice versa:"
-{ $subsection x>offset }
-{ $subsection offset>x }
+{ $subsections
+ x>offset
+ offset>x
+}
"Rendering text:"
-{ $subsection draw-text }
+{ $subsections draw-text }
"Low-level text protocol for UI backends:"
-{ $subsection string-width }
-{ $subsection string-height }
-{ $subsection string-dim }
-{ $subsection draw-string } ;
+{ $subsections
+ string-width
+ string-height
+ string-dim
+ draw-string
+} ;
ABOUT: "text-rendering"
\ No newline at end of file
ARTICLE: "ui-browser" "UI browser"
"The browser is used to display Factor code, documentation, and vocabularies. The browser is opened when a word or article link presentation is clicked. It can also be opened using words:"
-{ $subsection com-browse }
-{ $subsection browser-window }
+{ $subsections
+ com-browse
+ browser-window
+}
{ $command-map browser-gadget "toolbar" }
{ $command-map browser-gadget "scrolling" }
{ $command-map browser-gadget "navigation" }
"The application deployment UI tool provides a graphical front-end to deployment configuration. Using the tool, you can set deployment options graphically."
$nl
"To start the tool, pass a vocabulary name to a word:"
-{ $subsection deploy-tool }
+{ $subsections deploy-tool }
"Alternatively, right-click on a vocabulary presentation in the UI and choose " { $strong "Deploy tool" } " from the resulting popup menu."
{ $see-also "tools.deploy" } ;
"The graphical inspector provides functionality similar to the terminal inspector (see " { $link "inspector" } "), adding in-place editing of slot values."
$nl
"To display an object in the UI inspector, right-click a presentation and choose " { $strong "Inspector" } " from the menu that appears. The inspector can also be opened from the listener using a word:"
-{ $subsection inspector }
+{ $subsections inspector }
"The inspector embeds a table gadget, which supports keyboard navigation; see " { $link "ui.gadgets.tables" } ". It also provides a few other commands:"
{ $command-map inspector-gadget "toolbar" }
{ $command-map inspector-gadget "multi-touch" }
"The UI inspector is an instance of " { $link inspector-gadget } "."
-{ $subsection "ui-inspector-edit" } ;
+{ $subsections "ui-inspector-edit" } ;
HELP: inspector
{ $values { "obj" object } }
ARTICLE: "ui-tools" "UI developer tools"
"The " { $vocab-link "ui.tools" } " vocabulary hierarchy implements a collection of simple developer tools."
-{ $subsection "starting-ui-tools" }
+{ $subsections "starting-ui-tools" }
"To take full advantage of the UI tools, you should be using a supported text editor. See " { $link "editor" } "."
$nl
"Common functionality:"
-{ $subsection "ui-shortcuts" }
-{ $subsection "ui-presentations" }
-{ $subsection "definitions.icons" }
+{ $subsections
+ "ui-shortcuts"
+ "ui-presentations"
+ "definitions.icons"
+}
"Tools:"
-{ $subsection "ui-listener" }
-{ $subsection "ui-browser" }
-{ $subsection "ui-inspector" }
-{ $subsection "ui.tools.error-list" }
-{ $subsection "ui.tools.profiler" }
-{ $subsection "ui-walker" }
-{ $subsection "ui.tools.deploy" }
+{ $subsections
+ "ui-listener"
+ "ui-browser"
+ "ui-inspector"
+ "ui.tools.error-list"
+ "ui.tools.profiler"
+ "ui-walker"
+ "ui.tools.deploy"
+}
"Platform-specific features:"
-{ $subsection "ui-cocoa" } ;
+{ $subsections "ui-cocoa" } ;
TIP: "All UI developer tools support a common set of " { $link "ui-shortcuts" } ". Each individual tool has its own shortcuts as well; the F1 key is context-sensitive." ;
"The walker single-steps through quotations. To use the walker, enter a piece of code in the listener's input area and press " { $operation walk } "."\r
$nl\r
"Walkers are instances of " { $link walker-gadget } "."\r
-{ $subsection "ui-walker-step" }\r
-{ $subsection "breakpoints" }\r
+{ $subsections\r
+ "ui-walker-step"\r
+ "breakpoints"\r
+}\r
{ $command-map walker-gadget "toolbar" }\r
{ $command-map walker-gadget "multitouch" } ;\r
\r
ARTICLE: "building-ui" "Building user interfaces"
"A gadget is a graphical element which responds to user input. Gadgets are implemented as tuples which (directly or indirectly) inherit from " { $link gadget } ", which in turn inherits from " { $link rect } "."
-{ $subsection gadget }
+{ $subsections gadget }
"Gadgets are arranged in a hierarchy, and all visible gadgets except for instances of " { $link world } " are contained in a parent gadget, stored in the " { $snippet "parent" } " slot."
-{ $subsection "ui-geometry" }
-{ $subsection "ui-layouts" }
-{ $subsection "gadgets" }
-{ $subsection "ui-windows" }
-{ $subsection "ui.gadgets.status-bar" }
+{ $subsections
+ "ui-geometry"
+ "ui-layouts"
+ "gadgets"
+ "ui-windows"
+ "ui.gadgets.status-bar"
+}
{ $see-also "models" } ;
ARTICLE: "gadgets" "Pre-made UI gadgets"
-{ $subsection "ui.gadgets.labels" }
-{ $subsection "ui.gadgets.borders" }
-{ $subsection "ui.gadgets.labeled" }
-{ $subsection "ui.gadgets.buttons" }
-{ $subsection "ui.gadgets.sliders" }
-{ $subsection "ui.gadgets.scrollers" }
-{ $subsection "ui.gadgets.editors" }
-{ $subsection "ui.gadgets.menus" }
-{ $subsection "ui.gadgets.panes" }
-{ $subsection "ui.gadgets.presentations" }
-{ $subsection "ui.gadgets.tables" } ;
+{ $subsections
+ "ui.gadgets.labels"
+ "ui.gadgets.borders"
+ "ui.gadgets.labeled"
+ "ui.gadgets.buttons"
+ "ui.gadgets.sliders"
+ "ui.gadgets.scrollers"
+ "ui.gadgets.editors"
+ "ui.gadgets.menus"
+ "ui.gadgets.panes"
+ "ui.gadgets.presentations"
+ "ui.gadgets.tables"
+} ;
ARTICLE: "ui-geometry" "Gadget geometry"
"The " { $link gadget } " class inherits from the " { $link rect } " class, and thus all gadgets have a bounding box:"
-{ $subsection "math.rectangles" }
+{ $subsections "math.rectangles" }
"Word for converting from a child gadget's co-ordinate system to a parent's:"
-{ $subsection relative-loc }
-{ $subsection screen-loc }
+{ $subsections
+ relative-loc
+ screen-loc
+}
"Hit testing:"
-{ $subsection pick-up }
-{ $subsection children-on } ;
+{ $subsections
+ pick-up
+ children-on
+} ;
ARTICLE: "ui-windows" "Top-level windows"
"Opening a top-level window:"
-{ $subsection open-window }
+{ $subsections open-window }
"Finding top-level windows:"
-{ $subsection find-window }
+{ $subsections find-window }
"Top-level windows are stored in a global variable:"
-{ $subsection windows }
+{ $subsections windows }
"When a gadget is displayed in a top-level window, or added to a parent which is already showing in a top-level window, a generic word is called allowing the gadget to perform initialization tasks:"
-{ $subsection graft* }
+{ $subsections graft* }
"When the gadget is removed from a parent shown in a top-level window, or when the top-level window is closed, a corresponding generic word is called to clean up:"
-{ $subsection ungraft* }
+{ $subsections ungraft* }
"The root of the gadget hierarchy in a window is a special gadget which is rarely operated on directly, but it is helpful to know it exists:"
-{ $subsection world } ;
+{ $subsections world } ;
ARTICLE: "ui-backend" "Developing UI backends"
"None of the words documented in this section should be called directly by user code. They are only of interest when developing new UI backends."
-{ $subsection "ui-backend-init" }
-{ $subsection "ui-backend-windows" }
+{ $subsections
+ "ui-backend-init"
+ "ui-backend-windows"
+}
"UI backends may implement the " { $link "clipboard-protocol" } "." ;
ARTICLE: "ui-backend-init" "UI initialization and the event loop"
" ... start event loop here ... ;"
}
"The above word must call the following:"
-{ $subsection start-ui }
+{ $subsections start-ui }
"The " { $link (with-ui) } " word must not return until the event loop has stopped and the UI has been shut down." ;
ARTICLE: "ui-backend-windows" "UI backend window management"
"The high-level " { $link open-window } " word eventually calls a low-level word which you must implement:"
-{ $subsection open-world-window }
+{ $subsections open-world-window }
"This word should create a native window, store some kind of handle in the " { $snippet "handle" } " slot, then call two words:"
-{ $subsection register-window }
+{ $subsections register-window }
"The following words must also be implemented:"
-{ $subsection set-title }
-{ $subsection raise-window }
+{ $subsections
+ set-title
+ raise-window
+}
"When a world needs to be redrawn, the UI will call a word automatically:"
-{ $subsection draw-world }
+{ $subsections draw-world }
"This word can also be called directly if the UI backend is notified by the window system that window contents have been invalidated. Before and after drawing, two words are called, which the UI backend must implement:"
-{ $subsection select-gl-context }
-{ $subsection flush-gl-context }
+{ $subsections
+ select-gl-context
+ flush-gl-context
+}
"If the user clicks the window's close box, you must call the following word:"
-{ $subsection close-window } ;
+{ $subsections close-window } ;
ARTICLE: "ui-layouts" "Gadget hierarchy and layouts"
"A layout gadget is a gadget whose sole purpose is to contain other gadgets. Layout gadgets position and resize children according to a certain policy, taking the preferred size of the children into account. Gadget hierarchies are constructed by building up nested layouts."
-{ $subsection "ui-layout-basics" }
+{ $subsections "ui-layout-basics" }
"Common layout gadgets:"
-{ $subsection "ui-pack-layout" }
-{ $subsection "ui-track-layout" }
-{ $subsection "ui-grid-layout" }
-{ $subsection "ui-frame-layout" }
-{ $subsection "ui-book-layout" }
+{ $subsections
+ "ui-pack-layout"
+ "ui-track-layout"
+ "ui-grid-layout"
+ "ui-frame-layout"
+ "ui-book-layout"
+}
"Advanced topics:"
-{ $subsection "ui.gadgets.glass" }
-{ $subsection "ui-null-layout" }
-{ $subsection "ui-incremental-layout" }
-{ $subsection "ui-layout-impl" }
+{ $subsections
+ "ui.gadgets.glass"
+ "ui-null-layout"
+ "ui-incremental-layout"
+ "ui-layout-impl"
+}
{ $see-also "ui.gadgets.borders" } ;
ARTICLE: "ui-layout-basics" "Layout basics"
"Gadgets are arranged in a hierarchy, and all visible gadgets except for instances of " { $link world } " are contained in a parent gadget."
$nl
"Managing the gadget hierarchy:"
-{ $subsection add-gadget }
-{ $subsection unparent }
-{ $subsection add-gadgets }
-{ $subsection clear-gadget }
+{ $subsections
+ add-gadget
+ unparent
+ add-gadgets
+ clear-gadget
+}
"The children of a gadget are available via the "
{ $snippet "children" } " slot. "
$nl
"Working with gadget children:"
-{ $subsection gadget-child }
-{ $subsection nth-gadget }
-{ $subsection each-child }
-{ $subsection child? }
+{ $subsections
+ gadget-child
+ nth-gadget
+ each-child
+ child?
+}
"Working with gadget parents:"
-{ $subsection parents }
-{ $subsection each-parent }
-{ $subsection find-parent }
+{ $subsections
+ parents
+ each-parent
+ find-parent
+}
"Adding children, removing children and performing certain other operations initiates relayout requests automatically. In other cases, relayout may have to be triggered explicitly. There is no harm from doing this several times in a row as consecutive relayout requests are coalesced."
-{ $subsection relayout }
-{ $subsection relayout-1 }
+{ $subsections
+ relayout
+ relayout-1
+}
"Gadgets implement a generic word to inform their parents of their preferred size:"
-{ $subsection pref-dim* }
+{ $subsections pref-dim* }
"To get a gadget's preferred size, do not call the above word, instead use " { $link pref-dim } ", which caches the result." ;
ARTICLE: "ui-null-layout" "Manual layouts"
ARTICLE: "ui-layout-impl" "Implementing layout gadgets"
"The relayout process proceeds top-down, with parents laying out their children, which in turn lay out their children. Custom layout policy is implemented by defining a method on a generic word:"
-{ $subsection layout* }
+{ $subsections layout* }
"When a " { $link layout* } " method is called, the size and location of the gadget has already been determined by its parent, and the method's job is to lay out the gadget's children. Children can be positioned and resized by setting a pair of slots, " { $snippet "loc" } " and " { $snippet "dim" } "." $nl
"Some assorted utility words which are useful for implementing layout logic:"
-{ $subsection pref-dim }
-{ $subsection pref-dims }
-{ $subsection prefer }
-{ $subsection max-dim }
-{ $subsection dim-sum }
+{ $subsections
+ pref-dim
+ pref-dims
+ prefer
+ max-dim
+ dim-sum
+}
{ $warning
"When implementing the " { $link layout* } " generic word for a gadget which inherits from another layout, the " { $link children-on } " word might have to be re-implemented as well."
$nl
"One of the goals of the Factor UI is to minimize the need to implement new types of gadgets by offering a highly reusable, orthogonal set of building blocks. However, in some cases implementing a new type of gadget is necessary, for example when writing a graphical visualization."
$nl
"Bare gadgets can be constructed directly, which is useful if all you need is a custom appearance with no further behavior (see " { $link "ui-pen-protocol" } "):"
-{ $subsection <gadget> }
+{ $subsections <gadget> }
"New gadgets are defined as subclasses of an existing gadget type, perhaps even " { $link gadget } " itself. Direct subclasses of " { $link gadget } " can be constructed using " { $link new } ", however some subclasses may define their own parametrized constructors (see " { $link "parametrized-constructors" } ")."
$nl
"Further topics:"
-{ $subsection "ui-gestures" }
-{ $subsection "ui-paint" }
-{ $subsection "ui-control-impl" }
-{ $subsection "clipboard-protocol" }
-{ $subsection "ui.gadgets.line-support" }
+{ $subsections
+ "ui-gestures"
+ "ui-paint"
+ "ui-control-impl"
+ "clipboard-protocol"
+ "ui.gadgets.line-support"
+}
{ $see-also "ui-layout-impl" } ;
ARTICLE: "starting-ui" "Starting the UI"
"The main word of a vocabulary implementing a UI application should use a combinator to ensure that the application works when run from the command line as well as in the UI listener:"
-{ $subsection with-ui } ;
+{ $subsections with-ui } ;
ARTICLE: "ui" "UI framework"
"The " { $vocab-link "ui" } " vocabulary hierarchy implements the Factor UI framework. The implementation relies on a small amount of platform-specific code to open windows and receive keyboard and mouse events; UI gadgets are rendered using OpenGL."
-{ $subsection "starting-ui" }
-{ $subsection "ui-glossary" }
-{ $subsection "building-ui" }
-{ $subsection "new-gadgets" }
-{ $subsection "ui-backend" } ;
+{ $subsections
+ "starting-ui"
+ "ui-glossary"
+ "building-ui"
+ "new-gadgets"
+ "ui-backend"
+} ;
ABOUT: "ui"
ARTICLE: "ui.gadgets.worlds-window-controls" "Window controls"
"The following window controls can be placed in a " { $link world } " window:"
-{ $subsection close-button }
-{ $subsection minimize-button }
-{ $subsection maximize-button }
-{ $subsection resize-handles }
-{ $subsection small-title-bar }
-{ $subsection normal-title-bar }
-{ $subsection textured-background }
+{ $subsections
+ close-button
+ minimize-button
+ maximize-button
+ resize-handles
+ small-title-bar
+ normal-title-bar
+ textured-background
+}
"Provide a sequence of these values in the " { $snippet "window-controls" } " slot of the " { $link world-attributes } " tuple you pass to " { $link open-window } "." ;
ARTICLE: "unicode.breaks" "Word and grapheme breaks"
"The " { $vocab-link "unicode.breaks" "unicode.breaks" } " vocabulary partially implements Unicode Standard Annex #29. This provides for segmentation of a string along grapheme and word boundaries. In Unicode, a grapheme, or a basic unit of display in text, may be more than one code point. For example, in the string \"e\\u000301\" (where U+0301 is a combining acute accent), there is only one grapheme, as the acute accent goes above the e, forming a single grapheme. Word breaks, in general, are more complicated than simply splitting by whitespace, and the Unicode algorithm provides for that."
$nl "Operations for graphemes:"
-{ $subsection first-grapheme }
-{ $subsection first-grapheme-from }
-{ $subsection last-grapheme }
-{ $subsection last-grapheme-from }
-{ $subsection >graphemes }
-{ $subsection string-reverse }
+{ $subsections
+ first-grapheme
+ first-grapheme-from
+ last-grapheme
+ last-grapheme-from
+ >graphemes
+ string-reverse
+}
"Operations on words:"
-{ $subsection first-word }
-{ $subsection first-word-from }
-{ $subsection last-word }
-{ $subsection last-word-from }
-{ $subsection >words } ;
+{ $subsections
+ first-word
+ first-word-from
+ last-word
+ last-word-from
+ >words
+} ;
HELP: first-grapheme
{ $values { "str" string } { "i" "an index" } }
ARTICLE: "unicode.case" "Case mapping"
"When considering Unicode in general and not just ASCII or a smaller character set, putting a string in upper case, title case or lower case is slightly more complicated. In most contexts it's best to use the general Unicode routines for case conversion. There is an additional type of casing, case-fold, which is defined as bringing a string into upper case and then lower. This exists because in some cases it is different from simple lower case."
-{ $subsection >upper }
-{ $subsection >lower }
-{ $subsection >title }
-{ $subsection >case-fold }
+{ $subsections
+ >upper
+ >lower
+ >title
+ >case-fold
+}
"To test if a string is in a given case:"
-{ $subsection upper? }
-{ $subsection lower? }
-{ $subsection title? }
-{ $subsection case-fold? }
+{ $subsections
+ upper?
+ lower?
+ title?
+ case-fold?
+}
"For certain languages (Turkish, Azeri, Lithuanian), case mapping is dependent on locale; To change this, set the following variable to the ISO-639-1 code for your language:"
-{ $subsection locale }
+{ $subsections locale }
"This is unnecessary for most locales." ;
HELP: >upper
ARTICLE: "unicode.categories" "Character classes"
"The " { $vocab-link "unicode.categories" } " vocabulary implements predicates for determining if a code point has a particular property, for example being a lower cased letter. These should be used in preference to the " { $vocab-link "ascii" } " equivalents in most cases. Each character class has an associated predicate word."
-{ $subsection blank }
-{ $subsection blank? }
-{ $subsection letter }
-{ $subsection letter? }
-{ $subsection LETTER }
-{ $subsection LETTER? }
-{ $subsection Letter }
-{ $subsection Letter? }
-{ $subsection digit }
-{ $subsection digit? }
-{ $subsection printable }
-{ $subsection printable? }
-{ $subsection alpha }
-{ $subsection alpha? }
-{ $subsection control }
-{ $subsection control? }
-{ $subsection uncased }
-{ $subsection uncased? }
-{ $subsection character }
-{ $subsection character? }
-{ $subsection math }
-{ $subsection math? } ;
+{ $subsections
+ blank
+ blank?
+ letter
+ letter?
+ LETTER
+ LETTER?
+ Letter
+ Letter?
+ digit
+ digit?
+ printable
+ printable?
+ alpha
+ alpha?
+ control
+ control?
+ uncased
+ uncased?
+ character
+ character?
+ math
+ math?
+} ;
ABOUT: "unicode.categories"
ARTICLE: "unicode.categories.syntax" "Unicode category syntax"
"There is special syntax sugar for making predicate classes which are unions of Unicode general categories, plus some other code."
-{ $subsection POSTPONE: CATEGORY: }
-{ $subsection POSTPONE: CATEGORY-NOT: } ;
+{ $subsections
+ POSTPONE: CATEGORY:
+ POSTPONE: CATEGORY-NOT:
+} ;
HELP: CATEGORY:
{ $syntax "CATEGORY: foo Nl Pd Lu | \"Diacritic\" property? ;" }
ARTICLE: "unicode.collation" "Collation and weak comparison"
"The " { $vocab-link "unicode.collation" "unicode.collation" } " vocabulary implements the Unicode Collation Algorithm. The Unicode Collation Algorithm (UTS #10) forms a reasonable way to sort strings when accouting for all of the characters in Unicode. It is far preferred over code point order when sorting for human consumption, in user interfaces. At the moment, only the default Unicode collation element table (DUCET) is used, but a more accurate collation would take locale into account. The following words are useful for collation directly:"
-{ $subsection sort-strings }
-{ $subsection collation-key }
-{ $subsection string<=> }
+{ $subsections
+ sort-strings
+ collation-key
+ string<=>
+}
"Predicates for weak equality testing:"
-{ $subsection primary= }
-{ $subsection secondary= }
-{ $subsection tertiary= }
-{ $subsection quaternary= } ;
+{ $subsections
+ primary=
+ secondary=
+ tertiary=
+ quaternary=
+} ;
ABOUT: "unicode.collation"
ARTICLE: "unicode.data" "Unicode data tables"
"The " { $vocab-link "unicode.data" "unicode.data" } " vocabulary contains core Unicode data tables and code for parsing this from files. The following words access these data tables."
-{ $subsection canonical-entry }
-{ $subsection combine-chars }
-{ $subsection combining-class }
-{ $subsection non-starter? }
-{ $subsection name>char }
-{ $subsection char>name }
-{ $subsection property? }
-{ $subsection category }
-{ $subsection ch>upper }
-{ $subsection ch>lower }
-{ $subsection ch>title }
-{ $subsection special-case } ;
+{ $subsections
+ canonical-entry
+ combine-chars
+ combining-class
+ non-starter?
+ name>char
+ char>name
+ property?
+ category
+ ch>upper
+ ch>lower
+ ch>title
+ special-case
+} ;
HELP: canonical-entry
{ $values { "char" "a code point" } { "seq" string } }
"There are four normalization forms: NFD, NFC, NFKD, and NFKC. Basically, in NFD and NFKD, everything is expanded, whereas in NFC and NFKC, everything is contracted. In NFKD and NFKC, more things are expanded and contracted. This is a process which loses some information, so it should be done only with care."
$nl
"Most of the world uses NFC to communicate, but for many purposes, NFD/NFKD is easier to process. For more information, see Unicode Standard Annex #15 and section 3 of the Unicode standard."
-{ $subsection nfc }
-{ $subsection nfd }
-{ $subsection nfkc }
-{ $subsection nfkd } ;
+{ $subsections
+ nfc
+ nfd
+ nfkc
+ nfkd
+} ;
HELP: nfc
{ $values { "string" string } { "nfc" "a string in NFC" } }
\r
ARTICLE: "unicode.script" "Unicode script properties"\r
"The unicode standard gives every character a script. Note that this is different from a language, and that it is non-trivial to detect language from a string. To get the script of a character, use"\r
-{ $subsection script-of } ;\r
+{ $subsections script-of } ;\r
\r
HELP: script-of\r
{ $values { "char" "a code point" } { "script" string } }\r
"The " { $vocab-link "unix.groups" } " vocabulary contains words that return information about Unix groups."
$nl
"Listing all groups:"
-{ $subsection all-groups }
+{ $subsections all-groups }
"Real groups:"
-{ $subsection real-group-name }
-{ $subsection real-group-id }
-{ $subsection set-real-group }
+{ $subsections
+ real-group-name
+ real-group-id
+ set-real-group
+}
"Effective groups:"
-{ $subsection effective-group-name }
-{ $subsection effective-group-id }
-{ $subsection set-effective-group }
+{ $subsections
+ effective-group-name
+ effective-group-id
+ set-effective-group
+}
"Combinators to change groups:"
-{ $subsection with-real-group }
-{ $subsection with-effective-group } ;
+{ $subsections
+ with-real-group
+ with-effective-group
+} ;
ABOUT: "unix.groups"
"The " { $vocab-link "unix.users" } " vocabulary contains words that return information about Unix users."
$nl
"Listing all users:"
-{ $subsection all-users }
+{ $subsections all-users }
"Real user:"
-{ $subsection real-user-name }
-{ $subsection real-user-id }
-{ $subsection set-real-user }
+{ $subsections
+ real-user-name
+ real-user-id
+ set-real-user
+}
"Effective user:"
-{ $subsection effective-user-name }
-{ $subsection effective-user-id }
-{ $subsection set-effective-user }
+{ $subsections
+ effective-user-name
+ effective-user-id
+ set-effective-user
+}
"Combinators to change users:"
-{ $subsection with-real-user }
-{ $subsection with-effective-user } ;
+{ $subsections
+ with-real-user
+ with-effective-user
+} ;
ABOUT: "unix.users"
ARTICLE: "unrolled-lists" "Unrolled lists"
"The " { $vocab-link "unrolled-lists" } " vocabulary provides an implementation of the " { $link deque } " protocol with constant time insertion and removal at both ends, and lower memory overhead than a " { $link dlist } " due to packing 32 elements per every node. The one tradeoff is that unlike dlists, " { $link delete-node } " is not supported for unrolled lists."
-{ $subsection unrolled-list }
-{ $subsection <unrolled-list> }
-{ $subsection <hashed-unrolled-list> } ;
+{ $subsections
+ unrolled-list
+ <unrolled-list>
+ <hashed-unrolled-list>
+} ;
ABOUT: "unrolled-lists"
ARTICLE: "url-encoding" "URL encoding and decoding"
"URL encoding and decoding strings:"
-{ $subsection url-encode }
-{ $subsection url-decode }
-{ $subsection url-quotable? }
+{ $subsections
+ url-encode
+ url-decode
+ url-quotable?
+}
"Encoding and decoding queries:"
-{ $subsection assoc>query }
-{ $subsection query>assoc }
+{ $subsections
+ assoc>query
+ query>assoc
+}
"See " { $url "http://en.wikipedia.org/wiki/Percent-encoding" } " for a description of URL encoding." ;
ABOUT: "url-encoding"
{ $description "Like " { $link append-path } ", but intended for use with URL paths and not filesystem paths." } ;
ARTICLE: "url-utilities" "URL implementation utilities"
-{ $subsection parse-host }
-{ $subsection secure-protocol? }
-{ $subsection url-append-path } ;
+{ $subsections
+ parse-host
+ secure-protocol?
+ url-append-path
+} ;
ARTICLE: "urls" "URL objects"
"The " { $vocab-link "urls" } " vocabulary implements a URL data type. The benefit of using a data type to prepresent URLs rather than a string is that the parsing, printing and escaping logic is encapsulated and reused, rather than re-implemented in a potentially buggy manner every time."
"URL objects are used heavily by the " { $vocab-link "http" } " and " { $vocab-link "furnace" } " vocabularies, and are also useful on their own."
$nl
"The class of URLs, and a constructor:"
-{ $subsection url }
-{ $subsection <url> }
+{ $subsections
+ url
+ <url>
+}
"Converting strings to URLs:"
-{ $subsection >url }
+{ $subsections >url }
"URLs can be converted back to strings using the " { $link present } " word."
$nl
"URL literal syntax:"
-{ $subsection POSTPONE: URL" }
+{ $subsections POSTPONE: URL" }
"Manipulating URLs:"
-{ $subsection derive-url }
-{ $subsection relative-url }
-{ $subsection ensure-port }
-{ $subsection query-param }
-{ $subsection set-query-param }
+{ $subsections
+ derive-url
+ relative-url
+ ensure-port
+ query-param
+ set-query-param
+}
"Creating " { $link "network-addressing" } " from URLs:"
-{ $subsection url-addr }
+{ $subsections url-addr }
"The URL implemention encodes and decodes components of " { $link url } " instances automatically, but sometimes this functionality is needed for non-URL strings."
-{ $subsection "url-encoding" }
+{ $subsections "url-encoding" }
"Utility words used by the URL implementation:"
-{ $subsection "url-utilities" } ;
+{ $subsections "url-utilities" } ;
ABOUT: "urls"
"The below words can be used to generate version 1, 3, 4, and 5 UUIDs as specified in RFC 4122."
$nl
"If all you want is a unique ID, you should probably call " { $link uuid1 } " or " { $link uuid4 } "."
-{ $subsection uuid1 }
-{ $subsection uuid3 }
-{ $subsection uuid4 }
-{ $subsection uuid5 }
+{ $subsections
+ uuid1
+ uuid3
+ uuid4
+ uuid5
+}
;
ABOUT: "uuid"
"Note that validators which take numbers must be preceded by " { $link v-integer } " or " { $link v-number } " if the original input is a string."
$nl
"Higher-order validators which require additional parameters:"
-{ $subsection v-default }
-{ $subsection v-optional }
-{ $subsection v-min-length }
-{ $subsection v-max-length }
-{ $subsection v-min-value }
-{ $subsection v-max-value }
-{ $subsection v-regexp }
+{ $subsections
+ v-default
+ v-optional
+ v-min-length
+ v-max-length
+ v-min-value
+ v-max-value
+ v-regexp
+}
"Simple validators:"
-{ $subsection v-required }
-{ $subsection v-number }
-{ $subsection v-integer }
-{ $subsection v-one-line }
-{ $subsection v-one-word }
-{ $subsection v-captcha }
-{ $subsection v-checkbox }
+{ $subsections
+ v-required
+ v-number
+ v-integer
+ v-one-line
+ v-one-word
+ v-captcha
+ v-checkbox
+}
"More complex validators:"
-{ $subsection v-email }
-{ $subsection v-url }
-{ $subsection v-username }
-{ $subsection v-password }
-{ $subsection v-credit-card }
-{ $subsection v-mode } ;
+{ $subsections
+ v-email
+ v-url
+ v-username
+ v-password
+ v-credit-card
+ v-mode
+} ;
ABOUT: "validators"
\r
ARTICLE: "values" "Global values"\r
"Usually, dynamically-scoped variables subsume global variables and are sufficient for holding global data. But occasionally, for global information that's calculated just once and must be accessed more rapidly than a dynamic variable lookup can provide, it's useful to use the word mechanism instead, and set a word to the appropriate value just once. The " { $vocab-link "values" } " vocabulary implements " { $emphasis "values" } ", which abstract over this concept. To create a new word as a value, use the following syntax:"\r
-{ $subsection POSTPONE: VALUE: }\r
+{ $subsections POSTPONE: VALUE: }\r
"To get the value, just call the word. The following words manipulate values:"\r
-{ $subsection get-value }\r
-{ $subsection set-value }\r
-{ $subsection POSTPONE: to: }\r
-{ $subsection change-value } ;\r
+{ $subsections\r
+ get-value\r
+ set-value\r
+ POSTPONE: to:\r
+ change-value\r
+} ;\r
\r
ABOUT: "values"\r
\r
"These tools operate on all vocabularies found in the current set of " { $link vocab-roots } ", loaded or not."\r
$nl\r
"Loading vocabulary hierarchies:"\r
-{ $subsection load }\r
-{ $subsection load-all }\r
+{ $subsections\r
+ load\r
+ load-all\r
+}\r
"Getting all vocabularies from disk:"\r
-{ $subsection all-vocabs }\r
-{ $subsection all-vocabs-recursive }\r
+{ $subsections\r
+ all-vocabs\r
+ all-vocabs-recursive\r
+}\r
"Getting all vocabularies from disk whose names which match a string prefix:"\r
-{ $subsection child-vocabs }\r
-{ $subsection child-vocabs-recursive }\r
+{ $subsections\r
+ child-vocabs\r
+ child-vocabs-recursive\r
+}\r
"Words for modifying output:"\r
-{ $subsection no-roots }\r
-{ $subsection no-prefixes }\r
+{ $subsections\r
+ no-roots\r
+ no-prefixes\r
+}\r
"Getting " { $link "vocabs.metadata" } " for all vocabularies from disk:"\r
-{ $subsection all-tags }\r
-{ $subsection all-authors } ;\r
+{ $subsections\r
+ all-tags\r
+ all-authors\r
+} ;\r
\r
ABOUT: "vocabs.hierarchy"\r
\r
ARTICLE: "vocabs.metadata" "Vocabulary metadata"
"Vocabulary summaries:"
-{ $subsection vocab-summary }
-{ $subsection set-vocab-summary }
+{ $subsections
+ vocab-summary
+ set-vocab-summary
+}
"Vocabulary authors:"
-{ $subsection vocab-authors }
-{ $subsection set-vocab-authors }
+{ $subsections
+ vocab-authors
+ set-vocab-authors
+}
"Vocabulary tags:"
-{ $subsection vocab-tags }
-{ $subsection set-vocab-tags }
-{ $subsection add-vocab-tags }
+{ $subsections
+ vocab-tags
+ set-vocab-tags
+ add-vocab-tags
+}
"Getting and setting arbitrary vocabulary metadata:"
-{ $subsection vocab-file-contents }
-{ $subsection set-vocab-file-contents } ;
+{ $subsections
+ vocab-file-contents
+ set-vocab-file-contents
+} ;
ABOUT: "vocabs.metadata"
ARTICLE: "vocabs.refresh" "Runtime code reloading"
"Reloading source files changed on disk:"
-{ $subsection refresh }
-{ $subsection refresh-all } ;
+{ $subsections
+ refresh
+ refresh-all
+} ;
ABOUT: "vocabs.refresh"
ARTICLE: "wrap.strings" "String word wrapping"
"The " { $vocab-link "wrap.strings" } " vocabulary implements word wrapping for simple strings, assumed to be in monospace font."
-{ $subsection wrap-lines }
-{ $subsection wrap-string }
-{ $subsection wrap-indented-string } ;
+{ $subsections
+ wrap-lines
+ wrap-string
+ wrap-indented-string
+} ;
HELP: wrap-lines
{ $values { "lines" string } { "width" integer } { "newlines" "sequence of strings" } }
ARTICLE: "wrap.words" "Word object wrapping"
"The " { $vocab-link "wrap.words" } " vocabulary implements word wrapping on abstract word objects, which have certain properties making it a more suitable input representation than strings."
-{ $subsection wrap-words }
-{ $subsection word }
-{ $subsection <word> } ;
+{ $subsections
+ wrap-words
+ word
+ <word>
+} ;
HELP: wrap-words
{ $values { "words" { "a sequence of " { $instance word } "s" } } { "line-max" integer } { "line-ideal" integer } { "lines" "a sequence of sequences of words" } }
{ $description "posts an XML-RPC document to the specified URL, receives the response and parses it as XML-RPC, returning the tuple" } ;
ARTICLE: { "xml-rpc" "intro" } "XML-RPC"
- "This is the XML-RPC library. XML-RPC is used instead of SOAP because it is far simpler and easier to use for most tasks. The library was implemented by Daniel Ehrenberg."
- $nl
- "The most important words that this library implements are:"
- { $subsection send-rpc }
- { $subsection receive-rpc }
- "data types in XML-RPC"
- { $subsection base64 }
- { $subsection rpc-method }
- { $subsection rpc-response }
- { $subsection rpc-fault }
- "the constructors for these are"
- { $subsection <base64> }
- { $subsection <rpc-method> }
- { $subsection <rpc-response> }
- { $subsection <rpc-fault> }
- "other words include"
- { $subsection post-rpc } ;
+"This is the XML-RPC library. XML-RPC is used instead of SOAP because it is far simpler and easier to use for most tasks. The library was implemented by Daniel Ehrenberg."
+$nl
+"The most important words that this library implements are:"
+{ $subsections
+ send-rpc
+ receive-rpc
+}
+"data types in XML-RPC"
+{ $subsections
+ base64
+ rpc-method
+ rpc-response
+ rpc-fault
+}
+"the constructors for these are"
+{ $subsections
+ <base64>
+ <rpc-method>
+ <rpc-response>
+ <rpc-fault>
+}
+"other words include"
+{ $subsections post-rpc } ;
ARTICLE: "xml.data" "XML data types"
"The " { $vocab-link "xml.data" } " vocabulary defines a simple document object model for XML. Everything is simply a tuple and can be manipulated as such."
-{ $subsection { "xml.data" "classes" } }
-{ $subsection { "xml.data" "constructors" } }
+{ $subsections
+ { "xml.data" "classes" }
+ { "xml.data" "constructors" }
+}
"Simple words for manipulating names:"
- { $subsection names-match? }
- { $subsection assure-name }
+{ $subsections
+ names-match?
+ assure-name
+}
"For high-level tools for manipulating XML, see " { $vocab-link "xml.traversal" } ;
ARTICLE: { "xml.data" "classes" } "XML data classes"
- "XML documents and chunks are made of the following classes:"
- { $subsection xml }
- { $subsection xml-chunk }
- { $subsection tag }
- { $subsection name }
- { $subsection contained-tag }
- { $subsection open-tag }
- { $subsection prolog }
- { $subsection comment }
- { $subsection instruction }
- { $subsection unescaped }
- { $subsection element-decl }
- { $subsection attlist-decl }
- { $subsection entity-decl }
- { $subsection system-id }
- { $subsection public-id }
- { $subsection doctype-decl }
- { $subsection notation-decl } ;
+"XML documents and chunks are made of the following classes:"
+{ $subsections
+ xml
+ xml-chunk
+ tag
+ name
+ contained-tag
+ open-tag
+ prolog
+ comment
+ instruction
+ unescaped
+ element-decl
+ attlist-decl
+ entity-decl
+ system-id
+ public-id
+ doctype-decl
+ notation-decl
+} ;
ARTICLE: { "xml.data" "constructors" } "XML data constructors"
- "These data types are constructed with:"
- { $subsection <xml> }
- { $subsection <xml-chunk> }
- { $subsection <tag> }
- { $subsection <name> }
- { $subsection <contained-tag> }
- { $subsection <prolog> }
- { $subsection <comment> }
- { $subsection <instruction> }
- { $subsection <unescaped> }
- { $subsection <simple-name> }
- { $subsection <element-decl> }
- { $subsection <attlist-decl> }
- { $subsection <entity-decl> }
- { $subsection <system-id> }
- { $subsection <public-id> }
- { $subsection <doctype-decl> }
- { $subsection <notation-decl> } ;
+"These data types are constructed with:"
+{ $subsections
+ <xml>
+ <xml-chunk>
+ <tag>
+ <name>
+ <contained-tag>
+ <prolog>
+ <comment>
+ <instruction>
+ <unescaped>
+ <simple-name>
+ <element-decl>
+ <attlist-decl>
+ <entity-decl>
+ <system-id>
+ <public-id>
+ <doctype-decl>
+ <notation-decl>
+} ;
HELP: tag
{ $class-description "Tuple representing an XML tag, delegating to a " { $link
ARTICLE: "xml.entities" "XML entities"
"When XML is parsed, entities like &foo; are replaced with the characters they represent. A few entities like & and < are defined by default, but more are available, and the set of entities can be customized. Below are some words involved in XML entities, defined in the vocabulary 'entities':"
- { $subsection entities }
- { $subsection with-entities }
+{ $subsections
+ entities
+ with-entities
+}
"For entities used in HTML/XHTML, see " { $vocab-link "xml.entities.html" } ;
HELP: entities
ARTICLE: "xml.entities.html" "HTML entities"
{ $vocab-link "xml.entities.html" } " defines words for using entities defined in HTML/XHTML."
-{ $subsection html-entities }
-{ $subsection with-html-entities } ;
+{ $subsections
+ html-entities
+ with-html-entities
+} ;
HELP: html-entities
{ $description "A hash table from HTML entity names to their character values." }
ARTICLE: "xml.errors" "XML parsing errors"
"The " { $vocab-link "xml.errors" } " vocabulary provides a rich and highly inspectable set of parsing errors. All XML errors are described by the union class " { $link xml-error } "."
- { $subsection multitags }
- { $subsection notags }
- { $subsection extra-attrs }
- { $subsection nonexist-ns }
- { $subsection not-yes/no }
- { $subsection unclosed }
- { $subsection mismatched }
- { $subsection expected }
- { $subsection no-entity }
- { $subsection pre/post-content }
- { $subsection unclosed-quote }
- { $subsection bad-name }
- { $subsection quoteless-attr }
- { $subsection disallowed-char }
- { $subsection missing-close }
- { $subsection unexpected-end }
- { $subsection duplicate-attr }
- { $subsection bad-cdata }
- { $subsection text-w/]]> }
- { $subsection attr-w/< }
- { $subsection misplaced-directive }
- "Additionally, most of these errors are a kind of " { $link xml-error-at } " which provides more information about where the error occurred."
- $nl
- "Note that, in parsing an XML document, only the first error is reported." ;
+{ $subsections
+ multitags
+ notags
+ extra-attrs
+ nonexist-ns
+ not-yes/no
+ unclosed
+ mismatched
+ expected
+ no-entity
+ pre/post-content
+ unclosed-quote
+ bad-name
+ quoteless-attr
+ disallowed-char
+ missing-close
+ unexpected-end
+ duplicate-attr
+ bad-cdata
+ text-w/]]>
+ attr-w/<
+ misplaced-directive
+}
+"Additionally, most of these errors are a kind of " { $link xml-error-at } " which provides more information about where the error occurred."
+$nl
+"Note that, in parsing an XML document, only the first error is reported." ;
ABOUT: "xml.errors"
ARTICLE: "xml.syntax" "Syntax extensions for XML"
"The " { $link "xml.syntax" } " vocabulary defines a number of new parsing words forXML processing."
-{ $subsection { "xml.syntax" "tags" } }
-{ $subsection { "xml.syntax" "literals" } }
-{ $subsection POSTPONE: XML-NS: } ;
+{ $subsections
+ { "xml.syntax" "tags" }
+ { "xml.syntax" "literals" }
+ POSTPONE: XML-NS:
+} ;
ARTICLE: { "xml.syntax" "tags" } "Dispatch on XML tag names"
"There is a system, analogous to generic words, for processing XML. A word can dispatch off the name of the tag that is passed to it. To define such a word, use"
-{ $subsection POSTPONE: TAGS: }
+{ $subsections POSTPONE: TAGS: }
"and to define a new 'method' for this word, use"
-{ $subsection POSTPONE: TAG: } ;
+{ $subsections POSTPONE: TAG: } ;
HELP: TAGS:
{ $syntax "TAGS: word" }
ARTICLE: { "xml.syntax" "literals" } "XML literals"
"The following words provide syntax for XML literals:"
-{ $subsection POSTPONE: <XML }
-{ $subsection POSTPONE: [XML }
+{ $subsections
+ POSTPONE: <XML
+ POSTPONE: [XML
+}
"These can be used for creating an XML literal, which can be used with variables or a fry-like syntax to interpolate data into XML."
-{ $subsection { "xml.syntax" "interpolation" } } ;
+{ $subsections { "xml.syntax" "interpolation" } } ;
HELP: <XML
{ $syntax "<XML <?xml version=\"1.0\"?><document>...</document> XML>" }
ARTICLE: "xml.traversal" "Utilities for traversing XML"
"The " { $vocab-link "xml.traversal" } " vocabulary provides utilities for traversing an XML DOM tree and viewing the contents of a single tag. The following words are defined:"
- $nl
- { $subsection { "xml.traversal" "intro" } }
- { $subsection tag-named }
- { $subsection tags-named }
- { $subsection deep-tag-named }
- { $subsection deep-tags-named }
- { $subsection get-id }
- "To get at the contents of a single tag, use"
- { $subsection children>string }
- { $subsection children-tags }
- { $subsection first-child-tag }
- { $subsection assert-tag } ;
+$nl
+{ $subsections
+ { "xml.traversal" "intro" }
+ tag-named
+ tags-named
+ deep-tag-named
+ deep-tags-named
+ get-id
+}
+"To get at the contents of a single tag, use"
+{ $subsections
+ children>string
+ children-tags
+ first-child-tag
+ assert-tag
+} ;
ARTICLE: { "xml.traversal" "intro" } "An example of XML processing"
"To illustrate how to use the XML library, we develop a simple Atom parser in Factor. Atom is an XML-based syndication format, like RSS. To see the full version of what we develop here, look at " { $snippet "basis/syndication" } " at the " { $snippet "atom1.0" } " word. First, we want to load a file and get a DOM tree for it."
ABOUT: "xml.writer"
ARTICLE: "xml.writer" "Writing XML"
- "These words are used to print XML preserving whitespace in text nodes"
- { $subsection write-xml }
- { $subsection xml>string }
- "These words are used to prettyprint XML"
- { $subsection pprint-xml>string }
- { $subsection pprint-xml }
- "Certain variables can be changed to mainpulate prettyprinting"
- { $subsection sensitive-tags }
- { $subsection indenter }
- "All of these words operate on arbitrary pieces of XML: they can take, as in put, XML documents, comments, tags, strings (text nodes), XML chunks, etc." ;
+"These words are used to print XML preserving whitespace in text nodes"
+{ $subsections
+ write-xml
+ xml>string
+}
+"These words are used to prettyprint XML"
+{ $subsections
+ pprint-xml>string
+ pprint-xml
+}
+"Certain variables can be changed to mainpulate prettyprinting"
+{ $subsections
+ sensitive-tags
+ indenter
+}
+"All of these words operate on arbitrary pieces of XML: they can take, as in put, XML documents, comments, tags, strings (text nodes), XML chunks, etc." ;
HELP: xml>string
{ $values { "xml" "an XML document" } { "string" "a string" } }
{ read-dtd file>dtd string>dtd } related-words\r
\r
ARTICLE: { "xml" "reading" } "Reading XML"\r
- "The following words are used to read something into an XML document"\r
- { $subsection read-xml }\r
- { $subsection read-xml-chunk }\r
- { $subsection string>xml }\r
- { $subsection string>xml-chunk }\r
- { $subsection file>xml }\r
- { $subsection bytes>xml }\r
- "To read a DTD:"\r
- { $subsection read-dtd }\r
- { $subsection file>dtd }\r
- { $subsection string>dtd } ;\r
+"The following words are used to read something into an XML document"\r
+{ $subsections\r
+ read-xml\r
+ read-xml-chunk\r
+ string>xml\r
+ string>xml-chunk\r
+ file>xml\r
+ bytes>xml\r
+}\r
+"To read a DTD:"\r
+{ $subsections\r
+ read-dtd\r
+ file>dtd\r
+ string>dtd\r
+} ;\r
\r
ARTICLE: { "xml" "events" } "Event-based XML parsing"\r
"In addition to DOM-style parsing based around " { $link read-xml } ", the XML module also provides SAX-style event-based parsing. This uses much of the same data structures as normal XML, with the exception of the classes " { $link xml } " and " { $link tag } " and as such, the article " { $vocab-link "xml.data" } " may be useful in learning how to process documents in this way. Other useful words are:"\r
- { $subsection each-element }\r
- { $subsection opener }\r
- { $subsection closer }\r
- { $subsection contained }\r
- "There is also pull-based parsing to augment the push-parsing of SAX. This is probably easier to use and more logical. It uses the same parsing objects as the above style of parsing, except string elements are always in arrays, for example { \"\" }. Relevant pull-parsing words are:"\r
- { $subsection <pull-xml> }\r
- { $subsection pull-xml }\r
- { $subsection pull-event }\r
- { $subsection pull-elem } ;\r
+{ $subsections\r
+ each-element\r
+ opener\r
+ closer\r
+ contained\r
+}\r
+"There is also pull-based parsing to augment the push-parsing of SAX. This is probably easier to use and more logical. It uses the same parsing objects as the above style of parsing, except string elements are always in arrays, for example { \"\" }. Relevant pull-parsing words are:"\r
+{ $subsections\r
+ <pull-xml>\r
+ pull-xml\r
+ pull-event\r
+ pull-elem\r
+} ;\r
\r
ARTICLE: { "xml" "namespaces" } "Working with XML namespaces"\r
"The Factor XML parser implements XML namespaces, and provides convenient utilities for working with them. Anywhere in the public API that a name is accepted as an argument, either a string or an XML name is accepted. If a string is used, it is coerced into a name by giving it a null namespace. Names are stored as " { $link name } " tuples, which have slots for the namespace prefix and namespace URL as well as the main part of the tag name." $nl\r
\r
ARTICLE: "xml" "XML parser"\r
"The " { $vocab-link "xml" } " vocabulary implements the XML 1.0 and 1.1 standards, converting strings of text into XML and vice versa. The parser checks for well-formedness but is not validating. There is only partial support for processing DTDs."\r
- { $subsection { "xml" "reading" } }\r
- { $subsection { "xml" "events" } }\r
- { $subsection { "xml" "namespaces" } }\r
- { $vocab-subsection "Writing XML" "xml.writer" }\r
- { $vocab-subsection "XML parsing errors" "xml.errors" }\r
- { $vocab-subsection "XML entities" "xml.entities" }\r
- { $vocab-subsection "XML data types" "xml.data" }\r
- { $vocab-subsection "Utilities for traversing XML" "xml.traversal" }\r
- { $vocab-subsection "Syntax extensions for XML" "xml.syntax" } ;\r
+{ $subsections\r
+ { "xml" "reading" }\r
+ { "xml" "events" }\r
+ { "xml" "namespaces" }\r
+}\r
+{ $vocab-subsection "Writing XML" "xml.writer" }\r
+{ $vocab-subsection "XML parsing errors" "xml.errors" }\r
+{ $vocab-subsection "XML entities" "xml.entities" }\r
+{ $vocab-subsection "XML data types" "xml.data" }\r
+{ $vocab-subsection "Utilities for traversing XML" "xml.traversal" }\r
+{ $vocab-subsection "Syntax extensions for XML" "xml.syntax" } ;\r
\r
ABOUT: "xml"\r
"When an image is loaded, any alien objects which persisted from the previous session are marked as having expired. This is because the C pointers they contain are almost certainly no longer valid."
$nl
"For this reason, the " { $link POSTPONE: ALIEN: } " word should not be used in source files, since loading the source file then saving the image will result in the literal becoming expired. Use " { $link <alien> } " instead, and ensure the word calling " { $link <alien> } " is not declared " { $link POSTPONE: flushable } "."
-{ $subsection expired? } ;
+{ $subsections expired? } ;
ARTICLE: "aliens" "Alien addresses"
"Instances of the " { $link alien } " class represent pointers to C data outside the Factor heap:"
-{ $subsection <alien> }
-{ $subsection <displaced-alien> }
-{ $subsection alien-address }
+{ $subsections
+ <alien>
+ <displaced-alien>
+ alien-address
+}
"Anywhere that a " { $link alien } " instance is accepted, the " { $link f } " singleton may be passed in to denote a null pointer."
$nl
"Usually alien objects do not have to created and dereferenced directly; instead declaring C function parameters and return values as having a pointer type such as " { $snippet "void*" } " takes care of the details."
-{ $subsection "syntax-aliens" }
-{ $subsection "alien-expiry" }
+{ $subsections
+ "syntax-aliens"
+ "alien-expiry"
+}
"When higher-level abstractions won't do:"
-{ $subsection "reading-writing-memory" }
+{ $subsections "reading-writing-memory" }
{ $see-also "c-data" "c-types-specs" } ;
ARTICLE: "reading-writing-memory" "Reading and writing memory directly"
"Numerical values can be read from memory addresses and converted to Factor objects using the various typed memory accessor words:"
-{ $subsection alien-signed-1 }
-{ $subsection alien-unsigned-1 }
-{ $subsection alien-signed-2 }
-{ $subsection alien-unsigned-2 }
-{ $subsection alien-signed-4 }
-{ $subsection alien-unsigned-4 }
-{ $subsection alien-signed-cell }
-{ $subsection alien-unsigned-cell }
-{ $subsection alien-signed-8 }
-{ $subsection alien-unsigned-8 }
-{ $subsection alien-float }
-{ $subsection alien-double }
+{ $subsections
+ alien-signed-1
+ alien-unsigned-1
+ alien-signed-2
+ alien-unsigned-2
+ alien-signed-4
+ alien-unsigned-4
+ alien-signed-cell
+ alien-unsigned-cell
+ alien-signed-8
+ alien-unsigned-8
+ alien-float
+ alien-double
+}
"Factor numbers can also be converted to C values and stored to memory:"
-{ $subsection set-alien-signed-1 }
-{ $subsection set-alien-unsigned-1 }
-{ $subsection set-alien-signed-2 }
-{ $subsection set-alien-unsigned-2 }
-{ $subsection set-alien-signed-4 }
-{ $subsection set-alien-unsigned-4 }
-{ $subsection set-alien-signed-cell }
-{ $subsection set-alien-unsigned-cell }
-{ $subsection set-alien-signed-8 }
-{ $subsection set-alien-unsigned-8 }
-{ $subsection set-alien-float }
-{ $subsection set-alien-double } ;
+{ $subsections
+ set-alien-signed-1
+ set-alien-unsigned-1
+ set-alien-signed-2
+ set-alien-unsigned-2
+ set-alien-signed-4
+ set-alien-unsigned-4
+ set-alien-signed-cell
+ set-alien-unsigned-cell
+ set-alien-signed-8
+ set-alien-unsigned-8
+ set-alien-float
+ set-alien-double
+} ;
ARTICLE: "alien-invoke" "Calling C from Factor"
"The easiest way to call into a C library is to define bindings using a pair of parsing words:"
-{ $subsection POSTPONE: LIBRARY: }
-{ $subsection POSTPONE: FUNCTION: }
+{ $subsections
+ POSTPONE: LIBRARY:
+ POSTPONE: FUNCTION:
+}
"The above parsing words create word definitions which call a lower-level word; you can use it directly, too:"
-{ $subsection alien-invoke }
+{ $subsections alien-invoke }
"Sometimes it is necessary to invoke a C function pointer, rather than a named C function:"
-{ $subsection alien-indirect }
+{ $subsections alien-indirect }
"There are some details concerning the conversion of Factor objects to C values, and vice versa. See " { $link "c-data" } "." ;
HELP: alien-invoke-error
ARTICLE: "alien-callback" "Calling Factor from C"
"Callbacks can be defined and passed to C code as function pointers; the C code can then invoke the callback and run Factor code:"
-{ $subsection alien-callback }
-{ $subsection POSTPONE: CALLBACK: }
+{ $subsections
+ alien-callback
+ POSTPONE: CALLBACK:
+}
"There are some caveats concerning the conversion of Factor objects to C values, and vice versa. See " { $link "c-data" } "."
-{ $subsection "alien-callback-gc" }
+{ $subsections "alien-callback-gc" }
{ $see-also "byte-arrays-gc" } ;
ARTICLE: "dll.private" "DLL handles"
"DLL handles are a built-in class of objects which represent loaded native libraries. DLL handles are instances of the " { $link dll } " class, and have a literal syntax used for debugging prinouts; see " { $link "syntax-aliens" } "."
$nl
"Usually one never has to deal with DLL handles directly; the C library interface creates them as required. However if direct access to these operating system facilities is required, the following primitives can be used:"
-{ $subsection dlopen }
-{ $subsection dlsym }
-{ $subsection dlclose }
-{ $subsection dll-valid? } ;
+{ $subsections
+ dlopen
+ dlsym
+ dlclose
+ dll-valid?
+} ;
ARTICLE: "embedding-api" "Factor embedding API"
"The Factor embedding API is defined in " { $snippet "vm/master.h" } "."
"One exception is that the global " { $link input-stream } " and " { $link output-stream } " streams are not bound by default, to avoid conflicting with any I/O the host process might perform. The " { $link init-stdio } " words must be called explicitly to initialize terminal streams."
$nl
"There is a word which can detect when Factor is embedded:"
-{ $subsection embedded? }
+{ $subsections embedded? }
"No special support is provided for calling out from Factor into the owner process. The C library inteface works fine for this task - see " { $link "alien" } "." ;
ARTICLE: "embedding" "Embedding Factor into C applications"
{ "Other Unix" { $snippet "libfactor.a" } "No" }
}
"An image file must be supplied; a minimal image can be built, however the compiler must be included for the embedding API to work (see " { $link "bootstrap-cli-args" } ")."
-{ $subsection "embedding-api" }
-{ $subsection "embedding-factor" }
-{ $subsection "embedding-restrictions" } ;
+{ $subsections
+ "embedding-api"
+ "embedding-factor"
+ "embedding-restrictions"
+} ;
ARTICLE: "alien" "C library interface"
"Factor can directly call C functions in native libraries. It is also possible to compile callbacks which run Factor code, and pass them to native libraries as function pointers."
$nl
"C library interface words are found in the " { $vocab-link "alien" } " vocabulary and its subvocabularies."
{ $warning "C does not perform runtime type checking, automatic memory management or array bounds checks. Incorrect usage of C library functions can lead to crashes, data corruption, and security exploits." }
-{ $subsection "loading-libs" }
-{ $subsection "alien-invoke" }
-{ $subsection "alien-callback" }
-{ $subsection "c-data" }
-{ $subsection "classes.struct" }
-{ $subsection "dll.private" }
-{ $subsection "embedding" } ;
+{ $subsections
+ "loading-libs"
+ "alien-invoke"
+ "alien-callback"
+ "c-data"
+ "classes.struct"
+ "dll.private"
+ "embedding"
+} ;
ABOUT: "alien"
ARTICLE: "arrays-unsafe" "Unsafe array operations"
"These two words are used internally by the Factor implementation. User code should never need to call them; instead use " { $link nth } " and " { $link set-nth } "."
-{ $subsection array-nth }
-{ $subsection set-array-nth } ;
+{ $subsections
+ array-nth
+ set-array-nth
+} ;
ARTICLE: "arrays" "Arrays"
"The " { $vocab-link "arrays" } " vocabulary implements fixed-size mutable sequences which support the " { $link "sequence-protocol" } "."
"Array literal syntax is documented in " { $link "syntax-arrays" } ". Resizable arrays also exist and are known as " { $link "vectors" } "."
$nl
"Arrays form a class of objects:"
-{ $subsection array }
-{ $subsection array? }
+{ $subsections
+ array
+ array?
+}
"Creating new arrays:"
-{ $subsection >array }
-{ $subsection <array> }
+{ $subsections
+ >array
+ <array>
+}
"Creating an array from several elements on the stack:"
-{ $subsection 1array }
-{ $subsection 2array }
-{ $subsection 3array }
-{ $subsection 4array }
+{ $subsections
+ 1array
+ 2array
+ 3array
+ 4array
+}
"The class of two-element arrays:"
-{ $subsection pair }
+{ $subsections pair }
"Arrays can be accessed without bounds checks in a pointer unsafe way."
-{ $subsection "arrays-unsafe" } ;
+{ $subsections "arrays-unsafe" } ;
ABOUT: "arrays"
"There is no special syntax for literal alists since they are just sequences; in practice, literals look like so:"
{ $code "{" " { key1 value1 }" " { key2 value2 }" "}" }
"To make an assoc into an alist:"
-{ $subsection >alist } ;
+{ $subsections >alist } ;
ARTICLE: "enums" "Enumerations"
"An enumeration provides a view of a sequence as an assoc mapping integer indices to elements:"
-{ $subsection enum }
-{ $subsection <enum> }
+{ $subsections
+ enum
+ <enum>
+}
"Inverting a permutation using enumerations:"
{ $example "IN: scratchpad" ": invert ( perm -- perm' )" " <enum> >alist sort-values keys ;" "{ 2 0 4 1 3 } invert ." "{ 1 3 0 4 2 }" } ;
ARTICLE: "assocs-protocol" "Associative mapping protocol"
"All associative mappings must be instances of a mixin class:"
-{ $subsection assoc }
-{ $subsection assoc? }
+{ $subsections
+ assoc
+ assoc?
+}
"All associative mappings must implement methods on the following generic words:"
-{ $subsection at* }
-{ $subsection assoc-size }
-{ $subsection >alist }
+{ $subsections
+ at*
+ assoc-size
+ >alist
+}
"Mutable assocs should implement the following additional words:"
-{ $subsection set-at }
-{ $subsection delete-at }
-{ $subsection clear-assoc }
+{ $subsections
+ set-at
+ delete-at
+ clear-assoc
+}
"The following three words are optional:"
-{ $subsection value-at* }
-{ $subsection new-assoc }
-{ $subsection assoc-like }
+{ $subsections
+ value-at*
+ new-assoc
+ assoc-like
+}
"Assocs should also implement methods on the " { $link clone } ", " { $link equal? } " and " { $link hashcode* } " generic words. Two utility words will help with the implementation of the last two:"
-{ $subsection assoc= }
-{ $subsection assoc-hashcode }
+{ $subsections
+ assoc=
+ assoc-hashcode
+}
"Finally, assoc classes should define a word for converting other types of assocs; conventionally, such words are named " { $snippet ">" { $emphasis "class" } } " where " { $snippet { $emphasis "class" } } " is the class name. Such a word can be implemented using a utility:"
-{ $subsection assoc-clone-like } ;
+{ $subsections assoc-clone-like } ;
ARTICLE: "assocs-lookup" "Lookup and querying of assocs"
"Utility operations built up from the " { $link "assocs-protocol" } ":"
-{ $subsection key? }
-{ $subsection at }
-{ $subsection ?at }
-{ $subsection assoc-empty? }
-{ $subsection keys }
-{ $subsection values }
-{ $subsection assoc-stack }
+{ $subsections
+ key?
+ at
+ ?at
+ assoc-empty?
+ keys
+ values
+ assoc-stack
+}
{ $see-also at* assoc-size } ;
ARTICLE: "assocs-values" "Transposed assoc operations"
"default Most assoc words take a key and find the corresponding value. The following words take a value and find the corresponding key:"
-{ $subsection value-at }
-{ $subsection value-at* }
-{ $subsection value? }
+{ $subsections
+ value-at
+ value-at*
+ value?
+}
"With most assoc implementations, these words runs in linear time, proportional to the number of entries in the assoc. For fast value lookups, use " { $vocab-link "biassocs" } "." ;
ARTICLE: "assocs-sets" "Set-theoretic operations on assocs"
"It is often useful to use the keys of an associative mapping as a set, exploiting the constant or logarithmic lookup time of most implementations (" { $link "alists" } " being a notable exception)."
-{ $subsection assoc-subset? }
-{ $subsection assoc-intersect }
-{ $subsection update }
-{ $subsection assoc-union }
-{ $subsection assoc-diff }
-{ $subsection remove-all }
-{ $subsection substitute }
-{ $subsection substitute-here }
-{ $subsection extract-keys }
+{ $subsections
+ assoc-subset?
+ assoc-intersect
+ update
+ assoc-union
+ assoc-diff
+ remove-all
+ substitute
+ substitute-here
+ extract-keys
+}
{ $see-also key? assoc-any? assoc-all? "sets" } ;
ARTICLE: "assocs-mutation" "Storing keys and values in assocs"
"Utility operations built up from the " { $link "assocs-protocol" } ":"
-{ $subsection delete-at* }
-{ $subsection rename-at }
-{ $subsection change-at }
-{ $subsection at+ }
-{ $subsection inc-at }
+{ $subsections
+ delete-at*
+ rename-at
+ change-at
+ at+
+ inc-at
+}
{ $see-also set-at delete-at clear-assoc push-at } ;
ARTICLE: "assocs-conversions" "Associative mapping conversions"
"Converting to other assocs:"
-{ $subsection assoc-clone-like }
+{ $subsections assoc-clone-like }
"Combining a sequence of assocs into a single assoc:"
-{ $subsection assoc-combine }
+{ $subsections assoc-combine }
"Creating an assoc from key/value sequences:"
-{ $subsection zip }
+{ $subsections zip }
"Creating key/value sequences from an assoc:"
-{ $subsection unzip }
+{ $subsections unzip }
;
ARTICLE: "assocs-combinators" "Associative mapping combinators"
"The " { $link assoc-find } " combinator is part of the " { $link "assocs-protocol" } " and must be implemented once for each class of assoc. All other combinators are implemented in terms of this combinator."
$nl
"The standard functional programming idioms:"
-{ $subsection assoc-each }
-{ $subsection assoc-find }
-{ $subsection assoc-map }
-{ $subsection assoc-filter }
-{ $subsection assoc-filter-as }
-{ $subsection assoc-any? }
-{ $subsection assoc-all? }
+{ $subsections
+ assoc-each
+ assoc-find
+ assoc-map
+ assoc-filter
+ assoc-filter-as
+ assoc-any?
+ assoc-all?
+}
"Additional combinators:"
-{ $subsection assoc-partition }
-{ $subsection cache }
-{ $subsection 2cache }
-{ $subsection map>assoc }
-{ $subsection assoc>map }
-{ $subsection assoc-map-as } ;
+{ $subsections
+ assoc-partition
+ cache
+ 2cache
+ map>assoc
+ assoc>map
+ assoc-map-as
+} ;
ARTICLE: "assocs" "Associative mapping operations"
"An " { $emphasis "associative mapping" } ", abbreviated " { $emphasis "assoc" } ", is a collection of key/value pairs which provides efficient lookup and storage indexed by key."
"Words used for working with assocs are in the " { $vocab-link "assocs" } " vocabulary."
$nl
"Associative mappings implement a protocol:"
-{ $subsection "assocs-protocol" }
+{ $subsections "assocs-protocol" }
"A large set of utility words work on any object whose class implements the associative mapping protocol."
-{ $subsection "assocs-lookup" }
-{ $subsection "assocs-values" }
-{ $subsection "assocs-mutation" }
-{ $subsection "assocs-combinators" }
-{ $subsection "assocs-sets" }
-{ $subsection "assocs-conversions" } ;
+{ $subsections
+ "assocs-lookup"
+ "assocs-values"
+ "assocs-mutation"
+ "assocs-combinators"
+ "assocs-sets"
+ "assocs-conversions"
+} ;
ABOUT: "assocs"
"Byte arrays play a special role in the C library interface; they can be used to pass binary data back and forth between Factor and C. See " { $link "c-pointers" } "."
$nl
"Byte arrays form a class of objects."
-{ $subsection byte-array }
-{ $subsection byte-array? }
+{ $subsections
+ byte-array
+ byte-array?
+}
"There are several ways to construct byte arrays."
-{ $subsection >byte-array }
-{ $subsection <byte-array> }
-{ $subsection 1byte-array }
-{ $subsection 2byte-array }
-{ $subsection 3byte-array }
-{ $subsection 4byte-array }
+{ $subsections
+ >byte-array
+ <byte-array>
+ 1byte-array
+ 2byte-array
+ 3byte-array
+ 4byte-array
+}
"Resizing byte-arrays:"
-{ $subsection resize-byte-array } ;
+{ $subsections resize-byte-array } ;
ABOUT: "byte-arrays"
"The " { $vocab-link "byte-vectors" } " vocabulary implements resizable mutable sequence of unsigned bytes. Byte vectors implement the " { $link "sequence-protocol" } " and thus all " { $link "sequences" } " can be used with them."\r
$nl\r
"Byte vectors form a class:"\r
-{ $subsection byte-vector }\r
-{ $subsection byte-vector? }\r
+{ $subsections\r
+ byte-vector\r
+ byte-vector?\r
+}\r
"Creating byte vectors:"\r
-{ $subsection >byte-vector }\r
-{ $subsection <byte-vector> }\r
+{ $subsections\r
+ >byte-vector\r
+ <byte-vector>\r
+}\r
"Literal syntax:"\r
-{ $subsection POSTPONE: BV{ }\r
+{ $subsections POSTPONE: BV{ }\r
"If you don't care about initial capacity, a more elegant way to create a new byte vector is to write:"\r
{ $code "BV{ } clone" } ;\r
\r
"A " { $emphasis "checksum" } " is a function mapping sequences of bytes to fixed-length strings. While checksums are not one-to-one, a good checksum should have a low probability of collision. Additionally, some checksum algorithms are designed to be hard to reverse, in the sense that finding an input string which hashes to a given checksum string requires a brute-force search."
$nl
"Checksums are instances of a class:"
-{ $subsection checksum }
+{ $subsections checksum }
"Operations on checksums:"
-{ $subsection checksum-bytes }
-{ $subsection checksum-stream }
-{ $subsection checksum-lines }
+{ $subsections
+ checksum-bytes
+ checksum-stream
+ checksum-lines
+}
"Checksums should implement at least one of " { $link checksum-bytes } " and " { $link checksum-stream } ". Implementing " { $link checksum-lines } " is optional."
$nl
"Utilities:"
-{ $subsection checksum-file }
-{ $subsection hex-string }
+{ $subsections
+ checksum-file
+ hex-string
+}
"Checksum implementations:"
-{ $subsection "checksums.crc32" }
+{ $subsections "checksums.crc32" }
{ $vocab-subsection "MD5 checksum" "checksums.md5" }
{ $vocab-subsection "SHA checksums" "checksums.sha" }
{ $vocab-subsection "Adler-32 checksum" "checksums.adler-32" }
ARTICLE: "checksums.crc32" "CRC32 checksum"
"The CRC32 checksum algorithm provides a quick but unreliable way to detect changes in data."
-{ $subsection crc32 } ;
+{ $subsections crc32 } ;
ABOUT: "checksums.crc32"
\r
ARTICLE: "class-operations" "Class operations"\r
"Set-theoretic operations on classes:"\r
-{ $subsection class= }\r
-{ $subsection class< }\r
-{ $subsection class<= }\r
-{ $subsection class-and }\r
-{ $subsection class-or }\r
-{ $subsection classes-intersect? }\r
+{ $subsections\r
+ class=\r
+ class<\r
+ class<=\r
+ class-and\r
+ class-or\r
+ classes-intersect?\r
+}\r
"Low-level implementation detail:"\r
-{ $subsection flatten-class }\r
-{ $subsection flatten-builtin-class }\r
-{ $subsection class-types }\r
-{ $subsection class-tags } ;\r
+{ $subsections\r
+ flatten-class\r
+ flatten-builtin-class\r
+ class-types\r
+ class-tags\r
+} ;\r
\r
ARTICLE: "class-linearization" "Class linearization"\r
"Classes have an intrinsic partial order; given two classes A and B, we either have that A is a subset of B, B is a subset of A, A and B are equal as sets, or they are incomparable. The last two situations present difficulties for method dispatch:"\r
"The second problem is resolved with another tie-breaker. When performing the topological sort of classes, if there are multiple candidates at any given step of the sort, lexicographical order on the class name is used."\r
$nl\r
"Operations:"\r
-{ $subsection class< }\r
-{ $subsection sort-classes }\r
-{ $subsection smallest-class }\r
+{ $subsections\r
+ class<\r
+ sort-classes\r
+ smallest-class\r
+}\r
"Metaclass order:"\r
-{ $subsection rank-class } ;\r
+{ $subsections rank-class } ;\r
\r
HELP: flatten-builtin-class\r
{ $values { "class" class } { "assoc" "an assoc whose keys are classes" } }\r
"Every object is an instance of exactly one canonical " { $emphasis "built-in class" } " which defines its layout in memory and basic behavior."
$nl
"The set of built-in classes is a class:"
-{ $subsection builtin-class }
-{ $subsection builtin-class? }
+{ $subsections
+ builtin-class
+ builtin-class?
+}
"See " { $link "type-index" } " for a list of built-in classes." ;
HELP: builtin-class
{ { $link null } { $snippet "[ drop f ]" } { "No object is an instance of " { $link null } } }
}
"The set of class predicate words is a class:"
-{ $subsection predicate }
-{ $subsection predicate? }
+{ $subsections
+ predicate
+ predicate?
+}
"A predicate word holds a reference to the class it is predicating over in the " { $snippet "\"predicating\"" } " word property." ;
ARTICLE: "classes" "Classes"
"Words for working with classes are found in the " { $vocab-link "classes" } " vocabulary."
$nl
"Classes themselves form a class:"
-{ $subsection class? }
+{ $subsections class? }
"You can ask an object for its class:"
-{ $subsection class }
+{ $subsections class }
"Testing if an object is an instance of a class:"
-{ $subsection instance? }
+{ $subsections instance? }
"You can ask a class for its superclass:"
-{ $subsection superclass }
-{ $subsection superclasses }
-{ $subsection subclass-of? }
+{ $subsections
+ superclass
+ superclasses
+ subclass-of?
+}
"Class predicates can be used to test instances directly:"
-{ $subsection "class-predicates" }
+{ $subsections "class-predicates" }
"There is a universal class which all objects are an instance of, and an empty class with no instances:"
-{ $subsection object }
-{ $subsection null }
+{ $subsections
+ object
+ null
+}
"Obtaining a list of all defined classes:"
-{ $subsection classes }
+{ $subsections classes }
"There are several sorts of classes:"
-{ $subsection "builtin-classes" }
-{ $subsection "unions" }
-{ $subsection "intersections" }
-{ $subsection "mixins" }
-{ $subsection "predicates" }
-{ $subsection "singletons" }
+{ $subsections
+ "builtin-classes"
+ "unions"
+ "intersections"
+ "mixins"
+ "predicates"
+ "singletons"
+}
{ $link "tuples" } " are documented in their own section."
$nl
"Classes can be inspected and operated upon:"
-{ $subsection "class-operations" }
-{ $subsection "class-linearization" }
+{ $subsections
+ "class-operations"
+ "class-linearization"
+}
{ $see-also "class-index" } ;
ABOUT: "classes"
ARTICLE: "intersections" "Intersection classes"
"An object is an instance of a intersection class if it is an instance of all of its participants."
-{ $subsection POSTPONE: INTERSECTION: }
-{ $subsection define-intersection-class }
+{ $subsections POSTPONE: INTERSECTION: }
+{ $subsections define-intersection-class }
"Intersection classes can be introspected:"
-{ $subsection participants }
+{ $subsections participants }
"The set of intersection classes is a class:"
-{ $subsection intersection-class }
-{ $subsection intersection-class? }
+{ $subsections
+ intersection-class
+ intersection-class?
+}
"Intersection classes are used to associate a method with objects which are simultaneously instances of multiple different classes, as well as to conveniently define predicates." ;
ABOUT: "intersections"
ARTICLE: "mixins" "Mixin classes"
"An object is an instance of a union class if it is an instance of one of its members. In this respect, mixin classes are identical to union classes. However, mixin classes have the additional property that they are " { $emphasis "open" } "; new classes can be added to the mixin after the original definition of the mixin."
-{ $subsection POSTPONE: MIXIN: }
-{ $subsection POSTPONE: INSTANCE: }
-{ $subsection define-mixin-class }
-{ $subsection add-mixin-instance }
+{ $subsections
+ POSTPONE: MIXIN:
+ POSTPONE: INSTANCE:
+ define-mixin-class
+ add-mixin-instance
+}
"The set of mixin classes is a class:"
-{ $subsection mixin-class }
-{ $subsection mixin-class? }
+{ $subsections
+ mixin-class
+ mixin-class?
+}
"Mixins are used to defines suites of behavior which are generally useful and can be applied to user-defined classes. For example, the " { $link immutable-sequence } " mixin can be used with user-defined sequences to make them immutable."
{ $see-also "unions" "tuple-subclassing" } ;
ARTICLE: "predicates" "Predicate classes"
"Predicate classes allow fine-grained control over method dispatch."
-{ $subsection POSTPONE: PREDICATE: }
-{ $subsection define-predicate-class }
+{ $subsections
+ POSTPONE: PREDICATE:
+ define-predicate-class
+}
"The set of predicate classes is a class:"
-{ $subsection predicate-class }
-{ $subsection predicate-class? } ;
+{ $subsections
+ predicate-class
+ predicate-class?
+} ;
ABOUT: "predicates"
ARTICLE: "singletons" "Singleton classes"
"A singleton is a class with only one instance and with no state."
-{ $subsection POSTPONE: SINGLETON: }
-{ $subsection POSTPONE: SINGLETONS: }
-{ $subsection define-singleton-class }
+{ $subsections
+ POSTPONE: SINGLETON:
+ POSTPONE: SINGLETONS:
+ define-singleton-class
+}
"The set of all singleton classes is itself a class:"
-{ $subsection singleton-class? }
-{ $subsection singleton-class } ;
+{ $subsections
+ singleton-class?
+ singleton-class
+} ;
HELP: define-singleton-class
{ $values { "word" "a new word" } }
{ "The " { $link slots>tuple } " and " { $link >tuple } " words ensure that the values in the sequence satisfy the correct class predicates." }
{ { $link "tuple-redefinition" } " fills in new slots with initial values and ensures that changes to existing declarations result in incompatible values being replaced with the initial value of their respective slots." }
}
-{ $subsection "slot-class-coercion" } ;
+{ $subsections "slot-class-coercion" } ;
ARTICLE: "slot-class-coercion" "Coercive slot declarations"
"If the class of a slot is declared to be one of " { $link fixnum } " or " { $link float } ", then rather than testing values with the class predicate, writer words coerce values to the relevant type with " { $link >fixnum } " or " { $link >float } ". This may still result in error, but permits a wider range of values than a class predicate test. It also results in a possible loss of precision; for example, storing a large integer into a " { $link fixnum } " slot will silently overflow and discard high bits, and storing a ratio into a " { $link float } " slot may lose precision if the ratio is one which cannot be represented exactly with floating-point."
{ "whether a slot is read only or not (" { $link read-only } ")" }
{ "an initial value (" { $link initial: } ")" }
}
-{ $subsection "slot-read-only-declaration" }
-{ $subsection "slot-class-declaration" }
-{ $subsection "slot-initial-values" } ;
+{ $subsections
+ "slot-read-only-declaration"
+ "slot-class-declaration"
+ "slot-initial-values"
+} ;
ARTICLE: "parametrized-constructors" "Parameterized constructors"
"A " { $emphasis "parametrized constructor" } " is a word which directly or indirectly calls " { $link new } " or " { $link boa } ", but instead of passing a literal class symbol, it takes the class symbol as an input from the stack."
ARTICLE: "tuple-constructors" "Tuple constructors"
"Tuples are created by calling one of two constructor primitives:"
-{ $subsection new }
-{ $subsection boa }
+{ $subsections
+ new
+ boa
+}
"A shortcut for defining BOA constructors:"
-{ $subsection POSTPONE: C: }
+{ $subsections POSTPONE: C: }
"By convention, construction logic is encapsulated in a word named after the tuple class surrounded in angle brackets; for example, the constructor word for a " { $snippet "point" } " class might be named " { $snippet "<point>" } "."
$nl
"Constructors play a part in enforcing the invariant that slot values must always match slot declarations. The " { $link new } " word fills in the tuple with initial values, and " { $link boa } " ensures that the values on the stack match the corresponding slot declarations. See " { $link "tuple-declarations" } "."
"! Run-time error"
"\"not a number\" 2 3 4 color boa"
}
-{ $subsection "parametrized-constructors" } ;
+{ $subsections "parametrized-constructors" } ;
ARTICLE: "tuple-inheritance-example" "Tuple subclassing example"
"Rectangles, parallelograms and circles are all shapes. We support two operations on shapes:"
{ $code
"TUPLE: subclass < superclass ... ;"
}
-{ $subsection "tuple-inheritance-example" }
-{ $subsection "tuple-inheritance-anti-example" }
+{ $subsections
+ "tuple-inheritance-example"
+ "tuple-inheritance-anti-example"
+}
{ $see-also "call-next-method" "parametrized-constructors" "unions" "mixins" } ;
ARTICLE: "tuple-introspection" "Tuple introspection"
"In addition to the slot reader and writer words which " { $link POSTPONE: TUPLE: } " defines for every tuple class, it is possible to construct and take apart entire tuples in a generic way."
-{ $subsection >tuple }
-{ $subsection tuple>array }
-{ $subsection tuple-slots }
+{ $subsections
+ >tuple
+ tuple>array
+ tuple-slots
+}
"Tuple classes can also be defined at run time:"
-{ $subsection define-tuple-class }
+{ $subsections define-tuple-class }
{ $see-also "slots" "mirrors" } ;
ARTICLE: "tuple-examples" "Tuple examples"
"A " { $emphasis "protocol slot" } " is one which is assumed to exist by the implementation of a class, without being defined on the class itself. The burden is on subclasses (or mixin instances) to provide this slot."
$nl
"Protocol slots are defined using a parsing word:"
-{ $subsection POSTPONE: SLOT: }
+{ $subsections POSTPONE: SLOT: }
"Protocol slots are used where the implementation of a superclass needs to assume that each subclass defines certain slots, however the slots of each subclass are potentially declared with different class specializers, thus preventing the slots from being defined in the superclass."
$nl
"For example, the " { $link growable } " mixin provides an implementation of the sequence protocol which wraps an underlying sequence, resizing it as necessary when elements are added beyond the length of the sequence. It assumes that the concrete mixin instances define two slots, " { $snippet "length" } " and " { $snippet "underlying" } ". These slots are defined as protocol slots: " { $snippet "SLOT: length" } " and " { $snippet "SLOT: underlying" } ". "
ARTICLE: "tuples" "Tuples"
"Tuples are user-defined classes composed of named slots. They are the central data type of Factor's object system."
-{ $subsection "tuple-examples" }
+{ $subsections "tuple-examples" }
"A parsing word defines tuple classes:"
-{ $subsection POSTPONE: TUPLE: }
+{ $subsections POSTPONE: TUPLE: }
"For each tuple class, several words are defined, the class word, a class predicate, and accessor words for each slot."
$nl
"The class word is used for defining methods on the tuple class; it has the same name as the tuple class. The predicate is named " { $snippet { $emphasis "name" } "?" } ". Initially, no specific words are defined for constructing new instances of the tuple. Constructors must be defined explicitly, and tuple slots are accessed via automatically-generated accessor words."
-{ $subsection "accessors" }
-{ $subsection "tuple-constructors" }
-{ $subsection "tuple-subclassing" }
-{ $subsection "tuple-declarations" }
-{ $subsection "protocol-slots" }
-{ $subsection "tuple-introspection" }
+{ $subsections
+ "accessors"
+ "tuple-constructors"
+ "tuple-subclassing"
+ "tuple-declarations"
+ "protocol-slots"
+ "tuple-introspection"
+}
"Tuple classes can be redefined; this updates existing instances:"
-{ $subsection "tuple-redefinition" }
+{ $subsections "tuple-redefinition" }
"Tuple literal syntax is documented in " { $link "syntax-tuples" } "." ;
ABOUT: "tuples"
ARTICLE: "unions" "Union classes"
"An object is an instance of a union class if it is an instance of one of its members."
-{ $subsection POSTPONE: UNION: }
-{ $subsection define-union-class }
+{ $subsections
+ POSTPONE: UNION:
+ define-union-class
+}
"Union classes can be introspected:"
-{ $subsection members }
+{ $subsections members }
"The set of union classes is a class:"
-{ $subsection union-class }
-{ $subsection union-class? }
+{ $subsections
+ union-class
+ union-class?
+}
"Unions are used to define behavior shared between a fixed set of classes, as well as to conveniently define predicates."
{ $see-also "mixins" "tuple-subclassing" } ;
"The cleave combinators apply multiple quotations to a single value."
$nl
"Two quotations:"
-{ $subsections bi 2bi 3bi }
+{ $subsections
+ bi
+ 2bi
+ 3bi
+}
"Three quotations:"
-{ $subsections tri 2tri 3tri }
+{ $subsections
+ tri
+ 2tri
+ 3tri
+}
"An array of quotations:"
-{ $subsection cleave 2cleave 3cleave }
+{ $subsections
+ cleave
+ 2cleave
+ 3cleave
+}
$nl
"Technically, the cleave combinators are redundant because they can be simulated using shuffle words and other combinators, and in addition, they do not reduce token counts by much, if at all. However, they can make code more readable by expressing intention and exploiting any inherent symmetry. For example, a piece of code which performs three operations on the top of the stack can be written in one of two ways:"
{ $code
}
"The latter is more aesthetically pleasing than the former."
$nl
-{ $subsection "cleave-shuffle-equivalence" } ;
+{ $subsections "cleave-shuffle-equivalence" } ;
ARTICLE: "spread-shuffle-equivalence" "Expressing shuffle words with spread combinators"
"Spread combinators are defined in terms of shuffle words, and mappings from certain shuffle idioms to spread combinators are discussed in the documentation for " { $link bi* } ", " { $link 2bi* } ", " { $link tri* } ", and " { $link 2tri* } "."
}
"A generalization of the above combinators to any number of quotations can be found in " { $link "combinators" } "."
$nl
-{ $subsection "spread-shuffle-equivalence" } ;
+{ $subsections "spread-shuffle-equivalence" } ;
ARTICLE: "apply-combinators" "Apply combinators"
"The apply combinators apply a single quotation to multiple values. The " { $snippet "@" } " suffix signifies application."
{ $subsections ? }
"Two combinators which abstract out nested chains of " { $link if } ":"
{ $subsections cond case }
-{ $subsection "conditionals-boolean-equivalence" }
+{ $subsections "conditionals-boolean-equivalence" }
{ $see-also "booleans" "bitwise-arithmetic" both? either? } ;
ARTICLE: "dataflow-combinators" "Data flow combinators"
"The above are syntax sugar. The underlying words are a bit more verbose but allow non-constant effects to be passed in:"
{ $subsections call-effect execute-effect }
"The combinator variants that do not take an effect declaration can only be used if the compiler is able to infer the stack effect by other means. See " { $link "inference-combinators" } "."
-{ $subsection "call-unsafe" }
+{ $subsections "call-unsafe" }
{ $see-also "effects" "inference" } ;
ARTICLE: "combinators" "Combinators"
"Words defined in a compilation unit may not be called until the compilation unit is finished. The parser detects this case for parsing words and throws a " { $link staging-violation } "; calling any other word from within its own compilation unit throws an " { $link undefined } " error."
$nl
"The parser groups all definitions in a source file into one compilation unit, and parsing words do not need to concern themselves with compilation units. However, if definitions are being created at run time, a compilation unit must be created explicitly:"
-{ $subsection with-compilation-unit }
+{ $subsections with-compilation-unit }
"Compiling a set of words:"
-{ $subsection compile }
+{ $subsections compile }
"Words called to associate a definition with a compilation unit and a source file location:"
-{ $subsection remember-definition }
-{ $subsection remember-class }
+{ $subsections
+ remember-definition
+ remember-class
+}
"Forward reference checking (see " { $link "definition-checking" } "):"
-{ $subsection forward-reference? }
+{ $subsections forward-reference? }
"A hook to be called at the end of the compilation unit. If the optimizing compiler is loaded, this compiles new words with the " { $link "compiler" } ":"
-{ $subsection recompile }
+{ $subsections recompile }
"Low-level compiler interface exported by the Factor VM:"
-{ $subsection modify-code-heap } ;
+{ $subsections modify-code-heap } ;
ABOUT: "compilation-units"
ARTICLE: "errors-restartable" "Restartable errors"
"Support for restartable errors is built on top of the basic error handling facility. The following words signals recoverable errors:"
-{ $subsection throw-restarts }
-{ $subsection rethrow-restarts }
+{ $subsections
+ throw-restarts
+ rethrow-restarts
+}
"The list of restarts from the most recently-thrown error is stored in a global variable:"
-{ $subsection restarts }
+{ $subsections restarts }
"To invoke restarts, see " { $link "debugger" } "." ;
ARTICLE: "errors-post-mortem" "Post-mortem error inspection"
"The most recently thrown error, together with the continuation at that point, are stored in a pair of global variables:"
-{ $subsection error }
-{ $subsection error-continuation }
+{ $subsections
+ error
+ error-continuation
+}
"Developer tools for inspecting these values are found in " { $link "debugger" } "." ;
ARTICLE: "errors-anti-examples" "Common error handling pitfalls"
"Support for handling exceptional situations such as bad user input, implementation bugs, and input/output errors is provided by a set of words built using continuations."
$nl
"Two words raise an error in the innermost error handler for the current dynamic extent:"
-{ $subsection throw }
-{ $subsection rethrow }
+{ $subsections
+ throw
+ rethrow
+}
"Words for establishing an error handler:"
-{ $subsection cleanup }
-{ $subsection recover }
-{ $subsection ignore-errors }
+{ $subsections
+ cleanup
+ recover
+ ignore-errors
+}
"Syntax sugar for defining errors:"
-{ $subsection POSTPONE: ERROR: }
+{ $subsections POSTPONE: ERROR: }
"Unhandled errors are reported in the listener and can be debugged using various tools. See " { $link "debugger" } "."
-{ $subsection "errors-restartable" }
-{ $subsection "debugger" }
-{ $subsection "errors-post-mortem" }
-{ $subsection "errors-anti-examples" }
+{ $subsections
+ "errors-restartable"
+ "debugger"
+ "errors-post-mortem"
+ "errors-anti-examples"
+}
"When Factor encouters a critical error, it calls the following word:"
-{ $subsection die } ;
+{ $subsections die } ;
ARTICLE: "continuations.private" "Continuation implementation details"
"A continuation is simply a tuple holding the contents of the five stacks:"
-{ $subsection continuation }
-{ $subsection >continuation< }
+{ $subsections
+ continuation
+ >continuation<
+}
"The five stacks can be read and written:"
-{ $subsection datastack }
-{ $subsection set-datastack }
-{ $subsection retainstack }
-{ $subsection set-retainstack }
-{ $subsection callstack }
-{ $subsection set-callstack }
-{ $subsection namestack }
-{ $subsection set-namestack }
-{ $subsection catchstack }
-{ $subsection set-catchstack } ;
+{ $subsections
+ datastack
+ set-datastack
+ retainstack
+ set-retainstack
+ callstack
+ set-callstack
+ namestack
+ set-namestack
+ catchstack
+ set-catchstack
+} ;
ARTICLE: "continuations" "Continuations"
"At any point in the execution of a program, the " { $emphasis "current continuation" } " represents the future of the computation."
"Words for working with continuations are found in the " { $vocab-link "continuations" } " vocabulary; implementation details are in " { $vocab-link "continuations.private" } "."
$nl
"Continuations can be reified with the following two words:"
-{ $subsection callcc0 }
-{ $subsection callcc1 }
+{ $subsections
+ callcc0
+ callcc1
+}
"Another two words resume continuations:"
-{ $subsection continue }
-{ $subsection continue-with }
+{ $subsections
+ continue
+ continue-with
+}
"Continuations as control-flow:"
-{ $subsection attempt-all }
-{ $subsection with-return }
+{ $subsections
+ attempt-all
+ with-return
+}
"Continuations serve as the building block for a number of higher-level abstractions, such as " { $link "errors" } " and " { $link "threads" } "."
-{ $subsection "continuations.private" } ;
+{ $subsections "continuations.private" } ;
ABOUT: "continuations"
"A common protocol is used to build generic tools for working with all definitions."
$nl
"Definitions must know what source file they were loaded from, and provide a way to set this:"
-{ $subsection where }
-{ $subsection set-where }
+{ $subsections
+ where
+ set-where
+}
"Definitions can be removed:"
-{ $subsection forget }
+{ $subsections forget }
"Definitions must implement a few operations used for printing them in source form:"
-{ $subsection definer }
-{ $subsection definition }
+{ $subsections
+ definer
+ definition
+}
{ $see-also "see" } ;
ARTICLE: "definition-checking" "Definition sanity checking"
"Since this is undesirable, the parser explicitly raises a " { $link no-word } " error if a source file refers to a word which is in the dictionary, but defined after it is used."
$nl
"The parser also catches duplicate definitions. If an artifact is defined twice in the same source file, the earlier definition will never be accessible, and this is almost always a mistake, perhaps due to a bad choice of word names, or a copy and paste error. The parser raises an error in this case."
-{ $subsection redefine-error } ;
+{ $subsections redefine-error } ;
ARTICLE: "definitions" "Definitions"
"A " { $emphasis "definition" } " is an artifact read from a source file. Words for working with definitions are found in the " { $vocab-link "definitions" } " vocabulary."
"Instances of the definition may be introspected and modified with the definition protocol"
}
"For every source file loaded into the system, a list of definitions is maintained. Pathname objects implement the definition protocol, acting over the definitions their source files contain. See " { $link "source-files" } " for details."
-{ $subsection "definition-protocol" }
-{ $subsection "definition-checking" }
-{ $subsection "compilation-units" }
+{ $subsections
+ "definition-protocol"
+ "definition-checking"
+ "compilation-units"
+}
"A parsing word to remove definitions:"
-{ $subsection POSTPONE: FORGET: }
+{ $subsections POSTPONE: FORGET: }
{ $see-also "see" "parser" "source-files" "words" "generic" "help-impl" } ;
ABOUT: "definitions"
ARTICLE: "destructors-using" "Using destructors"
"Disposing of an object:"
-{ $subsection dispose }
+{ $subsections dispose }
"Utility word for scoped disposal:"
-{ $subsection with-disposal }
+{ $subsections with-disposal }
"Utility word for disposing multiple objects:"
-{ $subsection dispose-each }
+{ $subsections dispose-each }
"Utility words for more complex disposal patterns:"
-{ $subsection with-destructors }
-{ $subsection &dispose }
-{ $subsection |dispose } ;
+{ $subsections
+ with-destructors
+ &dispose
+ |dispose
+} ;
ARTICLE: "destructors-extending" "Writing new destructors"
"Superclass for disposable objects:"
-{ $subsection disposable }
+{ $subsections disposable }
"Parametrized constructor for disposable objects:"
-{ $subsection new-disposable }
+{ $subsections new-disposable }
"Generic disposal word:"
-{ $subsection dispose* }
+{ $subsections dispose* }
"Global set of disposable objects:"
-{ $subsection disposables } ;
+{ $subsections disposables } ;
ARTICLE: "destructors" "Deterministic resource disposal"
"Operating system resources such as streams, memory mapped files, and so on are not managed by Factor's garbage collector and must be released when you are done with them. Failing to release a resource can lead to reduced performance and instability."
-{ $subsection "destructors-using" }
-{ $subsection "destructors-extending" }
-{ $subsection "destructors-anti-patterns" }
+{ $subsections
+ "destructors-using"
+ "destructors-extending"
+ "destructors-anti-patterns"
+}
{ $see-also "tools.destructors" } ;
ABOUT: "destructors"
"Now, the linear order is the following, from least-specific to most-specific:"
{ $code "{ object sequence number integer }" }
"The " { $link order } " word can be useful to clarify method dispatch order:"
-{ $subsection order } ;
+{ $subsections order } ;
ARTICLE: "generic-introspection" "Generic word introspection"
"In most cases, generic words and methods are defined at parse time with " { $link POSTPONE: GENERIC: } " (or some other parsing word) and " { $link POSTPONE: M: } "."
"Sometimes, generic words need to be inspected defined at run time; words for performing these tasks are found in the " { $vocab-link "generic" } " vocabulary."
$nl
"The set of generic words is a class which implements the " { $link "definition-protocol" } ":"
-{ $subsection generic }
-{ $subsection generic? }
+{ $subsections
+ generic
+ generic?
+}
"New generic words can be defined:"
-{ $subsection define-generic }
-{ $subsection define-simple-generic }
+{ $subsections
+ define-generic
+ define-simple-generic
+}
"Methods can be added to existing generic words:"
-{ $subsection create-method }
+{ $subsections create-method }
"Method definitions can be looked up:"
-{ $subsection method }
+{ $subsections method }
"Finding the most specific method for an object:"
-{ $subsection effective-method }
+{ $subsections effective-method }
"A generic word contains methods; the list of methods specializing on a class can also be obtained:"
-{ $subsection implementors }
+{ $subsections implementors }
"Low-level word which rebuilds the generic word after methods are added or removed, or the method combination is changed:"
-{ $subsection make-generic }
+{ $subsections make-generic }
"Low-level method constructor:"
-{ $subsection <method> }
+{ $subsections <method> }
"Methods may be pushed on the stack with a literal syntax:"
-{ $subsection POSTPONE: M\ }
+{ $subsections POSTPONE: M\ }
{ $see-also "see" } ;
ARTICLE: "method-combination" "Custom method combination"
"If a generic word is called with an object and multiple methods specialize on classes that this object is an instance of, usually the most specific method is called (" { $link "method-order" } ")."
$nl
"Less-specific methods can be called directly:"
-{ $subsection POSTPONE: call-next-method }
+{ $subsections POSTPONE: call-next-method }
"A lower-level word which the above expands into:"
-{ $subsection (call-next-method) }
+{ $subsections (call-next-method) }
"To look up the next applicable method reflectively:"
-{ $subsection next-method }
+{ $subsections next-method }
"Errors thrown by improper calls to " { $link POSTPONE: call-next-method } ":"
-{ $subsection inconsistent-next-method }
-{ $subsection no-next-method } ;
+{ $subsections
+ inconsistent-next-method
+ no-next-method
+} ;
ARTICLE: "generic" "Generic words and methods"
"A " { $emphasis "generic word" } " is composed of zero or more " { $emphasis "methods" } " together with a " { $emphasis "method combination" } ". A method " { $emphasis "specializes" } " on a class; when a generic word executed, the method combination chooses the most appropriate method and calls its definition."
"A generic word behaves roughly like a long series of class predicate conditionals in a " { $link cond } " form, however methods can be defined in independent source files, reducing coupling and increasing extensibility. The method combination determines which object the generic word will " { $emphasis "dispatch" } " on; this could be the top of the stack, or some other value."
$nl
"Generic words which dispatch on the object at the top of the stack:"
-{ $subsection POSTPONE: GENERIC: }
+{ $subsections POSTPONE: GENERIC: }
"A method combination which dispatches on a specified stack position:"
-{ $subsection POSTPONE: GENERIC# }
+{ $subsections POSTPONE: GENERIC# }
"A method combination which dispatches on the value of a variable at the time the generic word is called:"
-{ $subsection POSTPONE: HOOK: }
+{ $subsections POSTPONE: HOOK: }
"A method combination which dispatches on a pair of stack values, which must be numbers, and upgrades both to the same type of number:"
-{ $subsection POSTPONE: MATH: }
+{ $subsections POSTPONE: MATH: }
"Method definition:"
-{ $subsection POSTPONE: M: }
+{ $subsections POSTPONE: M: }
"Generic words must declare their stack effect in order to compile. See " { $link "effects" } "."
-{ $subsection "method-order" }
-{ $subsection "call-next-method" }
-{ $subsection "method-combination" }
-{ $subsection "generic-introspection" }
+{ $subsections
+ "method-order"
+ "call-next-method"
+ "method-combination"
+ "generic-introspection"
+}
"Generic words specialize behavior based on the class of an object; sometimes behavior needs to be specialized on the object's " { $emphasis "structure" } "; this is known as " { $emphasis "pattern matching" } " and is implemented in the " { $vocab-link "match" } " vocabulary." ;
ABOUT: "generic"
"Words for treating associative mappings as directed graphs can be found in the " { $vocab-link "graphs" } " vocabulary. A directed graph is represented as an assoc mapping each vertex to a set of edges entering that vertex, where the set is itself an assoc, with equal keys and values."
$nl
"To create a new graph, just create an assoc, for example by calling " { $link <hashtable> } ". To add vertices and edges to a graph:"
-{ $subsection add-vertex }
+{ $subsections add-vertex }
"To remove vertices from the graph:"
-{ $subsection remove-vertex }
+{ $subsections remove-vertex }
"Since graphs are represented as assocs, they can be cleared out by calling " { $link clear-assoc } "."
$nl
"You can perform queries on the graph:"
-{ $subsection closure }
+{ $subsections closure }
"Directed graphs are used to maintain cross-referencing information for " { $link "definitions" } "." ;
ABOUT: "graphs"
"Resizable sequences are implementing by having a wrapper object hold a reference to an underlying sequence, together with a fill pointer indicating how many elements of the underlying sequence are occupied. When the fill pointer exceeds the underlying sequence capacity, the underlying sequence grows."
$nl
"There is a resizable sequence mixin:"
-{ $subsection growable }
+{ $subsections growable }
"This mixin implements the sequence protocol by assuming the object has two specific slots:"
{ $list
{ { $snippet "length" } " - the fill pointer (number of occupied elements in the underlying storage)" }
{ { $snippet "underlying" } " - the underlying storage" }
}
"The underlying sequence must implement a generic word:"
-{ $subsection resize }
+{ $subsections resize }
{ $link "vectors" } " and " { $link "sbufs" } " are implemented using the resizable sequence facility." ;
ABOUT: "growable"
"There are two special objects: the " { $link ((tombstone)) } " marker and the " { $link ((empty)) } " marker. Neither of these markers can be used as hashtable keys."
$nl
"The " { $snippet "count" } " slot is the number of entries including deleted entries, and " { $snippet "deleted" } " is the number of deleted entries."
-{ $subsection <hash-array> }
-{ $subsection set-nth-pair }
+{ $subsections
+ <hash-array>
+ set-nth-pair
+}
"If a hashtable's keys are mutated, or if hashing algorithms change, hashtables can be rehashed:"
-{ $subsection rehash } ;
+{ $subsections rehash } ;
ARTICLE: "hashtables" "Hashtables"
"A hashtable provides efficient (expected constant time) lookup and storage of key/value pairs. Keys are compared for equality, and a hashing function is used to reduce the number of comparisons made. The literal syntax is covered in " { $link "syntax-hashtables" } "."
"Words for constructing hashtables are in the " { $vocab-link "hashtables" } " vocabulary. Hashtables implement the " { $link "assocs-protocol" } ", and all " { $link "assocs" } " can be used on them; there are no hashtable-specific words to access and modify keys, because associative mapping operations are generic and work with all associative mappings."
$nl
"Hashtables are a class of objects."
-{ $subsection hashtable }
-{ $subsection hashtable? }
+{ $subsections
+ hashtable
+ hashtable?
+}
"You can create a new hashtable with an initial capacity."
-{ $subsection <hashtable> }
+{ $subsections <hashtable> }
"If you don't care about initial capacity, a more elegant way to create a new hashtable is to write:"
{ $code "H{ } clone" }
"To convert an assoc to a hashtable:"
-{ $subsection >hashtable }
+{ $subsections >hashtable }
"Further topics:"
-{ $subsection "hashtables.keys" }
-{ $subsection "hashtables.utilities" }
-{ $subsection "hashtables.private" } ;
+{ $subsections
+ "hashtables.keys"
+ "hashtables.utilities"
+ "hashtables.private"
+} ;
ARTICLE: "hashtables.keys" "Hashtable keys"
"Hashtables rely on the " { $link hashcode } " word to rapidly locate values associated with keys. The objects used as keys in a hashtable must obey certain restrictions."
ARTICLE: "hashtables.utilities" "Hashtable utilities"
"Utility words to create a new hashtable from a single key/value pair:"
-{ $subsection associate }
-{ $subsection ?set-at } ;
+{ $subsections
+ associate
+ ?set-at
+} ;
ABOUT: "hashtables"
ARTICLE: "init" "Initialization and startup"
"When Factor starts, the first thing it does is call a word:"
-{ $subsection boot }
+{ $subsections boot }
"Next, initialization hooks are called:"
-{ $subsection do-init-hooks }
+{ $subsections do-init-hooks }
"Initialization hooks can be defined:"
-{ $subsection add-init-hook }
+{ $subsections add-init-hook }
"The boot quotation can be changed:"
-{ $subsection boot-quot }
-{ $subsection set-boot-quot } ;
+{ $subsections
+ boot-quot
+ set-boot-quot
+} ;
ABOUT: "init"
{ "Value:" { $snippet "ca" } { $snippet "fe" } { $snippet "ba" } { $snippet "be" } }
}
"Two words convert a sequence of bytes into an integer:"
-{ $subsection be> }
-{ $subsection le> }
+{ $subsections
+ be>
+ le>
+}
"Two words convert an integer into a sequence of bytes:"
-{ $subsection >be }
-{ $subsection >le }
+{ $subsections
+ >be
+ >le
+}
"Words for taking larger integers apart into smaller integers:"
-{ $subsection d>w/w }
-{ $subsection w>h/h }
-{ $subsection h>b/b } ;
+{ $subsections
+ d>w/w
+ w>h/h
+ h>b/b
+} ;
ABOUT: "stream-binary"
ARTICLE: "encodings-descriptors" "Encoding descriptors"
"An encoding descriptor is something which can be used with binary input or output streams to encode or decode bytes stored in a certain representation. It must conform to the " { $link "encodings-protocol" } ". Encodings which you can use are defined in the following vocabularies:"
-{ $subsection "io.encodings.binary" }
-{ $subsection "io.encodings.utf8" }
+{ $subsections
+ "io.encodings.binary"
+ "io.encodings.utf8"
+}
{ $vocab-subsection "UTF-16 encoding" "io.encodings.utf16" }
{ $vocab-subsection "UTF-32 encoding" "io.encodings.utf32" }
{ $vocab-subsection "Strict encodings" "io.encodings.strict" }
ARTICLE: "encodings-protocol" "Encoding protocol"
"There are two parts to implementing a new encoding. First, methods for creating an encoded or decoded stream must be provided. These have defaults, however, which wrap a stream in an encoder or decoder wrapper with the given encoding descriptor."
-{ $subsection <encoder> }
-{ $subsection <decoder> }
+{ $subsections
+ <encoder>
+ <decoder>
+}
"If an encoding might be contained in the code slot of an encoder or decoder tuple, then the following methods must be implemented to read or write one code point from a stream:"
-{ $subsection decode-char }
-{ $subsection encode-char }
+{ $subsections
+ decode-char
+ encode-char
+}
{ $see-also "encodings-introduction" } ;
ARTICLE: "encodings-constructors" "Manually constructing an encoded stream"
"The following words can be used to construct encoded streams. Note that they are usually not used directly, but rather by the stream constructors themselves. Most stream constructors take an encoding descriptor as a parameter and call these constructors internally."
-{ $subsection <encoder> }
-{ $subsection <decoder> } ;
+{ $subsections
+ <encoder>
+ <decoder>
+} ;
ARTICLE: "io.encodings" "I/O encodings"
"The " { $vocab-link "io.encodings" } " vocabulary provides utilities for encoding and decoding bytes that represent text. Encodings can be used in the following situations:"
"With byte arrays, to convert bytes to characters"
"With strings, to convert characters to bytes"
}
-{ $subsection "encodings-descriptors" }
-{ $subsection "encodings-constructors" }
-{ $subsection "io.encodings.string" }
+{ $subsections
+ "encodings-descriptors"
+ "encodings-constructors"
+ "io.encodings.string"
+}
"New types of encodings can be defined:"
-{ $subsection "encodings-protocol" }
+{ $subsections "encodings-protocol" }
"Setting encodings on the current streams:"
-{ $subsection encode-output }
-{ $subsection decode-input }
+{ $subsections
+ encode-output
+ decode-input
+}
"Setting encodings on streams:"
-{ $subsection re-encode }
-{ $subsection re-decode }
+{ $subsections
+ re-encode
+ re-decode
+}
"Combinators to change the encoding:"
-{ $subsection with-encoded-output }
-{ $subsection with-decoded-input }
+{ $subsections
+ with-encoded-output
+ with-decoded-input
+}
{ $see-also "encodings-introduction" } ;
ABOUT: "io.encodings"
ARTICLE: "io.encodings.utf16" "UTF-16 encoding"
"The UTF-16 encoding is a variable-width encoding. Unicode code points are encoded as 2 or 4 byte sequences. There are three encoding descriptor classes for working with UTF-16, depending on endianness or the presence of a BOM:"
-{ $subsection utf16 }
-{ $subsection utf16le }
-{ $subsection utf16be } ;
+{ $subsections
+ utf16
+ utf16le
+ utf16be
+} ;
ABOUT: "io.encodings.utf16"
ARTICLE: "io.encodings.utf8" "UTF-8 encoding"
"UTF-8 is a variable-width encoding. 7-bit ASCII characters are encoded as single bytes, and other Unicode code points are encoded as 2 to 4 byte sequences."
-{ $subsection utf8 } ;
+{ $subsections utf8 } ;
ABOUT: "io.encodings.utf8"
} ;
ARTICLE: "io.files" "Reading and writing files"
-{ $subsection "io.files.examples" }
+{ $subsections "io.files.examples" }
"File streams:"
-{ $subsection <file-reader> }
-{ $subsection <file-writer> }
-{ $subsection <file-appender> }
+{ $subsections
+ <file-reader>
+ <file-writer>
+ <file-appender>
+}
"Reading and writing the entire contents of a file; this is only recommended for smaller files:"
-{ $subsection file-contents }
-{ $subsection set-file-contents }
-{ $subsection file-lines }
-{ $subsection set-file-lines }
+{ $subsections
+ file-contents
+ set-file-contents
+ file-lines
+ set-file-lines
+}
"Utility combinators:"
-{ $subsection with-file-reader }
-{ $subsection with-file-writer }
-{ $subsection with-file-appender } ;
+{ $subsections
+ with-file-reader
+ with-file-writer
+ with-file-appender
+} ;
ABOUT: "io.files"
"All streams must implement the " { $link dispose } " word in addition to the stream protocol."
$nl
"The following word is required for all input and output streams:"
-{ $subsection stream-element-type }
+{ $subsections stream-element-type }
"These words are required for binary and string input streams:"
-{ $subsection stream-read1 }
-{ $subsection stream-read }
-{ $subsection stream-read-until }
-{ $subsection stream-read-partial }
+{ $subsections
+ stream-read1
+ stream-read
+ stream-read-until
+ stream-read-partial
+}
"This word is only required for string input streams:"
-{ $subsection stream-readln }
+{ $subsections stream-readln }
"These words are required for binary and string output streams:"
-{ $subsection stream-flush }
-{ $subsection stream-write1 }
-{ $subsection stream-write }
+{ $subsections
+ stream-flush
+ stream-write1
+ stream-write
+}
"This word is only required for string output streams:"
-{ $subsection stream-nl }
+{ $subsections stream-nl }
"This word is for streams that allow seeking:"
-{ $subsection stream-seek }
+{ $subsections stream-seek }
{ $see-also "io.timeouts" } ;
ARTICLE: "stdio-motivation" "Motivation for default streams"
} ;
ARTICLE: "stdio" "Default input and output streams"
-{ $subsection "stdio-motivation" }
+{ $subsections "stdio-motivation" }
"The default input stream is stored in a dynamically-scoped variable:"
-{ $subsection input-stream }
+{ $subsections input-stream }
"Unless rebound in a child namespace, this variable will be set to a console stream for reading input from the user."
$nl
"Words reading from the default input stream:"
-{ $subsection read1 }
-{ $subsection read }
-{ $subsection read-until }
-{ $subsection read-partial }
+{ $subsections
+ read1
+ read
+ read-until
+ read-partial
+}
"If the default input stream is a character stream (" { $link stream-element-type } " outputs " { $link +character+ } "), lines of text can be read:"
-{ $subsection readln }
+{ $subsections readln }
"Seeking on the default input stream:"
-{ $subsection seek-input }
+{ $subsections seek-input }
"A pair of combinators for rebinding the " { $link input-stream } " variable:"
-{ $subsection with-input-stream }
-{ $subsection with-input-stream* }
+{ $subsections
+ with-input-stream
+ with-input-stream*
+}
"The default output stream is stored in a dynamically-scoped variable:"
-{ $subsection output-stream }
+{ $subsections output-stream }
"Unless rebound in a child namespace, this variable will be set to a console stream for showing output to the user."
$nl
"Words writing to the default output stream:"
-{ $subsection flush }
-{ $subsection write1 }
-{ $subsection write }
+{ $subsections
+ flush
+ write1
+ write
+}
"If the default output stream is a character stream (" { $link stream-element-type } " outputs " { $link +character+ } "), lines of text can be written:"
-{ $subsection print }
-{ $subsection nl }
-{ $subsection bl }
+{ $subsections
+ print
+ nl
+ bl
+}
"Seeking on the default output stream:"
-{ $subsection seek-output }
+{ $subsections seek-output }
"Seeking descriptors:"
-{ $subsection seek-absolute }
-{ $subsection seek-relative }
-{ $subsection seek-end }
+{ $subsections
+ seek-absolute
+ seek-relative
+ seek-end
+}
"A pair of combinators for rebinding the " { $link output-stream } " variable:"
-{ $subsection with-output-stream }
-{ $subsection with-output-stream* }
+{ $subsections
+ with-output-stream
+ with-output-stream*
+}
"A pair of combinators for rebinding both default streams at once:"
-{ $subsection with-streams }
-{ $subsection with-streams* } ;
+{ $subsections
+ with-streams
+ with-streams*
+} ;
ARTICLE: "stream-utils" "Stream utilities"
"There are a few useful stream-related words which are not generic, but merely built up from the stream protocol."
$nl
"First, a simple composition of " { $link stream-write } " and " { $link stream-nl } ":"
-{ $subsection stream-print }
+{ $subsections stream-print }
"Processing lines one by one:"
-{ $subsection stream-lines }
-{ $subsection lines }
-{ $subsection each-line }
+{ $subsections
+ stream-lines
+ lines
+ each-line
+}
"Processing blocks of data:"
-{ $subsection stream-contents }
-{ $subsection contents }
-{ $subsection each-block }
+{ $subsections
+ stream-contents
+ contents
+ each-block
+}
"Copying the contents of one stream to another:"
-{ $subsection stream-copy } ;
+{ $subsections stream-copy } ;
ARTICLE: "stream-examples" "Stream example"
"Ask the user for their age, and print it back:"
ARTICLE: "streams" "Streams"
"Input and output centers on the concept of a " { $emphasis "stream" } ", which is a source or sink of " { $emphasis "elements" } "."
-{ $subsection "stream-examples" }
+{ $subsections "stream-examples" }
"A stream can either be passed around on the stack or bound to a dynamic variable and used as one of the two implicit " { $emphasis "default streams" } "."
-{ $subsection "stream-protocol" }
-{ $subsection "stdio" }
-{ $subsection "stream-utils" }
+{ $subsections
+ "stream-protocol"
+ "stdio"
+ "stream-utils"
+}
{ $see-also "io.streams.string" "io.streams.plain" "io.streams.duplex" } ;
ABOUT: "streams"
ARTICLE: "io.pathnames" "Pathname manipulation"
"Pathname manipulation:"
-{ $subsection parent-directory }
-{ $subsection file-name }
-{ $subsection file-stem }
-{ $subsection file-extension }
-{ $subsection last-path-separator }
-{ $subsection path-components }
-{ $subsection prepend-path }
-{ $subsection append-path }
-{ $subsection canonicalize-path }
+{ $subsections
+ parent-directory
+ file-name
+ file-stem
+ file-extension
+ last-path-separator
+ path-components
+ prepend-path
+ append-path
+ canonicalize-path
+}
"Pathname presentations:"
-{ $subsection pathname }
-{ $subsection <pathname> }
+{ $subsections
+ pathname
+ <pathname>
+}
"Literal pathnames:"
-{ $subsection POSTPONE: P" }
+{ $subsections POSTPONE: P" }
"Low-level word:"
-{ $subsection normalize-path } ;
+{ $subsections normalize-path } ;
ABOUT: "io.pathnames"
ARTICLE: "io.streams.byte-array" "Byte-array streams"
"Byte array streams:"
-{ $subsection <byte-reader> }
-{ $subsection <byte-writer> }
+{ $subsections
+ <byte-reader>
+ <byte-writer>
+}
"Utility combinators:"
-{ $subsection with-byte-reader }
-{ $subsection with-byte-writer } ;
+{ $subsections
+ with-byte-reader
+ with-byte-writer
+} ;
HELP: <byte-reader>
{ $values { "byte-array" byte-array }
ARTICLE: "io.streams.c" "ANSI C streams"
"C streams are found in the " { $vocab-link "io.streams.c" } " vocabulary; they are " { $link "stream-protocol" } " implementations which read and write C " { $snippet "FILE*" } " handles."
-{ $subsection <c-reader> }
-{ $subsection <c-writer> }
+{ $subsections
+ <c-reader>
+ <c-writer>
+}
"Underlying primitives used to implement the above:"
-{ $subsection fopen }
-{ $subsection fwrite }
-{ $subsection fflush }
-{ $subsection fclose }
-{ $subsection fgetc }
-{ $subsection fread }
+{ $subsections
+ fopen
+ fwrite
+ fflush
+ fclose
+ fgetc
+ fread
+}
"The three standard file handles:"
-{ $subsection stdin-handle }
-{ $subsection stdout-handle }
-{ $subsection stderr-handle } ;
+{ $subsections
+ stdin-handle
+ stdout-handle
+ stderr-handle
+} ;
ABOUT: "io.streams.c"
ARTICLE: "looping-combinators" "Looping combinators"
"In most cases, loops should be written using high-level combinators (such as " { $link "sequences-combinators" } ") or tail recursion. However, sometimes, the best way to express intent is with a loop."
-{ $subsection while }
-{ $subsection until }
+{ $subsections
+ while
+ until
+}
"To execute one iteration of a loop, use the following word:"
-{ $subsection do }
+{ $subsections do }
"This word is intended as a modifier. The normal " { $link while } " loop never executes the body if the predicate returns false on the first iteration. To ensure the body executes at least once, use " { $link do } ":"
{ $code
"[ P ] [ Q ] do while"
}
"A simpler looping combinator which executes a single quotation until it returns " { $link f } ":"
-{ $subsection loop } ;
+{ $subsections loop } ;
HELP: assert
{ $values { "got" "the obtained value" } { "expect" "the expected value" } }
"The " { $link "cleave-combinators" } ", " { $link "spread-combinators" } " and " { $link "apply-combinators" } " are closely related to shuffle words and should be used instead where possible because they can result in clearer code; also, see the advice in " { $link "cookbook-philosophy" } "."
$nl
"Removing stack elements:"
-{ $subsection drop }
-{ $subsection 2drop }
-{ $subsection 3drop }
-{ $subsection nip }
-{ $subsection 2nip }
+{ $subsections
+ drop
+ 2drop
+ 3drop
+ nip
+ 2nip
+}
"Duplicating stack elements:"
-{ $subsection dup }
-{ $subsection 2dup }
-{ $subsection 3dup }
-{ $subsection dupd }
-{ $subsection over }
-{ $subsection 2over }
-{ $subsection pick }
-{ $subsection tuck }
+{ $subsections
+ dup
+ 2dup
+ 3dup
+ dupd
+ over
+ 2over
+ pick
+ tuck
+}
"Permuting stack elements:"
-{ $subsection swap }
-{ $subsection swapd }
-{ $subsection rot }
-{ $subsection -rot }
-{ $subsection spin }
-{ $subsection roll }
-{ $subsection -roll } ;
+{ $subsections
+ swap
+ swapd
+ rot
+ -rot
+ spin
+ roll
+ -roll
+} ;
ARTICLE: "equality" "Equality"
"There are two distinct notions of “sameness” when it comes to objects."
$nl
"You can test if two references point to the same object (" { $emphasis "identity comparison" } "). This is rarely used; it is mostly useful with large, mutable objects where the object identity matters but the value is transient:"
-{ $subsection eq? }
+{ $subsections eq? }
"You can test if two objects are equal in a domain-specific sense, usually by being instances of the same class, and having equal slot values (" { $emphasis "value comparison" } "):"
-{ $subsection = }
+{ $subsections = }
"A third form of equality is provided by " { $link number= } ". It compares numeric value while disregarding types."
$nl
"Custom value comparison methods for use with " { $link = } " can be defined on a generic word:"
-{ $subsection equal? }
+{ $subsections equal? }
"Utility class:"
-{ $subsection identity-tuple }
+{ $subsections identity-tuple }
"An object can be cloned; the clone has distinct identity but equal value:"
-{ $subsection clone } ;
+{ $subsections clone } ;
ARTICLE: "assertions" "Assertions"
"Some words to make assertions easier to enforce:"
-{ $subsection assert }
-{ $subsection assert= } ;
+{ $subsections
+ assert
+ assert=
+} ;
ARTICLE: "layouts-types" "Type numbers"
"Corresponding to every built-in class is a built-in type number. An object can be asked for its built-in type number:"
-{ $subsection hi-tag }
+{ $subsections hi-tag }
"Built-in type numbers can be converted to classes, and vice versa:"
-{ $subsection type>class }
-{ $subsection type-number }
-{ $subsection num-types }
+{ $subsections
+ type>class
+ type-number
+ num-types
+}
{ $see-also "builtin-classes" } ;
ARTICLE: "layouts-tags" "Tagged pointers"
"Getting the tag of an object:"
{ $link tag }
"Words for working with tagged pointers:"
-{ $subsection tag-bits }
-{ $subsection num-tags }
-{ $subsection tag-mask }
-{ $subsection tag-number }
+{ $subsections
+ tag-bits
+ num-tags
+ tag-mask
+ tag-number
+}
"The Factor VM does not actually expose any words for working with tagged pointers directly. The above words operate on integers; they are used in the bootstrap image generator and the optimizing compiler." ;
ARTICLE: "layouts-limits" "Sizes and limits"
"Processor cell size:"
-{ $subsection cell }
-{ $subsection cells }
-{ $subsection cell-bits }
+{ $subsections
+ cell
+ cells
+ cell-bits
+}
"Range of integers representable by " { $link fixnum } "s:"
-{ $subsection most-negative-fixnum }
-{ $subsection most-positive-fixnum }
+{ $subsections
+ most-negative-fixnum
+ most-positive-fixnum
+}
"Maximum array size:"
-{ $subsection max-array-capacity } ;
+{ $subsections max-array-capacity } ;
ARTICLE: "layouts-bootstrap" "Bootstrap support"
"Processor cell size for the target architecture:"
-{ $subsection bootstrap-cell }
-{ $subsection bootstrap-cells }
-{ $subsection bootstrap-cell-bits }
+{ $subsections
+ bootstrap-cell
+ bootstrap-cells
+ bootstrap-cell-bits
+}
"Range of integers representable by " { $link fixnum } "s of the target architecture:"
-{ $subsection bootstrap-most-negative-fixnum }
-{ $subsection bootstrap-most-positive-fixnum }
+{ $subsections
+ bootstrap-most-negative-fixnum
+ bootstrap-most-positive-fixnum
+}
"Maximum array size for the target architecture:"
-{ $subsection bootstrap-max-array-capacity } ;
+{ $subsections bootstrap-max-array-capacity } ;
ARTICLE: "layouts" "VM memory layouts"
"The words documented in this section do not ever need to be called by user code. They are documented for the benefit of those wishing to explore the internals of Factor's implementation."
-{ $subsection "layouts-types" }
-{ $subsection "layouts-tags" }
-{ $subsection "layouts-limits" }
-{ $subsection "layouts-bootstrap" } ;
+{ $subsections
+ "layouts-types"
+ "layouts-tags"
+ "layouts-limits"
+ "layouts-bootstrap"
+} ;
ABOUT: "layouts"
ARTICLE: "parser-lexer" "The lexer"
"A variable that encapsulate internal parser state:"
-{ $subsection lexer }
+{ $subsections lexer }
"Creating a default lexer:"
-{ $subsection <lexer> }
+{ $subsections <lexer> }
"A word to test of the end of input has been reached:"
-{ $subsection still-parsing? }
+{ $subsections still-parsing? }
"A word to advance the lexer to the next line:"
-{ $subsection next-line }
+{ $subsections next-line }
"Two generic words to override the lexer's token boundary detection:"
-{ $subsection skip-blank }
-{ $subsection skip-word }
+{ $subsections
+ skip-blank
+ skip-word
+}
"Utility combinator:"
-{ $subsection with-lexer } ;
+{ $subsections with-lexer } ;
"The " { $vocab-link "make" } " vocabulary implements a facility for constructing sequences by holding an accumulator sequence in a variable. Storing the accumulator sequence in a variable rather than the stack may allow code to be written with less stack manipulation."
$nl
"Sequence construction is wrapped in a combinator:"
-{ $subsection make }
+{ $subsections make }
"Inside the quotation passed to " { $link make } ", several words accumulate values:"
-{ $subsection , }
-{ $subsection % }
-{ $subsection # }
+{ $subsections
+ ,
+ %
+ #
+}
"The accumulator sequence can be accessed directly from inside a " { $link make } ":"
-{ $subsection building }
+{ $subsections building }
{ $example
"USING: make math.parser ;"
"[ \"Language #\" % CHAR: \\s , 5 # ] \"\" make print"
"Language # 5"
}
-{ $subsection "make-philosophy" } ;
+{ $subsections "make-philosophy" } ;
ABOUT: "namespaces-make"
"The " { $emphasis "ordered" } " comparison operators set floating point exception flags if the result of the comparison is unordered. The standard comparison operators (" { $link < } ", " { $link <= } ", " { $link > } ", " { $link >= } ") perform ordered comparisons."
$nl
"The " { $link number= } " operation performs an unordered comparison. The following set of operators also perform unordered comparisons:"
-{ $subsection u< }
-{ $subsection u<= }
-{ $subsection u> }
-{ $subsection u>= }
+{ $subsections
+ u<
+ u<=
+ u>
+ u>=
+}
"A word to check if two values are unordered with respect to each other:"
-{ $subsection unordered? }
+{ $subsections unordered? }
"To test for floating point exceptions, use the " { $vocab-link "math.floats.env" } " vocabulary."
$nl
"If neither input to a comparison operator is a floating point value, then " { $link u< } ", " { $link u<= } ", " { $link u> } " and " { $link u>= } " are equivalent to the ordered operators." ;
ARTICLE: "math.floats.bitwise" "Bitwise operations on floats"
"Floating point numbers are represented internally in IEEE 754 double-precision format. This internal representation can be accessed for advanced operations and input/output purposes."
-{ $subsection float>bits }
-{ $subsection double>bits }
-{ $subsection bits>float }
-{ $subsection bits>double }
+{ $subsections
+ float>bits
+ double>bits
+ bits>float
+ bits>double
+}
"Constructing floating point NaNs:"
-{ $subsection <fp-nan> }
+{ $subsections <fp-nan> }
"Floating point numbers are discrete:"
-{ $subsection prev-float }
-{ $subsection next-float }
+{ $subsections
+ prev-float
+ next-float
+}
"Introspection on floating point numbers:"
-{ $subsection fp-special? }
-{ $subsection fp-nan? }
-{ $subsection fp-qnan? }
-{ $subsection fp-snan? }
-{ $subsection fp-infinity? }
-{ $subsection fp-nan-payload }
+{ $subsections
+ fp-special?
+ fp-nan?
+ fp-qnan?
+ fp-snan?
+ fp-infinity?
+ fp-nan-payload
+}
"Comparing two floating point numbers for bitwise equality:"
-{ $subsection fp-bitwise= }
+{ $subsections fp-bitwise= }
{ $see-also POSTPONE: NAN: } ;
ARTICLE: "floats" "Floats"
-{ $subsection float }
+{ $subsections float }
"Rational numbers represent " { $emphasis "exact" } " quantities. On the other hand, a floating point number is an " { $emphasis "approximate" } " value. While rationals can grow to any required precision, floating point numbers have limited precision, and manipulating them is usually faster than manipulating ratios or bignums."
$nl
"Introducing a floating point number in a computation forces the result to be expressed in floating point."
"Floating point literal syntax is documented in " { $link "syntax-floats" } "."
$nl
"Integers and rationals can be converted to floats:"
-{ $subsection >float }
+{ $subsections >float }
"Two real numbers can be divided yielding a float result:"
-{ $subsection /f }
-{ $subsection "math.floats.bitwise" }
-{ $subsection "math.floats.compare" }
+{ $subsections
+ /f
+ "math.floats.bitwise"
+ "math.floats.compare"
+}
"The " { $vocab-link "math.floats.env" } " vocabulary provides functionality for controlling floating point exceptions, rounding modes, and denormal behavior." ;
ABOUT: "floats"
IN: math.integers
ARTICLE: "integers" "Integers"
-{ $subsection integer }
+{ $subsections integer }
"Integers come in two varieties -- fixnums and bignums. Fixnums fit in a machine word and are faster to manipulate; if the result of a fixnum operation is too large to fit in a fixnum, the result is upgraded to a bignum. Here is an example where two fixnums are multiplied yielding a bignum:"
{ $example "USE: classes" "134217728 class ." "fixnum" }
{ $example "USE: classes" "128 class ." "fixnum" }
"Integers can be entered using a different base; see " { $link "syntax-numbers" } "."
$nl
"Integers can be tested for, and real numbers can be converted to integers:"
-{ $subsection fixnum? }
-{ $subsection bignum? }
-{ $subsection >fixnum }
-{ $subsection >integer }
-{ $subsection >bignum }
+{ $subsections
+ fixnum?
+ bignum?
+ >fixnum
+ >integer
+ >bignum
+}
{ $see-also "prettyprint-numbers" "modular-arithmetic" "bitwise-arithmetic" "integer-functions" "syntax-integers" } ;
ABOUT: "integers"
{ $example "USE: classes" "3 >fixnum 6 >bignum * class ." "bignum" }
{ $example "1/2 2.0 + ." "2.5" }
"The following usual operations are supported by all numbers."
-{ $subsection + }
-{ $subsection - }
-{ $subsection * }
-{ $subsection / }
+{ $subsections
+ +
+ -
+ *
+ /
+}
"Non-commutative operations take operands from the stack in the natural order; " { $snippet "6 2 /" } " divides 6 by 2."
-{ $subsection "division-by-zero" }
+{ $subsections "division-by-zero" }
"Real numbers (but not complex numbers) can be ordered:"
-{ $subsection < }
-{ $subsection <= }
-{ $subsection > }
-{ $subsection >= }
+{ $subsections
+ <
+ <=
+ >
+ >=
+}
"Numbers can be compared for equality using " { $link = } ", or a less precise test which disregards types:"
-{ $subsection number= }
+{ $subsections number= }
{ $see-also "math.floats.compare" } ;
ARTICLE: "modular-arithmetic" "Modular arithmetic"
-{ $subsection mod }
-{ $subsection rem }
-{ $subsection /mod }
-{ $subsection /i }
+{ $subsections
+ mod
+ rem
+ /mod
+ /i
+}
{ $see-also "integer-functions" } ;
ARTICLE: "bitwise-arithmetic" "Bitwise arithmetic"
"There are two ways of looking at an integer -- as an abstract mathematical entity, or as a string of bits. The latter representation motivates " { $emphasis "bitwise operations" } "."
-{ $subsection bitand }
-{ $subsection bitor }
-{ $subsection bitxor }
-{ $subsection bitnot }
-{ $subsection shift }
-{ $subsection 2/ }
-{ $subsection 2^ }
-{ $subsection bit? }
+{ $subsections
+ bitand
+ bitor
+ bitxor
+ bitnot
+ shift
+ 2/
+ 2^
+ bit?
+}
"Advanced topics:"
-{ $subsection "math.bitwise" }
-{ $subsection "math.bits" }
+{ $subsections
+ "math.bitwise"
+ "math.bits"
+}
{ $see-also "booleans" } ;
ARTICLE: "arithmetic" "Arithmetic"
"Factor attempts to preserve natural mathematical semantics for numbers. Multiplying two large integers never results in overflow, and dividing two integers yields an exact ratio. Floating point numbers are also supported, along with complex numbers."
$nl
"Math words are in the " { $vocab-link "math" } " vocabulary. Implementation details are in the " { $vocab-link "math.private" } " vocabulary."
-{ $subsection "number-protocol" }
-{ $subsection "modular-arithmetic" }
-{ $subsection "bitwise-arithmetic" }
+{ $subsections
+ "number-protocol"
+ "modular-arithmetic"
+ "bitwise-arithmetic"
+}
{ $see-also "integers" "rationals" "floats" "complex-numbers" } ;
ABOUT: "arithmetic"
ARTICLE: "order-specifiers" "Ordering specifiers"
"Ordering words such as " { $link <=> } " output one of the following values, indicating that of two objects being compared, the first is less than the second, the two are equal, or that the first is greater than the second:"
-{ $subsection +lt+ }
-{ $subsection +eq+ }
-{ $subsection +gt+ } ;
+{ $subsections
+ +lt+
+ +eq+
+ +gt+
+} ;
ARTICLE: "math.order.example" "Linear order example"
"A tuple class which defines an ordering among instances by comparing the values of the " { $snippet "id" } " slot:"
ARTICLE: "math.order" "Linear order protocol"
"Some classes define an intrinsic order amongst instances. This includes numbers, sequences (in particular, strings), and words."
-{ $subsection <=> }
-{ $subsection >=< }
-{ $subsection compare }
-{ $subsection invert-comparison }
+{ $subsections
+ <=>
+ >=<
+ compare
+ invert-comparison
+}
"The above words output order specifiers."
-{ $subsection "order-specifiers" }
+{ $subsections "order-specifiers" }
"Utilities for comparing objects:"
-{ $subsection after? }
-{ $subsection before? }
-{ $subsection after=? }
-{ $subsection before=? }
+{ $subsections
+ after?
+ before?
+ after=?
+ before=?
+}
"Minimum, maximum, clamping:"
-{ $subsection min }
-{ $subsection max }
-{ $subsection clamp }
+{ $subsections
+ min
+ max
+ clamp
+}
"Out of the above generic words, it suffices to implement " { $link <=> } " alone. The others may be provided as an optimization."
-{ $subsection "math.order.example" }
+{ $subsections "math.order.example" }
{ $see-also "sequences-sorting" } ;
ABOUT: "math.order"
ARTICLE: "images" "Images"
"Factor has the ability to save the entire state of the system into an " { $emphasis "image file" } ". The image contains a complete dump of all data and code in the current Factor instance."
-{ $subsection save }
-{ $subsection save-image }
-{ $subsection save-image-and-exit }
+{ $subsections
+ save
+ save-image
+ save-image-and-exit
+}
"To start Factor with a custom image, use the " { $snippet "-i=" { $emphasis "image" } } " command line switch; see " { $link "runtime-cli-args" } "."
$nl
"One reason to save a custom image is if you find yourself loading the same libraries in every Factor session; some libraries take a little while to compile, so saving an image with those libraries loaded can save you a lot of time."
"For example, to save an image with the web framework loaded,"
{ $code "USE: furnace" "save" }
"New images can be created from scratch:"
-{ $subsection "bootstrap.image" }
+{ $subsections "bootstrap.image" }
"The " { $link "tools.deploy" } " tool creates stripped-down images containing just enough code to run a single application."
{ $see-also "tools.memory" } ;
IN: namespaces
ARTICLE: "namespaces-combinators" "Namespace combinators"
-{ $subsection make-assoc }
-{ $subsection with-scope }
-{ $subsection with-variable }
-{ $subsection bind } ;
+{ $subsections
+ make-assoc
+ with-scope
+ with-variable
+ bind
+} ;
ARTICLE: "namespaces-change" "Changing variable values"
-{ $subsection on }
-{ $subsection off }
-{ $subsection inc }
-{ $subsection dec }
-{ $subsection change }
-{ $subsection change-global } ;
+{ $subsections
+ on
+ off
+ inc
+ dec
+ change
+ change-global
+} ;
ARTICLE: "namespaces-global" "Global variables"
-{ $subsection namespace }
-{ $subsection global }
-{ $subsection get-global }
-{ $subsection set-global }
-{ $subsection initialize } ;
+{ $subsections
+ namespace
+ global
+ get-global
+ set-global
+ initialize
+} ;
ARTICLE: "namespaces.private" "Namespace implementation details"
"The namestack holds namespaces."
-{ $subsection namestack }
-{ $subsection set-namestack }
-{ $subsection namespace }
+{ $subsections
+ namestack
+ set-namestack
+ namespace
+}
"A pair of words push and pop namespaces on the namestack."
-{ $subsection >n }
-{ $subsection ndrop } ;
+{ $subsections
+ >n
+ ndrop
+} ;
ARTICLE: "namespaces" "Dynamic variables and namespaces"
"The " { $vocab-link "namespaces" } " vocabulary implements simple dynamically-scoped variables."
"A variable is an entry in an assoc of bindings, where the assoc is implicit rather than passed on the stack. These assocs are termed " { $emphasis "namespaces" } ". Nesting of scopes is implemented with a search order on namespaces, defined by a " { $emphasis "namestack" } ". Since namespaces are just assoc, any object can be used as a variable, however by convention, variables are keyed by symbols (see " { $link "words.symbol" } ")."
$nl
"The " { $link get } " and " { $link set } " words read and write variable values. The " { $link get } " word searches up the chain of nested namespaces, while " { $link set } " always sets variable values in the current namespace only. Namespaces are dynamically scoped; when a quotation is called from a nested scope, any words called by the quotation also execute in that scope."
-{ $subsection get }
-{ $subsection set }
+{ $subsections
+ get
+ set
+}
"Various utility words abstract away common variable access patterns:"
-{ $subsection "namespaces-change" }
-{ $subsection "namespaces-combinators" }
+{ $subsections
+ "namespaces-change"
+ "namespaces-combinators"
+}
"Implementation details your code probably does not care about:"
-{ $subsection "namespaces.private" }
+{ $subsections "namespaces.private" }
"An alternative to dynamic scope is lexical scope. Lexically-scoped values and closures are implemented in the " { $vocab-link "locals" } " vocabulary." ;
ABOUT: "namespaces"
ARTICLE: "reading-ahead" "Reading ahead"
"Parsing words can consume input:"
-{ $subsection scan }
-{ $subsection scan-word }
+{ $subsections
+ scan
+ scan-word
+}
"For example, the " { $link POSTPONE: HEX: } " word uses this feature to read hexadecimal literals:"
{ $see POSTPONE: HEX: }
"It is defined in terms of a lower-level word that takes the numerical base on the data stack, but reads the number from the parser and then adds it to the parse tree:"
"A simple example is the parsing word that reads a quotation:"
{ $see POSTPONE: [ }
"This word uses a utility word which recursively invokes the parser, reading objects into a new accumulator until an occurrence of " { $link POSTPONE: ] } ":"
-{ $subsection parse-literal }
+{ $subsections parse-literal }
"There is another, lower-level word for reading nested structure, which is also useful when called directly:"
-{ $subsection parse-until }
+{ $subsections parse-until }
"Words such as " { $link POSTPONE: ] } " use a declaration which causes them to throw an error when an unpaired occurrence is encountered:"
-{ $subsection POSTPONE: delimiter }
+{ $subsections POSTPONE: delimiter }
{ $see-also POSTPONE: { POSTPONE: H{ POSTPONE: V{ POSTPONE: W{ POSTPONE: T{ POSTPONE: } } ;
ARTICLE: "defining-words" "Defining words"
"Defining words add definitions to the dictionary without modifying the parse tree. The simplest example is the " { $link POSTPONE: SYMBOL: } " word."
{ $see POSTPONE: SYMBOL: }
"The key factor in the definition of " { $link POSTPONE: SYMBOL: } " is " { $link CREATE } ", which reads a token from the input and creates a word with that name. This word is then passed to " { $link define-symbol } "."
-{ $subsection CREATE }
-{ $subsection CREATE-WORD }
+{ $subsections
+ CREATE
+ CREATE-WORD
+}
"Colon definitions are defined in a more elaborate way:"
-{ $subsection POSTPONE: : }
+{ $subsections POSTPONE: : }
"The " { $link POSTPONE: : } " word first calls " { $link CREATE } ", and then reads input until reaching " { $link POSTPONE: ; } " using a utility word:"
-{ $subsection parse-definition }
+{ $subsections parse-definition }
"The " { $link POSTPONE: ; } " word is just a delimiter; an unpaired occurrence throws a parse error:"
{ $see POSTPONE: ; }
"There are additional parsing words whose syntax is delimited by " { $link POSTPONE: ; } ", and they are all implemented by calling " { $link parse-definition } "." ;
"One example is the " { $link POSTPONE: USING: } " parsing word."
{ $see POSTPONE: USING: }
"It reads a list of vocabularies terminated by " { $link POSTPONE: ; } ". However, the vocabulary names do not name words, except by coincidence; so " { $link parse-until } " cannot be used here. Instead, a lower-level word is called:"
-{ $subsection parse-tokens } ;
+{ $subsections parse-tokens } ;
ARTICLE: "parsing-words" "Parsing words"
"The Factor parser follows a simple recursive-descent design. The parser reads successive tokens from the input; if the token identifies a number or an ordinary word, it is added to an accumulator vector. Otherwise if the token identifies a parsing word, the parsing word is executed immediately."
$nl
"Parsing words are defined using the defining word:"
-{ $subsection POSTPONE: SYNTAX: }
+{ $subsections POSTPONE: SYNTAX: }
"Parsing words have uppercase names by convention. Here is the simplest possible parsing word; it prints a greeting at parse time:"
{ $code "SYNTAX: HELLO \"Hello world\" print ;" }
"Parsing words must not pop or push items from the stack; however, they are permitted to access the accumulator vector supplied by the parser at the top of the stack. That is, parsing words must have stack effect " { $snippet "( accum -- accum )" } ", where " { $snippet "accum" } " is the accumulator vector supplied by the parser."
"Because of the stack restriction, parsing words cannot pass data to other words by leaving values on the stack; instead, use " { $link parsed } " to add the data to the parse tree so that it can be evaluated later."
$nl
"Parsing words cannot be called from the same source file where they are defined, because new definitions are only compiled at the end of the source file. An attempt to use a parsing word in its own source file raises an error:"
-{ $subsection staging-violation }
+{ $subsections staging-violation }
"Tools for implementing parsing words:"
-{ $subsection "reading-ahead" }
-{ $subsection "parsing-word-nest" }
-{ $subsection "defining-words" }
-{ $subsection "parsing-tokens" }
-{ $subsection "word-search-parsing" } ;
+{ $subsections
+ "reading-ahead"
+ "parsing-word-nest"
+ "defining-words"
+ "parsing-tokens"
+ "word-search-parsing"
+} ;
ARTICLE: "parser-files" "Parsing source files"
"The parser can run source files:"
-{ $subsection run-file }
-{ $subsection parse-file }
+{ $subsections
+ run-file
+ parse-file
+}
"The parser cross-references source files and definitions. This allows it to keep track of removed definitions, and prevent forward references and accidental redefinitions."
$nl
"While the above words are useful for one-off experiments, real programs should be written to use the vocabulary system instead; see " { $link "vocabs.loader" } "."
"This parser is a general facility for reading textual representations of objects and definitions. The parser is implemented in the " { $vocab-link "parser" } " and " { $vocab-link "syntax" } " vocabularies."
$nl
"This section concerns itself with usage and extension of the parser. Standard syntax is described in " { $link "syntax" } "."
-{ $subsection "parser-files" }
+{ $subsections "parser-files" }
"The parser can be extended."
-{ $subsection "parser-lexer" }
+{ $subsections "parser-lexer" }
"The parser can be invoked reflectively;"
-{ $subsection parse-stream }
+{ $subsections parse-stream }
{ $see-also "parsing-words" "definitions" "definition-checking" } ;
ABOUT: "parser"
"Concretely, a quotation is an immutable sequence of objects, some of which may be words, together with a block of machine code which may be executed to achieve the effect of evaluating the quotation. The machine code is generated by a fast non-optimizing quotation compiler which is always running and is transparent to the developer."
$nl
"Quotations form a class of objects, however in most cases, methods should dispatch on " { $link callable } " instead, so that " { $link curry } " and " { $link compose } " values can participate."
-{ $subsection quotation }
-{ $subsection quotation? }
+{ $subsections
+ quotation
+ quotation?
+}
"Quotations evaluate sequentially from beginning to end. Literals are pushed on the stack and words are executed. Details can be found in " { $link "evaluator" } "."
$nl
"Quotation literal syntax is documented in " { $link "syntax-quots" } "."
$nl
"Quotations implement the " { $link "sequence-protocol" } ", and existing sequences can be converted into quotations:"
-{ $subsection >quotation }
-{ $subsection 1quotation }
+{ $subsections
+ >quotation
+ 1quotation
+}
"Wrappers:"
-{ $subsection "wrappers" } ;
+{ $subsections "wrappers" } ;
ARTICLE: "wrappers" "Wrappers"
"Wrappers are used to push words on the data stack; they evaluate to the object being wrapped:"
-{ $subsection wrapper }
-{ $subsection literalize }
+{ $subsections
+ wrapper
+ literalize
+}
"Wrapper literal syntax is documented in " { $link "syntax-words" } "."
{ $example
"IN: scratchpad"
"String buffers implement the " { $link "sequence-protocol" } " and thus all " { $link "sequences" } " can be used with them. String buffers can be used to construct new strings by accumilating substrings and characters, however usually they are only used indirectly, since the sequence construction words are more convenient to use in most cases (see " { $link "namespaces-make" } ")."
$nl
"String buffers form a class of objects:"
-{ $subsection sbuf }
-{ $subsection sbuf? }
+{ $subsections
+ sbuf
+ sbuf?
+}
"Words for creating string buffers:"
-{ $subsection >sbuf }
-{ $subsection <sbuf> }
+{ $subsections
+ >sbuf
+ <sbuf>
+}
"If you don't care about initial capacity, a more elegant way to create a new string buffer is to write:"
{ $code "SBUF\" \" clone" } ;
all?
}
{ $heading "Related Articles" }
-{ $subsection "sequence-2combinators" }
-{ $subsection "sequence-3combinators" } ;
+{ $subsections
+ "sequence-2combinators"
+ "sequence-3combinators"
+} ;
ARTICLE: "sequence-2combinators" "Pair-wise sequence combinators"
"There is a set of combinators which traverse two sequences pairwise. If one sequence is shorter than the other, then only the prefix having the length of the minimum of the two is examined."
{ { $link filter } { $link filter-here } }
}
{ $heading "Related Articles" }
-{ $subsection "sequences-destructive-discussion" }
-{ $subsection "sequences-stacks" }
+{ $subsections
+ "sequences-destructive-discussion"
+ "sequences-stacks"
+}
{ $see-also set-nth push pop } ;
ARTICLE: "sequences-stacks" "Treating sequences as stacks"
"Set-theoretic operations on sequences are defined on the " { $vocab-link "sets" } " vocabulary. All of these operations use hashtables internally to achieve linear running time."
$nl
"Remove duplicates:"
-{ $subsection prune }
+{ $subsections prune }
"Test for duplicates:"
-{ $subsection all-unique? }
-{ $subsection duplicates }
+{ $subsections
+ all-unique?
+ duplicates
+}
"Set operations on sequences:"
-{ $subsection diff }
-{ $subsection intersect }
-{ $subsection union }
+{ $subsections
+ diff
+ intersect
+ union
+}
"Set-theoretic predicates:"
-{ $subsection intersects? }
-{ $subsection subset? }
-{ $subsection set= }
+{ $subsections
+ intersects?
+ subset?
+ set=
+}
"A word used to implement the above:"
-{ $subsection unique }
+{ $subsections unique }
"Adding elements to sets:"
-{ $subsection adjoin }
-{ $subsection conjoin }
-{ $subsection conjoin-at }
+{ $subsections
+ adjoin
+ conjoin
+ conjoin-at
+}
{ $see-also member? memq? any? all? "assocs-sets" } ;
ABOUT: "sets"
{ "Otherwise, a " { $link no-initial-value } " error is thrown. In this case, an initial value must be specified explicitly using " { $link initial: } "." }
}
"A word can be used to check if a class has an initial value or not:"
-{ $subsection initial-value } ;
+{ $subsections initial-value } ;
ARTICLE: "slots" "Low-level slot operations"
"The " { $vocab-link "slots" } " vocabulary contains words for introspecting the slots of an object. A " { $emphasis "slot" } " is a component of an object which can store a value."
{ $link "tuples" } " are composed entirely of slots, and instances of " { $link "builtin-classes" } " consist of slots together with intrinsic data."
$nl
"The " { $snippet "\"slots\"" } " word property of built-in and tuple classes holds an array of " { $emphasis "slot specifiers" } " describing the slot layout of each instance."
-{ $subsection slot-spec }
+{ $subsections slot-spec }
"The four words associated with a slot can be looked up in the " { $vocab-link "accessors" } " vocabulary:"
-{ $subsection reader-word }
-{ $subsection writer-word }
-{ $subsection setter-word }
-{ $subsection changer-word }
+{ $subsections
+ reader-word
+ writer-word
+ setter-word
+ changer-word
+}
"Looking up a slot by name:"
-{ $subsection slot-named }
+{ $subsections slot-named }
"Defining slots dynamically:"
-{ $subsection define-reader }
-{ $subsection define-writer }
-{ $subsection define-setter }
-{ $subsection define-changer }
-{ $subsection define-slot-methods }
-{ $subsection define-accessors }
+{ $subsections
+ define-reader
+ define-writer
+ define-setter
+ define-changer
+ define-slot-methods
+ define-accessors
+}
"Unsafe slot access:"
-{ $subsection slot }
-{ $subsection set-slot }
+{ $subsections
+ slot
+ set-slot
+}
{ $see-also "accessors" "mirrors" } ;
ABOUT: "slots"
"Words in the " { $vocab-link "source-files" } " vocabulary are used to keep track of loaded source files. This is used to implement " { $link "vocabs.refresh" } "."
$nl
"The source file database:"
-{ $subsection source-files }
+{ $subsections source-files }
"The class of source files:"
-{ $subsection source-file }
+{ $subsections source-file }
"Words intended for the parser:"
-{ $subsection record-checksum }
-{ $subsection record-definitions }
+{ $subsections
+ record-checksum
+ record-definitions
+}
"Removing a source file from the database:"
-{ $subsection forget-source }
+{ $subsections forget-source }
"Updating the database:"
-{ $subsection reset-checksums }
+{ $subsections reset-checksums }
"The " { $link pathname } " class implements the definition protocol by working with the corresponding source file; see " { $link "definitions" } "." ;
ABOUT: "source-files"
ARTICLE: "sequences-split" "Splitting sequences"
"Splitting sequences at occurrences of subsequences:"
-{ $subsection ?head }
-{ $subsection ?head-slice }
-{ $subsection ?tail }
-{ $subsection ?tail-slice }
-{ $subsection split1 }
-{ $subsection split1-slice }
-{ $subsection split1-last }
-{ $subsection split1-last-slice }
-{ $subsection split }
+{ $subsections
+ ?head
+ ?head-slice
+ ?tail
+ ?tail-slice
+ split1
+ split1-slice
+ split1-last
+ split1-last-slice
+ split
+}
"Splitting a string into lines:"
-{ $subsection string-lines } ;
+{ $subsections string-lines } ;
ABOUT: "sequences-split"
"Since strings implement the " { $link "sequence-protocol" } ", basic string manipulation can be performed with " { $link "sequences" } " in the " { $vocab-link "sequences" } " vocabulary. More text processing functionality can be found in vocabularies carrying the " { $link T{ vocab-tag { name "text" } } } " tag."
$nl
"Strings form a class:"
-{ $subsection string }
-{ $subsection string? }
+{ $subsections
+ string
+ string?
+}
"Creating new strings:"
-{ $subsection >string }
-{ $subsection <string> }
+{ $subsections
+ >string
+ <string>
+}
"Creating a string from a single character:"
-{ $subsection 1string } ;
+{ $subsections 1string } ;
ABOUT: "strings"
"While parsing words supporting arbitrary syntax can be defined, the default set is found in the " { $vocab-link "syntax" } " vocabulary and provides the basis for all further syntactic interaction with Factor." ;
ARTICLE: "syntax-comments" "Comments"
-{ $subsection POSTPONE: ! }
-{ $subsection POSTPONE: #! } ;
+{ $subsections
+ POSTPONE: !
+ POSTPONE: #!
+} ;
ARTICLE: "syntax-immediate" "Parse time evaluation"
"Code can be evaluated at parse time. This is a rarely-used feature; one use-case is " { $link "loading-libs" } ", where you want to execute some code before the words in a source file are compiled."
-{ $subsection POSTPONE: << }
-{ $subsection POSTPONE: >> } ;
+{ $subsections
+ POSTPONE: <<
+ POSTPONE: >>
+} ;
ARTICLE: "syntax-integers" "Integer syntax"
"The printed representation of an integer consists of a sequence of digits, optionally prefixed by a sign."
"2432902008176640000"
}
"Integers are entered in base 10 unless prefixed with a base change parsing word."
-{ $subsection POSTPONE: BIN: }
-{ $subsection POSTPONE: OCT: }
-{ $subsection POSTPONE: HEX: }
+{ $subsections
+ POSTPONE: BIN:
+ POSTPONE: OCT:
+ POSTPONE: HEX:
+}
"More information on integers can be found in " { $link "integers" } "." ;
ARTICLE: "syntax-ratios" "Ratio syntax"
{ "Not-a-number" { $snippet "0/0." } }
}
"A Not-a-number with an arbitrary payload can also be parsed in:"
-{ $subsection POSTPONE: NAN: }
+{ $subsections POSTPONE: NAN: }
"More information on floats can be found in " { $link "floats" } "." ;
ARTICLE: "syntax-complex-numbers" "Complex number syntax"
"C{ 1/2 1/3 } ! the complex number 1/2+1/3i"
"C{ 0 1 } ! the imaginary unit"
}
-{ $subsection POSTPONE: C{ }
+{ $subsections POSTPONE: C{ }
"More information on complex numbers can be found in " { $link "complex-numbers" } "." ;
ARTICLE: "syntax-numbers" "Number syntax"
"If a vocabulary lookup of a token fails, the parser attempts to parse it as a number."
-{ $subsection "syntax-integers" }
-{ $subsection "syntax-ratios" }
-{ $subsection "syntax-floats" }
-{ $subsection "syntax-complex-numbers" } ;
+{ $subsections
+ "syntax-integers"
+ "syntax-ratios"
+ "syntax-floats"
+ "syntax-complex-numbers"
+} ;
ARTICLE: "syntax-words" "Word syntax"
"A word occurring inside a quotation is executed when the quotation is called. Sometimes a word needs to be pushed on the data stack instead. The canonical use-case for this is passing the word to the " { $link execute } " combinator, or alternatively, reflectively accessing word properties (" { $link "word-props" } ")."
-{ $subsection POSTPONE: \ }
-{ $subsection POSTPONE: POSTPONE: }
+{ $subsections
+ POSTPONE: \
+ POSTPONE: POSTPONE:
+}
"The implementation of the " { $link POSTPONE: \ } " word is discussed in detail in " { $link "reading-ahead" } ". Words are documented in " { $link "words" } "." ;
ARTICLE: "escape" "Character escape codes"
ARTICLE: "syntax-strings" "Character and string syntax"
"Factor has no distinct character type, however Unicode character value integers can be read by specifying a literal character, or an escaped representation thereof."
-{ $subsection POSTPONE: CHAR: }
-{ $subsection POSTPONE: " }
-{ $subsection "escape" }
+{ $subsections
+ POSTPONE: CHAR:
+ POSTPONE: "
+ "escape"
+}
"Strings are documented in " { $link "strings" } "." ;
ARTICLE: "syntax-sbufs" "String buffer syntax"
-{ $subsection POSTPONE: SBUF" }
+{ $subsections POSTPONE: SBUF" }
"String buffers are documented in " { $link "sbufs" } "." ;
ARTICLE: "syntax-arrays" "Array syntax"
-{ $subsection POSTPONE: { }
-{ $subsection POSTPONE: } }
+{ $subsections
+ POSTPONE: {
+ POSTPONE: }
+}
"Arrays are documented in " { $link "arrays" } "." ;
ARTICLE: "syntax-vectors" "Vector syntax"
-{ $subsection POSTPONE: V{ }
+{ $subsections POSTPONE: V{ }
"Vectors are documented in " { $link "vectors" } "." ;
ARTICLE: "syntax-hashtables" "Hashtable syntax"
-{ $subsection POSTPONE: H{ }
+{ $subsections POSTPONE: H{ }
"Hashtables are documented in " { $link "hashtables" } "." ;
ARTICLE: "syntax-tuples" "Tuple syntax"
-{ $subsection POSTPONE: T{ }
+{ $subsections POSTPONE: T{ }
"Tuples are documented in " { $link "tuples" } "." ;
ARTICLE: "syntax-quots" "Quotation syntax"
-{ $subsection POSTPONE: [ }
-{ $subsection POSTPONE: ] }
+{ $subsections
+ POSTPONE: [
+ POSTPONE: ]
+}
"Quotations are documented in " { $link "quotations" } "." ;
ARTICLE: "syntax-byte-arrays" "Byte array syntax"
-{ $subsection POSTPONE: B{ }
+{ $subsections POSTPONE: B{ }
"Byte arrays are documented in " { $link "byte-arrays" } "." ;
ARTICLE: "syntax-pathnames" "Pathname syntax"
-{ $subsection POSTPONE: P" }
+{ $subsections POSTPONE: P" }
"Pathnames are documented in " { $link "io.pathnames" } "." ;
ARTICLE: "syntax-effects" "Stack effect syntax"
"Note that this is " { $emphasis "not" } " syntax to declare stack effects of words. This pushes an " { $link effect } " instance on the stack for reflection, for use with words such as " { $link define-declared } ", " { $link call-effect } " and " { $link execute-effect } "."
-{ $subsection POSTPONE: (( }
+{ $subsections POSTPONE: (( }
{ $see-also "effects" "inference" "tools.inference" } ;
ARTICLE: "syntax-literals" "Literals"
"If a quotation contains a literal object, the same literal object instance is used each time the quotation executes; that is, literals are “live”."
$nl
"Using mutable object literals in word definitions requires care, since if those objects are mutated, the actual word definition will be changed, which is in most cases not what you would expect. Literals should be " { $link clone } "d before being passed to word which may potentially mutate them."
-{ $subsection "syntax-numbers" }
-{ $subsection "syntax-words" }
-{ $subsection "syntax-quots" }
-{ $subsection "syntax-arrays" }
-{ $subsection "syntax-strings" }
-{ $subsection "syntax-byte-arrays" }
-{ $subsection "syntax-vectors" }
-{ $subsection "syntax-sbufs" }
-{ $subsection "syntax-hashtables" }
-{ $subsection "syntax-tuples" }
-{ $subsection "syntax-pathnames" }
-{ $subsection "syntax-effects" } ;
+{ $subsections
+ "syntax-numbers"
+ "syntax-words"
+ "syntax-quots"
+ "syntax-arrays"
+ "syntax-strings"
+ "syntax-byte-arrays"
+ "syntax-vectors"
+ "syntax-sbufs"
+ "syntax-hashtables"
+ "syntax-tuples"
+ "syntax-pathnames"
+ "syntax-effects"
+} ;
ARTICLE: "syntax" "Syntax"
"Factor has two main forms of syntax: " { $emphasis "definition" } " syntax and " { $emphasis "literal" } " syntax. Code is data, so the syntax for code is a special case of object literal syntax. This section documents literal syntax. Definition syntax is covered in " { $link "words" } ". Extending the parser is the main topic of " { $link "parser" } "."
-{ $subsection "parser-algorithm" }
-{ $subsection "word-search" }
-{ $subsection "top-level-forms" }
-{ $subsection "syntax-comments" }
-{ $subsection "syntax-literals" }
-{ $subsection "syntax-immediate" } ;
+{ $subsections
+ "parser-algorithm"
+ "word-search"
+ "top-level-forms"
+ "syntax-comments"
+ "syntax-literals"
+ "syntax-immediate"
+} ;
ABOUT: "syntax"
ABOUT: "system"
ARTICLE: "system" "System interface"
-{ $subsection "cpu" }
-{ $subsection "os" }
+{ $subsections
+ "cpu"
+ "os"
+}
"Getting the path to the Factor VM and image:"
-{ $subsection vm }
-{ $subsection image }
+{ $subsections
+ vm
+ image
+}
"Getting the current time:"
-{ $subsection micros }
-{ $subsection millis }
+{ $subsections
+ micros
+ millis
+}
"Exiting the Factor VM:"
-{ $subsection exit } ;
+{ $subsections exit } ;
ARTICLE: "cpu" "Processor detection"
"Processor detection:"
-{ $subsection cpu }
+{ $subsections cpu }
"Supported processors:"
-{ $subsection x86.32 }
-{ $subsection x86.64 }
-{ $subsection ppc }
-{ $subsection arm }
+{ $subsections
+ x86.32
+ x86.64
+ ppc
+ arm
+}
"Processor families:"
-{ $subsection x86 } ;
+{ $subsections x86 } ;
ARTICLE: "os" "Operating system detection"
"Operating system detection:"
-{ $subsection os }
+{ $subsections os }
"Supported operating systems:"
-{ $subsection freebsd }
-{ $subsection linux }
-{ $subsection macosx }
-{ $subsection openbsd }
-{ $subsection netbsd }
-{ $subsection solaris }
-{ $subsection wince }
-{ $subsection winnt }
+{ $subsections
+ freebsd
+ linux
+ macosx
+ openbsd
+ netbsd
+ solaris
+ wince
+ winnt
+}
"Operating system families:"
-{ $subsection bsd }
-{ $subsection unix }
-{ $subsection windows } ;
+{ $subsections
+ bsd
+ unix
+ windows
+} ;
HELP: cpu
"Vectors are intended to be used with " { $link "sequences-destructive" } ". Code that does not modify sequences in-place can use fixed-size arrays without loss of generality; see " { $link "arrays" } "."
$nl
"Vectors form a class of objects:"
-{ $subsection vector }
-{ $subsection vector? }
+{ $subsections
+ vector
+ vector?
+}
"Creating new vectors:"
-{ $subsection >vector }
-{ $subsection <vector> }
+{ $subsections
+ >vector
+ <vector>
+}
"Creating a vector from a single element:"
-{ $subsection 1vector }
+{ $subsections 1vector }
"If you don't care about initial capacity, an elegant way to create a new vector is to write:"
{ $code "V{ } clone" } ;
"The first way is to use an environment variable. Factor looks at the " { $snippet "FACTOR_ROOTS" } " environment variable for a list of " { $snippet ":" } "-separated paths (on Unix) or a list of " { $snippet ";" } "-separated paths (on Windows)."
$nl
"The second way is to create a configuration file. You can list additional vocabulary roots in a file that Factor reads at startup:"
-{ $subsection "factor-roots" }
+{ $subsections "factor-roots" }
"Finally, you can add vocabulary roots dynamically using a word:"
-{ $subsection add-vocab-root } ;
+{ $subsections add-vocab-root } ;
ARTICLE: "vocabs.roots" "Vocabulary roots"
"The vocabulary loader searches for it in one of the root directories:"
-{ $subsection vocab-roots }
+{ $subsections vocab-roots }
"The default set of roots includes the following directories in the Factor source directory:"
{ $list
{ { $snippet "core" } " - essential system vocabularies such as " { $vocab-link "parser" } " and " { $vocab-link "sequences" } ". The vocabularies in this root constitute the boot image; see " { $link "bootstrap.image" } "." }
{ { $snippet "work" } " - a root for vocabularies which are not intended to be contributed back to Factor." }
}
"You can store your own vocabularies in the " { $snippet "work" } " directory."
-{ $subsection "add-vocab-roots" } ;
+{ $subsections "add-vocab-roots" } ;
ARTICLE: "vocabs.loader" "Vocabulary loader"
"The vocabulary loader is defined in the " { $vocab-link "vocabs.loader" } " vocabulary."
$nl
"Vocabularies are searched for in vocabulary roots."
-{ $subsection "vocabs.roots" }
+{ $subsections "vocabs.roots" }
"Vocabulary names map directly to source files. A vocabulary named " { $snippet "foo.bar" } " must be defined in a " { $snippet "bar" } " directory nested inside a " { $snippet "foo" } " directory of a vocabulary root. Any level of vocabulary nesting is permitted."
$nl
"The vocabulary directory - " { $snippet "bar" } " in our example - contains a source file:"
{ { $snippet "foo/bar/tags.txt" } " - a whitespace-separated list of tags which classify the vocabulary. Consult " { $link "vocab-tags" } " for a list of existing tags you can re-use" }
}
"While " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " load vocabularies which have not been loaded before adding them to the search path, it is also possible to load a vocabulary without adding it to the search path:"
-{ $subsection require }
+{ $subsections require }
"Forcing a reload of a vocabulary, even if it has already been loaded:"
-{ $subsection reload }
+{ $subsections reload }
"Application vocabularies can define a main entry point, giving the user a convenient way to run the application:"
-{ $subsection POSTPONE: MAIN: }
-{ $subsection run }
-{ $subsection runnable-vocab }
+{ $subsections
+ POSTPONE: MAIN:
+ run
+ runnable-vocab
+}
{ $see-also "vocabularies" "parser-files" "source-files" } ;
ABOUT: "vocabs.loader"
"If " { $link auto-use? } " mode is on and only one vocabulary has a word with this name, the vocabulary is added to the search path and parsing continues."
$nl
"If any restarts were invoked, or if " { $link auto-use? } " is on, the parser will print the correct " { $link POSTPONE: USING: } " after parsing completes. This form can be copy and pasted back into the source file."
-{ $subsection auto-use? } ;
+{ $subsections auto-use? } ;
ARTICLE: "word-search-syntax" "Syntax to control word lookup"
"Parsing words which make all words in a vocabulary available:"
-{ $subsection POSTPONE: USE: }
-{ $subsection POSTPONE: USING: }
-{ $subsection POSTPONE: QUALIFIED: }
-{ $subsection POSTPONE: QUALIFIED-WITH: }
+{ $subsections
+ POSTPONE: USE:
+ POSTPONE: USING:
+ POSTPONE: QUALIFIED:
+ POSTPONE: QUALIFIED-WITH:
+}
"Parsing words which make a subset of all words in a vocabulary available:"
-{ $subsection POSTPONE: FROM: }
-{ $subsection POSTPONE: EXCLUDE: }
-{ $subsection POSTPONE: RENAME: }
+{ $subsections
+ POSTPONE: FROM:
+ POSTPONE: EXCLUDE:
+ POSTPONE: RENAME:
+}
"Removing vocabularies from the search path:"
-{ $subsection POSTPONE: UNUSE: }
+{ $subsections POSTPONE: UNUSE: }
"In the listener, the " { $vocab-link "scratchpad" } " is the default vocabulary for new word definitions. In source files, there is no default vocabulary. Defining words before declaring a vocabulary with " { $link POSTPONE: IN: } " results in an error."
-{ $subsection POSTPONE: IN: } ;
+{ $subsections POSTPONE: IN: } ;
ARTICLE: "word-search-semantics" "Resolution of ambiguous word names"
"There is a distinction between parsing words which perform “open” imports versus “closed” imports. An open import introduces all words from a vocabulary as identifiers, except possibly a finite set of exclusions. The " { $link POSTPONE: USE: } ", " { $link POSTPONE: USING: } " and " { $link POSTPONE: EXCLUDE: } " words perform open imports. A closed import only adds a fixed set of identifiers. The " { $link POSTPONE: FROM: } ", " { $link POSTPONE: RENAME: } ", " { $link POSTPONE: QUALIFIED: } " and " { $link POSTPONE: QUALIFIED-WITH: } " words perform closed imports. Note that the latter two are considered as closed imports, due to the fact that all identifiers they introduce are unambiguously qualified with a prefix. The " { $link POSTPONE: IN: } " parsing word also performs a closed import of the newly-created vocabulary."
$nl
"When the parser encounters a reference to a word, it first searches the closed imports, in order. Closed imports are searched from the most recent to least recent. If the word could not be found this way, it searches open imports. Unlike closed imports, with open imports, the order does not matter -- instead, if more than one vocabulary defines a word with this name, an error is thrown."
-{ $subsection ambiguous-use-error }
+{ $subsections ambiguous-use-error }
"To resolve the error, add a closed import, using " { $link POSTPONE: FROM: } ", " { $link POSTPONE: QUALIFIED: } " or " { $link POSTPONE: QUALIFIED-WITH: } ". The closed import will then take precedence over the open imports, and the ambiguity will be resolved."
$nl
"The rationale for this behavior is as follows. Open imports are named such because they are open to future extension; if a future version of a vocabulary that you use adds new words, those new words will now be in scope in your source file, too. To avoid problems, any references to the new word have to be resolved since the parser cannot safely determine which vocabulary was meant. This problem can be avoided entirely by using only closed imports, but this leads to additional verbosity."
ARTICLE: "word-search-private" "Private words"
"Words which only serve as implementation detail should be defined in a private code block. Words in a private code blocks get defined in a vocabulary whose name is the name of the current vocabulary suffixed with " { $snippet ".private" } ". Privacy is not enforced by the system; private words can be called from other vocabularies, and from the listener. However, this should be avoided where possible."
-{ $subsection POSTPONE: <PRIVATE }
-{ $subsection POSTPONE: PRIVATE> } ;
+{ $subsections
+ POSTPONE: <PRIVATE
+ POSTPONE: PRIVATE>
+} ;
ARTICLE: "word-search" "Parse-time word lookup"
"When the parser reads a word name, it resolves the word at parse-time, looking up the " { $link word } " instance in the right vocabulary and adding it to the parse tree."
$nl
"Initially, only words from the " { $vocab-link "syntax" } " vocabulary are available in source files. Since most files will use words in other vocabularies, they will need to make those words available using a set of parsing words."
-{ $subsection "word-search-syntax" }
-{ $subsection "word-search-private" }
-{ $subsection "word-search-semantics" }
-{ $subsection "word-search-errors" }
+{ $subsections
+ "word-search-syntax"
+ "word-search-private"
+ "word-search-semantics"
+ "word-search-errors"
+}
{ $see-also "words" } ;
ARTICLE: "word-search-parsing" "Word lookup in parsing words"
"The parsing words described in " { $link "word-search-syntax" } " are implemented using the below words, which you can also call from your own parsing words."
$nl
"The current state used for word search is stored in a " { $emphasis "manifest" } ":"
-{ $subsection manifest }
+{ $subsections manifest }
"Words for working with the current manifest:"
-{ $subsection use-vocab }
-{ $subsection unuse-vocab }
-{ $subsection add-qualified }
-{ $subsection add-words-from }
-{ $subsection add-words-excluding }
+{ $subsections
+ use-vocab
+ unuse-vocab
+ add-qualified
+ add-words-from
+ add-words-excluding
+}
"Words used to implement " { $link POSTPONE: IN: } ":"
-{ $subsection current-vocab }
-{ $subsection set-current-vocab }
+{ $subsections
+ current-vocab
+ set-current-vocab
+}
"Words used to implement " { $link "word-search-private" } ":"
-{ $subsection begin-private }
-{ $subsection end-private } ;
+{ $subsections
+ begin-private
+ end-private
+} ;
ABOUT: "word-search"
"A " { $emphasis "vocabulary" } " is a named collection of words. Vocabularies are defined in the " { $vocab-link "vocabs" } " vocabulary."
$nl
"Vocabularies are stored in a global hashtable:"
-{ $subsection dictionary }
+{ $subsections dictionary }
"Vocabularies form a class."
-{ $subsection vocab }
-{ $subsection vocab? }
+{ $subsections
+ vocab
+ vocab?
+}
"Various vocabulary words are overloaded to accept a " { $emphasis "vocabulary specifier" } ", which is a string naming the vocabulary, the " { $link vocab } " instance itself, or a " { $link vocab-link } ":"
-{ $subsection vocab-link }
-{ $subsection >vocab-link }
+{ $subsections
+ vocab-link
+ >vocab-link
+}
"Looking up vocabularies by name:"
-{ $subsection vocab }
+{ $subsections vocab }
"Accessors for various vocabulary attributes:"
-{ $subsection vocab-name }
-{ $subsection vocab-main }
-{ $subsection vocab-help }
+{ $subsections
+ vocab-name
+ vocab-main
+ vocab-help
+}
"Looking up existing vocabularies and creating new vocabularies:"
-{ $subsection vocab }
-{ $subsection child-vocabs }
-{ $subsection create-vocab }
+{ $subsections
+ vocab
+ child-vocabs
+ create-vocab
+}
"Getting words from a vocabulary:"
-{ $subsection vocab-words }
-{ $subsection words }
-{ $subsection all-words }
-{ $subsection words-named }
+{ $subsections
+ vocab-words
+ words
+ all-words
+ words-named
+}
"Removing a vocabulary:"
-{ $subsection forget-vocab }
+{ $subsections forget-vocab }
{ $see-also "words" "vocabs.loader" } ;
ABOUT: "vocabularies"
"There is a syntax for defining new names for existing words. This useful for C library bindings, for example in the Win32 API, where words need to be renamed for symmetry."
$nl
"Define a new word that aliases another word:"
-{ $subsection POSTPONE: ALIAS: }
+{ $subsections POSTPONE: ALIAS: }
"Define an alias at run-time:"
-{ $subsection define-alias } ;
+{ $subsections define-alias } ;
ABOUT: "words.alias"
"There is a syntax for defining words which push literals on the stack."
$nl
"Define a new word that pushes a literal on the stack:"
-{ $subsection POSTPONE: CONSTANT: }
+{ $subsections POSTPONE: CONSTANT: }
"Define an constant at run-time:"
-{ $subsection define-constant } ;
+{ $subsections define-constant } ;
ABOUT: "words.constant"
ARTICLE: "words.symbol" "Symbols"
"A symbol pushes itself on the stack when executed. By convention, symbols are used as variable names (" { $link "namespaces" } ")."
-{ $subsection symbol }
-{ $subsection symbol? }
+{ $subsections
+ symbol
+ symbol?
+}
"Defining symbols at parse time:"
-{ $subsection POSTPONE: SYMBOL: }
-{ $subsection POSTPONE: SYMBOLS: }
+{ $subsections
+ POSTPONE: SYMBOL:
+ POSTPONE: SYMBOLS:
+}
"Defining symbols at run time:"
-{ $subsection define-symbol }
+{ $subsections define-symbol }
"Symbols are just compound definitions in disguise. The following two lines are equivalent:"
{ $code
"SYMBOL: foo"
"Words whose names are known at parse time -- that is, most words making up your program -- can be referenced in source code by stating their name. However, the parser itself, and sometimes code you write, will need to create look up words dynamically."
$nl
"Parsing words add definitions to the current vocabulary. When a source file is being parsed, the current vocabulary is initially set to " { $vocab-link "scratchpad" } ". The current vocabulary may be changed with the " { $link POSTPONE: IN: } " parsing word (see " { $link "word-search" } ")."
-{ $subsection create }
-{ $subsection create-in }
-{ $subsection lookup } ;
+{ $subsections
+ create
+ create-in
+ lookup
+} ;
ARTICLE: "uninterned-words" "Uninterned words"
"A word that is not a member of any vocabulary is said to be " { $emphasis "uninterned" } "."
$nl
"There are several ways of creating an uninterned word:"
-{ $subsection <word> }
-{ $subsection gensym }
-{ $subsection define-temp } ;
+{ $subsections
+ <word>
+ gensym
+ define-temp
+} ;
ARTICLE: "colon-definition" "Colon definitions"
"Every word has an associated quotation definition that is called when the word is executed. A " { $emphasis "colon definition" } " is a word where this quotation is supplied directly by the user. This is the simplest and most common type of word definition."
$nl
"Defining words at parse time:"
-{ $subsection POSTPONE: : }
-{ $subsection POSTPONE: ; }
+{ $subsections
+ POSTPONE: :
+ POSTPONE: ;
+}
"Defining words at run time:"
-{ $subsection define }
-{ $subsection define-declared }
-{ $subsection define-inline }
+{ $subsections
+ define
+ define-declared
+ define-inline
+}
"Word definitions must declare their stack effect. See " { $link "effects" } "."
$nl
"All other types of word definitions, such as " { $link "words.symbol" } " and " { $link "generic" } ", are just special cases of the above." ;
ARTICLE: "primitives" "Primitives"
"Primitives are words defined in the Factor VM. They provide the essential low-level services to the rest of the system."
-{ $subsection primitive }
-{ $subsection primitive? } ;
+{ $subsections
+ primitive
+ primitive?
+} ;
ARTICLE: "deferred" "Deferred words and mutual recursion"
"Words cannot be referenced before they are defined; that is, source files must order definitions in a strictly bottom-up fashion. This is done to simplify the implementation, facilitate better parse time checking and remove some odd corner cases; it also encourages better coding style."
$nl
"Sometimes this restriction gets in the way, for example when defining mutually-recursive words; one way to get around this limitation is to make a forward definition."
-{ $subsection POSTPONE: DEFER: }
+{ $subsections POSTPONE: DEFER: }
"The class of deferred word definitions:"
-{ $subsection deferred }
-{ $subsection deferred? }
+{ $subsections
+ deferred
+ deferred?
+}
"Deferred words throw an error when called:"
-{ $subsection undefined }
+{ $subsections undefined }
"Deferred words are just compound definitions in disguise. The following two lines are equivalent:"
{ $code
"DEFER: foo"
"Compiler declarations are parsing words that set a word property in the most recently defined word. They appear after the final " { $link POSTPONE: ; } " of a word definition:"
{ $code ": cubed ( x -- y ) dup dup * * ; foldable" }
"Compiler declarations assert that the word follows a certain contract, enabling certain optimizations that are not valid in general."
-{ $subsection POSTPONE: inline }
-{ $subsection POSTPONE: foldable }
-{ $subsection POSTPONE: flushable }
-{ $subsection POSTPONE: recursive }
+{ $subsections
+ POSTPONE: inline
+ POSTPONE: foldable
+ POSTPONE: flushable
+ POSTPONE: recursive
+}
"It is entirely up to the programmer to ensure that the word satisfies the contract of a declaration. Furthermore, if a generic word is declared " { $link POSTPONE: foldable } " or " { $link POSTPONE: flushable } ", all methods must satisfy the contract. Unspecified behavior may result if a word does not follow the contract of one of its declarations."
{ $see-also "effects" } ;
ARTICLE: "word-props" "Word properties"
"Each word has a hashtable of properties."
-{ $subsection word-prop }
-{ $subsection set-word-prop }
+{ $subsections
+ word-prop
+ set-word-prop
+}
"The stack effect of the above two words is designed so that it is most convenient when " { $snippet "name" } " is a literal pushed on the stack right before executing this word."
$nl
"The following are some of the properties used by the library:"
"The " { $snippet "def" } " slot of a word holds a " { $link quotation } " instance that is called when the word is executed."
$nl
"An " { $emphasis "XT" } " (execution token) is the machine code address of a word:"
-{ $subsection word-xt } ;
+{ $subsections word-xt } ;
ARTICLE: "words.introspection" "Word introspection"
"Word introspection facilities and implementation details are found in the " { $vocab-link "words" } " vocabulary."
{ { $snippet "props" } "an assoc of word properties, including documentation and other meta-data" }
}
"Words are instances of a class."
-{ $subsection word }
-{ $subsection word? }
+{ $subsections
+ word
+ word?
+}
"Words implement the definition protocol; see " { $link "definitions" } "."
-{ $subsection "interned-words" }
-{ $subsection "uninterned-words" }
-{ $subsection "word-props" }
-{ $subsection "word.private" } ;
+{ $subsections
+ "interned-words"
+ "uninterned-words"
+ "word-props"
+ "word.private"
+} ;
ARTICLE: "words" "Words"
"Words are the Factor equivalent of functions or procedures; a word is essentially a named quotation."
"The latter is a more dynamic feature that can be used to implement code generation and such, and in fact parse time defining words are implemented in terms of run time defining words."
$nl
"Types of words:"
-{ $subsection "colon-definition" }
-{ $subsection "words.symbol" }
-{ $subsection "words.alias" }
-{ $subsection "words.constant" }
-{ $subsection "primitives" }
+{ $subsections
+ "colon-definition"
+ "words.symbol"
+ "words.alias"
+ "words.constant"
+ "primitives"
+}
"Advanced topics:"
-{ $subsection "deferred" }
-{ $subsection "declarations" }
-{ $subsection "words.introspection" }
+{ $subsections
+ "deferred"
+ "declarations"
+ "words.introspection"
+}
{ $see-also "vocabularies" "vocabs.loader" "definitions" "see" } ;
ABOUT: "words"
ARTICLE: "24-game" "The Game of 24"
"A classic math game, where one attempts to create 24, by applying "
"arithmetical operations and some shuffle words to a stack of 4 numbers. "
-{ $subsection play-game }
-{ $subsection 24-able }
-{ $subsection 24-able? }
-{ $subsection build-quad } ;
+{ $subsections
+ play-game
+ 24-able
+ 24-able?
+ build-quad
+} ;
ABOUT: "24-game"
ARTICLE: "implementation details" "How 4DNav is done"
"4DNav is build using :"
-{ $subsection "4DNav.camera" }
-{ $subsection "adsoda-main-page" }
+{ $subsections
+ "4DNav.camera"
+ "adsoda-main-page"
+}
;
ARTICLE: "Space file" "Create a new space file"
}
{ $heading "Links" }
-{ $subsection "Space file" }
-
-{ $subsection "TODO" }
-{ $subsection "implementation details" }
+{ $subsections
+ "Space file"
+ "TODO"
+ "implementation details"
+}
;
"halfspace touching-corners adjacent-faces" $nl\r
"touching-corners list of pointers to the corners which touch this face" $nl\r
"adjacent-faces list of pointers to the faces which touch this face"\r
-{ $subsection face }\r
-{ $subsection <face> }\r
+{ $subsections\r
+ face\r
+ <face>\r
+}\r
"test relative position"\r
-{ $subsection point-inside-or-on-face? } \r
-{ $subsection point-inside-face? }\r
+{ $subsections\r
+ point-inside-or-on-face?\r
+ point-inside-face?\r
+}\r
"handling face"\r
-{ $subsection flip-face }\r
-{ $subsection face-translate }\r
-{ $subsection face-transform }\r
+{ $subsections\r
+ flip-face\r
+ face-translate\r
+ face-transform\r
+}\r
\r
;\r
\r
"explanation of solids"\r
$nl\r
"link to functions"\r
-{ $subsection solid }\r
-{ $subsection <solid> }\r
+{ $subsections\r
+ solid\r
+ <solid>\r
+}\r
"test relative position"\r
-{ $subsection point-inside-solid? }\r
-{ $subsection point-inside-or-on-solid? }\r
+{ $subsections\r
+ point-inside-solid?\r
+ point-inside-or-on-solid?\r
+}\r
"playing with faces and solids"\r
-{ $subsection add-face }\r
-{ $subsection cut-solid }\r
-{ $subsection slice-solid }\r
+{ $subsections\r
+ add-face\r
+ cut-solid\r
+ slice-solid\r
+}\r
"solid handling"\r
-{ $subsection solid-project }\r
-{ $subsection solid-translate }\r
-{ $subsection solid-transform }\r
-{ $subsection subtract }\r
-\r
-{ $subsection get-silhouette }\r
-\r
-{ $subsection solid= }\r
-\r
-\r
+{ $subsections\r
+ solid-project\r
+ solid-translate\r
+ solid-transform\r
+ subtract\r
+ get-silhouette \r
+ solid=\r
+}\r
;\r
\r
HELP: solid \r
"link to functions"\r
$nl\r
"Defining words"\r
-{ $subsection space }\r
-{ $subsection <space> } \r
-{ $subsection suffix-solids }\r
-{ $subsection suffix-lights }\r
-{ $subsection clear-space-solids }\r
-{ $subsection describe-space }\r
+{ $subsections\r
+ space\r
+ <space>\r
+ suffix-solids \r
+ suffix-lights\r
+ clear-space-solids \r
+ describe-space\r
+}\r
\r
\r
"Handling space"\r
-{ $subsection space-ensure-solids }\r
-{ $subsection eliminate-empty-solids }\r
-{ $subsection space-transform }\r
-{ $subsection space-translate }\r
-{ $subsection remove-hidden-solids }\r
-{ $subsection space-project }\r
+{ $subsections\r
+ space-ensure-solids\r
+ eliminate-empty-solids\r
+ space-transform\r
+ space-translate\r
+ remove-hidden-solids\r
+ space-project\r
+}\r
\r
\r
;\r
"explanation of 3D rendering"\r
$nl\r
"link to functions"\r
-{ $subsection face->GL }\r
-{ $subsection solid->GL }\r
-{ $subsection space->GL }\r
+{ $subsections\r
+ face->GL\r
+ solid->GL\r
+ space->GL\r
+}\r
\r
;\r
\r
"full explanation on adsoda page at " { $url "http://www.flowerfire.com/ADSODA/" }\r
$nl\r
"Useful words are describe on the following pages: "\r
-{ $subsection "face-page" }\r
-{ $subsection "solid-page" }\r
-{ $subsection "space-page" }\r
-{ $subsection "light-page" }\r
-{ $subsection "3D-rendering-page" }\r
- ;\r
+{ $subsections\r
+ "face-page"\r
+ "solid-page"\r
+ "space-page"\r
+ "light-page"\r
+ "3D-rendering-page"\r
+} ;\r
\r
ABOUT: "adsoda-main-page"\r
"that use rates which do not change across platforms. The speed of the "
"computer should correlate with the smoothness of the animation, not "
"the speed of the animation!"
-{ $subsection animate }
-{ $subsection reset-progress }
-{ $subsection progress }
+{ $subsections
+ animate
+ reset-progress
+ progress
+}
! A little talk about when to use progress and when to use animate
{ $link progress } " specifically provides the length of time since "
{ $link reset-progress } " was called, and also calls "
ARTICLE: "assoc-heaps" "Associative heaps"
"The " { $vocab-link "assoc-heaps" } " vocabulary combines exists to synthesize data structures with better time properties than either of the two component data structures alone." $nl
"Associative heap constructor:"
-{ $subsection <assoc-heap> }
+{ $subsection
s <assoc-heap> }
"Unique heaps:"
-{ $subsection <unique-min-heap> }
-{ $subsection <unique-max-heap> } ;
+{ $subsections
+ <unique-min-heap>
+ <unique-max-heap>
+} ;
ABOUT: "assoc-heaps"
$nl
"Bloom filters cannot be resized and do not support removal."
$nl
-{ $subsection <bloom-filter> }
-{ $subsection bloom-filter-insert }
-{ $subsection bloom-filter-member? } ;
+{ $subsections
+ <bloom-filter>
+ bloom-filter-insert
+ bloom-filter-member?
+} ;
ABOUT: "bloom-filters"
ARTICLE: "combinators.tuple" "Tuple-constructing combinators"
"The " { $vocab-link "combinators.tuple" } " vocabulary provides dataflow combinators that construct " { $link tuple } " objects."
-{ $subsection make-tuple }
-{ $subsection 2make-tuple }
-{ $subsection 3make-tuple }
-{ $subsection nmake-tuple }
-;
+{ $subsections
+ make-tuple
+ 2make-tuple
+ 3make-tuple
+ nmake-tuple
+} ;
ABOUT: "combinators.tuple"
"The " { $vocab-link "crypto.passwd-md5" } " vocabulary can encode passwords for use in an MD5 shadow password file." $nl
"Encoding a password:"
-{ $subsection passwd-md5 }
+{ $subsections passwd-md5 }
"Parsing a shadowed password entry:"
-{ $subsection parse-shadow-password }
+{ $subsections parse-shadow-password }
"Authenticating against a shadowed password:"
-{ $subsection authenticate-password } ;
+{ $subsections authenticate-password } ;
ABOUT: "crypto.passwd-md5"
ARTICLE: "ctags" "Ctags file"
{ $emphasis "ctags" } " generates a index file of every factor word in ctags format as supported by vi and other editors. More information can be found at " { $url "http://en.wikipedia.org/wiki/Ctags" } "."
-{ $subsection ctags }
-{ $subsection ctags-write }
-{ $subsection ctag-strings }
-{ $subsection ctag }
-{ $subsection ctag-word }
-{ $subsection ctag-path }
-{ $subsection ctag-lineno } ;
+{ $subsections
+ ctags
+ ctags-write
+ ctag-strings
+ ctag
+ ctag-word
+ ctag-path
+ ctag-lineno
+} ;
HELP: ctags ( path -- )
{ $values { "path" "a pathname string" } }
ARTICLE: "etags" "Etags file"
{ $emphasis "Etags" } " generates a index file of every factor word in etags format as supported by emacs and other editors. More information can be found at " { $url "http://en.wikipedia.org/wiki/Ctags#Etags_2" } "."
-{ $subsection etags }
-{ $subsection etags-write }
-{ $subsection etag-strings }
-{ $subsection etag-header }
+{ $subsections
+ etags
+ etags-write
+ etag-strings
+ etag-header
+}
HELP: etags ( path -- )
{ $values { "path" string } }
\r
ARTICLE: "descriptive" "Descriptive errors"\r
"This vocabulary defines automatic descriptive errors. Using it, you can define a word which acts as normal, except when it throws an error, the error is wrapped in an instance of a class:"\r
-{ $subsection descriptive-error }\r
+{ $subsections descriptive-error }\r
"The wrapper contains the word itself, the input parameters, as well as the original error."\r
$nl\r
"To annotate an existing word with descriptive error checking:"\r
-{ $subsection make-descriptive }\r
+{ $subsections make-descriptive }\r
"To define words which throw descriptive errors, use the following words:"\r
-{ $subsection POSTPONE: DESCRIPTIVE: }\r
-{ $subsection POSTPONE: DESCRIPTIVE:: } ;\r
+{ $subsections\r
+ POSTPONE: DESCRIPTIVE:\r
+ POSTPONE: DESCRIPTIVE::\r
+} ;\r
\r
ABOUT: "descriptive"\r
ARTICLE: "env" "Accessing the environment via the assoc protocol"
"The " { $vocab-link "env" } " vocabulary defines a " { $link env } " word which implements the " { $link "assocs-protocol" } " over " { $link "environment" } "."
-{ $subsection env }
+{ $subsections env }
;
ABOUT: "env"
ARTICLE: "gpu.buffers" "Buffer objects"
"The " { $vocab-link "gpu.buffers" } " vocabulary provides words for creating, allocating, updating, and reading GPU data buffers."
-{ $subsection buffer }
-{ $subsection <buffer> }
-{ $subsection byte-array>buffer }
+{ $subsections
+ buffer
+ <buffer>
+ byte-array>buffer
+}
"Declaring buffer usage:"
-{ $subsection buffer-kind }
-{ $subsection buffer-upload-pattern }
-{ $subsection buffer-usage-pattern }
+{ $subsections
+ buffer-kind
+ buffer-upload-pattern
+ buffer-usage-pattern
+}
"Referencing buffer data:"
-{ $subsection buffer-ptr }
-{ $subsection buffer-range }
+{ $subsections
+ buffer-ptr
+ buffer-range
+}
"Manipulating buffer data:"
-{ $subsection allocate-buffer }
-{ $subsection update-buffer }
-{ $subsection read-buffer }
-{ $subsection copy-buffer }
-{ $subsection with-mapped-buffer }
+{ $subsections
+ allocate-buffer
+ update-buffer
+ read-buffer
+ copy-buffer
+ with-mapped-buffer
+}
;
ABOUT: "gpu.buffers"
ARTICLE: "gpu.framebuffers" "Framebuffer objects"
"The " { $vocab-link "gpu.framebuffers" } " vocabulary provides words for creating, allocating, and reading from framebuffer objects. Framebuffer objects are used as rendering targets; the " { $link system-framebuffer } " is supplied by the window system and contains the contents of the window on screen. User-created " { $link framebuffer } " objects can also be created to direct rendering output to offscreen " { $link texture } "s or " { $link renderbuffer } "s."
-{ $subsection system-framebuffer }
-{ $subsection framebuffer }
-{ $subsection renderbuffer }
+{ $subsections
+ system-framebuffer
+ framebuffer
+ renderbuffer
+}
"The contents of a framebuffer can be cleared to known values before rendering a scene:"
-{ $subsection clear-framebuffer }
-{ $subsection clear-framebuffer-attachment }
+{ $subsections
+ clear-framebuffer
+ clear-framebuffer-attachment
+}
"The image memory for a renderbuffer can be resized, or the full set of textures and renderbuffers attached to a framebuffer can be resized to the same dimensions together:"
-{ $subsection allocate-renderbuffer }
-{ $subsection resize-framebuffer }
+{ $subsections
+ allocate-renderbuffer
+ resize-framebuffer
+}
"Rectangular regions of framebuffers can be read into memory, read into GPU " { $link buffer } "s, and copied between framebuffers:"
-{ $subsection framebuffer-rect }
-{ $subsection attachment-ref }
-{ $subsection read-framebuffer }
-{ $subsection read-framebuffer-to }
-{ $subsection read-framebuffer-image }
-{ $subsection copy-framebuffer } ;
+{ $subsections
+ framebuffer-rect
+ attachment-ref
+ read-framebuffer
+ read-framebuffer-to
+ read-framebuffer-image
+ copy-framebuffer
+} ;
ABOUT: "gpu.framebuffers"
ARTICLE: "gpu" "Graphics context management"
"Preparing the GPU library:"
-{ $subsection init-gpu }
+{ $subsections init-gpu }
"Forcing execution of queued commands:"
-{ $subsection flush-gpu }
-{ $subsection finish-gpu }
+{ $subsections
+ flush-gpu
+ finish-gpu
+}
"Resetting OpenGL state:"
-{ $subsection reset-gpu } ;
+{ $subsections reset-gpu } ;
ARTICLE: "gpu-summary" "GPU-accelerated rendering"
"The " { $vocab-link "gpu" } " library is a set of vocabularies that work together to provide a convenient interface to creating, managing, and using GPU resources."
-{ $subsection "gpu" }
-{ $subsection "gpu.state" }
-{ $subsection "gpu.buffers" }
-{ $subsection "gpu.textures" }
-{ $subsection "gpu.framebuffers" }
-{ $subsection "gpu.shaders" }
-{ $subsection "gpu.render" }
+{ $subsections
+ "gpu"
+ "gpu.state"
+ "gpu.buffers"
+ "gpu.textures"
+ "gpu.framebuffers"
+ "gpu.shaders"
+ "gpu.render"
+}
"The library is built on top of the OpenGL API, but it aims to be complete enough that raw OpenGL calls are never needed. OpenGL 2.0 with the vertex array object extension (" { $snippet "GL_APPLE_vertex_array_object" } " or " { $snippet "GL_ARB_vertex_array_object" } ") is required. Some features require later OpenGL versions or additional extensions; these requirements are documented alongside individual words. To make full use of the library, an OpenGL 3.1 or later implementation is recommended." ;
ABOUT: "gpu-summary"
ARTICLE: "gpu.render" "Rendering"
"The " { $vocab-link "gpu.render" } " vocabulary contains words for organizing and submitting data to the GPU for rendering."
-{ $subsection render }
-{ $subsection render-set }
+{ $subsections
+ render
+ render-set
+}
{ $link uniform-tuple } "s provide Factor types for containing and submitting shader uniform parameters:"
-{ $subsection POSTPONE: UNIFORM-TUPLE: }
+{ $subsections POSTPONE: UNIFORM-TUPLE: }
;
ABOUT: "gpu.render"
ARTICLE: "gpu.shaders" "Shader objects"
"The " { $vocab-link "gpu.shaders" } " vocabulary supports defining, compiling, and linking " { $link shader } "s into " { $link program } "s that run on the GPU and control rendering."
-{ $subsection POSTPONE: GLSL-PROGRAM: }
-{ $subsection POSTPONE: GLSL-SHADER: }
-{ $subsection POSTPONE: GLSL-SHADER-FILE: }
+{ $subsections
+ POSTPONE: GLSL-PROGRAM:
+ POSTPONE: GLSL-SHADER:
+ POSTPONE: GLSL-SHADER-FILE:
+}
"A program must be instantiated for each graphics context it is used in:"
-{ $subsection <program-instance> }
+{ $subsection
s <program-instance> }
"Program instances can be updated on the fly, allowing for interactive development of shaders:"
-{ $subsection refresh-program }
+{ $subsections refresh-program }
"Render data inside GPU " { $link buffer } "s is organized into " { $link vertex-array } "s for consumption by shader code:"
-{ $subsection vertex-array }
-{ $subsection <vertex-array> }
-{ $subsection buffer>vertex-array }
-{ $subsection POSTPONE: VERTEX-FORMAT: } ;
+{ $subsections
+ vertex-array
+ <vertex-array>
+ buffer>vertex-array
+ POSTPONE: VERTEX-FORMAT:
+} ;
ABOUT: "gpu.shaders"
ARTICLE: "gpu.state" "GPU state"
"The " { $vocab-link "gpu.state" } " vocabulary provides words for querying and setting GPU state."
-{ $subsection set-gpu-state }
+{ $subsections set-gpu-state }
"The following state tuples are available:"
-{ $subsection viewport-state }
-{ $subsection scissor-state }
-{ $subsection multisample-state }
-{ $subsection stencil-state }
-{ $subsection depth-range-state }
-{ $subsection depth-state }
-{ $subsection blend-state }
-{ $subsection mask-state }
-{ $subsection triangle-cull-state }
-{ $subsection triangle-state }
-{ $subsection point-state }
-{ $subsection line-state } ;
+{ $subsections
+ viewport-state
+ scissor-state
+ multisample-state
+ stencil-state
+ depth-range-state
+ depth-state
+ blend-state
+ mask-state
+ triangle-cull-state
+ triangle-state
+ point-state
+ line-state
+} ;
ABOUT: "gpu.state"
HELP: texture
{ $class-description "Textures are typed, multidimensional arrays of GPU memory used for storing image data, lookup tables, and other kinds of multidimensional data for use with shader programs. They come in different types depending on dimensionality and intended usage:"
-{ $subsection texture-1d }
-{ $subsection texture-2d }
-{ $subsection texture-3d }
-{ $subsection texture-cube-map }
-{ $subsection texture-rectangle }
-{ $subsection texture-1d-array }
-{ $subsection texture-2d-array }
+{ $subsections
+ texture-1d
+ texture-2d
+ texture-3d
+ texture-cube-map
+ texture-rectangle
+ texture-1d-array
+ texture-2d-array
+}
"Textures are constructed using the corresponding " { $snippet "<constructor word>" } " for their type. The constructor sets the texture's " { $link component-order } ", " { $link component-type } ", and " { $link texture-parameters } ". Once created, memory for a texture can be allocated with " { $link allocate-texture } ", updated with " { $link update-texture } ", or retrieved with " { $link read-texture } "." } ;
HELP: texture-1d
ARTICLE: "gpu.textures" "Texture objects"
"The " { $vocab-link "gpu.textures" } " vocabulary provides words for creating, allocating, updating, and reading GPU texture objects."
-{ $subsection texture }
-{ $subsection allocate-texture }
-{ $subsection update-texture }
-{ $subsection read-texture }
+{ $subsections
+ texture
+ allocate-texture
+ update-texture
+ read-texture
+}
"Words are also provided to interface textures with the " { $vocab-link "images" } " library:"
-{ $subsection allocate-texture-image }
-{ $subsection update-texture-image }
-{ $subsection read-texture-image }
+{ $subsections
+ allocate-texture-image
+ update-texture-image
+ read-texture-image
+}
;
ABOUT: "gpu.textures"
"This library provide basic utilities for hashcash creation and validation."
$nl
"Creating stamps:"
-{ $subsection mint }
-{ $subsection mint* }
+{ $subsections
+ mint
+ mint*
+}
"Validation:"
-{ $subsection check-stamp }
+{ $subsections check-stamp }
"Hashcash tuple and constructor:"
-{ $subsection hashcash }
-{ $subsection <hashcash> }
+{ $subsections
+ hashcash
+ <hashcash>
+}
"Utilities:"
-{ $subsection salt } ;
+{ $subsections salt } ;
{ mint mint* <hashcash> check-stamp salt } related-words
\r
ARTICLE: "histogram" "Computing histograms"\r
"Counting elements in a sequence:"\r
-{ $subsection histogram }\r
-{ $subsection histogram* }\r
+{ $subsections\r
+ histogram\r
+ histogram*\r
+}\r
"Combinators for implementing histogram:"\r
-{ $subsection sequence>assoc }\r
-{ $subsection sequence>assoc* }\r
-{ $subsection sequence>hashtable } ;\r
+{ $subsections\r
+ sequence>assoc\r
+ sequence>assoc*\r
+ sequence>hashtable\r
+} ;\r
\r
ABOUT: "histogram"\r
"For the full list of HTML tags and attributes, consult the word list for the " { $vocab-link "html.elements" } " vocabulary. In addition to HTML tag and attribute words, a few utilities are provided."
$nl
"Writing unescaped HTML to " { $vocab-link "html.streams" } ":"
-{ $subsection write-html }
-{ $subsection print-html } ;
+{ $subsections
+ write-html
+ print-html
+} ;
ABOUT: "html.elements"
ARTICLE: "id3" "ID3 tags"
"The " { $vocab-link "id3" } " vocabulary contains words for parsing " { $emphasis "ID3" } " tags, which are textual fields storing an MP3's title, artist, and other metadata." $nl
"Parsing ID3 tags for a directory of MP3s, recursively:"
-{ $subsection parse-mp3-directory }
+{ $subsections parse-mp3-directory }
"Finding MP3 files recursively:"
-{ $subsection find-mp3s }
+{ $subsections find-mp3s }
"Parsing a sequence of MP3 pathnames:"
-{ $subsection mp3-paths>id3s }
+{ $subsections mp3-paths>id3s }
"Parsing an MP3 file's ID3 tags:"
-{ $subsection mp3>id3 }
+{ $subsections mp3>id3 }
"ID3v1 frame tag accessors:"
-{ $subsection album }
-{ $subsection artist }
-{ $subsection comment }
-{ $subsection genre }
-{ $subsection title }
-{ $subsection year }
+{ $subsections
+ album
+ artist
+ comment
+ genre
+ title
+ year
+}
"Access any frame tag:"
-{ $subsection find-id3-frame } ;
+{ $subsections find-id3-frame } ;
ABOUT: "id3"
ARTICLE: "infix" "Infix notation"
"The " { $vocab-link "infix" } " vocabulary implements support for infix notation in Factor source code."
-{ $subsection POSTPONE: [infix }
-{ $subsection POSTPONE: [infix| }
+{ $subsections
+ POSTPONE: [infix
+ POSTPONE: [infix|
+}
$nl
"The usual infix math operators are supported:"
{ $list
ARTICLE: "irc.client" "IRC Client"
"An IRC Client library"
{ $heading "IRC objects:" }
-{ $subsection irc-client }
+{ $subsections irc-client }
{ $heading "Chat objects:" }
-{ $subsection irc-server-chat }
-{ $subsection irc-channel-chat }
-{ $subsection irc-nick-chat }
+{ $subsections
+ irc-server-chat
+ irc-channel-chat
+ irc-nick-chat
+}
{ $heading "Setup objects:" }
-{ $subsection irc-profile }
+{ $subsections irc-profile }
{ $heading "Words:" }
-{ $subsection connect-irc }
-{ $subsection terminate-irc }
-{ $subsection attach-chat }
-{ $subsection detach-chat }
-{ $subsection hear }
-{ $subsection speak }
+{ $subsections
+ connect-irc
+ terminate-irc
+ attach-chat
+ detach-chat
+ hear
+ speak
+}
{ $heading "IRC messages" }
"Some of the RFC defined irc messages as objects:"
{ $table
{ $description "Divides a number by the number of weeks in a year." } ;
ARTICLE: "time-period-calculations" "Calculations over periods of time"
-{ $subsection monthly }
-{ $subsection semimonthly }
-{ $subsection biweekly }
-{ $subsection weekly }
-{ $subsection daily-360 }
-{ $subsection daily-365 } ;
+{ $subsections
+ monthly
+ semimonthly
+ biweekly
+ weekly
+ daily-360
+ daily-365
+} ;
ARTICLE: "math.finance" "Financial math"
"The " { $vocab-link "math.finance" } " vocabulary contains financial calculation words." $nl
"Calculating payroll over periods of time:"
-{ $subsection "time-period-calculations" } ;
+{ $subsections "time-period-calculations" } ;
ABOUT: "math.finance"
ARTICLE: "memory.piles" "Piles"
"A " { $link pile } " is a block of raw memory. Portions of its memory can be allocated from the beginning of the pile in constant time, and the pile can be emptied and its pointer reset to the beginning."
-{ $subsection <pile> }
-{ $subsection pile-alloc }
-{ $subsection <pile-c-array> }
-{ $subsection <pile-c-object> }
-{ $subsection pile-align }
-{ $subsection pile-empty }
+{ $subsections
+ <pile>
+ pile-alloc
+ <pile-c-array>
+ <pile-c-object>
+ pile-align
+ pile-empty
+}
"An example of the utility of piles is in video games. For example, the game Abuse was scripted with a Lisp dialect. In order to avoid stalls from traditional GC or heap-based allocators, the Abuse Lisp VM would allocate values from a preallocated pile over the course of a frame, and release the entire pile at the end of the frame." ;
ABOUT: "memory.piles"
ARTICLE: "memory.pools" "Pools"
"The " { $vocab-link "memory.pools" } " vocabulary provides " { $link pool } " objects which manage preallocated collections of objects."
-{ $subsection pool }
-{ $subsection POSTPONE: POOL: }
-{ $subsection new-from-pool }
-{ $subsection free-to-pool } ;
+{ $subsections
+ pool
+ POSTPONE: POOL:
+ new-from-pool
+ free-to-pool
+} ;
ABOUT: "memory.pools"
\r
ARTICLE: "models-history" "History models"\r
"History models record previous values."\r
-{ $subsection history }\r
-{ $subsection <history> }\r
+{ $subsections\r
+ history\r
+ <history>\r
+}\r
"Recording history:"\r
-{ $subsection add-history }\r
+{ $subsections add-history }\r
"Navigating the history:"\r
-{ $subsection go-back }\r
-{ $subsection go-forward } ;\r
+{ $subsections\r
+ go-back\r
+ go-forward\r
+} ;\r
\r
ABOUT: "models-history"\r
{ $url "http://groups.google.com/group/comp.lang.scheme/msg/9f0d61da01540816" } "."
" See this blog entry for more details:"
{ $url "http://www.bluishcoder.co.nz/2006/03/factor-partial-continuation-updates.html" }
-{ $subsection breset }
-{ $subsection bshift } ;
+{ $subsections
+ breset
+ bshift
+} ;
ABOUT: "partial-continuations"
ARTICLE: "quadtrees" "Quadtrees"
"The " { $snippet "quadtrees" } " vocabulary implements the quadtree data structure in Factor."
-{ $subsection <quadtree> }
+{ $subsections <quadtree> }
"Quadtrees follow the " { $link "assocs-protocol" } " for insertion, deletion, and querying of exact points, using two-dimensional vectors as keys. Additional words are provided for spatial queries and pruning the tree structure:"
-{ $subsection in-rect }
-{ $subsection prune-quadtree }
+{ $subsections
+ in-rect
+ prune-quadtree
+}
"The following words are provided to help write quadtree algorithms:"
-{ $subsection descend }
-{ $subsection each-quadrant }
-{ $subsection map-quadrant }
+{ $subsections
+ descend
+ each-quadrant
+ map-quadrant
+}
"Quadtrees can be used to \"swizzle\" a sequence to improve the locality of spatial data in memory:"
-{ $subsection swizzle } ;
+{ $subsections swizzle } ;
ABOUT: "quadtrees"
ARTICLE: "qw" "Quoted words"
"The " { $vocab-link "qw" } " vocabulary offers a shorthand syntax for arrays-of-strings literals." $nl
"Construct an array of strings:"
-{ $subsection POSTPONE: qw{ } ;
+{ $subsections POSTPONE: qw{ } ;
ABOUT: "qw"
ARTICLE: "sequences-merge" "Merging sequences"
"When multiple sequences are merged into one sequence, the new sequence takes an element from each input sequence in turn. For example, if we merge " { $code "{ 1 2 3 }" } "and" { $code "{ \"a\" \"b\" \"c\" }" } "we get:" { $code "{ 1 \"a\" 2 \"b\" 3 \"c\" }" } "."
-{ $subsection merge }
-{ $subsection 2merge }
-{ $subsection 3merge }
-{ $subsection <merged> }
-{ $subsection <2merged> }
-{ $subsection <3merged> } ;
+{ $subsections
+ merge
+ 2merge
+ 3merge
+ <merged>
+ <2merged>
+ <3merged>
+} ;
ABOUT: "sequences-merge"
ARTICLE: "sequences.n-based" "N-based sequences"
"The " { $vocab-link "sequences.n-based" } " vocabulary provides a sequence adaptor that allows a sequence to be treated as an assoc with non-zero-based keys."
-{ $subsection n-based-assoc }
-{ $subsection <n-based-assoc> }
+{ $subsections
+ n-based-assoc
+ <n-based-assoc>
+}
;
ABOUT: "sequences.n-based"
ARTICLE: "sequences.product" "Product sequences"
"The " { $vocab-link "sequences.product" } " vocabulary provides a virtual sequence and combinators for manipulating the cartesian product of a set of sequences."
-{ $subsection product-sequence }
-{ $subsection <product-sequence> }
-{ $subsection product-map }
-{ $subsection product-each } ;
+{ $subsections
+ product-sequence
+ <product-sequence>
+ product-map
+ product-each
+} ;
ABOUT: "sequences.product"
ARTICLE: "spider" "Spider"
"The " { $vocab-link "spider" } " vocabulary implements a simple web spider for retrieving sets of webpages."
-{ $subsection "spider-tutorial" }
+{ $subsections "spider-tutorial" }
"Creating a new spider:"
-{ $subsection <spider> }
+{ $subsections <spider> }
"Running the spider:"
-{ $subsection run-spider } ;
+{ $subsections run-spider } ;
ABOUT: "spider"
ARTICLE: "trees.avl" "AVL trees"
"This is a library for AVL trees, with logarithmic time storage and retrieval operations. These trees conform to the assoc protocol."
-{ $subsection avl }
-{ $subsection <avl> }
-{ $subsection >avl }
-{ $subsection POSTPONE: AVL{ } ;
+{ $subsections
+ avl
+ <avl>
+ >avl
+ POSTPONE: AVL{
+} ;
ABOUT: "trees.avl"
ARTICLE: "trees.splay" "Splay trees"
"This is a library for splay trees. Splay trees have amortized average-case logarithmic time storage and retrieval operations, and better complexity on more skewed lookup distributions, though in bad situations they can degrade to linear time, resembling a linked list. These trees conform to the assoc protocol."
-{ $subsection splay }
-{ $subsection <splay> }
-{ $subsection >splay }
-{ $subsection POSTPONE: SPLAY{ } ;
+{ $subsections
+ splay
+ <splay>
+ >splay
+ POSTPONE: SPLAY{
+} ;
ABOUT: "trees.splay"
ARTICLE: "trees" "Binary search trees"
"This is a library for unbalanced binary search trees. It is not intended to be used directly in most situations but rather as a base class for new trees, because performance can degrade to linear time storage/retrieval by the number of keys. These binary search trees conform to the assoc protocol."
-{ $subsection tree }
-{ $subsection <tree> }
-{ $subsection >tree }
-{ $subsection POSTPONE: TREE{ } ;
+{ $subsections
+ tree
+ <tree>
+ >tree
+ POSTPONE: TREE{
+} ;
ABOUT: "trees"
ARTICLE: "ui.gadgets.lists" "List gadgets"
"The " { $vocab-link "ui.gadgets.lists" } " vocabulary implements lists, which displays a list of presentations (see " { $link "ui.gadgets.presentations" } ")."
-{ $subsection list }
-{ $subsection <list> }
-{ $subsection list-value } ;
+{ $subsections
+ list
+ <list>
+ list-value
+} ;
ABOUT: "ui.gadgets.lists"
ARTICLE: "variants" "Algebraic data types"
"The " { $vocab-link "variants" } " vocabulary provides syntax and combinators for defining and manipulating algebraic data types."
-{ $subsection POSTPONE: VARIANT: }
-{ $subsection variant-class }
-{ $subsection match } ;
+{ $subsections
+ POSTPONE: VARIANT:
+ variant-class
+ match
+} ;
ABOUT: "variants"
ARTICLE: "furnace.auth.user-admin" "Furnace user administration tool"
"The " { $vocab-link "webapps.user-admin" } " vocabulary implements a web application for adding, removing and editing users in authentication realms that use " { $link "furnace.auth.providers.db" } "."
-{ $subsection <user-admin> }
+{ $subsections <user-admin> }
"Access to the web app itself is protected, and only users having an administrative capability can access it:"
-{ $subsection can-administer-users? }
+{ $subsections can-administer-users? }
"To make an existing user an administrator, call the following word in a " { $link with-db } " scope:"
-{ $subsection make-admin } ;
+{ $subsections make-admin } ;
"automatic marshalling and unmarshalling of C function arguments, return values, and output parameters."
{ $subheading "Important words" }
-"Wrap an alien:" { $subsection alien-wrapper }
-"Wrap a struct:" { $subsection struct-wrapper }
-"Get the marshaller for a C type:" { $subsection marshaller }
-"Get the unmarshaller for a C type:" { $subsection unmarshaller }
-"Get the unmarshaller for an output parameter:" { $subsection out-arg-unmarshaller }
-"Get the unmarshaller for a struct field:" { $subsection struct-field-unmarshaller }
+"Wrap an alien:" { $subsections alien-wrapper }
+"Wrap a struct:" { $subsections struct-wrapper }
+"Get the marshaller for a C type:" { $subsections marshaller }
+"Get the unmarshaller for a C type:" { $subsections unmarshaller }
+"Get the unmarshaller for an output parameter:" { $subsections out-arg-unmarshaller }
+"Get the unmarshaller for a struct field:" { $subsections struct-field-unmarshaller }
$nl
"Other marshalling and unmarshalling words in this vocabulary are not intended to be "
"invoked directly."
"Most marshalling words allow non false c-ptrs to pass through unchanged."
{ $subheading "Primitive marshallers" }
-{ $subsection marshall-primitive } "for marshalling primitive values."
-{ $subsection marshall-int* }
+{ $subsections marshall-primitive } "for marshalling primitive values."
+{ $subsections marshall-int* }
"marshalls a number or sequence of numbers. If argument is a sequence, returns a pointer "
"to a C array, otherwise returns a pointer to a single value."
-{ $subsection marshall-int** }
+{ $subsections marshall-int** }
"marshalls a 1D or 2D array of numbers. Returns an array of pointers to arrays."
{ $subheading "Primitive unmarshallers" }
{ $snippet "unmarshall-<prim>*" } " and " { $snippet "unmarshall-<prim>*-free" }
" for all values of " { $snippet "<prim>" } " in " { $link primitive-types } "."
-{ $subsection unmarshall-int* }
+{ $subsections unmarshall-int* }
"unmarshalls a pointer to primitive. Returns a number. "
"Assumes the pointer is not an array (if it is, only the first value is returned). "
"C functions that return arrays are not handled correctly by " { $snippet "alien.marshall" }
" and must be unmarshalled by hand."
-{ $subsection unmarshall-int*-free }
+{ $subsections unmarshall-int*-free }
"unmarshalls a pointer to primitive, and then frees the pointer."
$nl
"Primitive values require no unmarshalling. The factor FFI already does this."
ARTICLE: "graph-protocol" "Graph protocol"
"All graphs must be instances of the graph mixin:"
-{ $subsection graph }
+{ $subsections graph }
"All graphs must implement a method on the following generic word:"
-{ $subsection vertices }
+{ $subsections vertices }
"At least one of the following two generic words must have a method; the " { $link graph } " mixin has default definitions which are mutually recursive:"
-{ $subsection adjlist }
-{ $subsection adj? }
+{ $subsections
+ adjlist
+ adj?
+}
"All mutable graphs must implement a method on the following generic word:"
-{ $subsection add-blank-vertex }
+{ $subsections add-blank-vertex }
"All mutable undirected graphs must implement a method on the following generic word:"
-{ $subsection add-edge }
+{ $subsections add-edge }
"Mutable directed graphs should not implement the above word, as it has a default definition defined in terms of the following generic word:"
-{ $subsection add-edge* }
+{ $subsections add-edge* }
"The following two words have default definitions, but are available as generics to allow implementations to optimize them:"
-{ $subsection num-vertices }
-{ $subsection num-edges } ;
+{ $subsections
+ num-vertices
+ num-edges
+} ;
HELP: graph
{ $class-description "A mixin class whose instances are graphs. Custom implementations of the graph protocol should be declared as instances of this mixin for all graph functionality to work correctly:"
ARTICLE: "derivatives" "The Derivative Toolkit"
"A toolkit for computing the derivative of functions."
-{ $subsection derivative }
-{ $subsection derivative-func }
-{ $subsection (derivative) } ;
+{ $subsections
+ derivative
+ derivative-func
+ (derivative)
+} ;
ABOUT: "derivatives"
ARTICLE: "ui.offscreen" "Offscreen UI rendering"
"The " { $vocab-link "ui.offscreen" } " provides words for rendering gadgets to an offscreen buffer so that bitmaps can be made from their contents."
-{ $subsection offscreen-world }
+{ $subsections offscreen-world }
"Opening gadgets offscreen:"
-{ $subsection open-offscreen }
-{ $subsection close-offscreen }
-{ $subsection do-offscreen }
+{ $subsections
+ open-offscreen
+ close-offscreen
+ do-offscreen
+}
"Creating bitmaps from offscreen buffers:"
-{ $subsection offscreen-world>bitmap }
-{ $subsection gadget>bitmap } ;
+{ $subsections
+ offscreen-world>bitmap
+ gadget>bitmap
+} ;
ABOUT: "ui.offscreen"
projects / factor.git / commitdiff