initial commit, 4.5 stable

doc/classes/Expression.xml

@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="Expression" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A class that stores an expression you can execute.
+	</brief_description>
+	<description>
+		An expression can be made of any arithmetic operation, built-in math function call, method call of a passed instance, or built-in type construction call.
+		An example expression text using the built-in math functions could be [code]sqrt(pow(3, 2) + pow(4, 2))[/code].
+		In the following example we use a [LineEdit] node to write our expression and show the result.
+		[codeblocks]
+		[gdscript]
+		var expression = Expression.new()
+
+		func _ready():
+			$LineEdit.text_submitted.connect(self._on_text_submitted)
+
+		func _on_text_submitted(command):
+			var error = expression.parse(command)
+			if error != OK:
+				print(expression.get_error_text())
+				return
+			var result = expression.execute()
+			if not expression.has_execute_failed():
+				$LineEdit.text = str(result)
+		[/gdscript]
+		[csharp]
+		private Expression _expression = new Expression();
+
+		public override void _Ready()
+		{
+			GetNode&lt;LineEdit&gt;("LineEdit").TextSubmitted += OnTextEntered;
+		}
+
+		private void OnTextEntered(string command)
+		{
+			Error error = _expression.Parse(command);
+			if (error != Error.Ok)
+			{
+				GD.Print(_expression.GetErrorText());
+				return;
+			}
+			Variant result = _expression.Execute();
+			if (!_expression.HasExecuteFailed())
+			{
+				GetNode&lt;LineEdit&gt;("LineEdit").Text = result.ToString();
+			}
+		}
+		[/csharp]
+		[/codeblocks]
+	</description>
+	<tutorials>
+		<link title="Evaluating Expressions">$DOCS_URL/tutorials/scripting/evaluating_expressions.html</link>
+	</tutorials>
+	<methods>
+		<method name="execute">
+			<return type="Variant" />
+			<param index="0" name="inputs" type="Array" default="[]" />
+			<param index="1" name="base_instance" type="Object" default="null" />
+			<param index="2" name="show_error" type="bool" default="true" />
+			<param index="3" name="const_calls_only" type="bool" default="false" />
+			<description>
+				Executes the expression that was previously parsed by [method parse] and returns the result. Before you use the returned object, you should check if the method failed by calling [method has_execute_failed].
+				If you defined input variables in [method parse], you can specify their values in the inputs array, in the same order.
+			</description>
+		</method>
+		<method name="get_error_text" qualifiers="const">
+			<return type="String" />
+			<description>
+				Returns the error text if [method parse] or [method execute] has failed.
+			</description>
+		</method>
+		<method name="has_execute_failed" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if [method execute] has failed.
+			</description>
+		</method>
+		<method name="parse">
+			<return type="int" enum="Error" />
+			<param index="0" name="expression" type="String" />
+			<param index="1" name="input_names" type="PackedStringArray" default="PackedStringArray()" />
+			<description>
+				Parses the expression and returns an [enum Error] code.
+				You can optionally specify names of variables that may appear in the expression with [param input_names], so that you can bind them when it gets executed.
+			</description>
+		</method>
+	</methods>
+</class>