# Guppy

An instance of Guppy. Calling `Guppy(id)` with the ID of an existing editor will simply return that instance.

## Constructor

#### new Guppy(element)

Source:
  - guppy.js, line 17

##### Parameters:

Name | Type | Description
--- | --- | ---
`element` | string | Node | The string id or the Dom Node of the element that should be converted to an editor.

### Members

#### engine :Engine

Source:
  - guppy.js, line 61

##### Type:

- Engine

### Methods

#### (static) add_global_symbol(name, symbol, templateopt)

Source:
  - guppy.js, line 162

Add a symbol to all instances of the editor

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`name` | string |  | The name of the symbol to add. This is also the string that will be autoreplaced with the symbol.
`symbol` | Object |  | If `template` is present, this is just the template arguments. Otherwise, it is the complete symbol specification ###### Properties
Name | Type | Attributes | Description
--- | --- | --- | ---
`output` | Object |  | Key/value pairs where the key is the output type (such as "latex" or "asciimath") and the value is the string by which the output will be rendered in that format. In this string, {$n} will be substituted with the rendering of the nth argument. If the nth argument is a d-dimensional list, then the argument should be specified as {$n{sep_1}{sep_2}...{sep_d}} where sep_i will be the separator used to separate entries in the ith dimension. Note that keys are not necessary to describe the AST or plain-text outputs.
`keys` | Array |  | A list of strings representing keystrokes that can be used to trigger the insertion of this symbol. For example, `"^" or`"shift+up"`for the`exponential` symbol.
`attrs` | Object |  | A specification of the attributes of the symbol ###### Properties
Name | Type | Description
--- | --- | ---
`type` | string | A longer description of the symbol type, suitable for searching and text rendering.
`group` | string | The group in which to place this symbol (for OSK)
`input` | Object | <optional> | If the symbol should subsume part of the existing content of the editor (as in, for example, the case of exponent), this object will contain the (1-based) index of the argument in which that content should be placed.
`ast` | Object | <optional> | Modifies the default construction of an entry in the AST for this symbol. ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`type` | Object | <optional> | `"operator"` | The type of symbol for AST purposes. Can be "name" (meaning this symbol represents a variable, as in the case of pi), "number" (meaning this symbol is a literal value), "operator" (meaning this symbol is a function or otherwise takes arguments (as in cos or +), or "pass" (meaning this symbol's first argument will be used as its AST entry, as in the case of brackets/parentheses).
`args` | Array.<Object> | <optional> | A list of specifications, one for each argument ###### Properties
Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`down` | string | <optional> |  | The index of the argument to jump to when the "down" arrow is pressed in this argument
`up` | string | <optional> |  | The index of the argument to jump to when the "up" arrow is pressed in this argument
`small` | string | <optional> | `"no"` | "yes" if the symbol is small (as in an exponent)
`name` | string | <optional> |  | The name of this particular argument (suitable for searching)
`bracket` | string | <optional> | `"no"` | "yes" if brackets should automatically be rendered around this argument when they might be needed to disambiguate.
`delete` | string | <optional> |  | If present, when the "backspace" key is pressed at the beginning of this argument, the symbol will be deleted and replaced with the argument whose index is specified in this parameter. For example, the second argument of an exponent has this value set to "1", so that when the exponent is deleted, the base remains.
`mode` | string | <optional> | `"math"` | Change the mode of an argument. Can be "text" (meaning the argument will be editable as and rendered as plain text), "symbol" (meaning the argument will specify a symbol name and will complete to an actual symbol when this is entered--only used for the backslash symbol), or "math" (the default)
`is_bracket` | string | <optional> | `"no"` | Set to "yes" if the symbol is itself a bracket/parenthesis equivalent.
`template` | string | <optional> | The name of the template to use

#### (static) configure(name, val)

Source:
  - guppy.js, line 204

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | string | The name of the setting to configure. Can be "xml_content", "autoreplace", "blank_caret", "empty_content", "blacklist", "buttons", or "cliptype"
`val` | Object | The value associated with the named setting: "xml_content": An XML string with which to initialise the editor's state. (Defaults to "".) "autoreplace": A string describing how to autoreplace typed text with symbols: "auto" (default): Replace symbls greedily "whole": Replace only entire tokens "delay": Same as "whole", but with 200ms delay before replacement "blank_caret": A LaTeX string that specifies what the caret should look like when in a blank spot. If `""`, the default caret is used. "empty_content": A LaTeX string that will be displayed when the editor is both inactive and contains no content. (Defaults to "\color{red}{[?]}") "blacklist": A list of string symbol names, corresponding to symbols that should not be allowed in this instance of the editor. "buttons": A list of strings corresponding to the helper buttons that should be displayed in the editor; should be a subset of ["osk","settings","symbols","controls"]] "cliptype": A string describing what gets placed on the system clipboard when content is copied from the editor. "text": Use plain-text editor content "latex": Use LaTeX rendering of editor content

#### (static) event(name, handler)

Source:
  - guppy.js, line 290

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | string | The name of an event. Can be: change - Called when the editor's content changes. Argument will be a dictionary with keys `old` and `new` containing the old and new documents, respectively. left_end - Called when the cursor is at the left-most point and a command is received to move the cursor to the left (e.g., via the left arrow key). Argument will be null. right_end - Called when the cursor is at the right-most point and a command is received to move the cursor to the right (e.g., via the right arrow key). Argument will be null. done - Called when the enter key is pressed in the editor. completion - Called when the editor outputs tab completion options. Argument is a dictionary with the key `candidates`, a list of the options for tab-completion. debug - Called when the editor outputs some debug information. Argument is a dictionary with the key `message`. error - Called when the editor receives an error. Argument is a dictionary with the key `message`. focus - Called when the editor is focused or unfocused. Argument will have a single key `focused` which will be `true` or `false` according to whether the editor is newly focused or newly unfocused (respectively).
`handler` | function | The function that will be called to handle the given event

#### (static) remove_global_symbol(name)

Source:
  - guppy.js, line 177

Remove a symbol from all instances of the editor

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | string | The name of the symbol to remove

#### (static) render_all(type, delimopt, root_nodeopt)

Source:
  - guppy.js, line 242

Render all guppy documents on the page.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`type` | string |  | The type of content to render
`delim` | string | <optional> | The string to delimit mathematical symbols
`root_node` | string | <optional> | The DOM Element object within which to do the rendering

#### (static) use_osk(oskopt)

Source:
  - guppy.js, line 309

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`osk` | GuppyOSK | <optional> | A GuppyOSK object to use for the on-screen keyboard if one is desired

#### activate()

Source:
  - guppy.js, line 740

Focus this instance of the editor

#### asciimath()

Source:
  - guppy.js, line 617

Get the content of the editor in AsciiMath.

#### configure(name, val)

Source:
  - guppy.js, line 227

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | string | The name of the setting to configure. Can be "xml_content", "autoreplace", "blank_caret", "empty_content", "blacklist", "buttons", or "cliptype"
`val` | Object | The value associated with the named setting: "xml_content": An XML string with which to initialise the editor's state. (Defaults to "".) "autoreplace": A string describing how to autoreplace typed text with symbols: "auto" (default): Replace symbls greedily "whole": Replace only entire tokens "delay": Same as "whole", but with 200ms delay before replacement "blank_caret": A LaTeX string that specifies what the caret should look like when in a blank spot. If `""`, the default caret is used. "empty_content": A LaTeX string that will be displayed when the editor is both inactive and contains no content. (Defaults to "\color{red}{[?]}") "blacklist": A list of string symbol names, corresponding to symbols that should not be allowed in this instance of the editor. "buttons": A list of strings corresponding to the helper buttons that should be displayed in the editor; should be a subset of ["osk","settings","symbols","controls"]] "cliptype": A string describing what gets placed on the system clipboard when content is copied from the editor. "text": Use plain-text editor content "latex": Use LaTeX rendering of editor content

#### deactivate()

Source:
  - guppy.js, line 756

Unfocus this instance of the editor

#### doc()

Source:
  - guppy.js, line 625

Get the Doc object representing the editor's contents.

#### equations()

Source:
  - guppy.js, line 600

Get the content of the editor as a list of equations, serialised using JSON. For example, `x < y = z` will be returned as `[["<", [["var", "x"], ["var", "y"]]],["=", [["var", "y"], ["var", "z"]]]]

#### evaluate(evaluatorsopt)

Source:
  - guppy.js, line 669

Recursively evaluate the syntax tree of the editor's contents using specified functions.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`evaluators` | Object | <optional> | An object with a key for each possible symbol type ("exponential", "integral", etc.) whose values are functions that will be applied whenever that symbol is encountered in the syntax tree. These functions take a single argument, `args`, which is a list of the results of evaluating that symbol's arguments.

##### Returns:

- Whatever the `evaluators` function for the root symbol in the syntax tree returns.

#### event(name, handler)

Source:
  - guppy.js, line 259

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | string | The name of an event. Can be: change - Called when the editor's content changes. Argument will be a dictionary with keys `old` and `new` containing the old and new documents, respectively. left_end - Called when the cursor is at the left-most point and a command is received to move the cursor to the left (e.g., via the left arrow key). Argument will be null. right_end - Called when the cursor is at the right-most point and a command is received to move the cursor to the right (e.g., via the right arrow key). Argument will be null. done - Called when the enter key is pressed in the editor. completion - Called when the editor outputs tab completion options. Argument is a dictionary with the key `candidates`, a list of the options for tab-completion. debug - Called when the editor outputs some debug information. Argument is a dictionary with the key `message`. error - Called when the editor receives an error. Argument is a dictionary with the key `message`. focus - Called when the editor is focused or unfocused. Argument will have a single key `focused` which will be `true` or `false` according to whether the editor is newly focused or newly unfocused (respectively).
`handler` | function | The function that will be called to handle the given event

#### func(evaluatorsopt) → {function}

Source:
  - guppy.js, line 650

Get the content of the editor as a Javascript function, with user-supplied interpretations of the various symbols. If not supplied, default interpretations will be given for the following symbols: `*,+,/,-,^,sqrt,sin,cos,tan,log`

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`evaluators` | Object | <optional> | An object with a key for each possible symbol type ("exponential", "integral", etc.) whose values are functions. These functions take in a single argument, `args`, which is an array of that symbol's arguments, and should return a function that takes in an object argument `vars`. In this inner function, to compute e.g. the sum of the first and second arguments, you would do `args[0](vars)+args[1](vars)`. This function should return the result of that symbol's operation.

##### Returns:

- Returns a function that takes in an object with a key for each variable in the expression and whose values are the values that will be passed in for those variables. In addition, this function is augmented with a `vars` member which is a list of the variables that appear in the expression.

Type
  function

#### import_latex(text)

Source:
  - guppy.js, line 712

Set the content of the document from input text in "semantic LaTeX" format. That is, all functions are represented as `\funcname{arg1}{arg2}`. For example, `\defintegral{1}{2}{x^2}{x}`.

##### Parameters:

Name | Type | Description
--- | --- | ---
`text` | String | A string representing the document to import.

#### import_syntax_tree(tree)

Source:
  - guppy.js, line 732

Import a syntax tree from a JSON object formatted as outputted by `guppy.syntax_tree()`.

##### Parameters:

Name | Type | Description
--- | --- | ---
`tree` | Object | A JSON object representing the syntax tree to import.

#### import_text(text)

Source:
  - guppy.js, line 700

Set the content of the document from text in the format outputted by `guppy.text()`.

##### Parameters:

Name | Type | Description
--- | --- | ---
`text` | String | A string representing the document to import.

#### import_xml(xml)

Source:
  - guppy.js, line 723

Set the content of the document from XML in the format outputted by `guppy.xml()`.

##### Parameters:

Name | Type | Description
--- | --- | ---
`xml` | String | An XML string representing the document to import.

#### latex()

Source:
  - guppy.js, line 575

Get the content of the editor as LaTeX

#### render(updatedopt)

Source:
  - guppy.js, line 557

Render the document

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`updated` | boolean | <optional> | `false` | Whether there have been visible changes to the document (i.e. that affect the positions of elements)

#### symbols_used(groupsopt)

Source:
  - guppy.js, line 683

Get a list of the symbols used in the document, in order of appearance, with each kind of symbol appearing only once. For example, a document representing `sin(x^3)+sqrt(x^2+x)` will have symbols `["sin","exponential","square_root"]`.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`groups` | Array.<String> | <optional> | A list of the groups whose symbols may be included in the output. If absent, all symbols in the document will be returned.

#### syntax_tree()

Source:
  - guppy.js, line 591

Get the content of the editor as a syntax tree, serialised using JSON

#### text()

Source:
  - guppy.js, line 608

Get the content of the editor in a parseable text format.

#### vars()

Source:
  - guppy.js, line 691

Get a list of the variable names used in the document.

#### xml()

Source:
  - guppy.js, line 583

Get the content of the editor as XML