ESOE Specification 0.2


	Copyright

Feng WeiGuo
forxm@21cn.com
http://www.viviasoft.com

2006-8


	Overview

This specification defines a method of object-oriented programming with ECMAScript 3rd compatible language.


	Glossary

This part list some terms and their meaning that used in ESOE. Note their meaning in ESOE may be different from their normal meaning.

Name space: The name space of an object is to show where this objet is located, relative to one of another object. It can be expressed by a chain of objects, or by a chain of the names of these objects.
Global name space: The GLOBAL object is the object which the name space is relative to.
Package: ...
Constructor: A Function object.
Prototype: A constructor's prototype object.
Class: A set that contain a constructor and its prototype. In ESOE, 'class' is especially used to indicate the prototype.
Declare: Ask a constructor to prepare its prototype.
Declare fucntion: A method of a constructor to do the declaring job.
Normalize: Create the name space of a declared class and make it ready for using.
Pre-Normalize: Create the name space of an un-declared class. The class is not ready for using.
Import: Map a normalized class to another object.
Derive: ESOE use statement like "Derive a class from a base class", and don't use words like 'extend', 'inherit', etc..
Base class & Derived class: Two sides of the deriving relationship. ESOE don't use words like 'subclass', 'superclass', 'parent class', etc..
Include: Load library files or class files.
Share: Share one ESOE object and its class libraries in deferrent GLOBAL object.
Memory leakage: Some ECMAScript system with deficiency will not release useless memory correctly, and cause memory consumption increasing continuously.
Circular references: A kind of memory leakage...
Enclosure function: A kind of memory leakage...
Destroy function: A method of the class to avoid or decrease memory leakage.
ESOE Application: Application that use ESOE.


	Modules

ESOE of current version includes 6 modules.

 Feature           Description               
M1 : kernel 1. Name space definition
2. Class definition
3. Class deriving
4. Keywords definition
5. Module loading
6. Debug tool 1. Support script language compatible with ECMA-262 3rd.
2. Manually load classes and libraries.
3. The  release version of an application can use only M1 for efficiency.
M2 : resource 1. Physcal mapping of name space.
2. Resource loading. 
M3 : loader 1. Automatically classes loading. 1. M3 depend on M2.
M4 : destroy 1. Destroy mechanism 1. A temprorary module.
2. M4 may be related to all other modules.
M5 : share 1. Class sharing
2. Share the ESOE itself


	Conventions


	Name Conventions

$esoe ESOE engine it self
_property Prefix "_" to a property, except the "$esoe.ns". All in lowercase.
$property Prefix "$" to the properties related to file loading. All in lowercase.
_keyword Prefix "_" to c2 and c4 keywords. All in lowercase.
$esoe.MyFunc() To other function in $esoe, the first letter of each word is uppercase.
func abbr. function/constructor
ns abbr. name space
pkg abbr. package


	Keywords


	Keywords Category

 Keyword Conflicting 
substitute Description                             
c1 $esoe
prototype._esoe
[object]._esoe 1. If any c1 keywords conflict, ESOE engine will fail.
c2 _ns
_package
_normalize
_import
_derive
_derivex
_setpath (M2)
_getpath (M2)
_loadres (M2)
_update (M3) $esoe.* 1. The substitute $esoe.* means that both '_keyword' and '$esoe._keyword' can be used.
2. If any c2 keywords conflict, close those keywords with the "nokey" parameter, and use the $esoe.* version..
3. In the release version, it's better to convert all c2 keywords to their $esoe.* version.
c3 prototype._base
prototype._pkg prototype._esoe.* 1. For ESOE class, c3 keywords are same as c4 keywords and it's user's duty to avoid c3 keywords conflicting.
2. If any c3 keywords conflict with a non-esoe object, close this object's all c3 keywords when it's normalized, and use the _esoe.* version.
c4 [func]._declare
prototype._set
prototype._destroy (M4)
prototype._share (M5)
$esoe.Share (M5) 1. C4 keywords is for ESOE class and will not conflict theoretically. Or it's user's duty to avoid c4 keywords conflicting.


	Keywords Introduction

Keyword Description
$esoe =window.$esoe, the esoe engine.
prototype._esoe Property to maintain classes/objects information.
[object]._esoe Property to maintain none-esoe classes/objects information.
_ns Pre-define a name space or get an object by its name space.
_package Same as _ns, for compatibility.
_normalize Normalize constructors or non-esoe objects.
_import Import a class
_derive Derive a class from a base class
_derivex Multiple deriving, or properties clone.
_setpath (M2) Set the physical path of a name space
_getpath (M2) Get the physical path of a name space
_loadres (M2) Load the resource files of a class
_update (M3) Update the imported classes. If the loading of classes or libraries need recursive process, call this to active it.
prototype._base Base class, that is, base class constructor's prototype
prototype._pkg The nearest package of a class
[func]._declare The declaring function of a class.
prototype._set The initializing function of a class.
prototype._destroy (M4) The destroy function of a class.
prototype._share (M5) The share initializing function of a class.
$esoe.Share (M5) Create a shared ESOE object for current GLOBAL.


	ESOE Object


	ESOE Layout

ESOE layout includes below parts,
1. Load ESOE engine, load parameters.
2. Set resource physical path. It's optional.
3. Manually load libraries. It's optional for M3.
4. Import all classes that will be used.

Note:
1. ESOE layout is strongly suggested to be independent from other user codes, although it's not necessary in some environment.
2. For M3, when loading non-esoe classes with dependency relationship, the part 4 of the layout can be used for many times by the dependency sequence.

Linked to: [Javascript Implementation for ESOE 0.2] > [ESOE Layout]


	Example 1, HTML/javascript, M1+M2


	Example 2, HTML/javascript, M1+M2+M3


	Example 3, HTML/javascript, M1+M2+M3+M5, primary ESOE


	Example 4, HTML/javascript, M1+M2+M3+M5, secondary ESOE


	Create ESOE Engine

Create a window.$esoe as an Object object.
	window.$esoe= new Object;


	ESOE Parameters

ESOE object has properties that can be loaded from external.

_param 保存所有参数以备将来使用.
_path ESOE引擎的物理路径
_module 指示要加载的模块的字串, 可选的模块代码为1,2,3,4,5. 其中1为默认加载的核心模块, 可省略. 其它模块代码以','分隔.
例子:
"1"          M1 (默认)
"2"          M1+M2
"4,5"        M1+M4+M5
_debug 调试级别参数, 当前版本可设为以下值,
0: 不调试 (默认)
1: 设置为最低的调试级别
9: 设置为最高的调试级别
_nokey c2 关键字冲突列表, 如果设为'*', 禁用所有c2关键字.
_libpath (M2) 默认类库加载路径, 只可设置1个. 如果未设置, 使用_path作为默认路径.
_libmode (M3) 默认类库/类文件加载模式
0: 不加载任何默认类库/类文件 (默认).
1: 先加载默认类库文件, 再加载类文件.
2: 先加载类文件, 再加载默认类库文件.
3: 仅加载默认类库文件.
4: 仅加载类文件
说明:
1. 对实际的应用系统, 并非所有的加载模式都可正常工作, 应根据调试/发行/配置等具体情况进行设置.
_nodestroy (M4) 在将来, 对于较完善的ECMAScript实现系统, 如果不存在内存泄漏问题, 可以关闭清理函数机制. 可选值, 0 (默认) 或1.


	Internal Properties

ESOE object has below internal properties, user should not change these values directly.


	Internal Properties

_id ESOE引擎序号, 主引擎为1, 共享引擎依次递增.
_nextid 用于产生_id的辅助变量
_global 当前$esoe的全局环境
_main (M5) 主引擎的全局环境
_track 1. 用于记录M5创建的所有共享ESOE对象.2. 用于记录M4创建的所有须要清理的对象.
ns 主名称空间根节点, 所有类库载入的位置
_lib 用于保存ns物理映射和类库载入过程的名称空间
_lib.$count (M3) 保存当前载入过程的已载入文件数量
_lib.$ext (M3) 如果载入了一个默认类库文件或外部文件, 此属性设为1, 否则为0.
_trace 用于保存调试信息的对象


	$esoe._lib item properties

[item].$path 保存由_setpath()所设置的路径
[item].$run 用于记录类的加载状态, 以避免循环加载. 如类正被加载, 值加1, 如加载退出, 值减1
[item].$alone (M5) 如共享类在主引擎加载, 设为0; 如在本地环境中被加载, 设为1
[item].$map (M3) 保存由_import()所设置的全局名称空间.
[item].$inc (M3) 保存一个类库/类文件已加载的次数
[item].$fail (M3) 如果类不存在, 保存类的名称空间字串. 如果类已加载, 清除此属性.


	Name Space


	Name Space Definition

The name space of an object is to use a chain of objects to indeicate where this objet is located. In ESOE, all object chain is look upon as some kind of name space. The first object of the chain is called the root of the name space, it must be the GLOBAL object or an object that can contain property, and we say that the name space is mapped into this root object.

Example:
var obj= new Object;
obj.com= new Object;
obj.com.mycompany= new Object;
obj.com.mycompany.myclass= new Object;

It can be said that the name spaces ("com", "com.mycompany", "com.mycompany.myclass") are mapped into the "obj" object, or the name spaces ("mycompany", "mycompany.myclass") are mapped into the "obj.com" object, etc.. Especially, the name space "obj.com.mycompany.myclass" is mapped into the GLOBAL object.


	Package Definition


	Name space of ESOE / _ns() / _package()


	Normalizing / _normalize()


	prototype._esoe properties

_esoe._type 标记对象类型, 1:  class, 2: object
_esoe._pkg 类所属的最底层的包.
_esoe._conflict 如果有c3关键字冲突, 设为1.
_esoe._nonesoe 如果类是非ESOE对象, 设为1.
_esoe._shared (M5) 如果类是共享对象, 设为1.


	Normalize Non-ESOE Constructor


	Normalize Non-ESOE Object

For some existed library system, it may have used global variables. To rapidly transform these systems to be compatible with ESOE engine, global variables can be map into the name space also. It does just like normalizing a non-esoe function. The _esoe property is directly added to the object instead of prototype.

Normalizing a non-esoe object will not set the prototype.constructor.


	Physical Mapping of Name Space


	Set Name Space Path / _setpath() / _getpath()


	Automatically Load Libraries (M3)


	Update Imported Classes / _update() (M3)


	Class


	Class Definition


	this


	Importing Class / _import()


	Class Deriving / _derive()


	Multiple Deriving and Properties Clone / _derivex()


	Member Access Control

 内在修饰 类型 属性声明位置 访问位置
1 private 任意 构造函数, var声明 构造函数
2 static, private 任意 独立的声明函数, var声明 声明函数
3 public 变量 使用prototype.[propety]  声明简单变量, 并直接赋值 任意
4 static, public 对象 使用prototype.[propety]  声明对象变量, 并直接赋值 任意
5 public 对象 使用prototype.[propety]  声明对象变量, 并在_set()中赋值 任意


	Instance initializing / _set()


	Use other classes


	Class Layout Example 1


	Class Layout Example 2


	Resource Loading / _loadres()


	ESOE Sharing (M5)


	Share the $esoe object


	Sharing Initializing / prototype._share


	Code Sample


	Destroy Function


	Destroy ESOE Engine


	Destroy Class / prototype._destroy()


	Destroy Sharing ESOE and Class

	Feature	Description
M1 : kernel	1. Name space definition 2. Class definition 3. Class deriving 4. Keywords definition 5. Module loading 6. Debug tool	1. Support script language compatible with ECMA-262 3rd. 2. Manually load classes and libraries. 3. The release version of an application can use only M1 for efficiency.
M2 : resource	1. Physcal mapping of name space. 2. Resource loading.
M3 : loader	1. Automatically classes loading.	1. M3 depend on M2.
M4 : destroy	1. Destroy mechanism	1. A temprorary module. 2. M4 may be related to all other modules.
M5 : share	1. Class sharing 2. Share the ESOE itself

$esoe	ESOE engine it self
_property	Prefix "_" to a property, except the "$esoe.ns". All in lowercase.
$property	Prefix "$" to the properties related to file loading. All in lowercase.
_keyword	Prefix "_" to c2 and c4 keywords. All in lowercase.
$esoe.MyFunc()	To other function in $esoe, the first letter of each word is uppercase.
func	abbr. function/constructor
ns	abbr. name space
pkg	abbr. package

	Keyword	Conflicting substitute	Description
c1	$esoe prototype._esoe [object]._esoe		1. If any c1 keywords conflict, ESOE engine will fail.
c2	_ns _package _normalize _import _derive _derivex _setpath (M2) _getpath (M2) _loadres (M2) _update (M3)	$esoe.*	1. The substitute $esoe.* means that both '_keyword' and '$esoe._keyword' can be used. 2. If any c2 keywords conflict, close those keywords with the "nokey" parameter, and use the $esoe.* version.. 3. In the release version, it's better to convert all c2 keywords to their $esoe.* version.
c3	prototype._base prototype._pkg	prototype._esoe.*	1. For ESOE class, c3 keywords are same as c4 keywords and it's user's duty to avoid c3 keywords conflicting. 2. If any c3 keywords conflict with a non-esoe object, close this object's all c3 keywords when it's normalized, and use the _esoe.* version.
c4	[func]._declare prototype._set prototype._destroy (M4) prototype._share (M5) $esoe.Share (M5)		1. C4 keywords is for ESOE class and will not conflict theoretically. Or it's user's duty to avoid c4 keywords conflicting.

_param	保存所有参数以备将来使用.
_path	ESOE引擎的物理路径
_module	指示要加载的模块的字串, 可选的模块代码为1,2,3,4,5. 其中1为默认加载的核心模块, 可省略. 其它模块代码以','分隔. 例子: "1" M1 (默认) "2" M1+M2 "4,5" M1+M4+M5
_debug	调试级别参数, 当前版本可设为以下值, 0: 不调试 (默认) 1: 设置为最低的调试级别 9: 设置为最高的调试级别
_nokey	c2 关键字冲突列表, 如果设为'*', 禁用所有c2关键字.
_libpath (M2)	默认类库加载路径, 只可设置1个. 如果未设置, 使用_path作为默认路径.
_libmode (M3)	默认类库/类文件加载模式 0: 不加载任何默认类库/类文件 (默认). 1: 先加载默认类库文件, 再加载类文件. 2: 先加载类文件, 再加载默认类库文件. 3: 仅加载默认类库文件. 4: 仅加载类文件说明: 1. 对实际的应用系统, 并非所有的加载模式都可正常工作, 应根据调试/发行/配置等具体情况进行设置.
_nodestroy (M4)	在将来, 对于较完善的ECMAScript实现系统, 如果不存在内存泄漏问题, 可以关闭清理函数机制. 可选值, 0 (默认) 或1.

_id	ESOE引擎序号, 主引擎为1, 共享引擎依次递增.
_nextid	用于产生_id的辅助变量
_global	当前$esoe的全局环境
_main (M5)	主引擎的全局环境
_track	1. 用于记录M5创建的所有共享ESOE对象.2. 用于记录M4创建的所有须要清理的对象.
ns	主名称空间根节点, 所有类库载入的位置
_lib	用于保存ns物理映射和类库载入过程的名称空间
_lib.$count (M3)	保存当前载入过程的已载入文件数量
_lib.$ext (M3)	如果载入了一个默认类库文件或外部文件, 此属性设为1, 否则为0.
_trace	用于保存调试信息的对象

[item].$path	保存由_setpath()所设置的路径
[item].$run	用于记录类的加载状态, 以避免循环加载. 如类正被加载, 值加1, 如加载退出, 值减1
[item].$alone (M5)	如共享类在主引擎加载, 设为0; 如在本地环境中被加载, 设为1
[item].$map (M3)	保存由_import()所设置的全局名称空间.
[item].$inc (M3)	保存一个类库/类文件已加载的次数
[item].$fail (M3)	如果类不存在, 保存类的名称空间字串. 如果类已加载, 清除此属性.

_esoe._type	标记对象类型, 1: class, 2: object
_esoe._pkg	类所属的最底层的包.
_esoe._conflict	如果有c3关键字冲突, 设为1.
_esoe._nonesoe	如果类是非ESOE对象, 设为1.
_esoe._shared (M5)	如果类是共享对象, 设为1.

	内在修饰	类型	属性声明位置	访问位置
1	private	任意	构造函数, var声明	构造函数
2	static, private	任意	独立的声明函数, var声明	声明函数
3	public	变量	使用prototype.[propety] 声明简单变量, 并直接赋值	任意
4	static, public	对象	使用prototype.[propety] 声明对象变量, 并直接赋值	任意
5	public	对象	使用prototype.[propety] 声明对象变量, 并在_set()中赋值	任意