From 88c4c0419a4d06d41049b34d05fa42415c230499 Mon Sep 17 00:00:00 2001 From: konrad Date: Sat, 30 Oct 2010 19:06:27 +0000 Subject: [PATCH] more draft docu start of first draft of API git-svn-id: https://silmor.de/svn/softmagic/elam/trunk@616 6e3c4bff-ac9f-4ac1-96c5-d2ea494d3e33 --- README | 10 +++--- doc/build.html | 6 ++-- doc/index.html | 6 ++-- doc/library.html | 4 +- doc/syntax.html | 99 ++++++++++++++++++++++++++++++++++++++++++++++---- src/elam.h | 13 +++++++ src/elamengine.h | 28 ++++++++++++++ src/elamexpression.h | 43 ++++++++++++++++++++++ src/elamvalue.h | 24 ++++++++++++ 9 files changed, 212 insertions(+), 21 deletions(-) create mode 100644 src/elam.h create mode 100644 src/elamengine.h create mode 100644 src/elamexpression.h create mode 100644 src/elamvalue.h diff --git a/README b/README index f23fd5e..6c5d22c 100644 --- a/README +++ b/README @@ -1,17 +1,17 @@ -README for ElAM +README for ELAM ================ -ElAM = Elementary Algebra Machine +ELAM = Elementary Logic and Arithmetic Machine (c) Konrad Rosenbaum, 2010 protected under the GNU LGPL version 3 or at your option any newer see COPYING for details -This engine can be fed simple algebraic formulas and will calculate their -result similar to those used in languages like C or Pascal. It is not able +This engine can be fed simple arithmetic formulas and will calculate their +result, similar to those used in languages like C or Pascal. It is not able to solve algebraic systems or use fancy expressions. -ElAM is based on and made for Qt 4.x. +ELAM is based on and made for Qt 4.x. Building ========= diff --git a/doc/build.html b/doc/build.html index 87840e1..6f534c0 100644 --- a/doc/build.html +++ b/doc/build.html @@ -1,9 +1,9 @@ -ElAM +ELAM -

Building The ElAM Libray

Building The ELAM Libray

-ElAM contains the following directories: +ELAM contains the following directories:

src - contains the sources for the static ElAM library. diff --git a/doc/index.html b/doc/index.html index a195b97..bcec004 100644 --- a/doc/index.html +++ b/doc/index.html @@ -1,10 +1,10 @@ -ElAM +ELAM -

The ElAM Libray

The ELAM Libray

Building ElAM +
Building ELAM
Syntactic Rules
Using and Extending the Library

Source Documentation diff --git a/doc/library.html b/doc/library.html index d0512f1..7a713ed 100644 --- a/doc/library.html +++ b/doc/library.html @@ -1,7 +1,7 @@ -ElAM +ELAM -

Using The ElAM Libray

Using The ELAM Libray

Project File and Includes

diff --git a/doc/syntax.html b/doc/syntax.html index 6b95116..700fc35 100644 --- a/doc/syntax.html +++ b/doc/syntax.html @@ -1,28 +1,89 @@ -ElAM +ELAM -

The ElAM Syntax

The ELAM Syntax

-ElAM has the following syntactic elements: +This page uses the example in demo to explain syntactic rules. Actual operators, types, and functions may differ significantly when used with different syntax libraries.

+ +ELAM has the following syntactic elements:

Expressions +
Literals
Types
Variables
Constants -
Parentheses
Unary and Binary Operators +
Parentheses
Functions
Assignments

Precedence Rules

Expressions

+ +Expressions are what ELAM interprets. They can be as simple as the number "1", or very complex: + + + + + + + + + + +

Expression	Explanation
1	a simple literal number
1+2	simple operation using two literals
2*a	simple operation using a literal and a variable
1+2*3	two operations with precedence (* is evaluated before +)
(1+2)*3	two operations with precedence changed through parentheses
a=3+4	operation with the result assigned to a variable
b=a=3+4	operation with the result assigned to two variables

+ +Expressions can be used recursively. For example the expression "1+2+3" consists of the two expressions "1+2" and "(1+2)+3". Expressions return the result of their evaluation, assignment expressions return the value that has been stored in the variable to the left. + +

Literals

Default Operator Precedence

+Literals are directly encoded values like "1" or "0.5".

+ +The default library knows numeric literals: + + + + + + +
Example Composition Description
123 starts with 1..9, contains any number of 0..9 decimal integer value
012 starts with 0, contains 0..7 octal integer value
0x12 starts with 0x, contains 0..9 and a..f/A..F hexadecimal integer value
1.8, .8, 1. 1e34 starts with digit or dot, contains digits, optionally a dot and/or "e" and more digits floating point value

+ +If the string library is loaded you can also formulate strings enclosed in "..." or '...'. + +

Types

+ +ELAM can handle arbitrary value types. The default library brings integer numbers, floating point numbers, and optionally strings. For some functions and operators it can cast values into different types automatically, for others cast-functions must be called. + +

Variables and Constants

+ +Variables are named values (e.g. "a" or "myVar2") that can be set by assignments and then be used instead of literal values. In the default implementation variable names must start with a letter and may contain letters, digits and underscores. Variable names are case sensitive (e.g. "myVar" is different from "MyVar").

+ +Constants are variables that have been marked as immutable, they can be of any type. + +

Operators

+ +There are two types of operators: unary and binary.

+ +Unary operator precede an expression and change it, returning the result. For example the unary "-" operator in the default library negates its numeric argument (e.g. if "a" is 12, then "-a" returns -12).

+ +Binary operators operate on two expressions, one to the left and one to the right of the operator.

+ +If operators follow each other (e.g. "a +| -b") then the operators must be separated by spaces.

+ +Parentheses group operations and may alter the order in which they are executed. Parentheses are evaluated before any other operation.

+ +The equals sign ("=") has a special meaning when used in operators. In the normal mode the direct assignment operator "=" cannot be overloaded with a user specific function. If an operator ends in "=" and there is no overloaded operator, then the remainder is interpreted as a binary operator and the result assigned to the left side of the operator, for example "a+=b" is interpreted as a short form of "a=a+b". + +

Operator Precedence

+ +Operators are interpreted in a specific order of precedence. First the highest precedence operators are evaluated, then the next lower precedence level, etc. with assignments being executed last. Consecutive operations with the same precedence level are executed from left to right.

+ +The default library has the following precedence order: - + @@ -33,8 +94,30 @@ ElAM has the following syntactic elements: - + +

Operator Class Operators Precedence Value

Parentheses (parentheses), functions(...) 100
Maximum usable Precedence 99
Maximum usable Precedence 99

Unary Operators ++, --, ~, !, -, + 95

Multiplicative *, /, % 90

Additive +, - 80
bitwise OR | 40

logical AND && 30

logical OR || 25
Lowest usable Precedence 1
Lowest usable Precedence 1

assignments =, +=, -=, ... 0

+ +This means for example that in "a=9+1+2*(3-1)" these operations are executed in this order: +

"(3-1)" yields "2" +
"2*2" yields "4" +
"9+1" yields "10" +
"10+4" yields "14" +
the variable "a" is assigned the value "14" +

+ +

Functions

+ +Functions take values of any kind as arguments and return exactly one value. Function names follow the same syntactic rules as variable names. Functions and variables share their namespace - no variable can have the same name as a function. Function arguments are separated by commas.

+ +The default library knows the following functions: + + + + + +
Function Description
int(value) converts value to integer, rounding towards zero
float(value) converts value to a floating point number
str(value) converts value to string
concat(v1,v2,...) concatenates strings

\ No newline at end of file diff --git a/src/elam.h b/src/elam.h new file mode 100644 index 0000000..f1f1887 --- /dev/null +++ b/src/elam.h @@ -0,0 +1,13 @@ +//ELAM main header +// +// (c) Konrad Rosenbaum, 2010 +// protected under the GNU LGPL v3 or at your option any newer + +#ifndef ELAM_LIB_H +#define ELAM_LIB_H + +#include "elamengine.h" +// #include "elamdefault.h" +// #include "elamfunction.h" + +#endif diff --git a/src/elamengine.h b/src/elamengine.h new file mode 100644 index 0000000..75be1cd --- /dev/null +++ b/src/elamengine.h @@ -0,0 +1,28 @@ +//ELAM main header +// +// (c) Konrad Rosenbaum, 2010 +// protected under the GNU LGPL v3 or at your option any newer + +#ifndef ELAM_ENGINE_H +#define ELAM_ENGINE_H + +#include +#include + +#include "elamexpression.h" + +class ELAMEngine:public QObject +{ + Q_OBJECT + public: + ELAMEngine(QObject*parent=0); + public slots: + ELAMExpression parseExpression(QString); + ELAMValue evaluate(QString); + ELAMValue evaluate(ELAMExpression); + private: + class Private; + Private *d; +}; + +#endif diff --git a/src/elamexpression.h b/src/elamexpression.h new file mode 100644 index 0000000..a552e9c --- /dev/null +++ b/src/elamexpression.h @@ -0,0 +1,43 @@ +//ELAM main header +// +// (c) Konrad Rosenbaum, 2010 +// protected under the GNU LGPL v3 or at your option any newer + +#ifndef ELAM_EXPRESSION_H +#define ELAM_EXPRESSION_H + +#include "elamvalue.h" + +class ELAMToken +{ + public: + enum Type { + Name, + Operator, + ParOpen, + ParClose, + Comma, + Literal + }; + QString content()const{return mcont;} + Type type()const{return mtype;} + private: + QString mcont; + Type mtype; +}; + +class ELAMExpression +{ + public: + enum Type { + Literal, + Variable, + Constant, + Function, + Parentheses, + UnaryOp, + BinaryOp, + }; +}; + +#endif diff --git a/src/elamvalue.h b/src/elamvalue.h new file mode 100644 index 0000000..d07e12b --- /dev/null +++ b/src/elamvalue.h @@ -0,0 +1,24 @@ +//ELAM main header +// +// (c) Konrad Rosenbaum, 2010 +// protected under the GNU LGPL v3 or at your option any newer + +#ifndef ELAM_VALUE_H +#define ELAM_VALUE_H + +#include +#include + +class ELAMValue +{ + public: + ELAMValue(); + ELAMValue(long long); + ELAMValue(double); + ELAMValue(QString); + ELAMValue(QVariant); + + +}; + +#endif -- 1.7.2.5

Example	Composition	Description
123	starts with 1..9, contains any number of 0..9	decimal integer value
012	starts with 0, contains 0..7	octal integer value
0x12	starts with 0x, contains 0..9 and a..f/A..F	hexadecimal integer value
1.8, .8, 1. 1e34	starts with digit or dot, contains digits, optionally a dot and/or "e" and more digits	floating point value

Operator Class	Operators	Precedence Value
Parentheses	(parentheses), functions(...)	100
Maximum usable Precedence		99
Maximum usable Precedence		99
Unary Operators	++, --, ~, !, -, +	95
Multiplicative	*, /, %	90
Additive	+, -	80
bitwise OR	\|	40
logical AND	&&	30
logical OR	\|\|	25
Lowest usable Precedence		1
Lowest usable Precedence		1
assignments	=, +=, -=, ...	0

Function	Description
int(value)	converts value to integer, rounding towards zero
float(value)	converts value to a floating point number
str(value)	converts value to string
concat(v1,v2,...)	concatenates strings