From afd6eaf7a9a19fafeaa1fc98dc4c3e7aabdd7543 Mon Sep 17 00:00:00 2001 From: "Alex A. Naanou" Date: Tue, 23 Aug 2016 17:25:55 +0300 Subject: [PATCH] working on docs.. Signed-off-by: Alex A. Naanou --- README.md | 221 +++++++++++++++++++++++++++--------------------------- 1 file changed, 111 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 37b3643..c191bb3 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,10 @@ Actions are an extension to the JavaScript object model tailored for a set of specific tasks. ### Goals: - - provide a unified mechanism to define and manage user API's for - use in UI-hooks, keyboard mappings, scripting, ... etc. - - a means to generate configuration UI's - - a means to generate documentation +- provide a unified mechanism to define and manage user API's for + use in UI-hooks, keyboard mappings, scripting, ... etc. +- a means to generate configuration UI's +- a means to generate documentation ### The main entities: @@ -72,152 +72,153 @@ Root Action o---|---x ### The action system main protocols: -1) Documentation generation and introspection (MetaActions) +1. Documentation generation and introspection (MetaActions) -``` -.toString() - -> code of original action function + ``` + .toString() + -> code of original action function -.getDoc() -.getDoc([, ..]) - -> dict of action-name, doc + .getDoc() + .getDoc([, ..]) + -> dict of action-name, doc -.a.getHandlerDocStr() - -> formated string of action handlers + .a.getHandlerDocStr() + -> formated string of action handlers -.actions - -> list of action names + .actions + -> list of action names -.length - -> number of actions -``` + .length + -> number of actions + ``` -2) Event-like callbacks for actions (MetaActions, Action) +2. Event-like callbacks for actions (MetaActions, Action) -``` -.on('action', function(){ ... }) -.on('action.post', function(){ ... }) + ``` + .on('action', function(){ ... }) + .on('action.post', function(){ ... }) -.on('action.pre', function(){ ... }) -``` + .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 mechanisms (Action, Actions) -``` -// Actions... -var X = Actions({ - m: [function(){ console.log('m') }] -}) -var O = Actions(X, { - m: [function(){ - console.log('pre') - return function(res){ - console.log('post') - } - }] -}) -``` + ``` + // Actions... + var X = Actions({ + m: [function(){ console.log('m') }] + }) + var O = Actions(X, { + m: [function(){ + console.log('pre') + return function(res){ + console.log('post') + } + }] + }) + ``` - NOTE: what is done here is similar to calling O.__proto__.m.call(..) - but is implicit, and not dependant on the original containing - object name/reference ('O'), thus enabling an action to be - referenced and called from any object and still chain correctly. + NOTE: what is done here is similar to calling `O.__proto__.m.call(..)` + but is implicit, and not dependant on the original containing + object name/reference ('O'), thus enabling an action to be + referenced and called from any object and still chain correctly. ### 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() -.pre(, [, ..]) - -> -``` + Pre phase... + ``` + .pre() + .pre(, [, ..]) + -> + ``` -Post phase... -``` -.post(, ) - -> -``` + Post phase... + ``` + .post(, ) + -> + ``` -This is internally used to implement the action call as well as the -chaining callbacks (see below). + This is internally used to implement the action call as well as the + 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 - calling the pre phase due to how the pre phase is defined (i.e. - pre phase functions can return post phase functions). + 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. + 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 the root action's (outer) pre and post stages. -``` -Outer action o-------x o-------x - v ^ -Inner action/callback o---|---x -``` + ``` + Outer action o-------x o-------x + v ^ + Inner action/callback o---|---x + ``` -A trivial example: + A trivial example: -``` -actionSet.someAction.chainApply(actionsSet, - function(){ - // this gets run between someAction's pre and post - // stages... - }, - args) -``` + ``` + actionSet.someAction.chainApply(actionsSet, + function(){ + // this gets run between someAction's pre and post + // stages... + }, + args) + ``` -This is intended to implement protocols where a single action is -intended to act as a hook point (outer) and multiple different -implementations (inner) within a single action set can be used as -entry points. + This is intended to implement protocols where a single action is + intended to act as a hook point (outer) and multiple different + implementations (inner) within a single action set can be used as + entry points. -``` -// Protocol root action (outer) definition... -protocolAction: [function(){}], + ``` + // Protocol root action (outer) definition... + protocolAction: [function(){}], -// Implementation actions (inner)... -implementationAction1: [function(){ - return this.protocolAction.chainApply(this, function(){ - // ... - }, ..) -}] + // Implementation actions (inner)... + implementationAction1: [function(){ + return this.protocolAction.chainApply(this, function(){ + // ... + }, ..) + }] -implementationAction2: [function(){ - return this.protocolAction.chainApply(this, function(){ - // ... - }, ..) -}] -``` + implementationAction2: [function(){ + return this.protocolAction.chainApply(this, function(){ + // ... + }, ..) + }] + ``` -Now calling any of the 'implementation' actions will execute code -in the following order: - 1) pre phase of protocol action (outer) - 2) implementation action (inner) - 3) post phase of protocol action (outer) + Now calling any of the 'implementation' actions will execute code + in the following order: + 1. pre phase of protocol action (outer) + 2. implementation action (inner) + 3. post phase of protocol action (outer) -NOTE: this will not affect to protocol/signature of the outer action - in any way. -NOTE: both the inner and outer actions will get passed the same - arguments. -NOTE: another use-case is testing/debugging actions. -NOTE: this is effectively the inside-out of normal action overloading. -NOTE: there is intentionally no shorthand for this feature, to avoid - confusion and to discourage the use of this feature unless - really necessary. + NOTE: this will not affect to protocol/signature of the outer action + in any way. + NOTE: both the inner and outer actions will get passed the same + arguments. + NOTE: another use-case is testing/debugging actions. + NOTE: this is effectively the inside-out of normal action overloading. + NOTE: there is intentionally no shorthand for this feature, to avoid + confusion and to discourage the use of this feature unless + really necessary. -3) `.__call__` action / handler +3. `.__call__` action / handler + This action if defined is called for every action called. It behaves 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