IKExpressoin简易表达式引擎V2.1.0使用说明

IKExpression简易表达式解析器使用说明目录1.IK表达式介绍（IKExpressionIntroduction）.....................................................22.快速入门（QuickStart）..........................................................................................63.表达式公式规范（ExpressionFormulaSpecification）..................................124.高级特性（Advance）.............................................................................................191.IK表达式介绍（IKExpressionIntroduction）IKExpression是一个开源的（OpenSource），可扩展的（Extensible），基于java语言开发的一个超轻量级（Superlightweight）的公式化语言解析执行工具包。IKExpression不依赖于任何第三方的java库。它做为一个简单的jar，可以集成于任意的Java应用中。这包括了JavaEE应用（基于应用服务器的），Java桌面应用以及JavaWebStart方式的应用。IKExpression最初诞生的原因是为了能增强工作流引擎，如jBPM等对流程配置的灵活度。使其能在流程运行期获得同配置期一样灵活地对执行逻辑条件进行变更。经过扩展后的IKExpression还可以适用于各种常规业务系统的动态条件配置，如需要图形化配置应用的场合，或是模拟Excel电子表格的公式运算的场景。同EL和BeanScript不同，IKExpression的设计目标是面向最终用户的，因此它被设计成语法简单（像数学算式），通俗易懂（支持中文变量及函数名）但功能有限的解析引擎。如果你需要一个功能强大的表达式引擎，也许IKExpression并不是最好的选择。1.1概要（OverView）IKExpression是一个采用逆波兰式算法结合指针栈优化的公式解析引擎，它由表达式编译、、表达式执行、变量容器、以及函数配置管理四部分构成。它具有以下特点：�支持基础运算符+-×/%逻辑运算符！&&||三元运算符？：以及特有的#集合运算。支持括号优先级，对&&，||，？：有短路优化处理。�支持函数执行，函数扩展，支持变量定义。�完整Jar包大小90K，API简单易学，超轻量级，无第三方类库依赖。IKExpression组件结构图1.2升级变更（ChangesLog）Version2.1的变更：�新增org.wltea.expression.ExpressionEvaluator.preparedCompile（Stringexpression,CollectionVariablevariables）方法和类org.wltea.expression.PreparedExpression用来支持表达式预编译。用户可以像处理SQL语句那样，对需要循环执行的相同表达式进行预编译处理，而后设置不同的执行参数，得到不同的计算结果。详见“样例代码”和”API说明”.�修订了对声明为Object类型的参数传入Integer、Double、String等类型的值时，会抛出类型不匹配异常的问题。原来版本中，参数必须显式申明为DATATYPE_OBJECT类型，新版本则不需要，所有java类型默认继承于Object。�修改了ExpressionEvaluator的两个compile方法，不再抛出IllegalExpressionException异常，而改为运行期异常，以简化用户编码。Version2.0.5的变更：�支持表达式的换行编辑，方便表达式编写和阅读，如：�提供了更多的开放API，如：表达式验证API，这使得表达式在执行前可以检查其语法正确性。�修订了“？：”三元操作符的“：“号两端对不同类型的数值不兼容的BUG。如：原有版本中，表达”10010?100:10.5“将会抛出“参数类型不兼容“异常，在新版本中，则返回double型的100.0Version2.0.2的变更：�修订了自定义函数返回类型为void时，表达式校验会抛出异常的BUG。$CALCDATE([2008-03-01],0,0,-(10+(23-3)*(4/5))%6,0,0,0)对于void返回类型，IK-Expression将当作null类型进行计算。Version2.0.1的变更：�添加了对表达式的折行书写的支持（即对表达式中出现CRLF的支持），方便于用户编写逻辑复杂的长表达式，增强表达式可阅读性。Version2.0的变更：�增加了“？：“三元操作符。�增强了“+“操作符，支持对null型，Date型，Boolean型的连接操作。�增加了自定义函数扩展，支持配置方式扩展函数和API编码方式扩展函数。�增加了函数别名映射功能，可配置中文函数别名。�增加了函数参数和返回值对javaObject类型的支持。�优化“||”、“&&”、“？：“操作符，实现相应逻辑的短路处理。�修订了Date类型的==比较逻辑。原有逻辑判定时间差小于1秒为相等，现在更正为精确到秒。�修订了==比较逻辑对数值类型运算的bug，使其支持Integer，Float，Long，Double类型的混合比较，以及当这四种类型混合比较时，其中一个参数为null的情况。�修改了V1.0中类Variable的方法createVariable的参数。�废除了V1.0中的“：“操作符（使用“？：“三元操作符代替）�废除了V1.0中类ExpressionEvaluator的compileExpression方法。2.快速入门（QuickStart）2.1下载（DownloadablesOverview）GoogleCode开源项目：下载：安装部署IKExpression的安装部署十分简单，安装包包含：1.使用说明文档（即本文档）2.IKExpression2.X.Y.jar（X.Y为子版本号）3.IKExpression.cfg.xml其中，IKExpression2.X.Y.jar部署于项目的lib目录中；IKExpression.cfg.xml（函数定义配置）文件放置在代码根目录（对于web项目，通常是WEB-INF/classes目录，同hibernate、log4j等配置文件相同）下即可。2.3API简易教程（APITutorial）代码样例HelloWorld/***HelloWorldExample*@paramargs*/publicstaticvoidmain(String[]args){if(args.length==0){args=newString[1];args[0]=IKExpression;}//定义表达式Stringexpression=\HelloWorld\+用户名;//给表达式中的变量“用户名”付上下文的值ListVariablevariables=newArrayListVariable();variables.add(Variable.createVariable(用户名,args[0]));//执行表达式Objectresult=ExpressionEvaluator.evaluate(expression,variables);System.out.println(Result=+result);}执行结果：Result=HelloWorldIKExpression预编译执行样例/***HelloWorldExample*@paramargs*/publicstaticvoidmain(String[]args){if(args.length==0){args=newString[1];args[0]=IKExpressionV2.0.5;}//定义表达式Stringexpression=\Hello\+版本;//给表达式中的变量[版本]付上下文的值ListVariablevariables=newArrayListVariable();variables.add(Variable.createVariable(版本,args[0]));//预编译表达式PreparedExpressionpe=ExpressionEvaluator.preparedCompile(expression,variables);//执行表达式Objectresult=pe.execute();System.out.println(Result=+result);//更改参数，再次执行预编译式pe.setArgument(版本,IKExpressionV2.1.0);result=pe.execute();System.out.println(Result=+result);}API说明�类org.wltea.expression.ExpressionEvaluator该类是IK-Expression主调用类，大部分执行方法都在这里。方法1：publicstaticObjectevaluate(Stringexpression,CollectionVariablevariables)说明：传入表达式和表达式上下文的变量，执行表达式返回结果参数1：Stringexpression,要传入执行的表达式参数2：CollectionVariablevariables表达式上下文的变量集合（详细请看类org.wltea.expression.datameta.Variable的说明）。返回值：表达式执行结果，可能是以下类型的java对象中的一种：Int、Long、Float、Double、Boolean、String、Date、List、Object。方法2：publicstaticObjectevaluate(Stringexpression)说明：对方法1的重载，执行简单的没有变量的表达式。请参考方法1说明.方法3：publicstaticStringcompile(Stringexpression,CollectionVariablevariables)执行结果：Result=HelloIKExpressionV2.0.5Result=HelloIKExpressionV2.1.0说明：传入表达式和表达式上下文的变量，对表达式进行语法编译测试，返回逆波兰式表示。参数1：Stringexpression,要传入执行的表达式参数2：CollectionVariablevariables表达式上下文的变量集合（详细请看类org.wltea.expression.datameta.Variable的说明）。返回值：表达式的逆波兰式表示方法4：publicstaticStringcompile(Stringexpression)说明：对方法3的重载，编译简单的没有变量的表达式。请参考方法3说明.方法5：publicstaticPreparedExpressionpreparedCompile(Stringexpression,CollectionVariablevariables)说明：传入表达式和表达式上下文的变量，对表达式进行预编译处理，返回预编译完的表达式对象。参数1：Stringexpression,要传入执行的表达式参数2：CollectionVariablevaria