psalaets / excel-formula-ast

Abstract syntax tree for excel formulas

excel-formula-ast

Abstract syntax tree for excel formulas.

Install

npm install excel-formula-ast -S

or

yarn add excel-formula-ast

Usage

const {tokenize} = require('excel-formula-tokenizer');
const {buildTree, visit} = require('excel-formula-ast');

const formula = 'SUM(1, 2)';
const tokens = tokenize(formula);

// build tree
const tree = buildTree(tokens);

// create visitor for parts of tree you're interested in
const visitor = {
  enterFunction(functionNode) {
    console.log(`function is ${functionNode.name}`);
  },
  enterNumber(numberNode) {
    console.log(`number is ${numberNode.value}`)
  }
};

// send visitor through tree
visit(tree, visitor);

// prints:
// function is SUM
// number is 1
// number is 2

API

const {buildTree, visit} = require('excel-formula-ast');

buildTree(tokens)

Build expression tree from tokens.

• tokens: Array of objects - Tokens from excel-formula-tokenizer (github | npm)

Returns: ast node

visit(tree, visitor)

Send a visitor through the tree nodes.

• tree: ast node
• visitor: object

visitor

Visitor is an object with any of these function properties:

{
  enterCell(node) {},
  exitCell(node) {},

  enterCellRange(node) {},
  exitCellRange(node) {},

  enterFunction(node) {},
  exitFunction(node) {},

  enterNumber(node) {},
  exitNumber(node) {},

  enterText(node) {},
  exitText(node) {},

  enterLogical(node) {},
  exitLogical(node) {},

  enterBinaryExpression(node) {},
  exitBinaryExpression(node) {},

  enterUnaryExpression(node) {},
  exitUnaryExpression(node) {}
}

For any node type Foo

• enterFoo() is called when the visitor gets to a Foo node.
• exitFoo() is called when the visitor has visited all of the Foo's child nodes (if any) and is leaving the Foo.

Node Types

cell

Passed to visitor methods: enterCell, exitCell

Properties:

• type: string - 'cell'
• key: string - Excel cell number. Example: 'A1'
• refType: string - 'relative' | 'mixed' | 'absolute'

cell range

Passed to visitor methods: enterCellRange, exitCellRange

Properties:

• type: string - 'cell-range'
• left: cell node
• right: cell node

function

Passed to visitor methods: enterFunction, exitFunction

Properties:

• type: string - 'function'
• name: string - function name
• arguments: Array of node

number

Passed to visitor methods: enterNumber, exitNumber

Properties:

• type: string - 'number'
• value: number

text

Passed to visitor methods: enterText, exitText

Properties:

• type: string - 'text'
• value: string

logical

Passed to visitor methods enterLogical, exitLogical

Properties:

• type: string - 'logical'
• value: boolean

binary expression

Passed to visitor methods: enterBinaryExpression, exitBinaryExpression

Properties:

• type: string - binary-expression
• operator: string
• left: node
• right: node

unary expression

Passed to visitor methods: enterUnaryExpression, exitUnaryExpression

Properties:

• type: string - 'unary-expression'
• operator: string
• operand: node

License

MIT

excel-formula-ast's Issues

support for german excel

I am not sure if this belongs to the tokenizer or the excel-formula-ast. If you are in german excel, you need to use ";" as separator for function arguments. "," is used for numbers.

=WENN(WAHR;1,1;1,2)

TypeScript support

I'd love to see typescript support for this library.

Contribution request

Hi Alex,

I've been evaluating a number of excel formula parsers (including writing my own) for a project I'm working on, when I discovered your parser.

The design of the AST builder is elegant and I'm wondering if you're open to contributions to the excel-formula-ast and excel-formula-tokenizer? Also, is github's issues the best way to reach you?

Thanks!

The library behaves badly on malformed formulas

If you pass a malformed formula to the library, it will be stuck in a loop.

For example:

const tokens=tokenize('SUM(')
const rootNode = buildTree(tokens)

Alpha/beta/stable release

Hey guys,

You are doing an awesome work to generate AST representation of excel formulas. It is a hardwork and I would like to thank you guys for it.

I just wanted to ask what is current status of the project? Is it still in active development phase, or it has reached to alpha/beta/stable phase? How much excel formulae it has supported until now? I guess https://github.com/psalaets/excel-formula-tokenizer is also closely related to this project and will be almost on the same stage.

Best regards

strange (incorrect?) whitespace handling

> tokenize('=1+3*2')
[
  { value: '1+3', type: 'operand', subtype: 'number' },
  { value: '*', type: 'operator-infix', subtype: 'math' },
  { value: '2', type: 'operand', subtype: 'number' }
]
> tokenize('= 1+3*2')
[
  { value: '1', type: 'operand', subtype: 'number' },
  { value: '+', type: 'operator-infix', subtype: 'math' },
  { value: '3', type: 'operand', subtype: 'number' },
  { value: '*', type: 'operator-infix', subtype: 'math' },
  { value: '2', type: 'operand', subtype: 'number' }
]
> buildTree(tokenize('=1+3*2'))
{
  type: 'binary-expression',
  operator: '*',
  left: { type: 'number', value: NaN },
  right: { type: 'number', value: 2 }
}

access to source line/column

the nodes do not have a corresponding token attached, therefore it is difficult to see where an error is in the original formula. I'd like to have linting for excel formulas (codemirror), but for it to work it needs line/column marks to where something is wrong (e.g., unknown cell range or unknown formula)

german excel: WAHR/FALSCH

In german excel, you have 'WAHR' and 'FALSCH' instead of 'TRUE' and 'FALSE'. The library will output a logicalNode only if the name is 'TRUE' or 'FALSE'. 'WAHR' and 'FALSCH' will be handled as 'cell'-Node. I am not sure if this is a lower-level (tokenizer) or ast problem.

It is easy to work around, but I think this could be handled better, e.g. a list of names for logical true, and a list of strings for logical false. I don't have any idea what this looks like in spanish, for example.