mathjs 10.5.2 → 10.5.3

package/docs/expressions/html_classes.md

@@ -1,38 +0,0 @@
-# HTML output
-
-The expression parser can output a HTML string, where every `Node` is
-transformed into a `<span>` element with semantic class names. Each class
-name begins with the `math-` prefix. These class names can be used in CSS to
-highlight the syntax or change the default layout (e.g. spaces around operators).
-
-## Available class names
-
-- `math-number`
-- `math-string`
-- `math-boolean` (`true` and `false`)
-- `math-undefined`
-- `math-function` (function names)
-- `math-parameter` (function parameters)
-- `math-property` (object members)
-- `math-symbol` (variables, units and built-in constants)
-  - `math-null-symbol` (`null`)
-  - `math-nan-symbol` (`NaN`)
-  - `math-infinity-symbol` (`Infinity`)
-  - `math-imaginary-symbol` (`i`)
-- `math-operator`
-  - `math-unary-operator`
-    - `math-lefthand-unary-operator`
-    - `math-righthand-unary-operator`
-  - `math-binary-operator`
-    - `math-explicit-binary-operator`
-    - `math-implicit-binary-operator` (empty element)
-  - `math-assignment-operator`
-    - `math-variable-assignment-operator` (`=`)
-    - `math-property-assignment-operator` (`:` in objects)
-  - `math-accessor-operator` (`.` in objects)
-  - `math-range-operator` (`:` in ranges)
-- `math-parenthesis`
-  -`math-round-parenthesis` (`(` and `)`)
-  -`math-square-parenthesis` (`[` and `]`)
-  -`math-curly-parenthesis` (`{` and `}`)
-- `math-separator` (�,`, `;` and <code>&lt;br /&gt;</code>)

package/docs/expressions/index.md

@@ -1,21 +0,0 @@
-# Expressions
-
-Math.js contains a flexible and easy to use expression parser.
-The parser supports all data types, functions and constants available in math.js.
-
-Whilst the math.js library is aimed at JavaScript developers, the expression
-parser is aimed at end users: mathematicians, engineers, students, pupils.
-The syntax of the expression parser differs from JavaScript and the low-level
-math.js library.
-
-This section is divided in the following pages:
-
-- [Parsing and evaluation](parsing.md) describes how to parse and
-  evaluate expressions with math.js.
-- [Syntax](syntax.md) describes how to write expressions.
-- [Expression trees](expression_trees.md) explains how to parse an expression into an
-  expression tree, and use this to analyse and manipulate the expression.
-- [Algebra](algebra.md) describing symbolic computation in math.js.
-- [Customization](customization.md) describes how to customize processing and
-  evaluation of expressions.
-- [Security](security.md) about security risks of executing arbitrary expressions.

package/docs/expressions/parsing.md

@@ -1,224 +0,0 @@
-# Expression parsing and evaluation
-
-Expressions can be parsed and evaluated in various ways:
-
-- Using the function [`math.evaluate(expr [,scope])`](#evaluate).
-- Using the function [`math.compile(expr)`](#compile).
-- Using the function [`math.parse(expr)`](#parse).
-- By creating a [parser](#parser), `math.parser()`, which contains a method
-  `evaluate` and keeps a scope with assigned variables in memory.
-
-
-## Evaluate
-
-Math.js comes with a function `math.evaluate` to evaluate expressions. Syntax:
-
-```js
-math.evaluate(expr)
-math.evaluate(expr, scope)
-math.evaluate([expr1, expr2, expr3, ...])
-math.evaluate([expr1, expr2, expr3, ...], scope)
-```
-
-Function `evaluate` accepts a single expression or an array with
-expressions as the first argument and has an optional second argument
-containing a scope with variables and functions. The scope can be a regular
-JavaScript Object, or Map. The scope will be used to resolve symbols, and to write
-assigned variables or function.
-
-The following code demonstrates how to evaluate expressions.
-
-```js
-// evaluate expressions
-math.evaluate('sqrt(3^2 + 4^2)')        // 5
-math.evaluate('sqrt(-4)')               // 2i
-math.evaluate('2 inch to cm')           // 5.08 cm
-math.evaluate('cos(45 deg)')            // 0.7071067811865476
-
-// provide a scope
-let scope = {
-    a: 3,
-    b: 4
-}
-math.evaluate('a * b', scope)           // 12
-math.evaluate('c = 2.3 + 4.5', scope)   // 6.8
-scope.c                                 // 6.8
-```
-
-
-## Compile
-
-Math.js contains a function `math.compile` which compiles expressions
-into JavaScript code. This is a shortcut for first [parsing](#parse) and then
-compiling an expression. The syntax is:
-
-```js
-math.compile(expr)
-math.compile([expr1, expr2, expr3, ...])
-```
-
-Function `compile` accepts a single expression or an array with
-expressions as the argument. Function `compile` returns an object with a function
-`evaluate([scope])`, which can be executed to evaluate the expression against an
-(optional) scope:
-
-```js
-const code = math.compile(expr)       // compile an expression
-const result = code.evaluate([scope]) // evaluate the code with an optional scope
-```
-
-An expression needs to be compiled only once, after which the
-expression can be evaluated repeatedly and against different scopes.
-The optional scope is used to resolve symbols and to write assigned
-variables or functions. Parameter [`scope`](#scope) can be a regular Object, or Map.
-
-Example usage:
-
-```js
-// parse an expression into a node, and evaluate the node
-const code1 = math.compile('sqrt(3^2 + 4^2)')
-code1.evaluate()  // 5
-```
-
-
-## Parse
-
-Math.js contains a function `math.parse` to parse expressions into an
-[expression tree](expression_trees.md). The syntax is:
-
-```js
-math.parse(expr)
-math.parse([expr1, expr2, expr3, ...])
-```
-
-Function `parse` accepts a single expression or an array with
-expressions as the argument. Function `parse` returns a the root node of the tree,
-which can be successively compiled and evaluated:
-
-```js
-const node = math.parse(expr)         // parse expression into a node tree
-const code = node.compile()           // compile the node tree
-const result = code.evaluate([scope]) // evaluate the code with an optional scope
-```
-
-The API of nodes is described in detail on the page
-[Expression trees](expression_trees.md).
-
-An expression needs to be parsed and compiled only once, after which the
-expression can be evaluated repeatedly. On evaluation, an optional scope
-can be provided, which is used to resolve symbols and to write assigned
-variables or functions. Parameter [`scope`](#scope) is a regular Object or Map.
-
-Example usage:
-
-```js
-// parse an expression into a node, and evaluate the node
-const node1 = math.parse('sqrt(3^2 + 4^2)')
-const code1 = node1.compile()
-code1.evaluate() // 5
-
-// provide a scope
-const node2 = math.parse('x^a')
-const code2 = node2.compile()
-let scope = {
-    x: 3,
-    a: 2
-}
-code2.evaluate(scope) // 9
-
-// change a value in the scope and re-evaluate the node
-scope.a = 3
-code2.evaluate(scope) // 27
-```
-
-Parsed expressions can be exported to text using `node.toString()`, and can
-be exported to LaTeX using `node.toTex()`. The LaTeX export can be used to
-pretty print an expression in the browser with a library like
-[MathJax](https://www.mathjax.org/). Example usage:
-
-```js
-// parse an expression
-const node = math.parse('sqrt(x/x+1)')
-node.toString()   // returns 'sqrt((x / x) + 1)'
-node.toTex()      // returns '\sqrt{ {\frac{x}{x} }+{1} }'
-```
-
-
-## Parser
-
-In addition to the static functions [`math.evaluate`](#evaluate) and
-[`math.parse`](#parse), math.js contains a parser with functions `evaluate` and
-`parse`, which automatically keeps a scope with assigned variables in memory.
-The parser also contains some convenience functions to get, set, and remove
-variables from memory.
-
-A parser can be created by:
-
-```js
-const parser = math.parser()
-```
-
-The parser contains the following functions:
-
-- `clear()`
-  Completely clear the parser's scope.
-- `evaluate(expr)`
-  Evaluate an expression. Returns the result of the expression.
-- `get(name)`
-  Retrieve a variable or function from the parser's scope.
-- `getAll()`
-  Retrieve a map with all defined a variables from the parser's scope.
-- `remove(name)`
-  Remove a variable or function from the parser's scope.
-- `set(name, value)`
-  Set a variable or function in the parser's scope.
-
-The following code shows how to create and use a parser.
-
-```js
-// create a parser
-const parser = math.parser()
-
-// evaluate expressions
-parser.evaluate('sqrt(3^2 + 4^2)')      // 5
-parser.evaluate('sqrt(-4)')             // 2i
-parser.evaluate('2 inch to cm')         // 5.08 cm
-parser.evaluate('cos(45 deg)')          // 0.7071067811865476
-
-// define variables and functions
-parser.evaluate('x = 7 / 2')            // 3.5
-parser.evaluate('x + 3')                // 6.5
-parser.evaluate('f(x, y) = x^y')        // f(x, y)
-parser.evaluate('f(2, 3)')              // 8
-
-// get and set variables and functions
-const x = parser.get('x')               // x = 7
-const f = parser.get('f')               // function
-const g = f(3, 3)                       // g = 27
-parser.set('h', 500)
-parser.evaluate('h / 2')                // 250
-parser.set('hello', function (name) {
-    return 'hello, ' + name + '!'
-})
-parser.evaluate('hello("user")')        // "hello, user!"
-
-// clear defined functions and variables
-parser.clear()
-```
-
-## Scope
-
-The scope is a data-structure used to store and lookup variables and functions defined and used by expressions.
-
-It is passed to mathjs via calls to [`math.evaluate`](#evaluate) or `simplify`.
-
-For ease of use, it can be a Plain Javascript Object; for safety it can be a plain `Map` and for flexibility, any object that has
-the methods `get`/`set`/`has`/`keys`, seen on `Map`.
-
-Some care is taken to mutate the same object that is passed into mathjs, so they can collect the definitions from mathjs scripts and expressions.
-
-`evaluate` will fail if the expression uses a blacklisted symbol, preventing mathjs expressions to escape into Javascript. This is enforced by access to the scope.
-
-For less reliance on this blacklist, scope can also be a `Map`, which allows mathjs expressions to define variables and functions of any name.
-
-For more, see [examples of custom scopes](../../examples/advanced/custom_scope_objects.js).

package/docs/expressions/security.md

@@ -1,89 +0,0 @@
-# Security
-
-Executing arbitrary expressions like enabled by the expression parser of
-mathjs involves a risk in general. When you're using mathjs to let users
-execute arbitrary expressions, it's good to take a moment to think about
-possible security and stability implications, especially when running
-the code server side.
-
-## Security risks
-
-A user could try to inject malicious JavaScript code via the expression
-parser. The expression parser of mathjs offers a sandboxed environment
-to execute expressions which should make this impossible. It's possible
-though that there are unknown security vulnerabilities, so it's important
-to be careful, especially when allowing server side execution of
-arbitrary expressions.
-
-The expression parser of mathjs parses the input in a controlled
-way into an expression tree or abstract syntax tree (AST).
-In a "compile" step, it does as much as possible preprocessing on the
-static parts of the expression, and creates a fast performing function
-which can be used to evaluate the expression repeatedly using a
-dynamically passed scope.
-
-The parser actively prevents access to JavaScripts internal `eval` and
-`new Function` which are the main cause of security attacks. Mathjs
-versions 4 and newer does not use JavaScript's `eval` under the hood.
-Version 3 and older did use `eval` for the compile step. This is not
-directly a security issue but results in a larger possible attack surface.
-
-When running a node.js server, it's good to be aware of the different
-types of security risks. The risk whe running inside a browser may be
-limited though it's good to be aware of [Cross side scripting (XSS)](https://www.wikiwand.com/en/Cross-site_scripting) vulnerabilities. A nice overview of
-security risks of a node.js servers is listed in an article [Node.js security checklist](https://blog.risingstack.com/node-js-security-checklist/) by Gergely Nemeth.
-
-### Less vulnerable expression parser
-
-There is a small number of functions which yield the biggest security
-risk in the expression parser:
-
-- `import` and `createUnit` which alter the built-in functionality and
-  allow overriding existing functions and units.
-- `evaluate`, `parse`, `simplify`, and `derivative` which parse arbitrary
-  input into a manipulable expression tree.
-
-To make the expression parser less vulnerable whilst still supporting
-most functionality, these functions can be disabled:
-
-```js
-import { create, all } from 'mathjs'
-
-const math = create(all)
-const limitedEvaluate = math.evaluate
-
-math.import({
-  'import':     function () { throw new Error('Function import is disabled') },
-  'createUnit': function () { throw new Error('Function createUnit is disabled') },
-  'evaluate':   function () { throw new Error('Function evaluate is disabled') },
-  'parse':      function () { throw new Error('Function parse is disabled') },
-  'simplify':   function () { throw new Error('Function simplify is disabled') },
-  'derivative': function () { throw new Error('Function derivative is disabled') }
-}, { override: true })
-
-console.log(limitedEvaluate('sqrt(16)'))     // Ok, 4
-console.log(limitedEvaluate('parse("2+3")')) // Error: Function parse is disabled
-```
-
-
-### Found a security vulnerability? Please report in private!
-
-You found a security vulnerability? Awesome! We hope you don't have bad
-intentions and want to help fix the issue. Please report the
-vulnerability in a private way by contacting one of the maintainers
-via mail or an other private channel. That way we can work together
-on a fix before sharing the issue with everybody including the bad guys.
-
-## Stability risks
-
-A user could accidentally or on purpose execute a
-heavy expression like creating a huge matrix. That can let the
-JavaScript engine run out of memory or freeze it when the CPU goes
-to 100% for a long time.
-
-To protect against this sort of issue, one can run the expression parser
-in a separate Web Worker or child_process, so it can't affect the
-main process. The workers can be killed when it runs for too
-long or consumes too much memory. A useful library in this regard
-is [workerpool](https://github.com/josdejong/workerpool), which makes
-it easy to manage a pool of workers in both browser and node.js.