分享开源表达式解析器IK-Expression2.0

[size=xx-large][b][align=center]IKExpressionV2.0简易表达式解析器使用说明[/align][/b][/size]

[size=large][b]目录[/b][/size]
[list]
[*][size=large]1. IK表达式介绍（IK Expression Introduction）[/size]
[*][size=large]2. 快速入门（Quick Start）[/size]
[*][size=large]3. 表达式公式规范（Expression Formula Specification）[/size]
[*][size=large]4. 高级特性（Advance）[/size]
[/list]

[size=large][color=red]注：V2.1.2已发布，请参考 [url]http://linliangyi2007.iteye.com/blog/481407[/url][/color][/size]

[size=x-large][b]1. IK表达式介绍（IK Expression Introduction）[/b][/size]
IK Expression是一个开源的（OpenSource），可扩展的（Extensible），基于java语言开发的一个超轻量级（Super lightweight）的公式化语言解析执行工具包。

IK ExpressionV2.0不依赖于任何第三方的java库。它做为一个简单的jar，可以集成于任意的Java应用中。这包括了JavaEE应用（基于应用服务器的）， Java桌面应用以及Java WebStart方式的应用。

IK Expression最初诞生的原因是为了能增强工作流引擎，如jBPM等对流程配置的灵活度。使其能在流程运行期获得同配置期一样灵活地对执行逻辑条件进行变更。经过扩展后的IK Expression还可以适用于各种常规业务系统的动态条件配置，如需要图形化配置应用的场合，或是模拟Excel电子表格的公式运算的场景。

同EL和BeanScript不同，IK Expression的设计目标是面向最终用户的，因此它被设计成语法简单（像数学算式），通俗易懂（支持中文变量及函数名）但功能有限的解析引擎。如果你需要一个功能强大的表达式引擎，也许IK Expression并不是最好的选择。

[size=large][b]1.1 概要（OverView）[/b][/size]
IK Expression是一个采用逆波兰式算法结合指针栈优化的公式解析引擎，它由表达式编译、、表达式执行、变量容器、以及函数配置管理四部分构成。它具有以下特点：

[list]
[*]支持基础运算符+ - × / % 逻辑运算符！ && || 三元运算符？：以及特有的#集合运算。支持括号优先级，对&&，||，？：有短路优化处理。
[*]支持函数执行，函数扩展，支持变量定义。
[*]完整Jar包大小90K，API简单易学，超轻量级，无第三方类库依赖。
[/list]
[align=center][img]http://linliangyi2007.iteye.com/upload/picture/pic/31733/356bd635-614c-3ae8-988f-674240763dd1.png[/img][/align]
[align=center]IK Expression 组件结构图[/align]


[size=large][b]1.2 升级变更（Changes Log）[/b][/size]
[b]Version2.0.2的变更：[/b]
[list]
[*]修订了自定义函数返回类型为void时，表达式校验会抛出异常的BUG。对于void返回类型，IK-Expression将当作null类型进行计算。
[/list]

[b]Version2.0.1的变更：[/b]
[list]
[*]添加了对表达式的折行书写的支持（即对表达式中出现CRLF的支持），方便于用户编写逻辑复杂的长表达式，增强表达式可阅读性。
[/list]

[b]Version2.0.0相对于V1.0的变更：[/b]
[list]
[*]增加了“？：“三元操作符。
[*]增强了“+“操作符，支持对null型，Date型，Boolean型的连接操作。
[*]增加了自定义函数扩展，支持配置方式扩展函数和API编码方式扩展函数。
[*]增加了函数别名映射功能，可配置中文函数别名。
[*]增加了函数参数和返回值对java Object类型的支持。
[*]优化“||”、“&&”、“？：“操作符，实现相应逻辑的短路处理。
[*]修订了Date类型的==比较逻辑。原有逻辑判定时间差小于1秒为相等，现在更正为精确到秒。
[*]修订了==比较逻辑对数值类型运算的bug，使其支持Integer，Float，Long，Double类型的混合比较，以及当这四种类型混合比较时，其中一个参数为null的情况。
[*]修改了V1.0中类Variable的方法createVariable的参数。
[*]废除了V1.0中的“：“操作符（使用“？：“三元操作符代替）
[*]废除了V1.0中类ExpressionEvaluator的compileExpression方法。
[*]
[/list]


[size=x-large][b]2. 快速入门（Quick Start）[/b][/size]
[size=large][b]2.1 下载（Downloadables Overview）[/b][/size]

GoogleCode开源项目：[url]http://code.google.com/p/ik-expression/[/url]
GoogleCode SVN下载：[url]http://ik-expression.googlecode.com/svn/trunk/[/url]


[size=large][b]2.2 安装部署[/b][/size]
IK Expression 的安装部署十分简单，安装包包含：
[list]
[*]1. 使用说明文档（即本文档）
[*]2. IKExpression2.0.jar
[*]3. functionConfig.xml
[/list]其中，IKExpression2.0.jar部署于项目的lib目录中；functionConfig.xml（函数定义配置）文件放置在代码根目录（对于web项目，通常是WEB-INF/classes目录，同hibernate、log4j等配置文件相同）下即可。


[size=large][b]2.3 API简易教程（API Tutorial）[/b][/size]

[b]代码样例HelloWorld [/b]

/**
 * Hello World Example
 * @param args
 */
public static void main(String[] args){
	if(args.length == 0){
		args = new String[1];
		args[0] = "IK Expression";
	}
	//定义表达式
	String expression = "\"Hello World \" + 用户名";
	//给表达式中的变量 "用户名" 付上下文的值
	List<Variable> variables = new ArrayList<Variable>();
	variables.add(Variable.createVariable("用户名", args[0]));
	//执行表达式
	Object result = ExpressionEvaluator.evaluate(expression, variables);
	System.out.println("Result = " + result);		
} 

执行结果： [color=red]Hello World IK Expression[/color]

[b]API说明[/b]
[b]*类org.wltea.expression.ExpressionEvaluator[/b]
方法1：
[b]public static Object evaluate(String expression, Collection<Variable> variables)[/b]
[b]说明：[/b]传入表达式和表达式上下文的变量，执行表达式返回结果
[b]参数1 ：[/b]String expression, 要传入执行的表达式
[b]参数2 ：[/b]Collection<Variable> variables 表达式上下文的变量集合（详细请看类org.wltea.expression.datameta.Variable的说明）。
[b]返回值：[/b]表达式执行结果，可能是以下类型的java对象中的一种：
Int、Long、Float、Double、Boolean、String、Date、List、Object。


方法2：
[b]public static Object evaluate(String expression)[/b]
[b]说明：[/b]对方法1的重载，执行简单的没有变量的表达式。请参考方法1说明.

[b]*类org.wltea.expression.datameta.Variable[/b]
该类是用来表示表达式的上下文变量的，上面的例子中用到了别名为[color=blue]“用户名”[/color]的上下文变量，这是也是表达式最有用的地方。例如，在jBPM的流程定义中，我们需要定义一个报销审批流程中，用来决定流程分支走向的表达式：

（申请金额 > 10000）？“总经理审批”：“部门经理审批”

这里需要定义一个别名为[color=blue]“申请金额“[/color]变量。变量通过evaluate(String expression, Collection<Variable> variables)方法中的variables参数传入表达式中。而Variable类型变量的构造十分的简单，它是标准的POJO。


方法1：
[b]public static Variable createVariable(String varName , Object varValue)[/b]
[b]说明：[/b]根据参数别名和参数值，构造 Variable 实例
[b]参数1 ：[/b]String varName, 参数的别名，可以是中文别名
[b]参数2 ：[/b]Object varValue，参数的值 , 可以是下类型的java对象中的一种：
Int、Long、Float、Double、Boolean、String、Date、List、Object。
[b]返回值：[/b]org.wltea.expression.datameta.Variable类的实例

方法2：(直接使用构造函数)
[b]public Variable(String varName , DataType varDataType , Object varValue)[/b]
[b]说明：[/b]根据指定的参数类型、参数别名和参数值，构造 Variable 实例
[b]参数1 ：[/b]String varName, 参数的别名，可以是中文别名
[b]参数2 ：[/b]DataType varDataType, 变量类型，它是
org.wltea.expression.datameta. BaseDataMeta.DataType枚举类型，包括的枚举值有:
[list]
[*]//NULL类型 DATATYPE_NULL ,
[*]//字符窜 DATATYPE_STRING ,
[*]//布尔类 DATATYPE_BOOLEAN ,
[*]//整型数 DATATYPE_INT ,
[*]//长整型数 DATATYPE_LONG ,
[*]//浮点数 DATATYPE_FLOAT ,
[*]//双精度浮点 DATATYPE_DOUBLE ,
[*]//日期时间 DATATYPE_DATE ,
[*]//集合对象 DATATYPE_LIST,
[*]//通用对象类型 DATATYPE_OBJECT,
[/list]
[b]参数3 ：[/b]Object varValue，参数的值 , 可以是下类型的java对象中的一种：
Int、Long、Float、Double、Boolean、String、Date、List、Object。
[b]返回值：[/b]org.wltea.expression.datameta.Variable类的实例


[size=x-large][b]3. 表达式公式规范（Expression Formula Specification）[/b][/size]
[size=large][b]3.1 数据类型（Types, Values, and Variables）[/b][/size]
[b]a) 数字型 ：[/b]
i. 整形 integer ： -2321 ， 34234
ii. 长整型 long ：3245235235L
iii. 单精度浮点 float ： 342.555F
iv. 双精度浮点 double： 234234.3423
[b]b) 字符型：[/b]“a-zA-Z012456789”
[b]c) 布尔型：[/b]true、false
[b]d) 日期时间型：[/b][2008-08-08] 或 [2009-01-01 12:33:14]
[b]e) 扩展类型：[/b]List对象集合 （该类型不支持表达式字面定义，由操作符或函数运算结果生成）
[b]f) 通用对象：[/b]Object类型 （该类型不支持表达式字面定义，由操作符或函数运算结果生成）

[size=large][b]3.2 运算符（Operators）[/b][/size]
[align=center][img]http://linliangyi2007.iteye.com/upload/picture/pic/31737/47a9c374-9896-3bb8-9e20-953bd3da486a.gif[/img][/align]
[align=center][img]http://linliangyi2007.iteye.com/upload/picture/pic/31739/552c63cd-b222-373d-9754-150d2694cb13.gif[/img][/align]

[size=large][b]3.3 分割符（Separators）[/b][/size]
[list]
[*]a) 括号 "(" ")" —— 标识优先级
[*]b) 逗号 "," —— 分隔函数的参数
[*]c) 方括号 "[" "]" —— 标识日期型常量
[*]d) 双引号 """ —— 标识字符型常量
[*]e) 美元号 "$" —— 函数标识前缀
[*]f) 转义符 "\" —— 字符串转义，支持\\ , \”, \r , \n , \t
[/list]

[size=large][b]3.4 内部函数（Inner Functions）[/b][/size]
内置函数是目前解析器已经实现的一些非常简单、实用的函数
[align=center][img]http://linliangyi2007.iteye.com/upload/picture/pic/31735/45b7dd44-f4df-3e8d-b48c-ed258596e88e.gif[/img][/align]

[size=large][b]3.5 语法约束（Lexical Structure）[/b][/size]
[list]
[*]变量命名遵循java变量命名规范（如，不能以数字打头，不能用系统操作符打头等）。
[*]函数声明以“$”符号打头，自定义函数命名遵循java方法命名规范。
[*]日期型常量使用“[]”符号界定，格式为 [yyyy-MM-dd 24h-mm-ss]，不支持毫秒。
[*]用户自定义函数别名不能重复。（详细请参阅本文4.1章节）
[*]用户自定义函数的参数和返回值类型限定于3.1章节描述的数据类型。（详细请参阅本文4.1章节）
[/list]

[size=large][b]3.6 公式样例（Formula Example）[/b][/size]
[b]1. +、- 、* 、/ 、%（取模） 常规的算术运算，支持括号优先级 ：[/b]
如：常见的OA中用于年休假工资计算公式
[color=red]3000 / 21.5 *（12 - 转正月份）/ 2 [/color]
其中，“转正月份”可以是上下文变量

[b]2. 不同数据类型的字符串连接 ：[/b]
[color=red]“ABC”+（123+10）[/color] 运算结果 “ABC133”
[color=red]“ABC”+ 123 + 10[/color] 运算结果“ABC12310”
[color=red]“[2009-08-08] + false + 123 + \"a String\" + null”[/color]
运算结果 “2009-08-08 00:00:00false123a String” （[color=red]PS:忽略 null型变量[/color]）

[b]3. > >= < <= == !=逻辑比较运算，返回布尔值 ：[/b]
[list]
[*]3-1.数值大小比较 : [color=red]1234>223 [/color] 运算结果 true
[*]3-2.字符大小比较 : [color=red]“1234”>“223”[/color] 运算结果 fasle
[*]3-3.日期大小比较 : [color=red][2008-12-23] >= [2008-08-08][/color] —— true
[*]3-4.同null的 == 与 != 比较 ： 申请人!=null (其中，“申请人”为执行上下文的变量)
[/list]

[b]4. 逻辑与、逻辑或、逻辑非运算：[/b]
[color=red]true && $DAYEQUALS([2008-01-01] , [2008-11-01])[/color] ——false
[color=red]true || $DAYEQUALS([2008-01-01] , [2008-11-01])[/color] —— true
[color=red]true && ！$DAYEQUALS([2008-01-01] , [2008-11-01])[/color] —— true

[b]5. 结果连接运算“#”：[/b]
[color=red]1000/10 # [2008-12-23]>$SYSDATE() # “ABC”+123 [/color]
运算结果 包含 100 ， false ， “ABC123”三种不同类型对象的List

[b]6. 函数与操作符混合、嵌套调用[/b]，如：

$DAYEQUALS(
 	$CALCDATE(
 	 	$SYSDATE() , 0 , 0 , 
 	 	(8+11-5*(6/3)) * (2- 59 % 7) ,
 	 	0 ,0,0 ),
 	[2009-10-01]
)  

运算结果 false

[size=x-large][b]4. 高级特性（Advance）[/b][/size]
[size=large][b]4.1 函数定制（Functions Customize）[/b][/size]
IK-Expression最吸引人的特性莫过于它允许你以非常简单的方式扩展你的自定义函数。IK-Expression带有一个xml配置文件functionConfig.xml。在使用IK-Expression时，该配置文件应放置于class的根目录中(如同spring和hibernate等的配置文件一样)。配置文件内部格式如下：
[b]functionConfig.xml[/b]

<?xml version="1.0" encoding="UTF-8"?>
<function-configuration>
	<!-- 系统函数默认配置 -->
	<bean class="org.wltea.expression.function.SystemFunctions">
		<function name="CONTAINS" method="contains">
			<parameter-type>java.lang.String</parameter-type>
			<parameter-type>java.lang.String</parameter-type>
		</function>
		<function name="STARTSWITH" method="startsWith">
			<parameter-type>java.lang.String</parameter-type>
			<parameter-type>java.lang.String</parameter-type>
		</function>
		<function name="ENDSWITH" method="endsWith">
			<parameter-type>java.lang.String</parameter-type>
			<parameter-type>java.lang.String</parameter-type>
		</function>
		<function name="CALCDATE" method="calcDate">
			<parameter-type>java.util.Date</parameter-type>
			<parameter-type>int</parameter-type>
			<parameter-type>int</parameter-type>
			<parameter-type>int</parameter-type>
			<parameter-type>int</parameter-type>
			<parameter-type>int</parameter-type>
			<parameter-type>int</parameter-type>
		</function>
		<function name="SYSDATE" method="sysDate" />
		<function name="DAYEQUALS" method="dayEquals">
			<parameter-type>java.util.Date</parameter-type>
			<parameter-type>java.util.Date</parameter-type>
		</function>
	</bean>

	<!-- 用户函数配置  ，请在这里定制您自己的函数-->

</function-configuration>

配置文件中默认配置了系统内部函数定义（[color=blue]在没有绝对必要的原因下，不建议修改系统默认函数配置[/color]）。在默认配置的下方，用户可以定义自己的函数，格式如下：
[b]用户自定义函数配置[/b]

<bean class="org.wltea.expression.test.TestFunctions">
<constructor-args>
	<constructor-arg type="java.lang.Integer">123</constructor-arg>
	<constructor-arg type="java.lang.String">aa</constructor-arg>
</constructor-args>
<function name="问好" method="sayHello">
	<parameter-type>java.lang.String</parameter-type>
</function>
</bean>

这里自定义了一个名称为“[b]问好[/b]”的函数，它有一个[b]String[/b]类型的参数。该函数映射对应于[b]org.wltea.expression.test.TestFunctions[/b]类的[b]sayHello[/b]方法，而类[b]org.wltea.expression.test.TestFunctions[/b]具有一个构造函数，构造函数带有[b]Integer[/b]型和[b]String[/b]型的参数。配置中给出了构造函数的初始化参数“[b]123[/b]”和“aa”。通过上述定义，用户就可以在表达式中使用该函数，如:
[color=red]$问好（当前用户）[/color] ， 其中“当前用户”为表达式的上下文变量。
上述例子直观的展示了用户函数自定义的过程。下面，我们将系统的了解一下IK-Expression的函数扩展定义规则和约束：

[b]1. 在IK-Expression中，函数直接对应于java的一个类的一个明确的方法。[/b]如：$CONTAINS对应org.wltea.expression.function.SystemFunctions类的contains方法；

[b]2. 所有的函数定义前，必须先定义对应的java类。如果该类使用带参数的构造函数，则必须提供明确的构造参数[/b]，如：

<bean class="org.wltea.expression.test.TestFunctions">
    <constructor-args>
        <constructor-arg type="java.lang.Integer">123</constructor-arg>
        <constructor-arg type="java.lang.String">aa</constructor-arg>
    </constructor-args>
    <function name="问好" method="sayHello">
	 <parameter-type>java.lang.String</parameter-type>
    </function>
</bean>

[b]3. java类的加载和实例化在初始化阶段一次性完成。目前IK-Expression仅支持单例形式的加载，即对一个java类仅实例化一次。[/b]
[b]
4. 定义函数时，必须明确定义函数对应java方法，以及java方法的参数类型和顺序[/b]，如：

<function name="CONTAINS" method="contains">
	<parameter-type>java.lang.String</parameter-type>
	<parameter-type>java.lang.String</parameter-type>
</function>

[b]你可以使用不同的函数名（英文的和中文的），对应相同的java方法，但对java中的方法重载必须使用不同的函数名对应([color=red]即，IK-Expression不支持函数名重载[/color])[/b]
[b]5. 函数的参数和返回值只能是IK-Expression支持的数据类型(请参考3.1数据类型 章节).[/b]
[b]6. 为了增加灵活性，IK-Expression给出了一个通过编码方式添加自定义函数的static方法。[/b]

[b]函数扩展API说明[/b]
[b]*类org.wltea.expression.function.FunctionLoader[/b]
方法1：
[b]public static void addFunction(String functionName, Object instance, Method method)[/b]
[b]参数1 ：[/b]String functionName, 要定义的函数名称（中英文皆可）。
[b]参数2 ：[/b]Object instance 函数要映射的java 类的实例。
[b]参数3 ：[/b]Method method 函数要映射的java 类的方法对象。

[align=right]（全文终）[/align]

[size=large][b]下载地址：[url]http://code.google.com/p/ik-expression/downloads/list[/url][/b][/size]