HELP: basic-block
{ $class-description
"Factors representation of a basic block in the Call Flow Graph (CFG). A basic block is a sequence of instructions that always are executed sequentially and doesn't contain any internal branching. It has the following slots:"
- { $table
+ { $slots
{
- { $slot "number" }
+ "number"
{ "The blocks sequence number. Generated by calling " { $link number-blocks } "." }
}
{
- { $slot "successors" }
+ "successors"
{ "A " { $link vector } " of basic blocks that may be executed directly after this block. Most blocks only have one successor but a block that checks where an if-condition should branch to would have two for example." }
}
{
- { $slot "predecessors" }
+ "predecessors"
{ "The opposite of successors -- a " { $link vector } " of basic blocks from which the execution may have arrived into this block." }
}
{
- { $slot "instructions" }
+ "instructions"
{ "A " { $link vector } " of " { $link insn } " tuples which form the instructions of the basic block." }
}
{
- { $slot "kill-block?" }
+ "kill-block?"
{ "The first and the last block in a cfg and all blocks containing " { $link ##call } " instructions are kill blocks. Kill blocks can't be optimized so they are omitted from certain optimization steps." }
}
{
- { $slot "height" }
+ "height"
"Block's height as a " { $link height-state } ". What the heights of the block was at entry and how much they were increased in the block."
}
{
- { $slot "replaces" }
+ "replaces"
{ "Used by " { $vocab-link "compiler.cfg.stacks.local" } " for local stack analysis." }
}
{
- { $slot "peeks" }
+ "peeks"
{ "Used by " { $vocab-link "compiler.cfg.stacks.local" } " for local stack analysis." }
}
{
- { $slot "kills" }
+ "kills"
{ "Used by " { $vocab-link "compiler.cfg.stacks.local" } " for local stack analysis." }
}
}
HELP: cfg
{ $class-description
"Call flow graph. It has the following slots:"
- { $table
- { { $slot "entry" } { "Root " { $link basic-block } " of the graph." } }
- { { $slot "word" } { "The " { $link word } " the cfg is produced from." } }
- { { $slot "post-order" } { "The blocks of the cfg in a post order traversal " { $link sequence } "." } }
- { { $slot "stack-frame" } { { $link stack-frame } " of the cfg." } }
- { { $slot "frame-pointer?" } { "Whether the cfg needs a frame pointer. Only cfgs generated for " { $link #alien-callback } " nodes does need it. If the slot is " { $link t } ", then the frame pointer register (" { $link RBP } " on x86.64 archs) will not be clobbered by register allocation. See " { $vocab-link "compiler.cfg.linear-scan" } " for details." } }
+ { $slots
+ { "entry" { "Root " { $link basic-block } " of the graph." } }
+ { "word" { "The " { $link word } " the cfg is produced from." } }
+ { "post-order" { "The blocks of the cfg in a post order traversal " { $link sequence } "." } }
+ { "stack-frame" { { $link stack-frame } " of the cfg." } }
+ { "frame-pointer?" { "Whether the cfg needs a frame pointer. Only cfgs generated for " { $link #alien-callback } " nodes does need it. If the slot is " { $link t } ", then the frame pointer register (" { $link RBP } " on x86.64 archs) will not be clobbered by register allocation. See " { $vocab-link "compiler.cfg.linear-scan" } " for details." } }
}
}
{ $see-also <cfg> post-order } ;
HELP: ##alien-invoke
{ $class-description
"An instruction for calling a function in a dynamically linked library. It has the following slots:"
- { $table
+ { $slots
{
- { $slot "dead-outputs" }
+ "dead-outputs"
{ "A sequence of return values from the function that the compiler.cfg.dce pass has figured out are not used." }
}
{
- { $slot "reg-inputs" }
+ "reg-inputs"
{ "Registers to use for the arguments to the function call. Each sequence item is a 3-tuple consisting of a " { $link spill-slot } ", register representation and a register. When the function is called, the parameter is copied from the spill slot to the given register." }
}
{
- { $slot "stack-inputs" }
+ "stack-inputs"
{ "Stack slots used for the arguments to the function call." }
}
{
- { $slot "reg-outputs" }
+ "reg-outputs"
{ "If the called function returns a value, then this slot is a one-element sequence containing a 3-tuple describing which register is used for the return value." }
}
- { { $slot "symbols" } { "Name of the function to call." } }
- { { $slot "dll" } { "A dll handle or " { $link f } "." } }
+ { "symbols" { "Name of the function to call." } }
+ { "dll" { "A dll handle or " { $link f } "." } }
{
- { $slot "gc-map" }
+ "gc-map"
{
"If the invoked C function calls Factor code which triggers a GC, then a "
{ $link gc-map }
HELP: ##alien-indirect
{ $class-description
"An instruction representing an indirect alien call. The first item on the datastack is a pointer to the function to call and the parameters follows. It has the following slots:"
- { $table
- { { $slot "src" } { "Spill slot containing the function pointer." } }
- { { $slot "reg-outputs" } { "Sequence of output values passed in registers." } }
+ { $slots
+ { "src" { "Spill slot containing the function pointer." } }
+ { "reg-outputs" { "Sequence of output values passed in registers." } }
}
}
{ $see-also alien-indirect %alien-indirect } ;
HELP: ##allot
{ $class-description
"An instruction for allocating memory in the nursery. Usually the instruction is preceded by " { $link ##check-nursery-branch } " which checks that there is enough room in the nursery to allocate. It has the following slots:"
- { $table
- { { $slot "dst" } { "Register to put the pointer to the memory in." } }
- { { $slot "size" } { "Number of bytes to allocate." } }
- { { $slot "class-of" } { "Class of object to allocate, e.g " { $link tuple } " or " { $link array } "." } }
- { { $slot "temp" } { "Temporary register to clobber." } }
+ { $slots
+ { "dst" { "Register to put the pointer to the memory in." } }
+ { "size" { "Number of bytes to allocate." } }
+ { "class-of" { "Class of object to allocate, e.g " { $link tuple } " or " { $link array } "." } }
+ { "temp" { "Temporary register to clobber." } }
}
} ;
HELP: ##call
{ $class-description
"An instruction for calling a Factor word."
- { $table
- { { $slot "word" } { "The word called." } }
+ { $slots
+ { "word" { "The word called." } }
}
} ;
"Instruction that inserts a conditional branch to a " { $link basic-block } " that garbage collects the nursery. The " { $vocab-link "compiler.cfg.gc-checks" } " vocab goes through each block in the " { $link cfg } " and checks if it allocates memory. If it does, then this instruction is inserted in the cfg before that block and checks if there is enough available space in the nursery. If it isn't, then a basic block containing code for garbage collecting the nursery is executed."
$nl
"It has the following slots:"
- { $table
- { { $slot "size" } { "Number of bytes the next block in the cfg will allocate." } }
- { { $slot "cc" } { "A comparison symbol." } }
- { { $slot "temp1" } { "First register that will be clobbered." } }
- { { $slot "temp2" } { "Second register that will be clobbered." } }
+ { $slots
+ { "size" { "Number of bytes the next block in the cfg will allocate." } }
+ { "cc" { "A comparison symbol." } }
+ { "temp1" { "First register that will be clobbered." } }
+ { "temp2" { "Second register that will be clobbered." } }
}
}
{ $see-also %check-nursery-branch } ;
HELP: ##compare-float-ordered-branch
{ $class-description
"It has the following slots:"
- { $table
- { { $slot "cc" } { "Comparison symbol." } }
+ { $slots
+ { "cc" { "Comparison symbol." } }
}
} ;
HELP: ##copy
{ $class-description "Instruction that copies a value from one register to another of the same type. For example, you can copy between two gprs or two simd registers but not across. It has the following slots:"
- { $table
- { { $slot "rep" } { "Value representation. Both the source and destination register must have the same representation." } }
+ { $slots
+ { "rep" { "Value representation. Both the source and destination register must have the same representation." } }
}
} ;
HELP: ##jump
{ $class-description
"An uncondiation jump instruction. It has the following slots:"
- { $table
- { { $slot "word" } { "Word whose address the instruction is jumping to." } }
+ { $slots
+ { "word" { "Word whose address the instruction is jumping to." } }
}
"Note that the optimizer is sometimes able to optimize away a " { $link ##call } " and " { $link ##return } " pair into one ##jump instruction."
} ;
HELP: ##load-reference
{ $class-description
"An instruction for loading a pointer to an object into a register. It has the following slots:"
- { $table
- { { $slot "dst" } { "Register to load the pointer into." } }
- { { $slot "obj" } { "A Factor object." } }
+ { $slots
+ { "dst" { "Register to load the pointer into." } }
+ { "obj" { "A Factor object." } }
}
} ;
HELP: ##local-allot
{ $class-description
"An instruction for allocating memory in the words own stack frame. It's mostly used for receiving data from alien calls. It has the following slots:"
- { $table
- { { $slot "dst" } { "Register into which a pointer to the stack allocated memory is put." } }
- { { $slot "size" } { "Number of bytes to allocate." } }
- { { $slot "offset" } { } }
+ { $slots
+ { "dst" { "Register into which a pointer to the stack allocated memory is put." } }
+ { "size" { "Number of bytes to allocate." } }
+ { "offset" { } }
}
}
{ $see-also ##allot } ;
HELP: ##parallel-copy
{ $class-description "An instruction for performing multiple copies. It allows for optimizations or (or prunings) if more than one source or destination vreg is the same. They are transformed into " { $link ##copy } " instructions in " { $link destruct-ssa } ". It has the following slots:"
- { $table
- { { $slot "values" } { "An assoc mapping source vregs to destinations." } }
+ { $slots
+ { "values" { "An assoc mapping source vregs to destinations." } }
}
} ;
HELP: ##phi
{ $class-description
"A special kind of instruction used to mark control flow. It is inserted by the " { $vocab-link "compiler.cfg.ssa.construction" } " vocab. It has the following slots:"
- { $table
- { { $slot "inputs" } { "An assoc containing as keys the blocks/block numbers where the vreg was defined and as values the vreg. Why care about the blocks?" } }
- { { $slot "dst" } { "A merged vreg for the value." } }
+ { $slots
+ { "inputs" { "An assoc containing as keys the blocks/block numbers where the vreg was defined and as values the vreg. Why care about the blocks?" } }
+ { "dst" { "A merged vreg for the value." } }
}
} ;
HELP: ##set-slot
{ $class-description
"An instruction for the non-primitive, non-immediate variant of " { $link set-slot } ". It has the following slots:"
- { $table
- { { $slot "src" } { "Object to put in the slot." } }
- { { $slot "obj" } { "Object to set the slot on." } }
- { { $slot "slot" } { "Slot index." } }
- { { $slot "tag" } { "Type tag for obj." } }
+ { $slots
+ { "src" { "Object to put in the slot." } }
+ { "obj" { "Object to set the slot on." } }
+ { "slot" { "Slot index." } }
+ { "tag" { "Type tag for obj." } }
}
} ;
HELP: ##set-slot-imm
{ $class-description
"An instruction for what? It has the following slots:"
- { $table
- { { $slot "src" } { "Register containing the value to put in the slot." } }
- { { $slot "obj" } { "Register containing the object to set the slot on.." } }
- { { $slot "slot" } { "Slot index." } }
- { { $slot "tag" } { "Type tag for obj." } }
+ { $slots
+ { "src" { "Register containing the value to put in the slot." } }
+ { "obj" { "Register containing the object to set the slot on.." } }
+ { "slot" { "Slot index." } }
+ { "tag" { "Type tag for obj." } }
}
}
{ $see-also ##set-slot %set-slot-imm } ;
HELP: ##shuffle-vector-imm
{ $class-description "Shuffles the vector in a SSE register according to the given shuffle pattern. It is used to extract a given element of the vector."
- { $table
- { { $slot "dst" } { "Destination register to shuffle the vector to." } }
- { { $slot "src" } { "Source register." } }
- { { $slot "shuffle" } { "Shuffling pattern." } }
+ { $slots
+ { "dst" { "Destination register to shuffle the vector to." } }
+ { "src" { "Source register." } }
+ { "shuffle" { "Shuffling pattern." } }
}
}
{ $see-also %shuffle-vector-imm } ;
HELP: ##slot-imm
{ $class-description
"Instruction for reading a slot with a given index from an object."
- { $table
- { { $slot "dst" } { "Register to read the slot value into." } }
- { { $slot "obj" } { "Register containing the object with the slot." } }
- { { $slot "slot" } { "Slot index." } }
- { { $slot "tag" } { "Type tag for obj." } }
+ { $slots
+ { "dst" { "Register to read the slot value into." } }
+ { "obj" { "Register containing the object with the slot." } }
+ { "slot" { "Slot index." } }
+ { "tag" { "Type tag for obj." } }
}
} { $see-also %slot-imm } ;
HELP: ##spill
{ $class-description "Instruction that copies a value from a register to a " { $link spill-slot } "."
- { $table
- { { $slot "rep" } { "Register representation which is necessary when spilling SIMD registers." } }
+ { $slots
+ { "rep" { "Register representation which is necessary when spilling SIMD registers." } }
}
} { $see-also ##reload } ;
HELP: ##store-memory-imm
{ $class-description "Instruction that copies an 8 byte value from a XMM register to a memory location addressed by a normal register. This instruction is often turned into a cheaper " { $link ##store-memory } " instruction in the " { $link value-numbering } " pass."
- { $table
- { { $slot "base" } { "Vreg that contains the base address." } }
+ { $slots
+ { "base" { "Vreg that contains the base address." } }
{
- { $slot "offset" }
+ "offset"
{ "Offset in bytes from the address to where the data should be written." }
}
- { { $slot "rep" } { "Value representation in the vector register." } }
- { { $slot "src" } { "Vreg that contains the item to set." } }
+ { "rep" { "Value representation in the vector register." } }
+ { "src" { "Vreg that contains the item to set." } }
}
}
{ $see-also %store-memory-imm } ;
HELP: ##unbox-any-c-ptr
{ $class-description "Instruction that unboxes a pointer in a register so that it can be fed to a C FFI function. For example, if 'src' points to a " { $link byte-array } ", then in 'dst' will be put a pointer to the first byte of that byte array."
- { $table
- { { $slot "dst" } { "Destination register." } }
- { { $slot "src" } { "Source register." } }
+ { $slots
+ { "dst" { "Destination register." } }
+ { "src" { "Source register." } }
}
}
{ $see-also %unbox-any-c-ptr } ;
HELP: ##vector>scalar
{ $class-description
"This instruction is very similar to " { $link ##copy } "."
- { $table
- { { $slot "dst" } { "destination vreg" } }
- { { $slot "src" } { "source vreg" } }
- { { $slot "rep" } { "representation for the source vreg" } }
+ { $slots
+ { "dst" { "destination vreg" } }
+ { "src" { "source vreg" } }
+ { "rep" { "representation for the source vreg" } }
}
}
{ $notes "The two vregs must not necessarily share the same representation." }
HELP: ##vm-field
{ $class-description "Instruction for loading a pointer to a vm field."
- { $table
- { { $slot "dst" } { "Register to load the field into." } }
- { { $slot "offset" } { "Offset of the field relative to the vm address." } }
+ { $slots
+ { "dst" { "Register to load the field into." } }
+ { "offset" { "Offset of the field relative to the vm address." } }
}
}
{ $see-also %vm-field } ;
HELP: ##write-barrier
{ $class-description
"An instruction for inserting a write barrier. This instruction is almost always inserted after a " { $link ##set-slot } " instruction. If the container object is in an older generation than the item inserted, this instruction guarantees that the item will not be garbage collected. It has the following slots:"
- { $table
- { { $slot "src" } { "Object to which the writer barrier refers." } }
- { { $slot "slot" } { "Slot index of the object." } }
- { { $slot "scale" } { "No idea." } }
- { { $slot "tag" } { "Type tag for obj." } }
- { { $slot "temp1" } { "First temporary register to clobber." } }
- { { $slot "temp2" } { "Second temporary register to clobber." } }
+ { $slots
+ { "src" { "Object to which the writer barrier refers." } }
+ { "slot" { "Slot index of the object." } }
+ { "scale" { "No idea." } }
+ { "tag" { "Type tag for obj." } }
+ { "temp1" { "First temporary register to clobber." } }
+ { "temp2" { "Second temporary register to clobber." } }
}
} ;
HELP: gc-map
{ $class-description "A tuple that holds info necessary for a gc cycle to figure out where the gc root pointers are. It has the following slots:"
- { $table
+ { $slots
{
- { $slot "gc-roots" }
+ "gc-roots"
{ { $link sequence } " of vregs or spill-slots" }
}
{
- { $slot "derived-roots" }
+ "derived-roots"
{ "An " { $link assoc } " of pairs of vregs or spill slots." } }
}
"The 'gc-roots' and 'derived-roots' slots are initially vreg integers referencing objects that are live during the gc call and needs to be spilled so that they can be traced. In the " { $link emit-gc-map-insn } " word in " { $vocab-link "compiler.cfg.linear-scan.assignment" } " they are converted to spill slots which the collector is able to trace."
HELP: live-interval-state
{ $class-description "A class encoding the \"liveness\" of a virtual register. It has the following slots:"
- { $table
- { { $slot "vreg" } { "The vreg this live interval state is bound to." } }
+ { $slots
+ { "vreg" { "The vreg this live interval state is bound to." } }
{
- { $slot "reg" }
+ "reg"
{ "The allocated register, set in the " { $link allocate-registers } " step." }
}
{
- { $slot "spill-rep" }
+ "spill-rep"
{ { $link representation } " the vreg will have when it is spilled." }
}
{
- { $slot "spill-to" }
+ "spill-to"
{ { $link spill-slot } " to use for spilling, if it needs to be spilled." }
}
{
- { $slot "ranges" }
+ "ranges"
{ "Inclusive ranges where the live interval is live. This is because the [start,end] interval can have gaps." }
}
{
- { $slot "uses" } { "sequence of insn# numbers which reference insructions that use the register in the live interval." }
+ "uses"
+ { "sequence of insn# numbers which reference insructions that use the register in the live interval." }
}
}
}
HELP: sync-point
{ $class-description "A location where all live registers have to be spilled. For example when garbage collection is run or an alien ffi call is invoked. Figuring out where in the " { $link cfg } " the sync points are is done in the " { $link compute-live-intervals } " step. The tuple has the following slots:"
- { $table
- { { $slot "n" } { "Set from an instructions sequence number." } }
- { { $slot "keep-dst?" } { "Boolean that determines whether registers are spilled around this sync point." } }
+ { $slots
+ { "n" { "Set from an instructions sequence number." } }
+ { "keep-dst?" { "Boolean that determines whether registers are spilled around this sync point." } }
}
}
{ $see-also cfg>sync-points clobber-insn hairy-clobber-insn insn } ;
HELP: vreg-info
{ $class-description
"Slots:"
- { $table
- { { $slot "vreg" } { "The vreg the vreg-info is the info for." } }
- { { $slot "bb" } { "The " { $link basic-block } " in which the vreg is defined." } }
+ { $slots
+ { "vreg" { "The vreg the vreg-info is the info for." } }
+ { "bb" { "The " { $link basic-block } " in which the vreg is defined." } }
}
} ;
{ "One final " { $link cell } " of padding." }
}
"The stack frame is also aligned to a 16 byte boundary. It has the following slots:"
- { $table
- { { $slot "total-size" } { "Total size of the stack frame." } }
- { { $slot "params" } { "Reserved parameter space." } }
- { { $slot "allot-area-base" } { "Base offset of the allocation area." } }
- { { $slot "allot-area-size" } { "Number of bytes requires for the allocation area." } }
- { { $slot "allot-area-align" } { "This slot is always at least " { $link cell } " bytes." } }
- { { $slot "spill-area-base" } { "Base offset for the spill area." } }
- { { $slot "spill-area-size" } { "Number of bytes requires for all spill slots." } }
- { { $slot "spill-area-align" } { "This slot is always at least " { $link cell } " bytes." } }
+ { $slots
+ { "total-size" { "Total size of the stack frame." } }
+ { "params" { "Reserved parameter space." } }
+ { "allot-area-base" { "Base offset of the allocation area." } }
+ { "allot-area-size" { "Number of bytes requires for the allocation area." } }
+ { "allot-area-align" { "This slot is always at least " { $link cell } " bytes." } }
+ { "spill-area-base" { "Base offset for the spill area." } }
+ { "spill-area-size" { "Number of bytes requires for all spill slots." } }
+ { "spill-area-align" { "This slot is always at least " { $link cell } " bytes." } }
}
}
{ $see-also align-stack } ;
HELP: height-state
{ $description "A tuple which keeps track of the stacks heights and increments of a " { $link basic-block } " during local analysis. The idea is that if the stack change instructions are tracked, then multiple changes can be folded into one. It has the following slots:"
- { $table
+ { $slots
{
- { $slot "ds-begin" }
+ "ds-begin"
"Datastack height at the beginning of the block."
}
{
- { $slot "rs-begin" }
+ "rs-begin"
"Retainstack height at the beginning of the block."
}
{
- { $slot "ds-inc" }
+ "ds-inc"
"Datastack change during the block."
}
{
- { $slot "rs-inc" }
+ "rs-inc"
"Retainstack change during the block."
}
}
ARTICLE: "compiler.cfg.stacks.local" "Local stack analysis"
"For each " { $link basic-block } " in the " { $link cfg } ", local stack analysis is performed. The analysis is started right after the block is created with " { $link begin-local-analysis } " and finished with " { $link end-local-analysis } ", when the construction of the block is complete. During the analysis, three sets containing stack locations are built:"
-{ $list
- { { $slot "peeks" } " all stack locations that the block reads before writing" }
- { { $slot "replaces" } " all stack locations that the block writes" }
- { { $slot "kills" } " all stack locations which become unavailable after the block ends because of the stack height being decremented. For example, if the block contains " { $link drop } ", then D: 0 will be contained in kills because that stack location will not be live anymore." }
+{ $slots
+ { "peeks" { " all stack locations that the block reads before writing" } }
+ { "replaces" { " all stack locations that the block writes" } }
+ { "kills" { " all stack locations which become unavailable after the block ends because of the stack height being decremented. For example, if the block contains " { $link drop } ", then D: 0 will be contained in kills because that stack location will not be live anymore." } }
}
"This is done while constructing the CFG. These sets are then used by the " { $link end-stack-analysis } " word to emit optimal sequences of " { $link ##peek } " and " { $link ##replace } " instructions to the cfg."
$nl
{ $description "Gets the value info for the given SSA value. If none is found then a null empty interval is returned." } ;
HELP: value-info<=
-{ $values { "info1" value-info } { "info2" value-info } { "?" boolean } }
+{ $values { "info1" value-info-state } { "info2" value-info-state } { "?" boolean } }
{ $description "Checks if the first value info is equal to, or smaller than the second one." } ;
HELP: value-info-state
{ $class-description "Represents constraints the compiler knows about the input and output variables to an SSA tree node. It has the following slots:"
- { $table
- { { $slot "class" } { "Class of values the variable can take." } }
- { { $slot "interval" } { "Range of values the variable can take." } }
- { { $slot "literal" } { "Literal value, if present." } }
- { { $slot "literal?" } { "Whether the value of the variable is known at compile-time or not." } }
- { { $slot "slots" } { "If the value is a literal tuple or fixed length type, then slots is a " { $link sequence } " of " { $link value-info-state } " encoding what is known about its slots at compile-time." } }
+ { $slots
+ { "class" { "Class of values the variable can take." } }
+ { "interval" { "Range of values the variable can take." } }
+ { "literal" { "Literal value, if present." } }
+ { "literal?" { "Whether the value of the variable is known at compile-time or not." } }
+ { "slots" { "If the value is a literal tuple or fixed length type, then slots is a " { $link sequence } " of " { $link value-info-state } " encoding what is known about its slots at compile-time." } }
}
"Don't mutate value infos you receive, always construct new ones. We don't declare the slots read-only to allow cloning followed by writing, and to simplify constructors."
} ;
HELP: #call
{ $class-description "SSA tree node that calls a word. It has the following slots:"
- { $table
- { { $slot "word" } { "The " { $link word } " to call." } }
- { { $slot "in-d" } { "Sequence of input variables to the call. The items are ordered from top to bottom of the stack." } }
- { { $slot "out-d" } { "Output values of the call." } }
- { { $slot "method" } { "If the called word is generic and inlined here, then 'method' contains the inlined " { $link quotation } "." } }
- { { $slot "body" } { "If the called word is generic and inlined, then 'body' is a sequence of SSA nodes built from the inlined method." } }
- { { $slot "info" } { "If the called word is generic and inlined, then the info slot contains an assoc of value infos for the body of the inlined generic. It is set during the propagation pass of the optimizer." } }
+ { $slots
+ { "word" { "The " { $link word } " to call." } }
+ { "in-d" { "Sequence of input variables to the call. The items are ordered from top to bottom of the stack." } }
+ { "out-d" { "Output values of the call." } }
+ { "method" { "If the called word is generic and inlined here, then 'method' contains the inlined " { $link quotation } "." } }
+ { "body" { "If the called word is generic and inlined, then 'body' is a sequence of SSA nodes built from the inlined method." } }
+ { "info" { "If the called word is generic and inlined, then the info slot contains an assoc of value infos for the body of the inlined generic. It is set during the propagation pass of the optimizer." } }
}
} ;
HELP: #declare
{ $class-description "SSA tree node emitted when " { $link declare } " declarations are encountered. It has the following slots:"
- { $table
- { { $slot "declaration" } { { $link assoc } " that maps values to the types they are declared as." } }
+ { $slots
+ { "declaration" { { $link assoc } " that maps values to the types they are declared as." } }
}
} ;
HELP: #if
{ $class-description "SSA tree node that implements conditional branching. It has the following slots:"
- { $table
- { { $slot "children" }
+ { $slots
+ { "children"
{ "A two item " { $link sequence } ". The first item holds the instructions executed if the condition is true and the second those that are executed if it is not true." }
}
}
HELP: #introduce
{ $class-description "SSA tree node that puts an input value from the \"outside\" on the stack. It is used to \"introduce\" data stack parameter whenever they are needed. It has the following slots:"
- { $table
- { { $slot "out-d" } { "Array of values of the parameters being introduced." } }
+ { $slots
+ { "out-d" { "Array of values of the parameters being introduced." } }
}
} ;
HELP: #push
{ $class-description "SSA tree node that puts a literal value on the stack. It has the following slots:"
- { $table
- { { $slot "out-d" } { "A one item array containing the " { $link <value> } " of the literal being pushed." } }
+ { $slots
+ { "out-d" { "A one item array containing the " { $link <value> } " of the literal being pushed." } }
}
}
{ $notes "A " { $link quotation } " is also a literal." } ;
HELP: #recursive
{ $class-description "Instruction which encodes a loop. It has the following slots:"
- { $table
- { { $slot "child" } { "A sequence of nodes representing the body of the loop." } }
- { { $slot "loop?" } { "If " { $link t } ", the recursion is implemented using a jump, otherwise as a call back to the word." } }
+ { $slots
+ { "child" { "A sequence of nodes representing the body of the loop." } }
+ { "loop?" { "If " { $link t } ", the recursion is implemented using a jump, otherwise as a call back to the word." } }
}
}
{ $see-also inline-recursive-word } ;
HELP: #shuffle
{ $class-description "SSA tree node that represents a stack shuffling operation such as " { $link swap } ". It has the following slots:"
- { $table
- { { $slot "mapping" } { "An " { $link assoc } " that shows how the shuffle output values (the keys) correspond to their inputs (the values)." } }
+ { $slots
+ { "mapping" { "An " { $link assoc } " that shows how the shuffle output values (the keys) correspond to their inputs (the values)." } }
}
} ;
HELP: indirect
{ $class-description "Tuple that represents an indirect addressing operand. It has the following slots:"
- { $table
- { { $slot "index" } { "Register for the index value. It must not be " { $link ESP } " or " { $link RSP } "." } }
- { { $slot "displacement" } { "An integer offset." } }
+ { $slots
+ { "index" { "Register for the index value. It must not be " { $link ESP } " or " { $link RSP } "." } }
+ { "displacement" { "An integer offset." } }
}
} ;
ARTICLE: "furnace.actions.config" "Furnace action configuration"
"Actions have the following slots:"
-{ $table
- { { $slot "rest" } { "A parameter name to map the rest of the URL, after the action name, to. If this is not set, then navigating to a URL where the action is not the last path component will return to the client with an error. A more general facility can be found in the " { $vocab-link "http.server.rewrite" } " vocabulary." } }
- { { $slot "init" } { "A quotation called at the beginning of a GET or HEAD request. Typically this quotation configures " { $link "html.forms" } " and parses query parameters." } }
- { { $slot "authorize" } { "A quotation called at the beginning of a GET, HEAD or POST request. In GET requests, it is called after the " { $slot "init" } " quotation; in POST requests, it is called after the " { $slot "validate" } " quotation. By convention, this quotation performs custom authorization checks which depend on query parameters or POST parameters." } }
- { { $slot "display" } { "A quotation called after the " { $slot "init" } " quotation in a GET request. This quotation must return an HTTP " { $link response } "." } }
- { { $slot "validate" } { "A quotation called at the beginning of a POST request to validate POST parameters." } }
- { { $slot "submit" } { "A quotation called after the " { $slot "validate" } " quotation in a POST request. This quotation must return an HTTP " { $link response } "." } }
- { { $slot "replace" } { "A quotation called after the " { $slot "validate" } " quotation in a PUT request. This quotation must return an HTTP " { $link response } "." } }
- { { $slot "update" } { "A quotation called after the " { $slot "validate" } " quotation in a PATCH request. This quotation must return an HTTP " { $link response } "." } }
+{ $slots
+ { "rest" { "A parameter name to map the rest of the URL, after the action name, to. If this is not set, then navigating to a URL where the action is not the last path component will return to the client with an error. A more general facility can be found in the " { $vocab-link "http.server.rewrite" } " vocabulary." } }
+ { "init" { "A quotation called at the beginning of a GET or HEAD request. Typically this quotation configures " { $link "html.forms" } " and parses query parameters." } }
+ { "authorize" { "A quotation called at the beginning of a GET, HEAD or POST request. In GET requests, it is called after the " { $slot "init" } " quotation; in POST requests, it is called after the " { $slot "validate" } " quotation. By convention, this quotation performs custom authorization checks which depend on query parameters or POST parameters." } }
+ { "display" { "A quotation called after the " { $slot "init" } " quotation in a GET request. This quotation must return an HTTP " { $link response } "." } }
+ { "validate" { "A quotation called at the beginning of a POST request to validate POST parameters." } }
+ { "submit" { "A quotation called after the " { $slot "validate" } " quotation in a POST request. This quotation must return an HTTP " { $link response } "." } }
+ { "replace" { "A quotation called after the " { $slot "validate" } " quotation in a PUT request. This quotation must return an HTTP " { $link response } "." } }
+ { "update" { "A quotation called after the " { $slot "validate" } " quotation in a PATCH request. This quotation must return an HTTP " { $link response } "." } }
}
"At least one of the " { $slot "display" } " and " { $slot "submit" } " slots must be set, otherwise the action will be useless." ;
<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" }
- { { $slot "capabilities" } { "A sequence of capabilities; see " { $link "furnace.auth.capabilities" } } }
+{ $slots
+ { "description" "A string identifying the protected resource for user interface purposes" }
+ { "capabilities" { "A sequence of capabilities; see " { $link "furnace.auth.capabilities" } } }
} ;
ARTICLE: "furnace.auth.realm-config" "Authentication realm configuration"
"Instances of subclasses of " { $link realm } " have the following slots which may be set:"
-{ $table
- { { $slot "name" } "A string identifying the realm for user interface purposes" }
- { { $slot "users" } { "An authentication provider (see " { $link "furnace.auth.providers" } "). By default, the " { $link users-in-db } " provider is used." } }
- { { $slot "checksum" } { "An implementation of the checksum protocol used for verifying passwords (see " { $link "checksums" } "). The " { $link sha-256 } " checksum is used by default." } }
- { { $slot "secure" } { "A boolean, that when set to a true value, forces the client to access the authentication realm via HTTPS. An attempt to access the realm via HTTP results in a redirect to the corresponding HTTPS URL. On by default." } }
+{ $slots
+ { "name" "A string identifying the realm for user interface purposes" }
+ { "users" { "An authentication provider (see " { $link "furnace.auth.providers" } "). By default, the " { $link users-in-db } " provider is used." } }
+ { "checksum" { "An implementation of the checksum protocol used for verifying passwords (see " { $link "checksums" } "). The " { $link sha-256 } " checksum is used by default." } }
+ { "secure" { "A boolean, that when set to a true value, forces the client to access the authentication realm via HTTPS. An attempt to access the realm via HTTP results in a redirect to the corresponding HTTPS URL. On by default." } }
} ;
ARTICLE: "furnace.auth.providers" "Authentication providers"
HELP: couchdb-auth-provider
{
$class-description "Implements the furnace authentication protocol for CouchDB."
- { $table
- { { $slot "base-url" } { "The base URL for the CouchDB database, e.g. http://foo.org:5984/mydatabase" } }
- { { $slot "username-view" } { "A URL for a view which emits usernames as keys and user documents as values, "
+ { $slots
+ { "base-url" { "The base URL for the CouchDB database, e.g. http://foo.org:5984/mydatabase" } }
+ { "username-view" { "A URL for a view which emits usernames as keys and user documents as values, "
"i.e. something like emit(doc.username, doc). The URL should be relative"
" to base-url (e.g. \"_design/my_views/_view/by_username\")."
" The view is not defined automatically by the library." } }
- { { $slot "prefix" } { "In order to ensure the uniqueness of user IDs and email addresses,"
+ { "prefix" { "In order to ensure the uniqueness of user IDs and email addresses,"
" the library creates documents in the database with ids corresponding to these values. "
"These ids "
"are prefixed by the string given as the value for this slot. Ideally, you should guarantee that no other "
"documents in the database can have ids with this prefix. However, "
"the worst that can happen is for someone to falsely be told that a username "
"is taken when it is in fact free." } }
- { { $slot "field-map" } { "An assoc taking " { $link user } " slot names to CouchDB document "
+ { "field-map" { "An assoc taking " { $link user } " slot names to CouchDB document "
"field names. It is not usually necessary to set this slot - it is useful only if "
"you do not wish to use the default field names." } }
}
HELP: user
{ $class-description "The class of users. Instances have the following slots:"
-{ $table
- { { $slot "username" } { "The username, used to identify the user for login purposes" } }
- { { $slot "realname" } { "The user's real name, optional" } }
- { { $slot "password" } { "The user's password, encoded with a checksum" } }
- { { $slot "salt" } { "A random salt prepended to the password to ensure that two users with the same plain-text password still have different checksum output" } }
- { { $slot "email" } { "The user's e-mail address, optional" } }
- { { $slot "ticket" } { "Used for password recovery" } }
- { { $slot "capabilities" } { "A sequence of capabilities; see " { $link "furnace.auth.capabilities" } } }
- { { $slot "profile" } { "A hashtable with webapp-specific configuration" } }
- { { $slot "deleted" } { "A boolean indicating whether the user is active or not. This allows a user account to be deactivated without removing the user from the database" } }
- { { $slot "changed?" } { "A boolean indicating whether the user has changed since being retrieved from the database" } }
+{ $slots
+ { "username" { "The username, used to identify the user for login purposes" } }
+ { "realname" { "The user's real name, optional" } }
+ { "password" { "The user's password, encoded with a checksum" } }
+ { "salt" { "A random salt prepended to the password to ensure that two users with the same plain-text password still have different checksum output" } }
+ { "email" { "The user's e-mail address, optional" } }
+ { "ticket" { "Used for password recovery" } }
+ { "capabilities" { "A sequence of capabilities; see " { $link "furnace.auth.capabilities" } } }
+ { "profile" { "A hashtable with webapp-specific configuration" } }
+ { "deleted" { "A boolean indicating whether the user is active or not. This allows a user account to be deactivated without removing the user from the database" } }
+ { "changed?" { "A boolean indicating whether the user has changed since being retrieved from the database" } }
} } ;
HELP: add-user
ARTICLE: "furnace.sessions.config" "Session manager configuration"
"The " { $link sessions } " tuple has two slots which contain configuration parameters:"
-{ $table
- { { $slot "verify?" } { "If set to a true value, the client IP address and user agent of each session is tracked, and checked every time a client attempts to re-establish a session. While this does not offer any real security, it can thwart unskilled packet-sniffing attacks. On by default." } }
- { { $slot "timeout" } { "A " { $link duration } " storing the maximum time that inactive sessions will be stored on the server. The default timeout is 20 minutes. Note that for sessions to actually expire, you must start a thread to do so; see the " { $vocab-link "furnace.alloy" } " vocabulary for an easy way of doing this." } }
+{ $slots
+ { "verify?" { "If set to a true value, the client IP address and user agent of each session is tracked, and checked every time a client attempts to re-establish a session. While this does not offer any real security, it can thwart unskilled packet-sniffing attacks. On by default." } }
+ { "timeout" { "A " { $link duration } " storing the maximum time that inactive sessions will be stored on the server. The default timeout is 20 minutes. Note that for sessions to actually expire, you must start a thread to do so; see the " { $vocab-link "furnace.alloy" } " vocabulary for an easy way of doing this." } }
} ;
ARTICLE: "furnace.sessions.serialize" "Session state serialization"
ARTICLE: "furnace.syndication.config" "Configuring Atom feed actions"
"Instances of " { $link feed-action } " have three slots which need to be set:"
-{ $table
- { { $slot "title" } "The title of the feed as a string" }
- { { $slot "url" } { "The feed " { $link url } } }
- { { $slot "entries" } { "A quotation with stack effect " { $snippet "( -- seq )" } ", which produces a sequence of objects responding to the " { $link "furnace.syndication.protocol" } " protocol" } }
+{ $slots
+ { "title" "The title of the feed as a string" }
+ { "url" { "The feed " { $link url } } }
+ { "entries" { "A quotation with stack effect " { $snippet "( -- seq )" } ", which produces a sequence of objects responding to the " { $link "furnace.syndication.protocol" } " protocol" } }
} ;
ARTICLE: "furnace.syndication.protocol" "Atom feed entry protocol"
: $snippet ( children -- )
[ snippet-style get print-element* ] ($span) ;
-! for help-lint
-ALIAS: $slot $snippet
-
: $emphasis ( children -- )
[ emphasis-style get print-element* ] ($span) ;
] each
] ($grid) ;
+! for help-lint
+ALIAS: $slot $snippet
+
+: $slots ( children -- )
+ [ unclip \ $slot swap 2array prefix ] map $table ;
+
: a/an ( str -- str )
[ first ] [ length ] bi 1 =
"afhilmnorsx" "aeiou" ? member? "an" "a" ? ;
{ $description "An HTTP request."
$nl
"Instances contain the following slots:"
-{ $table
- { { $slot "method" } { "The HTTP method as a " { $link string } ". The most frequently-used HTTP methods are " { $snippet "GET" } ", " { $snippet "HEAD" } " and " { $snippet "POST" } "." } }
- { { $slot "url" } { "The " { $link url } " being requested" } }
- { { $slot "proxy-url" } { "The proxy " { $link url } " to use, or " { $link f } " for no proxy. If not " { $link f } ", the url will additionally be " { $link derive-url } "'d from the " { $link "http.proxy-variables" } ". The proxy is used if the result has at least the " { $slot "host" } " slot set." } }
- { { $slot "version" } { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
- { { $slot "header" } { "An assoc of HTTP header values. See " { $link "http.headers" } } }
- { { $slot "post-data" } { "See " { $link "http.post-data" } } }
- { { $slot "cookies" } { "A sequence of HTTP cookies. See " { $link "http.cookies" } } }
- { { $slot "redirects" } { "Number of redirects to attempt before throwing an error. Default is " { $snippet "max-redirects" } "." } }
+{ $slots
+ { "method" { "The HTTP method as a " { $link string } ". The most frequently-used HTTP methods are " { $snippet "GET" } ", " { $snippet "HEAD" } " and " { $snippet "POST" } "." } }
+ { "url" { "The " { $link url } " being requested" } }
+ { "proxy-url" { "The proxy " { $link url } " to use, or " { $link f } " for no proxy. If not " { $link f } ", the url will additionally be " { $link derive-url } "'d from the " { $link "http.proxy-variables" } ". The proxy is used if the result has at least the " { $slot "host" } " slot set." } }
+ { "version" { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
+ { "header" { "An assoc of HTTP header values. See " { $link "http.headers" } } }
+ { "post-data" { "See " { $link "http.post-data" } } }
+ { "cookies" { "A sequence of HTTP cookies. See " { $link "http.cookies" } } }
+ { "redirects" { "Number of redirects to attempt before throwing an error. Default is " { $snippet "max-redirects" } "." } }
} } ;
HELP: <response>
{ $class-description "An HTTP response."
$nl
"Instances contain the following slots:"
-{ $table
- { { $slot "version" } { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
- { { $slot "code" } { "HTTP status code, an " { $link integer } ". Examples are 200 for success, 404 for file not found, and so on." } }
- { { $slot "message" } { "HTTP status message, only displayed to the user. If the status code is 200, the status message might be “Success”, for example." } }
- { { $slot "header" } { "An assoc of HTTP header values. See " { $link "http.headers" } } }
- { { $slot "cookies" } { "A sequence of HTTP cookies. See " { $link "http.cookies" } } }
- { { $slot "content-type" } { "an HTTP content type" } }
- { { $slot "content-charset" } { "an encoding name" } }
- { { $slot "content-encoding" } { "an encoding descriptor. See " { $link "io.encodings" } } }
- { { $slot "body" } { "an HTTP response body" } }
+{ $slots
+ { "version" { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
+ { "code" { "HTTP status code, an " { $link integer } ". Examples are 200 for success, 404 for file not found, and so on." } }
+ { "message" { "HTTP status message, only displayed to the user. If the status code is 200, the status message might be “Success”, for example." } }
+ { "header" { "An assoc of HTTP header values. See " { $link "http.headers" } } }
+ { "cookies" { "A sequence of HTTP cookies. See " { $link "http.cookies" } } }
+ { "content-type" { "an HTTP content type" } }
+ { "content-charset" { "an encoding name" } }
+ { "content-encoding" { "an encoding descriptor. See " { $link "io.encodings" } } }
+ { "body" { "an HTTP response body" } }
} } ;
HELP: <raw-response>
{ $class-description "A minimal HTTP response used by webapps which need full control over all output sent to the client. Most webapps can use " { $link response } " instead."
$nl
"Instances contain the following slots:"
-{ $table
- { { $slot "version" } { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
- { { $slot "code" } { "HTTP status code, an " { $link integer } ". Examples are 200 for success, 404 for file not found, and so on." } }
- { { $slot "message" } { "HTTP status message, only displayed to the user. If the status code is 200, the status message might be “Success”, for example." } }
- { { $slot "body" } { "an HTTP response body" } }
+{ $slots
+ { "version" { "The HTTP version. Default is " { $snippet "1.1" } " and should not be changed without good reason." } }
+ { "code" { "HTTP status code, an " { $link integer } ". Examples are 200 for success, 404 for file not found, and so on." } }
+ { "message" { "HTTP status message, only displayed to the user. If the status code is 200, the status message might be “Success”, for example." } }
+ { "body" { "an HTTP response body" } }
} } ;
HELP: <cookie>
"An HTTP cookie."
$nl
"Instances contain a number of slots which correspond exactly to the fields of a cookie in the cookie specification:"
-{ $table
- { { $slot "name" } { "The cookie name, a " { $link string } } }
- { { $slot "value" } { "The cookie value, an object supported by " { $link present } } }
- { { $slot "comment" } { "A " { $link string } } }
- { { $slot "path" } { "The pathname prefix where the cookie is valid, a " { $link string } } }
- { { $slot "domain" } { "The domain name where the cookie is valid, a " { $link string } } }
- { { $slot "expires" } { "The expiry time, a " { $link timestamp } " or " { $link f } " for a session cookie" } }
- { { $slot "max-age" } { "The expiry duration, a " { $link duration } " or " { $link f } " for a session cookie" } }
- { { $slot "http-only" } { "If set to a true value, JavaScript code cannot see the cookie" } }
- { { $slot "secure" } { "If set to a true value, the cookie is only sent for " { $snippet "https" } " protocol connections" } }
+{ $slots
+ { "name" { "The cookie name, a " { $link string } } }
+ { "value" { "The cookie value, an object supported by " { $link present } } }
+ { "comment" { "A " { $link string } } }
+ { "path" { "The pathname prefix where the cookie is valid, a " { $link string } } }
+ { "domain" { "The domain name where the cookie is valid, a " { $link string } } }
+ { "expires" { "The expiry time, a " { $link timestamp } " or " { $link f } " for a session cookie" } }
+ { "max-age" { "The expiry duration, a " { $link duration } " or " { $link f } " for a session cookie" } }
+ { "http-only" { "If set to a true value, JavaScript code cannot see the cookie" } }
+ { "secure" { "If set to a true value, the cookie is only sent for " { $snippet "https" } " protocol connections" } }
}
"Only one of " { $snippet "expires" } " and " { $snippet "max-age" } " can be set; the latter is preferred and is supported by all modern browsers." } ;
{ $class-description "HTTP POST data passed in a POST request."
$nl
"Instances contain the following slots:"
-{ $table
- { { $slot "data" } { "The POST data. This can be in a higher-level form, such as an assoc of POST parameters, a string, or an XML document" } }
- { { $slot "params" } { "Parameters passed in the POST request." } }
- { { $slot "content-type" } { "A MIME type" } }
- { { $slot "content-encoding" } { "Encoding used for the POST data" } }
+{ $slots
+ { "data" { "The POST data. This can be in a higher-level form, such as an assoc of POST parameters, a string, or an XML document" } }
+ { "params" { "Parameters passed in the POST request." } }
+ { "content-type" { "A MIME type" } }
+ { "content-encoding" { "Encoding used for the POST data" } }
} } ;
HELP: set-header
HELP: rewrite
{ $class-description "The class of directory rewrite responders. The slots are as follows:"
-{ $list
- { { $slot "default" } " - the responder to call if no file name is provided." }
- { { $slot "child" } " - the responder to call if a file name is provided." }
- { { $slot "param" } " - the name of a request parameter which will store the first path component of the file name passed to the responder." }
+{ $slots
+ { "default" "the responder to call if no file name is provided." }
+ { "child" "the responder to call if a file name is provided." }
+ { "param" "the name of a request parameter which will store the first path component of the file name passed to the responder." }
} } ;
HELP: <rewrite>
HELP: vhost-rewrite
{ $class-description "The class of virtual host rewrite responders. The slots are as follows:"
-{ $list
- { { $slot "default" } " - the responder to call if no host name prefix is provided." }
- { { $slot "child" } " - the responder to call if a host name prefix is provided." }
- { { $slot "param" } " - the name of a request parameter which will store the first host name component of the host name passed to the responder." }
- { { $slot "suffix" } " - the domain name suffix which will be chopped off the end of the request's host name in order to produce the parameter." }
+{ $slots
+ { "default" "the responder to call if no host name prefix is provided." }
+ { "child" " the responder to call if a host name prefix is provided." }
+ { "param" "the name of a request parameter which will store the first host name component of the host name passed to the responder." }
+ { "suffix" "the domain name suffix which will be chopped off the end of the request's host name in order to produce the parameter." }
} } ;
HELP: <vhost-rewrite>
HELP: buffer
{ $class-description "The class of I/O buffers, which resemble FIFO queues, but are optimized for holding bytes, are have underlying storage allocated at a fixed address. Buffers must be de-allocated manually. It has the following slots:"
- { $table
- { { $slot "size" } "The total size, in bytes, of the buffer" }
- { { $slot "ptr" } { "The " { $link c-ptr } " memory where data is stored" } }
- { { $slot "fill" } "The fill pointer, a write index where new data is added" }
- { { $slot "pos" } "The position, a read index where data is consumed" }
+ { $slots
+ { "size" "The total size, in bytes, of the buffer" }
+ { "ptr" { "The " { $link c-ptr } " memory where data is stored" } }
+ { "fill" "The fill pointer, a write index where new data is added" }
+ { "pos" "The position, a read index where data is consumed" }
}
} ;
HELP: rect
{ $class-description "A rectangle with the following slots:"
- { $list
- { { $slot "loc" } " - the top-left corner of the rectangle as an x/y pair" }
- { { $slot "dim" } " - the dimensions of the rectangle as a width/height pair" }
+ { $slots
+ { "loc" "the top-left corner of the rectangle as an x/y pair" }
+ { "dim" "the dimensions of the rectangle as a width/height pair" }
}
"Rectangles are constructed by calling " { $link <rect> } " and " { $link <extent-rect> } "."
} ;
HELP: model
{ $class-description "A mutable cell holding a single value. When the value is changed, a sequence of connected objects are notified. Models have the following slots:"
- { $list
- { { $slot "value" } " - the value of the model. Use " { $link set-model } " to change the value." }
- { { $slot "connections" } " - a sequence of objects implementing the " { $link model-changed } " generic word, to be notified when the model's value changes." }
- { { $slot "dependencies" } " - a sequence of models which should have this model added to their sequence of connections when activated." }
- { { $slot "ref" } " - a reference count tracking the number of models which depend on this one." }
- { { $slot "locked?" } " - a slot set by " { $link with-locked-model } " to ensure that the model doesn't get changed recursively" }
+ { $slots
+ { "value" "the value of the model. Use " { $link set-model } " to change the value." }
+ { "connections" "a sequence of objects implementing the " { $link model-changed } " generic word, to be notified when the model's value changes." }
+ { "dependencies" "a sequence of models which should have this model added to their sequence of connections when activated." }
+ { "ref" "a reference count tracking the number of models which depend on this one." }
+ { "locked?" "a slot set by " { $link with-locked-model } " to ensure that the model doesn't get changed recursively" }
}
"Other classes may inherit from " { $link model } "."
} ;
HELP: smtp-config
{ $class-description "An SMTP configuration object, with the following slots:"
- { $table
- { { $slot "domain" } { "Name of the machine sending the email, or " { $link host-name } " if empty." } }
- { { $slot "server" } { "An " { $link <inet> } " of the SMTP server." } }
- { { $slot "tls?" } { "Secure socket after connecting to server, server must support " { $snippet "STARTTLS" } } }
- { { $slot "read-timeout" } { "Length of time after which we give up waiting for a response." } }
- { { $slot "auth" } { "Either " { $link no-auth } " or an instance of " { $link plain-auth } " or " { $link login-auth } } }
+ { $slots
+ { "domain" { "Name of the machine sending the email, or " { $link host-name } " if empty." } }
+ { "server" { "An " { $link <inet> } " of the SMTP server." } }
+ { "tls?" { "Secure socket after connecting to server, server must support " { $snippet "STARTTLS" } } }
+ { "read-timeout" { "Length of time after which we give up waiting for a response." } }
+ { "auth" { "Either " { $link no-auth } " or an instance of " { $link plain-auth } " or " { $link login-auth } } }
}
} ;
HELP: email
{ $class-description "An e-mail. E-mails have the following slots:"
- { $table
- { { $slot "from" } "The sender of the e-mail. An e-mail address." }
- { { $slot "to" } "The recipients of the e-mail. A sequence of e-mail addresses." }
- { { $slot "cc" } "Carbon-copy. A sequence of e-mail addresses." }
- { { $slot "bcc" } "Blind carbon-copy. A sequence of e-mail addresses." }
- { { $slot "subject" } "The subject of the e-mail. A string." }
- { { $slot "content-type" } { "The MIME type of the body. A string, default is " { $snippet "text/plain" } "." } }
- { { $slot "encoding" } { "An encoding to send the body as. Default is " { $link utf8 } "." } }
- { { $slot "body" } " The body of the e-mail. A string." }
+ { $slots
+ { "from" "The sender of the e-mail. An e-mail address." }
+ { "to" "The recipients of the e-mail. A sequence of e-mail addresses." }
+ { "cc" "Carbon-copy. A sequence of e-mail addresses." }
+ { "bcc" "Blind carbon-copy. A sequence of e-mail addresses." }
+ { "subject" "The subject of the e-mail. A string." }
+ { "content-type" { "The MIME type of the body. A string, default is " { $snippet "text/plain" } "." } }
+ { "encoding" { "An encoding to send the body as. Default is " { $link utf8 } "." } }
+ { "body" " The body of the e-mail. A string." }
}
"The " { $slot "from" } " and " { $slot "to" } " slots are required; the rest are optional."
$nl
HELP: alien-node-params
{ $class-description "Base class for the parameter slot of " { $link #alien-node } " nodes. It has the following slots:"
- { $table
- { { $slot "return" } { "a " { $link c-type-name } " which indicates the type of the functions return value." } }
- { { $slot "parameters" } { "a " { $link sequence } " of " { $link c-type-name } " giving the types of the functions parameters." } }
- { { $slot "abi" } { "calling convention of the function the node parameters operates on." } }
+ { $slots
+ { "return" { "a " { $link c-type-name } " which indicates the type of the functions return value." } }
+ { "parameters" { "a " { $link sequence } " of " { $link c-type-name } " giving the types of the functions parameters." } }
+ { "abi" { "calling convention of the function the node parameters operates on." } }
}
}
{ $see-also abi } ;
HELP: aligned-gadget
{ $class-description "A " { $link gadget } " that adds the following slots:"
- { $list
- { { $slot "baseline" } " - a cached value for " { $link baseline } "; do not read or write this slot directly." }
- { { $slot "cap-height" } " - a cached value for " { $link cap-height } "; do not read or write this slot directly." }
+ { $slots
+ { "baseline" "a cached value for " { $link baseline } "; do not read or write this slot directly." }
+ { "cap-height" "a cached value for " { $link cap-height } "; do not read or write this slot directly." }
}
} ;
{ $class-description "Base class for gadgets that implements display of sequences of text."
$nl
"Line gadgets have the following slots:"
- { $table
+ { $slots
{
- { $slot "font" }
+ "font"
{ "a " { $link font } "." }
}
{
- { $slot "selection-color" }
+ "selection-color"
{ "a " { $link color } "." }
}
{
- { $slot "min-rows" }
+ "min-rows"
{ "The preferred minimum number of visible rows when the gadget is contained in a viewport." }
}
{
- { $slot "max-rows" }
+ "max-rows"
{ "The preferred maximum number of visible rows when the gadget is cotnained in a viewport." }
}
{
- { $slot "min-cols" }
+ "min-cols"
{ "The preferred minimum number of visible columns when the gadget is contained in a viewport." }
}
{
- { $slot "max-cols" }
+ "max-cols"
{ "The preferred maximum number of visible columns when the gadget is contained in a viewport." }
}
}
ARTICLE: "ui.gadgets.tables.selection" "Table row selection"
"A few slots in the table gadget concern row selection:"
-{ $table
- { { $slot "selection" } { " - if set to a model, the values of the currently selected row or rows, as determined by a " { $link row-value } " call to the renderer, is stored in this model. See " { $link "models" } "." } }
- { { $slot "selection-index" } { " - if set to a model, the indices of the currently selected rows." } }
- { { $slot "selection-required?" } { " - if set to a true value, the table ensures that some row is always selected, if the model is non-empty. If set to " { $link f } ", a state where nothing is selected is permitted to occur. The default is " { $link f } "." } }
+{ $slots
+ { "selection" { " - if set to a model, the values of the currently selected row or rows, as determined by a " { $link row-value } " call to the renderer, is stored in this model. See " { $link "models" } "." } }
+ { "selection-index" { " - if set to a model, the indices of the currently selected rows." } }
+ { "selection-required?" { " - if set to a true value, the table ensures that some row is always selected, if the model is non-empty. If set to " { $link f } ", a state where nothing is selected is permitted to occur. The default is " { $link f } "." } }
}
"Some words for row selection:"
{ $subsections
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."
-{ $table
- { { $slot "gap" } }
- { { $slot "focus-border-color" } }
- { { $slot "mouse-color" } }
- { { $slot "column-line-color" } }
- { { $slot "takes-focus?" } }
+{ $slots
+ { "gap" }
+ { "focus-border-color" }
+ { "mouse-color" }
+ { "column-line-color" }
+ { "takes-focus?" }
} ;
ARTICLE: "ui.gadgets.tables.example" "Table gadget example"
HELP: world
{ $class-description "A gadget which appears at the top of the gadget hieararchy, and in turn may be displayed in a native window. Worlds have the following slots:"
- { $table
+ { $slots
{
- { $slot "active?" }
+ "active?"
{ "an " { $link integer } " initially set to 0. The active " { $link ui-backend } " increases the value in steps up to 100 while the native window containing the world is being initialized but not yet visible on the screen. The world is only redrawn when the value is 100 which prevents redundant redraws from happening during initialization. The slot is set to 0 if an error is thrown while drawing the world; this prevents multiple debugger windows from being shown." }
}
{
- { $slot "layers" }
+ "layers"
{ "a sequence of glass panes in front of the primary gadget, used to implement behaviors such as popup menus which are hidden when the mouse is clicked outside the menu. See " { $link "ui.gadgets.glass" } "." }
}
{
- { $slot "title" }
+ "title"
{ "a string to be displayed in the title bar of the native window containing the world." }
}
{
- { $slot "status" }
+ "status"
{ "a " { $link model } " holding a string to be displayed in the world's status bar." }
}
{
- { $slot "status-owner" }
+ "status-owner"
{ "the gadget that displayed the most recent status message." }
}
{
- { $slot "focus" }
+ "focus"
{ "the current owner of the keyboard focus in the world." }
}
{
- { $slot "focused?" }
+ "focused?"
{ "a boolean indicating if the native window containing the world has keyboard focus." }
}
{
- { $slot "grab-input?" }
+ "grab-input?"
{ "if set to " { $link t } ", the world will hide the mouse cursor and disable normal mouse input while focused. Use " { $link grab-input } " and " { $link ungrab-input } " to change this setting." }
}
{
- { $slot "handle" }
+ "handle"
{ "a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
}
{
- { $slot "window-loc" }
+ "window-loc"
{ "the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
}
{
- { $slot "window-controls" }
+ "window-controls"
{ "the set of " { $link "ui.gadgets.worlds-window-controls" } " with which the world window was created." }
}
}
HELP: gadget
{ $class-description "An object which displays itself on the screen and acts on user input gestures. Gadgets have the following slots:"
- { $list
- { { $slot "pref-dim" } " - a cached value for " { $link pref-dim } "; do not read or write this slot directly." }
- { { $slot "parent" } " - the gadget containing this one, or " { $link f } " if this gadget is not part of the visible gadget hierarchy." }
- { { $slot "children" } " - a vector of child gadgets. Do not modify this vector directly, instead use " { $link add-gadget } ", " { $link add-gadgets } ", " { $link unparent } " or " { $link clear-gadget } "." }
- { { $slot "graft-state" } { " - a pair of " { $link boolean } " values that represent the current graft state of the gadget and what its next state will become." } }
- { { $slot "orientation" } " - an orientation specifier. This slot is used by layout gadgets." }
- { { $slot "layout-state" } " - stores the layout state of the gadget. Do not read or write this slot directly, instead call " { $link relayout } " and " { $link relayout-1 } " if the gadget needs to be re-laid out." }
- { { $slot "visible?" } " - a boolean indicating if the gadget should display and receive user input." }
- { { $slot "root?" } " - if set to " { $link t } ", layout changes in this gadget will not propagate to the gadget's parent." }
- { { $slot "clipped?" } " - a boolean indicating if clipping will be enabled when drawing this gadget's children." }
- { { $slot "interior" } " - an implementation of the " { $link "ui-pen-protocol" } }
- { { $slot "boundary" } " - an implementation of the " { $link "ui-pen-protocol" } }
- { { $slot "model" } " - a " { $link model } " or " { $link f } "; see " { $link "ui-control-impl" } }
+ { $slots
+ { "pref-dim" { "a cached value for " { $link pref-dim } "; do not read or write this slot directly." } }
+ { "parent" { "the gadget containing this one, or " { $link f } " if this gadget is not part of the visible gadget hierarchy." } }
+ { "children" { "a vector of child gadgets. Do not modify this vector directly, instead use " { $link add-gadget } ", " { $link add-gadgets } ", " { $link unparent } " or " { $link clear-gadget } "." } }
+ { "graft-state" { "a pair of " { $link boolean } " values that represent the current graft state of the gadget and what its next state will become." } }
+ { "orientation" "an orientation specifier. This slot is used by layout gadgets." }
+ { "layout-state" { "stores the layout state of the gadget. Do not read or write this slot directly, instead call " { $link relayout } " and " { $link relayout-1 } " if the gadget needs to be re-laid out." } }
+ { "visible?" "a boolean indicating if the gadget should display and receive user input." }
+ { "root?" { "if set to " { $link t } ", layout changes in this gadget will not propagate to the gadget's parent." } }
+ { "clipped?" "a boolean indicating if clipping will be enabled when drawing this gadget's children." }
+ { "interior" { "an implementation of the " { $link "ui-pen-protocol" } } }
+ { "boundary" { "an implementation of the " { $link "ui-pen-protocol" } } }
+ { "model" { "a " { $link model } " or " { $link f } "; see " { $link "ui-control-impl" } } }
}
"Gadgets subclass the " { $link rect } " class, and thus all instances have " { $slot "loc" } " and " { $slot "dim" } " instances holding their location and dimensions." }
{ $notes
HELP: interactor
{ $class-description "An interactor is an " { $link editor } " intended to be used as the input component of a " { $link "ui-listener" } ". It has the following slots:"
-{ $table
+{ $slots
{
- { $slot "waiting" }
+ "waiting"
{ "If waiting is " { $link t } ", the interactor is waiting for user input, and invoking " { $link evaluate-input } " resumes the thread." }
}
}
HELP: zone
{ $class-description "A struct that defines the memory layout for an allocation zone in the virtual machine. Factor code cannot directly access allocation zones, but the struct is used by the compiler to calculate memory addresses. Its slots are:"
- { $table
- { { $slot "here" } { "Memory address to the last allocated byte in the zone. Initially, this slot is equal to " { $snippet "start" } " but each allocation in the zone will increment this pointer." } }
- { { $slot "start" } { "Memory address to the start of the zone." } }
- { { $slot "end" } { "Memory address to the end of the zone." } }
+ { $slots
+ { "here" { "Memory address to the last allocated byte in the zone. Initially, this slot is equal to " { $snippet "start" } " but each allocation in the zone will increment this pointer." } }
+ { "start" { "Memory address to the start of the zone." } }
+ { "end" { "Memory address to the end of the zone." } }
}
} ;
HELP: vm
{ $class-description "A struct that defines the memory layout of the running virtual machine. It is used by the optimizing compiler to calculate field offsets. Its slots are:"
- { $table
- { { $slot "nursery" } { "A " { $link zone } " in which all new objects are allocated." } }
+ { $slots
+ { "nursery" { "A " { $link zone } " in which all new objects are allocated." } }
}
} ;
HELP: gc-info
{ $class-description "A struct that defines the sizes of the garbage collection maps for a word. It has the following slots:"
- { $table
- { { $slot "gc-root-count" } "Number of gc root bits per callsite." }
- { { $slot "derived-root-count" } "Number of derived roots per callsite." }
- { { $slot "return-address-count" } "Number of gc callsites." }
+ { $slots
+ { "gc-root-count" "Number of gc root bits per callsite." }
+ { "derived-root-count" "Number of derived roots per callsite." }
+ { "return-address-count" "Number of gc callsites." }
}
} ;
HELP: element
{ $class-description "An element to be wrapped. It has the following slots:" }
-{ $table
- { { $slot "contents" } "The object being wrapped." }
- { { $slot "black" } "The width of the object (e.g., the text length)." }
- { { $slot "white" } "The space after the object (e.g., trailing whitespace)." }
+{ $slots
+ { "contents" "The object being wrapped." }
+ { "black" "The width of the object (e.g., the text length)." }
+ { "white" "The space after the object (e.g., trailing whitespace)." }
} ;
HELP: wrap
HELP: disposable
{ $class-description "Parent class for disposable resources. This class has two slots:"
- { $list
- { { $slot "disposed" } " - boolean. Set to true by " { $link dispose } ". Assert that it is false with " { $link check-disposed } "." }
- { { $slot "continuation" } " - current continuation at construction time, for debugging. Set by " { $link new-disposable } " if " { $link debug-leaks? } " is on." }
+ { $slots
+ { "disposed" { "A boolean value, set to true by " { $link dispose } ". Assert that it is false with " { $link check-disposed } "." } }
+ { "continuation" { "The current continuation at construction time, for debugging. Set by " { $link new-disposable } " if " { $link debug-leaks? } " is on." } }
}
"New instances must be constructed with " { $link new-disposable } " and subclasses must implement " { $link dispose* } "." } ;
{ $description "A definition of a class of errors"
$nl
"Instances contain the following slots:"
- { $table
- { { $slot "type" } { "symbol representing the error type." } }
- { { $slot "word" } { "name of the word that lists all errors of this error type." } }
- { { $slot "plural" } { "pluralized description of this error type." } }
- { { $slot "icon" } { "path to an icon image representing this error type." } }
- { { $slot "quot" } { "quotation that produces a list of all errors of this type." } }
- { { $slot "forget-quot" } { "a quotation that removes errors of this type for a given word." } }
- { { $slot "fatal?" } { "whether the error is fatal or not. default " { $link t } "." } }
+ { $slots
+ { "type" { "symbol representing the error type." } }
+ { "word" { "name of the word that lists all errors of this error type." } }
+ { "plural" { "pluralized description of this error type." } }
+ { "icon" { "path to an icon image representing this error type." } }
+ { "quot" { "quotation that produces a list of all errors of this type." } }
+ { "forget-quot" { "a quotation that removes errors of this type for a given word." } }
+ { "fatal?" { "whether the error is fatal or not. default " { $link t } "." } }
}
} ;
HELP: source-file
{ $class-description "Instances retain information about loaded source files, and have the following slots:"
- { $list
- { { $slot "path" } " - a pathname string." }
- { { $slot "top-level-form" } " - a " { $link quotation } " composed of any code not used to define new words and classes" }
- { { $slot "checksum" } " - the CRC32 checksum of the source file's contents at the time it was most recently loaded." }
- { { $slot "definitions" } " - a pair of assocs, containing definitions and classes defined in this source file, respectively" }
- { { $slot "main" } " - a word that gets called if you " { $link run } " the vocabulary" }
+ { $slots
+ { "path" { "a pathname string." } }
+ { "top-level-form" { " - a " { $link quotation } " composed of any code not used to define new words and classes" } }
+ { "checksum" { "the CRC32 checksum of the source file's contents at the time it was most recently loaded." } }
+ { "definitions" { "a pair of assocs, containing definitions and classes defined in this source file, respectively" } }
+ { "main" { "a word that gets called if you " { $link run } " the vocabulary" } }
}
} ;
HELP: gdbm
{ $class-description "Instance of this class is used as database configuration object. It has following slots:"
-
- { $table
- { { $slot "name" } "The file name of the database." }
- { { $slot "block-size" } "The size of a single transfer from disk to memory. If the value is less than 512, the file system blocksize is used (this is default)." }
- { { $slot "role" } "Determines what kind of access the user wants to obtain (see below)." }
- { { $slot "sync" } { "Being set to " { $link t } " causes all database operations to be synchronized to the disk." } }
- { { $slot "nolock" } { "Being set to " { $link t } " prevents gdbm from performing any locking on the database file." } }
- { { $slot "mode" } "An integer representing standard UNIX access permissions." }
+ { $slots
+ { "name" "The file name of the database." }
+ { "block-size" "The size of a single transfer from disk to memory. If the value is less than 512, the file system blocksize is used (this is default)." }
+ { "role" "Determines what kind of access the user wants to obtain (see below)." }
+ { "sync" { "Being set to " { $link t } " causes all database operations to be synchronized to the disk." } }
+ { "nolock" { "Being set to " { $link t } " prevents gdbm from performing any locking on the database file." } }
+ { "mode" "An integer representing standard UNIX access permissions." }
}
"The " { $slot "role" } " can be set to one of the folowing values:"
{ $table
HELP: hashcash
{ $class-description "An hashcash object. An hashcash have the following slots:"
- { $table
- { { $slot "version" } "The version number. Only version 1 is supported." }
- { { $slot "bits" } "The claimed bit value." }
- { { $slot "date" } "The date a stamp was minted." }
- { { $slot "resource" } "The resource for which a stamp is minted." }
- { { $slot "ext" } "Extensions that a specialized application may want." }
- { { $slot "salt" } "A random salt." }
- { { $slot "suffix" } "The computed suffix. This is supposed to be manipulated by the library." }
+ { $slots
+ { "version" "The version number. Only version 1 is supported." }
+ { "bits" "The claimed bit value." }
+ { "date" "The date a stamp was minted." }
+ { "resource" "The resource for which a stamp is minted." }
+ { "ext" "Extensions that a specialized application may want." }
+ { "salt" "A random salt." }
+ { "suffix" "The computed suffix. This is supposed to be manipulated by the library." }
}
} ;
HELP: pop3-account
{ $class-description "A POP3 account on a POP3 server. It has the following slots:"
- { $table
- { { $slot "#" } "The ephemeral ordinal number of the message." }
- { { $slot "host" } "The name or IP address of the remote host to which a POP3 connection is required." }
- { { $slot "port" } "The POP3 server port (defaults to 110)." }
- { { $slot "timeout" } "Maximum time in minutes to wait for a response from the POP3 server (defaults to 1 minutes)." }
- { { $slot "user" } "The userID of the account on the POP3 server." }
- { { $slot "pwd" } { "The clear-text password for the userID." } }
- { { $slot "stream" } { "The duplex input/output stream wrapping the POP3 session." } }
- { { $slot "capa" } { "A list of the mail server capabilities." } }
- { { $slot "count" } { "Number of messages in the mailbox." } }
- { { $slot "list" } { "A list of every message with its number and size in bytes" } }
- { { $slot "uidls" } { "The UIDL (Unique IDentification Listing) of every message in the mailbox together with its ordinal number." } }
- { { $slot "messages" } { "A sequence of email tuples in the mailbox containing each email's headers, number, uidl, and size." } }
+ { $slots
+ { "#" "The ephemeral ordinal number of the message." }
+ { "host" "The name or IP address of the remote host to which a POP3 connection is required." }
+ { "port" "The POP3 server port (defaults to 110)." }
+ { "timeout" "Maximum time in minutes to wait for a response from the POP3 server (defaults to 1 minutes)." }
+ { "user" "The userID of the account on the POP3 server." }
+ { "pwd" { "The clear-text password for the userID." } }
+ { "stream" { "The duplex input/output stream wrapping the POP3 session." } }
+ { "capa" { "A list of the mail server capabilities." } }
+ { "count" { "Number of messages in the mailbox." } }
+ { "list" { "A list of every message with its number and size in bytes" } }
+ { "uidls" { "The UIDL (Unique IDentification Listing) of every message in the mailbox together with its ordinal number." } }
+ { "messages" { "A sequence of email tuples in the mailbox containing each email's headers, number, uidl, and size." } }
}
"The " { $slot "host" } " is required; the rest are either set by default or optional." $nl
"The " { $slot "user" } " and " { $slot "pwd" } " must either be set before using " { $link connect } " or immediately after it with the " { $link >user } " and " { $link >pwd } " words."
HELP: message
{ $class-description "An e-mail message having the following slots:"
- { $table
- { { $slot "#" } "The ephemeral ordinal number of the message." }
- { { $slot "uidl" } "The POP3 UIDL (Unique IDentification Listing) of the message." }
- { { $slot "headers" } "The From:, Subject:, and To: headers of the message." }
- { { $slot "from" } "The sender of the message. An e-mail address." }
- { { $slot "to" } "The recipients of the message." }
- { { $slot "subject" } { "The subject of the message." } }
- { { $slot "size" } { "The size of the message in octets." } }
+ { $slots
+ { "#" "The ephemeral ordinal number of the message." }
+ { "uidl" "The POP3 UIDL (Unique IDentification Listing) of the message." }
+ { "headers" "The From:, Subject:, and To: headers of the message." }
+ { "from" "The sender of the message. An e-mail address." }
+ { "to" "The recipients of the message." }
+ { "subject" { "The subject of the message." } }
+ { "size" { "The size of the message in octets." } }
}
} ;
{ $class-description "This is a " { $link gadget } " which, when added as a child to the " { $link chart } ", will display its data as straight line segments. The implementation is oriented towards speed to allow large data sets to be displayed as quickly as possible."
$nl
"Slots:"
-{ $list
- { { $slot "data" } " - a " { $link sequence } " of { x y } pairs sorted by non-descending x;" }
- { { $slot "data" } " - a " { $link color } " to draw the line with." }
+{ $slots
+ { "data" { "a " { $link sequence } " of { x y } pairs sorted by non-descending x;" } }
+ { "color" { "a " { $link color } " to draw the line with." } }
} } ;
HELP: y-at
projects / factor.git / commitdiff