Core state types

To top.

The most important core states are designed to be really easy to use; they have a simple tack-on operation, treating all types of pieces similarly, and may often be frozen to harvest the goods being piled up. There is almost nothing one has to know about these states. Then, however, there are also state types defining more complex behaviors, and some states interact in special ways with core functions. This part of the documentation will be useful when it comes to these types of states.

Sections: Containers Streams Miscellaneous

Alphabetical list

§•Array §•Catalog §•Debugger §•Graph §•Group §•Group3D §•Ignore §•Ostream §•Random §•Text §•Time

States of types in this section are used to produce containers with objects in.

§•Array §•Catalog §•Graph §•Group §•Group3D §•Text

§•Group

Abstraction:

States of type §•Group are used to fill containers of type §Group.

Construction:

..Shapes..Graphics..newGroup

Mutators

• <<
::§Drawable → §Void
Dynamic references:	none
Side effect:	Put element on top of pile.

(•)
→ §Group
Dynamic references:	none
Get current pile.

freeze •
→ §Group
Dynamic references:	none
Get current pile.

erase
→ §Void
Dynamic references:	none
Side effect:	Erase contents.
A common application of this is when ..Shapes..IO..•page has been used to define the contents of the pages in ..Shapes..IO..•catalog. Then, when ..Shapes..IO..•catalog is non-empty at the end of the program, it is an error if ..Shapes..IO..•page is also non-tmpty. All you have to do then is to write •page.[erase] at the end of the program.

remove
key::§Symbol → §Void
Dynamic references:	none
Side effect:	Remove shallow tagged objects with the key key.
Here, shallow refers to objects that were tacked on directly to the state. For instance, •page << [shift (1cm,0cm)] [] [tag 'a [stroke (0cm,0cm)--(1cm,1cm)]] •page.[remove 'a] will not remove the stroke from the page, since the value being tacked on to the state is transformed. To make it work, apply the transform to the object being tagged: •page << [tag 'a [[shift (1cm,0cm)] [stroke (0cm,0cm)--(1cm,1cm)]]]
See also:	..Shapes..Graphics..Tag..tag

§•Group3D

Abstraction:

States of type §•Group3D are used to fill containers of type §Group3D.

Construction:

..Shapes..Graphics3D..newGroup

Mutators

• <<
::§Drawable3D → §Void
Dynamic references:	none
Side effect:	Put element on top of pile.

(•)
→ §Group3D
Dynamic references:	none
Get current pile.

freeze •
→ §Group3D
Dynamic references:	none
Get current pile.

erase
→ §Void
Dynamic references:	none
Side effect:	Erase contents.
Analogous to §•Group/erase.

remove
key::§Symbol → §Void
Dynamic references:	none
Side effect:	Remove shallow tagged objects with the key key.
Analogous to §•Group/remove.

§•Catalog

Abstraction:

States of type §•Catalog are used to construct documents with many pages, page labels, cross references, and so on.

Construction:

..Shapes..IO..•catalog

There is currently no way a user can create their own §•Catalog states; only the global ..Shapes..IO..•catalog may be accessed. It is directly associated with the program output, so instead of peeking or freezing the state, the program is terminated, at which point the contents of the state is used.

See also:

..Shapes..IO..•catalog

Mutators

• <<
::§Drawable → §Void
Dynamic references:	none
Side effect:	Add graphics as page att the end of the catalog. Note that a §Drawable value can contain objects that have special meaning when appearing on a page out output. Below, functions that construct such objects are listed. Don't expect the lista of dynamic references to be complete, and don't expect any of the listed references to actually be used.

See also:	destination site annotationText annotationLaunch annotationLink

(•)
The state cannot be peeked.

freeze •
The state cannot be frozen.

setbboxgroup
key::§Symbol → §Void
Dynamic references:	none
Side effect:	Define the bounding box key to be used for pages subsequently tacked on to the catalog. These pages will get equal media boxes in the end, being the smallest that contains all the bounding boxes of the pages in the group.

→ §Void
Dynamic references:	none
Side effect:	Clear the bounding box key to be used for pages subsequently tacked on to the catalog. Pages will get a media box equal to their own bounding box.

setpagelabel
prefix::§String style::§Symbol number::§Integer → §Void
Dynamic references:	none
Side effect:	Change the page labeling properties to use for future pages being added to the state.
All arguments may be omitted, and their names explain their meanings. If omitted, the corresponding property is not changed by the mutator. The parameter style can be any of 'none, 'decimal, 'ROMAN, 'roman, 'ALPHABET, or 'alphabet.

nextpagelabel
→ §String
Dynamic references:	none
Side effect:	None.
Returns the string that would be used as page label for the next page being added to the state.

nextpagenumber
→ §Integer
Dynamic references:	none
Side effect:	None.
Returns the document page number (as opposed to logic page number) for the next page being added to the state.

§•Text

Abstraction:

States of type §•Text are used to combine font properties with strings to paint text.

Construction:

..Shapes..Text..newText

Mutators

• <<
::§TextOperation → §Void
Dynamic references:	none
Side effect:	Append operation.

::§String → §Void
Dynamic references:	none
Side effect:	Append text without kerning.

::§Transform → §Void
Dynamic references:	none
Side effect:	Append move to command.

::§Coords → §Void
Dynamic references:	none
Side effect:	Append newline command followed by relative move.

::§FloatPair → §Void
Dynamic references:	none
Side effect:	Append newline command followed by relative move, interpreting the move in units of ..Shapes..Text..@size.

(•)
The state cannot be peeked.

freeze •
→ §Drawable
Dynamic references:	<The graphics dynamic state> <The text dynamic state>
Produce graphic representation of entered objects.

§•Array

Abstraction:

States of type §•Array are used to create one-dimensional random access arrays.

Construction:

..Shapes..Data..newArray

Mutators

• <<
::§Value → §Void
Dynamic references:	none
Side effect:	Append the new value to the end of the array. The size of the array will increase by one, and if there is not enough memory allocated to hold an array of the new size, memory will be reallocated. To avoid reallocation, it is possible to reserve memory in advance, see §•Array/reserve.

(•)
The state cannot be peeked.

freeze •
→ §Array
Return final state as a value.

size
→ §Integer
Returns the current size of the array. The size may be less than the size of the allocated memory.
See also:	§•Array/resize

resize
size::§Integer fill:void → §Void
Changes the size of the array. If the new size is less than the current size, values at the end of the array are discarded. If the new size is greater than the current size, the array will be padded with the value fill.
See also:	§•Array/size §•Array/reserve

reserve
size::§Integer → §Void
Allocates more memory for the array, if necessary. Use this call to preallocate memory that will be filled later using tack-on operations. Unless size is greater than the size of the currently allocated block of memory, there is no effect. In any case, the size of the array remains unchanged.
See also:	§•Array/resize

set
index::§Integer value → §Void
Change the value in the array at position index so that it becomes value.
See also:	§•Array/get

get
index::§Integer → §Value
Get the value at position index.
See also:	§•Array/set

§•Graph

Abstraction:

States of type §•Graph are used for sequential construction of graphs.

Construction:

§Graph

A §•Graph state is always initialized using an existing §Graph value. In particular, the graph domain of the state is that of the §Graph value. This is illustrated with a short example.

Graph construction using state
Using a §•Graph state. The first state is initialized with an empty graph which just defined the graph domain. Then a second state is used to add more nodes and edges to the graph constructed with the first state.

Source: show/hide — visit
##needs ..Shapes..Data / seq-support ##lookin ..Shapes ##lookin ..Shapes..Data / Helper function for converting a sequence to a string, with elements separated by spaces. / seq_sep_string: \ seq → [seq_string [separate ` ´ seq]] / Initialize a state in the domain of undirected multigraphs. / •dst: [graph undirected:true parallel:true] / Add some nodes. / •dst.[node 'a] •dst.[node 'b] •dst.[node 'c] / Add some edges. / •dst.[edge 'a 'b] •dst.[edge 'b 'a] •dst.[edge 'b 'c] g1: freeze •dst IO..•stdout << `Edges in g1: ´ << [seq_sep_string g1.edges] << "{n} / Add more nodes and edges using an unnamed state. / g2: ( g1 << >>.[node 'd] << >>.[edge 'c 'd] ) IO..•stdout << `Edges in g2: ´ << [seq_sep_string g2.edges] << "{n}

stdout: show/hide
Edges in g1: < undirected edge ( 'a, 'b ) > < undirected edge ( 'a, 'b ) > < undirected edge ( 'b, 'c ) > Edges in g2: < undirected edge ( 'a, 'b ) > < undirected edge ( 'a, 'b ) > < undirected edge ( 'b, 'c ) > < undirected edge ( 'c, 'd ) >

Mutators

§N	Type of node values.
§E	Type of edge values.

• <<
There are no tack-on mutators.

(•)
→ [§Graph §N §E]
Construct a graph value from the internal state.

freeze •
→ [§Graph §N §E]
Construct a graph value from the internal state.

node
key::§GraphKey value:void::( §N ∪ §Void ) partition:void::( §GraphKey ∪ §Void ) → §Void
Dynamic references:	none
Side effect:	Add a node to the graph, compare §NodeData. The default value for value is only allowed when §N is §Void.

edge
source::§GraphKey target::§GraphKey value:void::( §E ∪ §Void ) label:void::( §GraphKey ∪ §Void ) directed:void::( §Boolean ∪ §Void ) → §Void
Dynamic references:	none
Side effect:	Add an edge to the graph, compare §EdgeData. The default value for value is only allowed when §E is §Void.

States of types in this section are used to wrap files for input/output.

§•Ostream

Abstraction:

States of type §•Ostream wrap a file stream for output.

Mutators

• <<
::§Object → §Void
Side effect:	Allow object to produce a textual representation (may not be unique or have anything to do with the value, well behaved object do a reasonable job here), which is appended to the stream.

(•)
The state cannot be peeked.

freeze •
The state cannot be frozen.

All the rest…

§•Debugger §•Ignore §•Random §•Time

§•Ignore

Abstraction:

States of type §•Ignore just ignores everything tacked onto them.

See also:

..Shapes..newIgnore ..Shapes..•ignore

Mutators

• <<
::§Object → §Void
Side effect:	Nothing.

(•)
The state cannot be peeked.

freeze •
The state cannot be frozen.

§•Time

Abstraction:

States of type §•Time represent the ever-changing time.

See also:

..Shapes..•time

Mutators

• <<
There are no tack-on mutators.

(•)
→ §ChronologicalTime
Dynamic references:	none
Get current time.

freeze •
The state cannot be frozen.

§•Random

Abstraction:

Random number generator state.

A random number generator state gives direct access to the random integers generated by the generator. Sampling from other distributions is implemented as non-pure functions, such as ball3D, acting on the state.

Mutators

• <<
There are no tack-on mutators.

(•)
→ §Integer
Dynamic references:	none
Get raw sample from the random number generator.
See also:	ball1D ball2D ball3D

freeze •
The state cannot be frozen.

§•Debugger

Abstraction:

States of type §•Debugger let the user interact with the compiler.

In the interactive mode of the compiler, a state of type §•Debugger is present in every environment for interactive evaluation. This state is always named •db, and there is no way to create other states. See interactive.html for a more pedagogical treatment of the actual use of §•Debugger states.

Mutators

• <<
There are no tack-on mutators.

(•)
The state cannot be peeked.

freeze •
The state cannot be frozen.

resume alias: r
result:expr → §Void
Side effect:	Invokes ..Shapes..Debug..C—resume.
Invokes the continuation ..Shapes..Debug..C—resume with the argument result. If result is not provided, the expression where evaluation was interrupted is made the next expression to evaluate (with the corresponding lexical and dynamic environments), rather than actually passing the corresponding thunk expr to the continuation. The special treatment of the default for result also includes making sure that a breakpoint is not triggered immediately, which is very convenient if evaluation was previously interrupted at a breakpoint. For instance, •db.[resume void] shall be equivalent to (escape_continue resume void) and •db.[resume] (at a breakpoint) shall be similar to •db.[breakIgnore] (escape_continue resume expr)

top_repl
result:void → §Void
Side effect:	Invokes ..Shapes..Debug..C—top_repl.
Invokes the continuation ..Shapes..Debug..C—top_repl with the argument result. Note that while the default value for result in §•Debugger/resume depends on where evaluation was interrupted, the default value here is always the same.

backtrace alias: t
→ §String
The returned string will display the backtrace when printed by the interactive continuation. Here, a backtrace refers to the chain of continuations starting from the current continuation. When the chain reaches an interactive continuation, it is continued at its ..Shapes..Debug..C—resume.

env alias: e
→ §String
The returned string will display the lexical environment at the point of interaction.

dyn alias: d
→ §String
The returned string will display the dynamic environment at the point of interaction.

breakList alias: bl

→ §String

The returned string displays information about the currently existing breakpoints. The first column lists the current index of a breakpoint, but note that this number may change over time as breakpoints are cleared or created. The second column (within parentheses) tells if the breakpoint is enabled (on) or not (off), optionally followed by other information about the breakpoint. Following a colon, each line ends with the breakpoint location.

breakAt alias: ba
file::§String line::§Integer column:0::§Integer enable::§Boolean → §Void
Side effect:	Enable, disable, or toggle breakpoint at a given source location.
If enable is not provided, it defaults to toggle the breakpoint. The expression pointed out is defined as the expression with the smallest source location that includes the given position.

breakIn alias: bi
function::§UserFunction enable::§Boolean → §Void
Side effect:	Enable, disable, or toggle breakpoint at the body of a function.
If enable is not provided, it defaults to toggle the breakpoint.

breakIgnore alias: bg
index:0::§Integer count:1::§Integer → §Void
Side effect:	Set count for how many times a breakpoint shall be ignored.
The default value for index refers to the expression where evaluation was interrupted. Any other value is interpreted by the indices listed by §•Debugger/breakList.

breakClear alias: bc
index:0::§Integer → §Void
Side effect:	Remove breakpoint completely.
The default value for index refers to the expression where evaluation was interrupted. Any other value is interpreted by the indices listed by §•Debugger/breakList.

breakClearAll alias: bC
→ §Void
Side effect:	Remove all breakpoints completely.

step alias: s
count:1::§Integer → §Void
Continue program evaluation until reaching an expression which is not lexically inside the current expression. The argument count tells how many times to continue evaluation before actually interrupting again.
See also:	§•Debugger/resume

stepe alias: se
count:1::§Integer → §Void
Step program evaluation to the next expression count times, and then interrupt evaluation.
See also:	§•Debugger/resume

stepc alias: sc
→ §Void
Step program evaluation to the next child expression of the current expression. Uses temporary breakpoints internally. If no breakpoints are set, the stepping is aborted. The ignore count (see §•Debugger/breakIgnore) is not affected, which means that it can be used to avoid stopping in some of the expressions where temporary breakpoints are set.
See also:	§•Debugger/steps

steps alias: ss
→ §Void
Step program evaluation to the next sibling expression of the current expression. Uses temporary breakpoints internally, compare with §•Debugger/stepc.

contUp alias: cu
count:1::§Integer → §Void
Side effect:	Update to be consistent with a new ..Shapes..Debug..C—resume.
Replace the current interactive context with one where ..Shapes..Debug..C—resume is found by following the backtrace count steps up. Since this mutator has side effects on the involved state, it is not possible to go past the next interactive continuation in the backtrace. (Doing so would break the rule that only states appearing in an expression may be modified by that expression. Exactly reaching the next interactive continuation is possible since it is then possible to reuse that interactive context as is.)
See also:	§•Debugger/resume §•Debugger/backtrace §•Debugger/contExit

contExit alias: ce
count:1::§Integer → §Void
Exit the current interactive context by replacing it with an interactive continuation higher up in the backtrace. Unlike §•Debugger/contUp this mutator has no side effects on the state in the new interactive context, which explains why this mutator can go past the next interactive continuation in the backtrace.
See also:	§•Debugger/resume §•Debugger/backtrace §•Debugger/contUp