Automaton - Documentation

Fcnew Automaton($container, rows, cols, stepFn, renderFn, sopt)

A prototype to represent a cellular automaton.

The automaton uses a lower-right quadrant zero-indexed coordinate system. The horizontal axis is labeled the x axis and numbered from left to right in whole number increments. The vertical axis is labeled the y axis, and numbered from top to bottom in whole-number increments. When describing a cell it's x coordinate is specified first, and its y coordinate second. Hence, the cell in the top-left corner has the coordinates (0, 0), the second cell in the top row has the coordiantes (1, 0), and the cell in the second cell on the left-most column has the coordinates (0, 1).

The automaton will be represented within the DOM by an automatically generated table, with the cells that make up the automaton as table cells. The table will be generated within a given container.

The constructor expects to be passed a jQuery object representing a sigle container element. That element will be emptied, and the table representing the automaton will then be added to it. The class bartificer-ca-container will be added to the conainer, and the generated table will have the class bartificer-ca-automaton added. The table. A reference to the constructed object will be added to both the container and the table as the data attribute data-bartificer-object (bartificerObject from JavaScipt's point of view).

Parameters:

Name	Type	Attributes	Description
`$container`	`jQuerySingleContainer`		A jQuery object representing the container that will be converted into the cellular automaton.
`rows`	`GridDimension`		the number of rows to build the automaton with.
`cols`	`GridDimension`		the number of columns to build the automaton with.
`stepFn`	`stepFunction`		a callback that will be used to calcualte the next state of each cell for each step the automaton takes. it's next state.
`renderFn`	`renderFunction`		a callback that will be used to render the state of each cell.
`s`	`CellState` \| `Array.<CellState>` \| `initialisationFunction`	<optional>	the automaton's initial state. The state can be specified in three different ways: a single state - each cell in the automaton will be initialised with this state. an array of states. The array must have the same dimensions as the automaton. an intialisation callback. The callback will be used to calculate the initial state of each cell given its coordinates.

Throws:

An error is thrown if the first five arguments are not present and valid, and if the sixth argument is present but not valid.

Type

TypeError
An error is thrown if the table has already been initialised as an automaton.

Type

Error

Methods

F$container() → {jQuerySingleContainer}

A read-only accessor function to access a reference to the jQuery object representing the container that holds the table that represents the automaton within the DOM.

Throws:

An error is thrown if the accessor is called with arguments.
Type Error

Returns:

Type:: jQuerySingleContainer

F$table() → {jQuerySingleTable}

A read-only accessor function to access a reference to the jQuery object representing the table that represents the automaton within the DOM.

Throws:

An error is thrown if the accessor is called with arguments.
Type Error

Returns:

Type:: jQuerySingleTable

FautoStepIntervalMS(msopt) → {IntervalMS}

Get or set the number of milliseconds between automatic steps.

Parameters:

Name	Type	Attributes	Description
`ms`	`IntervalMS`	<optional>	if passed, the number of milliseconds to pause between automatic steps.

Throws:

If an argument is passed and it's not valid, an error is thrown.
Type TypeError

Returns:

Type:: IntervalMS

Fcell(x, y) → {bartificer.ca.Cell}

A function for accessing a given cell within the automaton.

Parameters:

Name	Type	Description
`x`	`GridCoordinate`	the x coordinate of the requested cell.
`y`	`GridCoordinate`	the y coordinate of the requested cell.

Throws:

A type error is thrown if invalid arguments are passed.

Type

TypeError
A range error is thrown if the coordinates specify a cell beyond the edges of the automaton.

Type

RangeError

Returns:

Type:: bartificer.ca.Cell

a reference to the object representing the requested cell.

FcellNeighbourStates(x, y) → {Array.<CellState>}

Get the states of a cell's neighbouring cells.

Parameters:

Name	Type	Description
`x`	`GridCoordinate`	the x coordinate of the requested cell.
`y`	`GridCoordinate`	the y coordinate of the requested cell.

Throws:

A type error is thrown if invalid arguments are passed.

Type

TypeError
A range error is thrown if the coordinates specify a cell beyond the edges of the automaton.

Type

RangeError

Returns:

Type:: Array.<CellState>

Returns an array of eight cell states where the state at index zero is that from the cell directly above the current cell, and then moving clockwise from there. If a cell is at an edge, the indexes for the non-existent positions will still be included in the array, but they will have the value null.

FcellState(x, y) → {CellState}

A function for accessing the current state of a given cell within the automaton.

Parameters:

Name	Type	Description
`x`	`GridCoordinate`	the x coordinate of the requested cell.
`y`	`GridCoordinate`	the y coordinate of the requested cell.

Throws:

A type error is thrown if invalid arguments are passed.

Type

TypeError
A range error is thrown if either of the coordinates specify a cell who's coordiantes are beyond the edges of the automaton.

Type

RangeError

Returns:

Type:: CellState

The current state of the cell at the given coordinates.

Fcols() → {GridDimension}

A read-only accessor function to get the number of columns within the automaton.

Throws:

An error is thrown if the accessor is called with arguments.
Type Error

Returns:

Type:: GridDimension

Fdimensions() → {Array.<number>}

A read-only accessor function to return both the width and height of the grid, i.e. the number of rows and columns.

Throws:

An error is thrown if the accessor is called with arguments.
Type Error

Returns:

Type:: Array.<number>

An array of two numbers, the width (number of cols), and height (number of rows).

Fgeneration() → {number}

A read-only accessor function to get the automaton's current generation number.

Throws:

An error is thrown if the accessor is called with arguments.
Type Error

Returns:

Type:: number

FgenerationChange(fnopt) → {bartificer.ca.CellularAutomaton}

A function for adding a callback to be executed when ever the generation changes, or, to execute all registered geneation-change callbacks.

When called with no parameters all callbacks are execute, when called with a callback as the first parameter, that callback is registered.

Parameters:

Name	Type	Attributes	Description
`fn`	`function`	<optional>

Throws:

An error is thrown if called with parameters, and the first parameter is not a callback.
Type TypeError

Returns:

Type:: bartificer.ca.CellularAutomaton

Returns a reference to self.

FrenderFunction() → {renderFunction}

A read-only accessor function to get a reference to the automaton's render function.

Throws:

An error is thrown if the accessor is called with arguments.
Type Error

Returns:

Type:: renderFunction

Frows() → {GridDimension}

A read-only accessor function to get the number of rows within the automaton.

Throws:

An error is thrown if the accessor is called with arguments.
Type Error

Returns:

Type:: GridDimension

FsetState(newStateopt) → {bartificer.ca.CellularAutomaton}

Set the current state of the automaton as a whole.

Parameters:

Name Type Attributes Description

Name	Type	Attributes	Description
`newState`	`CellState` \| `Array.<CellState>` \| `initialisationFunction`	<optional>	a new state for the automaton. The state can be specified in three different ways: a single state - each cell in the automaton will be initialised with this state. an array of states. The array must have the same dimensions as the automaton. an intialisation callback. The callback will be used to calculate the initial state of each cell given its coordinates.

newState

CellState | Array.<CellState> | initialisationFunction

a new state for the automaton. The state can be specified in three different ways:

a single state - each cell in the automaton will be initialised with this state.
an array of states. The array must have the same dimensions as the automaton.
an intialisation callback. The callback will be used to calculate the initial state of each cell given its coordinates.

Throws:

An error is thrown if an invalid new state is passed.
Type TypeError

Returns:

Type:: bartificer.ca.CellularAutomaton

Returns a reference to self.

Fstart(msopt) → {bartificer.ca.CellylarAutomaton}

Start automatically stepping the automaton.

If the automaton is already in automatic mode, this function does nothing.

Parameters:

Name	Type	Attributes	Description
`ms`	`IntervalMS`	<optional>	An optional interval between steps in milliseconds.

Throws:

A type error is thrown if the optoinal parameter is present, but not a whole number greater than zero.
Type TypeError

Returns:

Type:: bartificer.ca.CellylarAutomaton

Returns a reference to self.

Fstep() → {bartificer.ca.CellylarAutomaton}

Step the automaton forward by one step.

Returns:

Type:: bartificer.ca.CellylarAutomaton

Returns a reference to self.

FstepFunction() → {stepFunction}

A read-only accessor function to get a reference to the automaton's step function.

Throws:

An error is thrown if the accessor is called with arguments.
Type Error

Returns:

Type:: stepFunction

Fstop() → {bartificer.ca.CellylarAutomaton}

Stop automatically stepping the automaton.

Returns:

Type:: bartificer.ca.CellylarAutomaton

Returns a reference to self.