Formulas

From Freeplane - free mind mapping and knowledge management software
Revision as of 09:23, 21 October 2012 by DimitryPolivaev (talk | contribs)

Formulas are very similar to formulas in spreadsheet processors like Excel or OpenOffice Calc:

<groovy> 

=2 + 3

</groovy>

Formulas, which are identified by the leading '=', are expressions that are evaluated for display. That is their result is displayed instead of the formula text. In case of =2 + 3 this would be 5. The formula itself (=2 + 3) is only visible in the editor.

Overview

Formulas can be defined in

  • node texts
  • attribute values
  • notes

Formulas are evaluated as Groovy scripts. This fact defines the basic syntax of formulas. But although Groovy is a full-blown programming language simple things are very simple in Groovy like this:

<groovy> 

 = 3 * 2

</groovy>

gives 6,

<groovy> 

 = (3 * 2) + " times"

</groovy>

gives 6 times. Note that the space after the '=' is optional.

Now something more complex:

<groovy> 

 = children.sum(""){ it.text }

</groovy>

gives the concatenation of all child node texts. By using sum("") instead of sum we set the start value to "" and ensure that the formula also works if the node has no children at all.

<groovy> 

 = children.sum(0){ it.to.num }

</groovy>

sums over the numerical values of the child nodes.

The following statement sums over the numerical values of the attribute item of all childrens. If one child does not have that attribute or if it isn't convertible to a number num0 (or getNum0()) uses 0 instead [since 1.2.1_17].

<groovy> 

 = children.sum(0){ it['item'].num0 }

</groovy>

Formulas have access to a read-only variant of the Scripting API, i.e. formulas may not change anything in a map. There are some minor extensions to the Groovy language for formulas to improve the ease of use, e.g. for simpler data type conversion. See preview version of the Scripting API for the latest API.

Note that properties and methods of a formula node (like children or text) are directly available to the formula, i.e. the leading "node." can be left out.

References

Formulas have access to all nodes in the map by

  • navigating the hierarchy for instance via =node.children, =node.parent or =node.map.root
  • searching the map via find, e.g. =node.find{ it.text == 'sum'}.
  • direct references to a specific node by id like ID_172581364.to.num. Use the function Copy Node ID in the context menu of a node to get the id of a node. (There will be special editor support later.)

Note that like in Excel you can easily create circular references if a node references itself (either directly or indirectly).

<groovy> 

 = parent.children.sum{ it.to.text }

</groovy>

The circular reference is obviously due to navigating back and forth in the hierarchy. Now an Example that more likely may occur to you (paste the next lines into a map):

<groovy> 

 = "count nodes above 10: " + node.find { it.to.num > 10 }.size()
   = 10
   = 11

</groovy>

The result should be count nodes above 10: 1 but the find tries to evaluate itself since it.to involves a formula evaluation. This leads to this error: 

 Circular reference: The formula in node '= count nodes....' references itself.

To prevent that you should avoid formula evaluation in the argument to find like this:

<groovy> 

 = "count nodes matching '11': " + node.find { it.text == '11' }.size()

</groovy>

For analysis of complicated cases you will have to look up the logfile. Search for messages like this: 

 WARNING: Circular reference detected! Traceback (innermost last):
  * ID_1323597872 = "count nodes above 10: " ... ->  "count nodes above 10: " + node.find { it.to.num > 10 }....
  -> * ID_1323597872 = "count nodes above 10: " ... ->  "count nodes above 10: " + node.find { it.to.num > 10 }....

The node that is causing the circular reference is highlighted by an asterisk. We see that the cycle is a direct one, i.e. the node is directly referencing itself. But it doesn't need to be so simple and there might be more nodes involved when you happen to see this kind of error.

Note that many problems with circular references arise from using find. So here's one advice: Avoid find if you don't need it.

Also note that references between texts, notes and attributes of the same node do not result in a "circular reference" warning. On the other hand it doesn't matter which attribute, text or note is referenced by another node: cycles are detected only on the (coarse) node level.

When the map is changed...

Formulas are immediately updated when necessary. (Otherwise it's a bug that you should report.)

Formula evaluation is significantly more costly than many other things that will happen during normal operation. To reduce the overhead of formula evaluation Freeplane implements a dependency tracking mechanism that takes care to only update those formulas that reference a changed node.

But this mechanism could theoretically get fooled by complex Groovy expressions. I can't give you an example currently but it's definitely possible.

So just in case the formula processor got confused somehow there's a function Tools > Formulas > Evaluate all that re-evaluate the whole map.


Caching formula evaluation results

For continuous node visualization the properties of a node are queried much more often than they are changed. To avoid recalculation in this cases all evaluation results are stored/cached internally. This cache is initially filled on opening a map and emptied on unload of it.

For debugging purposes it is possible to switch off caching completely via the preferences page of the formula plugin. But keep in mind that this might severely impair application's performance.


Editor support for formulas

For editing of nodes containing a formula a special editor is used that provides the following features:

  • Syntax highlighting: Support for standard Groovy expressions and node references.
  • GUI-Support for referencing other nodes: Double click a node to insert a reference to it into the formula.
  • GUI-Support for visualization of node references: If the cursor is in a node id the referenced node will be selected in the map. The tooltip of the editor will show the (transformed) text of the node in this case.

Note that the special editor will only be used if the node text already starts with an equal sign. The editor support will be further extended in the future, especially with code completion.

Formatting

Formatting of numbers and dates is available as an element of Styles, that means that they are not formula specific. Make sure to choose the right format for dates: Choose ISO format to be on the safe side (use TextUtils.toStringISO()). See the Format panel.


Security

Formulas will have strict security limitations that can not be disabled via configuration. From formulas it's impossible to access the file system or the network and you can not execute external programs.


Miscelleneous

Richtext nodes (in node texts and notes) are supported by stripping all HTML clutter from the text before evaluation but using plaintext is definitely preferable for formulas.

Borders: Formula nodes are marked with a green border. To remove the border select the option Preferences... > Plugins > Don't mark formulas with a border.

Open issues

Please help to fix some open issues. Please leave your opinion on the discussion page or in the discussion forum.

Named nodes

Node references by node id are effective and the referenced node can be easily inspected if viewed in the formula editor. But without the editor support the node ids don't make any sense for themselves.

Named nodes would allow to make references more readable. If for instance one "parameter node" with ID ID_241399282 is used in many formulas in a map, then it would be good to give it a name, e.g. scale and to use N("scale").to.num instead of using ID_241399282.to.num.

Do you have an idea how such names should be defined? Is it enough to have named nodes or do we need named collections of nodes, too?

Plus operator for nodes

Given the following map:

<groovy> 

= children.sum()
  1
  2

</groovy>

What should be the result of the formula? (Currently you'll get the error "no ... method ... NodeProxy.plus(NodeProxy) ... found")

  • Should it be an error (like now)?
  • Should it be "3"? (In this case NodeProxy.plus(NodeProxy) would be implemented as NodeProxy.to.object + NodeProxy.to.object)
  • Should it be "12"? (In this case NodeProxy.plus(NodeProxy) would be implemented as NodeProxy.text + NodeProxy.text)

Attribute Access

Formulas provide simplified attribute access via the ['name'] operator:

<groovy> 

 = children.sum(0){ it['attrib_name'].num0 }

</groovy>

Are there any votes for the following version?

<groovy> 

 = children.sum(0){ it.attributes['attrib_name'].num0 }

</groovy>

Implementation of functions available in spreadsheet processors?

Spreadsheet processors have a large number of functions that are not directly supported by Freeplane (see [ODF specification]). Of course many of these functions are not easily translatable from tabulars to mindmaps but one might strive to provide as many as possible to increase portability of existing formulas to Freeplane.

What do you think, do we need implementations for functions like NOW(), SECOND(), PPMT(), RRI(), COLUMNS(), etc., even if Groovy equivalents exist?

Limitations

Not all functionality described above is yet available. This is the roadmap for missing features:

To be implemented after 1.3

Most of the following features will probably be implemented only after the 1.2 release:

  • Readonly API. Note that formulas that change the state of the script, e.g. by invoking a setter method on nodes, attributes etc. will stop working without further notice. Please stick to the public, official API.
  • References to nodes in other maps.


Example Maps

Retrieved from "https://www.freeplane.org/oldwiki/index.php?title=Formulas&oldid=4378"