Skip to content

Commit

Permalink
v4.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@rjrodger
rjrodger committed May 18, 2020
1 parent 8a0142c commit b0a330d
Show file tree
Hide file tree
Showing 10 changed files with 425 additions and 419 deletions.
38 changes: 19 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,8 +109,8 @@ itself.

## Action Patterns

* [describe:plugin,sys:doc](#-describepluginsysdoc-)
* [describe:pin,sys:doc](#-describepinsysdoc-)
* [sys:doc,describe:pin](#-sysdocdescribepin-)
* [sys:doc,describe:plugin](#-sysdocdescribeplugin-)


<!--END:action-list-->
Expand All @@ -120,9 +120,9 @@ itself.

## Action Descriptions

### &laquo; `describe:plugin,sys:doc` &raquo;
### &laquo; `sys:doc,describe:pin` &raquo;

Provide introspection data for a plugin and its actions.
Provide introspection data for actions matching a _pin_ (a sub pattern).



Expand All @@ -131,16 +131,13 @@ Provide introspection data for a plugin and its actions.



* `describe:plugin,sys:doc,plugin:entity`
* Describe the seneca-entity plugin.

* `describe:plugin,sys:doc,plugin:entity$foo`
* Describe the seneca-entity plugin instance with tag _foo_.
* `sys:doc,describe:pin,pin:"a:1,b:2"`
* Describe actions matching at least `a:1,b:2`.
#### Parameters


* _plugin_ : string <i><small>{presence:required}</small></i>
: The full name of the plugin (if tagged, use the form name$tag).
* _pin_ : alternatives <i><small>"&nbsp;"</small></i>
: The pin sub pattern in string or object format.



Expand All @@ -150,7 +147,7 @@ Provide introspection data for a plugin and its actions.

```
{
plugin: 'plugin parameter',
pin: 'pin parameter',
actions: [
'{ Seneca action definition }'
]
Expand All @@ -159,9 +156,9 @@ Provide introspection data for a plugin and its actions.


----------
### &laquo; `describe:pin,sys:doc` &raquo;
### &laquo; `sys:doc,describe:plugin` &raquo;

Provide introspection data for actions matching a _pin_ (a sub pattern).
Provide introspection data for a plugin and its actions.



Expand All @@ -170,13 +167,16 @@ Provide introspection data for actions matching a _pin_ (a sub pattern).



* `describe:pin,sys:doc,pin:"a:1,b:2"`
* Describe actions matching at least `a:1,b:2`.
* `sys:doc,describe:plugin,plugin:entity`
* Describe the seneca-entity plugin.

* `sys:doc,describe:plugin,plugin:entity$foo`
* Describe the seneca-entity plugin instance with tag _foo_.
#### Parameters


* _pin_ : alternatives <i><small>{presence:required}</small></i>
: The pin sub pattern in string or object format.
* _plugin_ : string <i><small>"&nbsp;"</small></i>
: The full name of the plugin (if tagged, use the form name$tag).



Expand All @@ -186,7 +186,7 @@ Provide introspection data for actions matching a _pin_ (a sub pattern).

```
{
pin: 'pin parameter',
plugin: 'plugin parameter',
actions: [
'{ Seneca action definition }'
]
Expand Down
14 changes: 8 additions & 6 deletions bin/seneca-doc-exec.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,10 @@ async function inspect_local_plugin() {
: null

// NOTE: use -t for further top level names
var top = ['role','sys'].concat((argv.t||'').split(',')).filter(x=>''!=x)

var top = ['role', 'sys']
.concat((argv.t || '').split(','))
.filter(x => '' != x)

var options = {
plugins: extra_plugins,
top: top
Expand All @@ -36,14 +38,14 @@ async function inspect_local_plugin() {
var plugin = await Inspect(LocalFolder, LocalPackage, options)

var inj = {
'options': {
text: Render.options(plugin,options)
options: {
text: Render.options(plugin, options)
},
'action-list': {
text: Render.action_list(plugin,options)
text: Render.action_list(plugin, options)
},
'action-desc': {
text: Render.action_desc(plugin,options)
text: Render.action_desc(plugin, options)
}
}

Expand Down
10 changes: 4 additions & 6 deletions doc.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,11 +82,10 @@ module.exports.preload = function() {
}

if (docdef) {

// TODO: document this as it should be prefered way to define Joi schemas
// in doc definition
if('function' === typeof(docdef)) {
docdef = docdef(seneca, {Joi})
if ('function' === typeof docdef) {
docdef = docdef(seneca, { Joi })
}

plugin.docdef = docdef
Expand Down Expand Up @@ -158,12 +157,11 @@ function doc(options) {
}
})


function describe_plugin_msg(msg, reply) {
var desc = describe_plugin.call(this, msg)
reply(desc)
}

function describe_plugin(msg) {
var instance = this || seneca

Expand All @@ -172,7 +170,7 @@ function doc(options) {
}

var def = instance.find_plugin(msg.plugin)

var plugin = msg.plugin.replace(/-/g, '_')

var actions = []
Expand Down
15 changes: 8 additions & 7 deletions lib/inspect.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,11 @@ module.exports = async function(
}

await seneca.ready()

return new Promise(resolve => {
var plugin_order = seneca.order.plugin
var describe_plugin = seneca.export('doc/describe_plugin')

plugin_order.add({
name: 'seneca_doc_single',
after: 'post_meta',
Expand All @@ -49,20 +49,21 @@ module.exports = async function(
},
exec: function(spec) {
var path = spec.data.plugin.args[0]
if(path === local_plugin_path) {
var plugin_desc = describe_plugin({plugin:spec.data.plugin.fullname})
if (path === local_plugin_path) {
var plugin_desc = describe_plugin({
plugin: spec.data.plugin.fullname
})

// NOTE: need to wait for seneca-doc to complete
seneca.ready(()=>{
seneca.ready(() => {
resolve(plugin_desc)
})
}
}
})


seneca.use(local_plugin_path, {
init$: false,
init$: false
/*
xdefined$: function(plugin) {
seneca.act(
Expand Down
115 changes: 68 additions & 47 deletions lib/render.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,11 @@ module.exports = {

var joi_schema = plugin.def.options_schema

if(Joi.isSchema(joi_schema,{legacy:true}) &&
joi_schema.keys &&
0 < joi_schema.keys.length )
{
if (
Joi.isSchema(joi_schema, { legacy: true }) &&
joi_schema.keys &&
0 < joi_schema.keys.length
) {
var joidesc = joi_schema.describe()

intern.walk_options('', b, joidesc)
Expand All @@ -28,21 +29,22 @@ seneca.use('${plugin.def.name}', { name: value, ... })
<small>Note: <code>foo.bar</code> in the list above means
<code>{ foo: { bar: ... } }</code></small>
`)
}
else {
} else {
b.push('*None.*')
}

return b.join('\n') + '\n\n'
},

action_list: function(plugin,options) {
action_list: function(plugin, options) {
options = options || {}
var list = (plugin.actions||[]).map(a=>({
pattern: intern.nicepat(a.pattern,options.top),
})).sort((a,b)=>{
return a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0
})
var list = (plugin.actions || [])
.map(a => ({
pattern: intern.nicepat(a.pattern, options.top)
}))
.sort((a, b) => {
return a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0
})

const b = ['\n\n## Action Patterns\n']

Expand All @@ -53,25 +55,27 @@ seneca.use('${plugin.def.name}', { name: value, ... })
return b.join('\n') + '\n\n'
},

action_desc: function(plugin,options) {
action_desc: function(plugin, options) {
options = options || {}
var list = (plugin.actions||[]).map(a=>({
pattern: intern.nicepat(a.pattern,options.top),
examples: a.examples,
rules: a.rules,
desc: a.desc,
reply_desc: a.reply_desc,
})).sort((a,b)=>{
return a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0
})

var list = (plugin.actions || [])
.map(a => ({
pattern: intern.nicepat(a.pattern, options.top),
examples: a.examples,
rules: a.rules,
desc: a.desc,
reply_desc: a.reply_desc
}))
.sort((a, b) => {
return a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0
})

const b = ['\n\n## Action Descriptions\n']

list.forEach(x => {
b.push('### &laquo; `' + x.pattern + '` &raquo;\n')
b.push((x.desc||'*None.*') + '\n\n')
var example_keys = Object.keys(x.examples||{})
b.push((x.desc || '*None.*') + '\n\n')

var example_keys = Object.keys(x.examples || {})
if (0 < example_keys.length) {
b.push('\n\n#### Examples\n\n')
example_keys.forEach(patpart => {
Expand Down Expand Up @@ -110,13 +114,12 @@ seneca.use('${plugin.def.name}', { name: value, ... })

const intern = (module.exports.intern = {
walk_options: function(prefix, b, joidesc) {
if(joidesc.keys) {
Object.keys(joidesc.keys).forEach(optname=>{
if (joidesc.keys) {
Object.keys(joidesc.keys).forEach(optname => {
var optjoi = joidesc.keys[optname]
intern.walk_options((prefix?prefix+'.':'')+optname, b, optjoi)
intern.walk_options((prefix ? prefix + '.' : '') + optname, b, optjoi)
})
}
else {
} else {
var opt_md = '* `' + prefix + '` : '
b.push(opt_md + joidesc.type + intern.joiflags(joidesc.flags))
if (joidesc.flags && null != joidesc.flags.description) {
Expand Down Expand Up @@ -161,13 +164,20 @@ const intern = (module.exports.intern = {
if (null != flags) {
var names = Object.keys(flags)
if (0 < names.length) {
var dval = null == flags.default ? '&nbsp;' :
('function'===typeof(flags.default)?flags.default():flags.default)
var dval =
null == flags.default
? '&nbsp;'
: 'function' === typeof flags.default
? flags.default()
: flags.default

dval =
'function' === typeof dval
? dval.name
: 'string' === typeof dval
? '"' + dval + '"'
: '' + dval

dval = 'function'===typeof(dval)?dval.name:
'string'===typeof(dval)?'"'+dval+'"':
''+dval

return ' <i><small>' + dval + '</small></i>'
}
}
Expand All @@ -176,20 +186,31 @@ const intern = (module.exports.intern = {
},

// order alpha but top level names (sys,role) go first
nicepat: function(orig,top) {
nicepat: function(orig, top) {
top = top || []
var pat = Jsonic(orig)
var names = Object.keys(pat).sort((a,b)=>{
return top.includes(a) && top.includes(b) ? (a < b ? -1 : b < a ? 1 : 0) :
(top.includes(a) && !top.includes(b) ? -1 :
(!top.includes(a) && top.includes(b) ? 1 :
(a < b ? -1 : b < a ? 1 : 0)))
var names = Object.keys(pat).sort((a, b) => {
return top.includes(a) && top.includes(b)
? a < b
? -1
: b < a
? 1
: 0
: top.includes(a) && !top.includes(b)
? -1
: !top.includes(a) && top.includes(b)
? 1
: a < b
? -1
: b < a
? 1
: 0
})

var out = {}
names.forEach(n=>{
names.forEach(n => {
out[n] = pat[n]
})
return Jsonic.stringify(out).replace(/[{}]/g,'')
return Jsonic.stringify(out).replace(/[{}]/g, '')
}
})

0 comments on commit b0a330d

Please sign in to comment.