elegant.def v3.0.0-alpha.2
elegant.def
Elegant define javascript function
Usage
Using
this
var index = def(function index() { /** * @rule (Array arr [, Int num]) -> * */ return this.arr[this.num]; }); index([1,2,3], 1) === 2;
Using
self
var index = def(function index(self) { /** * @rule (Array arr [, Int num]) -> * */ return self.arr[self.num]; }); index([1,2,3], 1) === 2;
Using arguments inject
var index = def(function index(arr, other) { /** * @rule (Array arr [, Int num]) -> * */ // Parameter `other` will always be `undefined` return arr[this.num]; }); index([1,2,3], 1) === 2;
Install
Node
npm install elegant.def --save
var def = require('elegant.def');
Browser
bower install elegant.def --save
// Then use elegant.def/browser/full.js or elegant.def/browser/simple.js
Code Need Minimize?
When code minimized, comment will be removed, include the def's heredoc comment, so you must compile it before minimizing your code.
You can using below 5 methods to compile your code:
CLI
- Global install
elegant.def
:npm install -g elegant.def
- Compile your file:
def-compile path/to/source/file
- Global install
Node script
var compile = require('elegant.def/src/compile'); var fs = require('fs'); var inputContent = fs.readFileSync('path/to/source/file').toString(); var outputContent = compile(inputContent, {defName: 'def'}); // process the outputContent // ...
Online compile
gulp-def
grunt-def
Surprise
when your code is compiled, you can use a smaller elegant.def script.
- Small version in node:
var def = require('elegant.def/src/simple')
- Small version in browser:
elegant.def/browser/simple.js
Doc generate
- Global install this package:
npm install -g elegant.def
- Using
def-doc
cli command:def-doc path/to/*.js
Config items in heredoc
ITEM | DESCRIPTION |
---|---|
@name | String , Function name |
@alias | String , Function name alias |
@example | String , Function example, used in generating doc |
@defaults | Object , Function's arguments default values |
@rule | The main config item (Continue to see more detail) |
rule
Format: (type_1 name_1, [type_2 name_2 = defaultValue]) -> returnType
e.g:
// Basic
(int min, int max) -> int
(int length) -> int
// Optional argument with a default value
([string pool='alpha'], int repeat) -> string
// Rest argument
(int ...numbers, string foo) -> int
Note
- Values in heredoc (include @defaults and @rule's arguments value) is parsed by jsonfy.
- If no rule defined, it will return the original function.
- For now,
returnType
was just used as understanding the rule's return type, no other use.
API
def.is(mix, type)
Judge if mix
is type
e.g:
def.is(true, 'boolean') // true
def.is('123', 'number') // false
def.type(key, fn)
Define a new type or overwrite an exists type.
fn
is used to judge if a parameter is your defined type.
e.g:
def.type('float', function(mix) {
return def.is(mix, 'number') && !def.is(mix, 'int')
});
def.unType(key), def.untype(key)
Delete a defined type name.
e.g:
def.unType('float');
def.normalize(key)
Transform type alias name to it original name.
e.g:
def.normalize('integer'); // => int
Support types
Case Insensitive
TYPE | DESCRIPTION |
---|---|
int, integer, signed | 整数 |
unsigned, nature | 大于等于0的整数(自然数) |
positive | 大于0的整数 |
negative | 小于0的整数 |
number | 所有数字(包括浮点数) |
string | 字符串 |
object | 简单的 object (不包括 array, arguments 等) |
array | 数组 |
function | 函数 |
arguments | 函数的参数类型 |
bool, boolean | 布尔 |
null | Null(其实这个没什么意义,这个变量的类型是 Null) |
* | 通配类型,可以匹配任何的类型(尽量少用,写这个程序的目的就是强化JS里的数据类型) |
TODO
- 支持 SourceMap
- 加上返回值的监控(5)
- rule 可以指定名称,然后在函数执行是可以知道当前是匹配了哪条 rule
- 整合我的 spa-bootstrap
- 支持新类型 enum: (string flag = ok|cancel, string foo)
- 支持多 type: (string|int some, bool other) -> *
- 根据 rule 自动化测试
- 自动测试
silent def
// hack silent def var _def = def; def = function() { var binder = this; try { _def.apply(this, arguments); } catch (e) {}; };
HISTORY
v1.0.0 之后更新日志移入到 CHANGELOG.md
2015-01-13 可以用
def.type
来重新定义系统上已经存在的 type,但def.unType
只能删除重新定义的,不会删除系统已有的(尚末测试)- 2015-01-12 在 self 中添加变量
$defaults
,可以让函数体访问自己定义的默认值(尚末测试) 2015-01-12 rule 中设置参数的默认 int 值为 0 或 负数 时,会将它们当作字符串(已加测试,待发布)
主要是 isNumerical 函数少判断了为 0 和 负数 的情况