flynx/actions.js
1
0
Fork 0
mirror of https://github.com/flynx/actions.js.git synced 2025-10-29 10:20:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

working on docs..

Browse Source 
Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
This commit is contained in:
Alex A. Naanou 2016-08-23 17:25:55 +03:00
parent 0df03cab41
commit afd6eaf7a9
1 changed files with 111 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
README.md
View File

@ -7,10 +7,10 @@ Actions are an extension to the JavaScript object model tailored for
a set of specific tasks. a set of specific tasks.
### Goals: ### Goals:
- provide a unified mechanism to define and manage user API's for - provide a unified mechanism to define and manage user API's for
use in UI-hooks, keyboard mappings, scripting, ... etc. use in UI-hooks, keyboard mappings, scripting, ... etc.
- a means to generate configuration UI's - a means to generate configuration UI's
- a means to generate documentation - a means to generate documentation
### The main entities: ### The main entities:
@ -72,152 +72,153 @@ Root Action o---|---x
### The action system main protocols: ### The action system main protocols:
1) Documentation generation and introspection (MetaActions) 1. Documentation generation and introspection (MetaActions)
``` ```
<action>.toString() <action>.toString()
-> code of original action function -> code of original action function
<action-set>.getDoc() <action-set>.getDoc()
<action-set>.getDoc(<action-name>[, ..]) <action-set>.getDoc(<action-name>[, ..])
-> dict of action-name, doc -> dict of action-name, doc
<action-set>.a.getHandlerDocStr(<action-name>) <action-set>.a.getHandlerDocStr(<action-name>)
-> formated string of action handlers -> formated string of action handlers
<action-set>.actions <action-set>.actions
-> list of action names -> list of action names
<action-set>.length <action-set>.length
-> number of actions -> number of actions
``` ```
2) Event-like callbacks for actions (MetaActions, Action) 2. Event-like callbacks for actions (MetaActions, Action)
``` ```
<action-set>.on('action', function(){ ... }) <action-set>.on('action', function(){ ... })
<action-set>.on('action.post', function(){ ... }) <action-set>.on('action.post', function(){ ... })
<action-set>.on('action.pre', function(){ ... }) <action-set>.on('action.pre', function(){ ... })
``` ```
3) A mechanism to define and extend already defined actions 3. A mechanism to define and extend already defined actions
This replaces / complements the standard JavaScript overloading This replaces / complements the standard JavaScript overloading
mechanisms (Action, Actions) mechanisms (Action, Actions)
``` ```
// Actions... // Actions...
var X = Actions({ var X = Actions({
m: [function(){ console.log('m') }] m: [function(){ console.log('m') }]
}) })
var O = Actions(X, { var O = Actions(X, {
m: [function(){ m: [function(){
console.log('pre') console.log('pre')
return function(res){ return function(res){
console.log('post') console.log('post')
} }
}] }]
}) })
``` ```
NOTE: what is done here is similar to calling O.__proto__.m.call(..) NOTE: what is done here is similar to calling `O.__proto__.m.call(..)`
but is implicit, and not dependant on the original containing but is implicit, and not dependant on the original containing
object name/reference ('O'), thus enabling an action to be object name/reference ('O'), thus enabling an action to be
referenced and called from any object and still chain correctly. referenced and called from any object and still chain correctly.
### Secondary action protocols: ### Secondary action protocols:
1) A mechanism to manually call the pre/post stages of an action 1. A mechanism to manually call the pre/post stages of an action
Pre phase... Pre phase...
``` ```
<action>.pre(<context>) <action>.pre(<context>)
<action>.pre(<context>, [<arg>, ..]) <action>.pre(<context>, [<arg>, ..])
-> <call-data> -> <call-data>
``` ```
Post phase... Post phase...
``` ```
<action>.post(<context>, <call-data>) <action>.post(<context>, <call-data>)
-> <result> -> <result>
``` ```
This is internally used to implement the action call as well as the This is internally used to implement the action call as well as the
chaining callbacks (see below). chaining callbacks (see below).
All action protocol details apply. All action protocol details apply.
NOTE: there is not reliable way to call the post phase without first NOTE: there is not reliable way to call the post phase without first
calling the pre phase due to how the pre phase is defined (i.e. calling the pre phase due to how the pre phase is defined (i.e.
pre phase functions can return post phase functions). pre phase functions can return post phase functions).
2) A mechanism to chain/wrap actions or an action and a function. 2. A mechanism to chain/wrap actions or an action and a function.
This enables us to call a callback or another action (inner) between This enables us to call a callback or another action (inner) between
the root action's (outer) pre and post stages. the root action's (outer) pre and post stages.
``` ```
Outer action o-------x o-------x Outer action o-------x o-------x
v ^ v ^
Inner action/callback o---|---x Inner action/callback o---|---x
``` ```
A trivial example: A trivial example:
``` ```
actionSet.someAction.chainApply(actionsSet, actionSet.someAction.chainApply(actionsSet,
function(){ function(){
// this gets run between someAction's pre and post // this gets run between someAction's pre and post
// stages... // stages...
}, },
args) args)
``` ```
This is intended to implement protocols where a single action is This is intended to implement protocols where a single action is
intended to act as a hook point (outer) and multiple different intended to act as a hook point (outer) and multiple different
implementations (inner) within a single action set can be used as implementations (inner) within a single action set can be used as
entry points. entry points.
``` ```
// Protocol root action (outer) definition... // Protocol root action (outer) definition...
protocolAction: [function(){}], protocolAction: [function(){}],
// Implementation actions (inner)... // Implementation actions (inner)...
implementationAction1: [function(){ implementationAction1: [function(){
return this.protocolAction.chainApply(this, function(){ return this.protocolAction.chainApply(this, function(){
// ... // ...
}, ..) }, ..)
}] }]
implementationAction2: [function(){ implementationAction2: [function(){
return this.protocolAction.chainApply(this, function(){ return this.protocolAction.chainApply(this, function(){
// ... // ...
}, ..) }, ..)
}] }]
``` ```
Now calling any of the 'implementation' actions will execute code Now calling any of the 'implementation' actions will execute code
in the following order: in the following order:
1) pre phase of protocol action (outer) 1. pre phase of protocol action (outer)
2) implementation action (inner) 2. implementation action (inner)
3) post phase of protocol action (outer) 3. post phase of protocol action (outer)
NOTE: this will not affect to protocol/signature of the outer action NOTE: this will not affect to protocol/signature of the outer action
in any way. in any way.
NOTE: both the inner and outer actions will get passed the same NOTE: both the inner and outer actions will get passed the same
arguments. arguments.
NOTE: another use-case is testing/debugging actions. NOTE: another use-case is testing/debugging actions.
NOTE: this is effectively the inside-out of normal action overloading. NOTE: this is effectively the inside-out of normal action overloading.
NOTE: there is intentionally no shorthand for this feature, to avoid NOTE: there is intentionally no shorthand for this feature, to avoid
confusion and to discourage the use of this feature unless confusion and to discourage the use of this feature unless
really necessary. really necessary.
3) `.__call__` action / handler 3. `.__call__` action / handler
This action if defined is called for every action called. It behaves This action if defined is called for every action called. It behaves
like any other action but with a fixed signature, it always receives like any other action but with a fixed signature, it always receives
the action name as first argument and a list of action arguments as the action name as first argument and a list of action arguments as