mirror of
https://github.com/ether/etherpad-lite.git
synced 2025-04-24 17:36:14 -04:00
cleanup after workspace refactoring (#6174)
* fix bin folder and workflows as far its possible cleanup of dockerfile changed paths of scripts add lock file fix working directory for workflows fix windows bin fix travis (is travis used anyway?) fix package refs remove pnpm-lock file in root as these conflicts with the docker volume setup optimize comments use install again refactor prod image call to run fix --workspace can only be used inside a workspace correct comment try fix pipeline try fix pipeline for upgrade-from-latest-release install all deps smaller adjustments save update dockerfile remove workspace command fix run test command start repair latest release workflow start repair latest release workflow start repair latest release workflow further repairs * remove test plugin from docker compose
This commit is contained in:
JannikStreek
GitHub
parent
4f53142d7f
commit
04063d664b
75 changed files with 158 additions and 192 deletions
18
bin/doc/LICENSE
Normal file
18
bin/doc/LICENSE
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
Copyright Joyent, Inc. and other Node contributors. All rights reserved.
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to
|
||||
deal in the Software without restriction, including without limitation the
|
||||
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
||||
sell copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
||||
IN THE SOFTWARE.
|
||||
76
bin/doc/README.md
Normal file
76
bin/doc/README.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
Here's how the node docs work.
|
||||
|
||||
Each type of heading has a description block.
|
||||
|
||||
|
||||
## module
|
||||
|
||||
Stability: 3 - Stable
|
||||
|
||||
description and examples.
|
||||
|
||||
### module.property
|
||||
|
||||
* Type
|
||||
|
||||
description of the property.
|
||||
|
||||
### module.someFunction(x, y, [z=100])
|
||||
|
||||
* `x` {String} the description of the string
|
||||
* `y` {Boolean} Should I stay or should I go?
|
||||
* `z` {Number} How many zebras to bring.
|
||||
|
||||
A description of the function.
|
||||
|
||||
### Event: 'blerg'
|
||||
|
||||
* Argument: SomeClass object.
|
||||
|
||||
Modules don't usually raise events on themselves. `cluster` is the
|
||||
only exception.
|
||||
|
||||
## Class: SomeClass
|
||||
|
||||
description of the class.
|
||||
|
||||
### Class Method: SomeClass.classMethod(anArg)
|
||||
|
||||
* `anArg` {Object} Just an argument
|
||||
* `field` {String} anArg can have this field.
|
||||
* `field2` {Boolean} Another field. Default: `false`.
|
||||
* Return: {Boolean} `true` if it worked.
|
||||
|
||||
Description of the method for humans.
|
||||
|
||||
### someClass.nextSibling()
|
||||
|
||||
* Return: {SomeClass object | null} The next someClass in line.
|
||||
|
||||
### someClass.someProperty
|
||||
|
||||
* String
|
||||
|
||||
The indication of what someProperty is.
|
||||
|
||||
### Event: 'grelb'
|
||||
|
||||
* `isBlerg` {Boolean}
|
||||
|
||||
This event is emitted on instances of SomeClass, not on the module itself.
|
||||
|
||||
|
||||
* Modules have (description, Properties, Functions, Classes, Examples)
|
||||
* Properties have (type, description)
|
||||
* Functions have (list of arguments, description)
|
||||
* Classes have (description, Properties, Methods, Events)
|
||||
* Events have (list of arguments, description)
|
||||
* Methods have (list of arguments, description)
|
||||
* Properties have (type, description)
|
||||
|
||||
# CLI usage
|
||||
|
||||
Run the following from the etherpad-lite root directory:
|
||||
```sh
|
||||
$ node src/bin/doc/generate doc/index.md --format=html --template=doc/template.html > out.html
|
||||
```
|
||||
122
bin/doc/generate.js
Normal file
122
bin/doc/generate.js
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
'use strict';
|
||||
|
||||
// Copyright Joyent, Inc. and other Node contributors.
|
||||
//
|
||||
// Permission is hereby granted, free of charge, to any person obtaining a
|
||||
// copy of this software and associated documentation files (the
|
||||
// "Software"), to deal in the Software without restriction, including
|
||||
// without limitation the rights to use, copy, modify, merge, publish,
|
||||
// distribute, sublicense, and/or sell copies of the Software, and to permit
|
||||
// persons to whom the Software is furnished to do so, subject to the
|
||||
// following conditions:
|
||||
//
|
||||
// The above copyright notice and this permission notice shall be included
|
||||
// in all copies or substantial portions of the Software.
|
||||
//
|
||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
||||
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
|
||||
// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
|
||||
// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
||||
// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
|
||||
// USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
const fs = require('fs');
|
||||
const path = require('path');
|
||||
|
||||
// parse the args.
|
||||
// Don't use nopt or whatever for this. It's simple enough.
|
||||
|
||||
const args = process.argv.slice(2);
|
||||
let format = 'json';
|
||||
let template = null;
|
||||
let inputFile = null;
|
||||
|
||||
args.forEach((arg) => {
|
||||
if (!arg.match(/^--/)) {
|
||||
inputFile = arg;
|
||||
} else if (arg.match(/^--format=/)) {
|
||||
format = arg.replace(/^--format=/, '');
|
||||
} else if (arg.match(/^--template=/)) {
|
||||
template = arg.replace(/^--template=/, '');
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
if (!inputFile) {
|
||||
throw new Error('No input file specified');
|
||||
}
|
||||
|
||||
|
||||
console.error('Input file = %s', inputFile);
|
||||
fs.readFile(inputFile, 'utf8', (er, input) => {
|
||||
if (er) throw er;
|
||||
// process the input for @include lines
|
||||
processIncludes(inputFile, input, next);
|
||||
});
|
||||
|
||||
|
||||
const includeExpr = /^@include\s+([A-Za-z0-9-_/]+)(?:\.)?([a-zA-Z]*)$/gmi;
|
||||
const includeData = {};
|
||||
const processIncludes = (inputFile, input, cb) => {
|
||||
const includes = input.match(includeExpr);
|
||||
if (includes == null) return cb(null, input);
|
||||
let errState = null;
|
||||
console.error(includes);
|
||||
let incCount = includes.length;
|
||||
if (incCount === 0) cb(null, input);
|
||||
|
||||
includes.forEach((include) => {
|
||||
let fname = include.replace(/^@include\s+/, '');
|
||||
if (!fname.match(/\.md$/)) fname += '.md';
|
||||
|
||||
if (Object.prototype.hasOwnProperty.call(includeData, fname)) {
|
||||
input = input.split(include).join(includeData[fname]);
|
||||
incCount--;
|
||||
if (incCount === 0) {
|
||||
return cb(null, input);
|
||||
}
|
||||
}
|
||||
|
||||
const fullFname = path.resolve(path.dirname(inputFile), fname);
|
||||
fs.readFile(fullFname, 'utf8', (er, inc) => {
|
||||
if (errState) return;
|
||||
if (er) return cb(errState = er);
|
||||
processIncludes(fullFname, inc, (er, inc) => {
|
||||
if (errState) return;
|
||||
if (er) return cb(errState = er);
|
||||
incCount--;
|
||||
includeData[fname] = inc;
|
||||
input = input.split(include).join(includeData[fname]);
|
||||
if (incCount === 0) {
|
||||
return cb(null, input);
|
||||
}
|
||||
});
|
||||
});
|
||||
});
|
||||
};
|
||||
|
||||
|
||||
const next = (er, input) => {
|
||||
if (er) throw er;
|
||||
switch (format) {
|
||||
case 'json':
|
||||
require('./json.js')(input, inputFile, (er, obj) => {
|
||||
console.log(JSON.stringify(obj, null, 2));
|
||||
if (er) throw er;
|
||||
});
|
||||
break;
|
||||
|
||||
case 'html':
|
||||
require('./html.js')(input, inputFile, template, (er, html) => {
|
||||
if (er) throw er;
|
||||
console.log(html);
|
||||
});
|
||||
break;
|
||||
|
||||
default:
|
||||
throw new Error(`Invalid format: ${format}`);
|
||||
}
|
||||
};
|
||||
165
bin/doc/html.js
Normal file
165
bin/doc/html.js
Normal file
|
|
@ -0,0 +1,165 @@
|
|||
'use strict';
|
||||
|
||||
// Copyright Joyent, Inc. and other Node contributors.
|
||||
//
|
||||
// Permission is hereby granted, free of charge, to any person obtaining a
|
||||
// copy of this software and associated documentation files (the
|
||||
// "Software"), to deal in the Software without restriction, including
|
||||
// without limitation the rights to use, copy, modify, merge, publish,
|
||||
// distribute, sublicense, and/or sell copies of the Software, and to permit
|
||||
// persons to whom the Software is furnished to do so, subject to the
|
||||
// following conditions:
|
||||
//
|
||||
// The above copyright notice and this permission notice shall be included
|
||||
// in all copies or substantial portions of the Software.
|
||||
//
|
||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
||||
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
|
||||
// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
|
||||
// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
||||
// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
|
||||
// USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
const fs = require('fs');
|
||||
const marked = require('marked');
|
||||
const path = require('path');
|
||||
|
||||
|
||||
const toHTML = (input, filename, template, cb) => {
|
||||
const lexed = marked.lexer(input);
|
||||
fs.readFile(template, 'utf8', (er, template) => {
|
||||
if (er) return cb(er);
|
||||
render(lexed, filename, template, cb);
|
||||
});
|
||||
};
|
||||
module.exports = toHTML;
|
||||
|
||||
const render = (lexed, filename, template, cb) => {
|
||||
// get the section
|
||||
const section = getSection(lexed);
|
||||
|
||||
filename = path.basename(filename, '.md');
|
||||
|
||||
lexed = parseLists(lexed);
|
||||
|
||||
// generate the table of contents.
|
||||
// this mutates the lexed contents in-place.
|
||||
buildToc(lexed, filename, (er, toc) => {
|
||||
if (er) return cb(er);
|
||||
|
||||
template = template.replace(/__FILENAME__/g, filename);
|
||||
template = template.replace(/__SECTION__/g, section);
|
||||
template = template.replace(/__TOC__/g, toc);
|
||||
|
||||
// content has to be the last thing we do with
|
||||
// the lexed tokens, because it's destructive.
|
||||
const content = marked.parser(lexed);
|
||||
template = template.replace(/__CONTENT__/g, content);
|
||||
|
||||
cb(null, template);
|
||||
});
|
||||
};
|
||||
|
||||
|
||||
// just update the list item text in-place.
|
||||
// lists that come right after a heading are what we're after.
|
||||
const parseLists = (input) => {
|
||||
let state = null;
|
||||
let depth = 0;
|
||||
const output = [];
|
||||
output.links = input.links;
|
||||
input.forEach((tok) => {
|
||||
if (state == null) {
|
||||
if (tok.type === 'heading') {
|
||||
state = 'AFTERHEADING';
|
||||
}
|
||||
output.push(tok);
|
||||
return;
|
||||
}
|
||||
if (state === 'AFTERHEADING') {
|
||||
if (tok.type === 'list_start') {
|
||||
state = 'LIST';
|
||||
if (depth === 0) {
|
||||
output.push({type: 'html', text: '<div class="signature">'});
|
||||
}
|
||||
depth++;
|
||||
output.push(tok);
|
||||
return;
|
||||
}
|
||||
state = null;
|
||||
output.push(tok);
|
||||
return;
|
||||
}
|
||||
if (state === 'LIST') {
|
||||
if (tok.type === 'list_start') {
|
||||
depth++;
|
||||
output.push(tok);
|
||||
return;
|
||||
}
|
||||
if (tok.type === 'list_end') {
|
||||
depth--;
|
||||
if (depth === 0) {
|
||||
state = null;
|
||||
output.push({type: 'html', text: '</div>'});
|
||||
}
|
||||
output.push(tok);
|
||||
return;
|
||||
}
|
||||
if (tok.text) {
|
||||
tok.text = parseListItem(tok.text);
|
||||
}
|
||||
}
|
||||
output.push(tok);
|
||||
});
|
||||
|
||||
return output;
|
||||
};
|
||||
|
||||
|
||||
const parseListItem = (text) => {
|
||||
text = text.replace(/\{([^}]+)\}/, '<span class="type">$1</span>');
|
||||
// XXX maybe put more stuff here?
|
||||
return text;
|
||||
};
|
||||
|
||||
|
||||
// section is just the first heading
|
||||
const getSection = (lexed) => {
|
||||
for (let i = 0, l = lexed.length; i < l; i++) {
|
||||
const tok = lexed[i];
|
||||
if (tok.type === 'heading') return tok.text;
|
||||
}
|
||||
return '';
|
||||
};
|
||||
|
||||
|
||||
const buildToc = (lexed, filename, cb) => {
|
||||
let toc = [];
|
||||
let depth = 0;
|
||||
|
||||
marked.setOptions({
|
||||
headerIds: true,
|
||||
headerPrefix: `${filename}_`,
|
||||
});
|
||||
|
||||
lexed.forEach((tok) => {
|
||||
if (tok.type !== 'heading') return;
|
||||
if (tok.depth - depth > 1) {
|
||||
return cb(new Error(`Inappropriate heading level\n${JSON.stringify(tok)}`));
|
||||
}
|
||||
|
||||
depth = tok.depth;
|
||||
|
||||
const slugger = new marked.Slugger();
|
||||
const id = slugger.slug(`${filename}_${tok.text.trim()}`);
|
||||
|
||||
toc.push(`${new Array((depth - 1) * 2 + 1).join(' ')}* <a href="#${id}">${tok.text}</a>`);
|
||||
|
||||
tok.text += `<span><a class="mark" href="#${id}" ` +
|
||||
`id="${id}">#</a></span>`;
|
||||
});
|
||||
|
||||
toc = marked.parse(toc.join('\n'));
|
||||
cb(null, toc);
|
||||
};
|
||||
556
bin/doc/json.js
Normal file
556
bin/doc/json.js
Normal file
|
|
@ -0,0 +1,556 @@
|
|||
'use strict';
|
||||
// Copyright Joyent, Inc. and other Node contributors.
|
||||
//
|
||||
// Permission is hereby granted, free of charge, to any person obtaining a
|
||||
// copy of this software and associated documentation files (the
|
||||
// "Software"), to deal in the Software without restriction, including
|
||||
// without limitation the rights to use, copy, modify, merge, publish,
|
||||
// distribute, sublicense, and/or sell copies of the Software, and to permit
|
||||
// persons to whom the Software is furnished to do so, subject to the
|
||||
// following conditions:
|
||||
//
|
||||
// The above copyright notice and this permission notice shall be included
|
||||
// in all copies or substantial portions of the Software.
|
||||
//
|
||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
||||
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
|
||||
// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
|
||||
// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
||||
// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
|
||||
// USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
module.exports = doJSON;
|
||||
|
||||
// Take the lexed input, and return a JSON-encoded object
|
||||
// A module looks like this: https://gist.github.com/1777387
|
||||
|
||||
const marked = require('marked');
|
||||
|
||||
const doJSON = (input, filename, cb) => {
|
||||
const root = {source: filename};
|
||||
const stack = [root];
|
||||
let depth = 0;
|
||||
let current = root;
|
||||
let state = null;
|
||||
const lexed = marked.lexer(input);
|
||||
lexed.forEach((tok) => {
|
||||
const type = tok.type;
|
||||
let text = tok.text;
|
||||
|
||||
// <!-- type = module -->
|
||||
// This is for cases where the markdown semantic structure is lacking.
|
||||
if (type === 'paragraph' || type === 'html') {
|
||||
const metaExpr = /<!--([^=]+)=([^-]+)-->\n*/g;
|
||||
text = text.replace(metaExpr, (_0, k, v) => {
|
||||
current[k.trim()] = v.trim();
|
||||
return '';
|
||||
});
|
||||
text = text.trim();
|
||||
if (!text) return;
|
||||
}
|
||||
|
||||
if (type === 'heading' &&
|
||||
!text.trim().match(/^example/i)) {
|
||||
if (tok.depth - depth > 1) {
|
||||
return cb(new Error(`Inappropriate heading level\n${
|
||||
JSON.stringify(tok)}`));
|
||||
}
|
||||
|
||||
// Sometimes we have two headings with a single
|
||||
// blob of description. Treat as a clone.
|
||||
if (current &&
|
||||
state === 'AFTERHEADING' &&
|
||||
depth === tok.depth) {
|
||||
const clone = current;
|
||||
current = newSection(tok);
|
||||
current.clone = clone;
|
||||
// don't keep it around on the stack.
|
||||
stack.pop();
|
||||
} else {
|
||||
// if the level is greater than the current depth,
|
||||
// then it's a child, so we should just leave the stack
|
||||
// as it is.
|
||||
// However, if it's a sibling or higher, then it implies
|
||||
// the closure of the other sections that came before.
|
||||
// root is always considered the level=0 section,
|
||||
// and the lowest heading is 1, so this should always
|
||||
// result in having a valid parent node.
|
||||
let d = tok.depth;
|
||||
while (d <= depth) {
|
||||
finishSection(stack.pop(), stack[stack.length - 1]);
|
||||
d++;
|
||||
}
|
||||
current = newSection(tok);
|
||||
}
|
||||
|
||||
depth = tok.depth;
|
||||
stack.push(current);
|
||||
state = 'AFTERHEADING';
|
||||
return;
|
||||
} // heading
|
||||
|
||||
// Immediately after a heading, we can expect the following
|
||||
//
|
||||
// { type: 'code', text: 'Stability: ...' },
|
||||
//
|
||||
// a list: starting with list_start, ending with list_end,
|
||||
// maybe containing other nested lists in each item.
|
||||
//
|
||||
// If one of these isn't found, then anything that comes between
|
||||
// here and the next heading should be parsed as the desc.
|
||||
let stability;
|
||||
if (state === 'AFTERHEADING') {
|
||||
if (type === 'code' &&
|
||||
(stability = text.match(/^Stability: ([0-5])(?:\s*-\s*)?(.*)$/))) {
|
||||
current.stability = parseInt(stability[1], 10);
|
||||
current.stabilityText = stability[2].trim();
|
||||
return;
|
||||
} else if (type === 'list_start' && !tok.ordered) {
|
||||
state = 'AFTERHEADING_LIST';
|
||||
current.list = current.list || [];
|
||||
current.list.push(tok);
|
||||
current.list.level = 1;
|
||||
} else {
|
||||
current.desc = current.desc || [];
|
||||
if (!Array.isArray(current.desc)) {
|
||||
current.shortDesc = current.desc;
|
||||
current.desc = [];
|
||||
}
|
||||
current.desc.push(tok);
|
||||
state = 'DESC';
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
if (state === 'AFTERHEADING_LIST') {
|
||||
current.list.push(tok);
|
||||
if (type === 'list_start') {
|
||||
current.list.level++;
|
||||
} else if (type === 'list_end') {
|
||||
current.list.level--;
|
||||
}
|
||||
if (current.list.level === 0) {
|
||||
state = 'AFTERHEADING';
|
||||
processList(current);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
current.desc = current.desc || [];
|
||||
current.desc.push(tok);
|
||||
});
|
||||
|
||||
// finish any sections left open
|
||||
while (root !== (current = stack.pop())) {
|
||||
finishSection(current, stack[stack.length - 1]);
|
||||
}
|
||||
|
||||
return cb(null, root);
|
||||
};
|
||||
|
||||
|
||||
// go from something like this:
|
||||
// [ { type: 'list_item_start' },
|
||||
// { type: 'text',
|
||||
// text: '`settings` Object, Optional' },
|
||||
// { type: 'list_start', ordered: false },
|
||||
// { type: 'list_item_start' },
|
||||
// { type: 'text',
|
||||
// text: 'exec: String, file path to worker file. Default: `__filename`' },
|
||||
// { type: 'list_item_end' },
|
||||
// { type: 'list_item_start' },
|
||||
// { type: 'text',
|
||||
// text: 'args: Array, string arguments passed to worker.' },
|
||||
// { type: 'text',
|
||||
// text: 'Default: `process.argv.slice(2)`' },
|
||||
// { type: 'list_item_end' },
|
||||
// { type: 'list_item_start' },
|
||||
// { type: 'text',
|
||||
// text: 'silent: Boolean, whether or not to send output to parent\'s stdio.' },
|
||||
// { type: 'text', text: 'Default: `false`' },
|
||||
// { type: 'space' },
|
||||
// { type: 'list_item_end' },
|
||||
// { type: 'list_end' },
|
||||
// { type: 'list_item_end' },
|
||||
// { type: 'list_end' } ]
|
||||
// to something like:
|
||||
// [ { name: 'settings',
|
||||
// type: 'object',
|
||||
// optional: true,
|
||||
// settings:
|
||||
// [ { name: 'exec',
|
||||
// type: 'string',
|
||||
// desc: 'file path to worker file',
|
||||
// default: '__filename' },
|
||||
// { name: 'args',
|
||||
// type: 'array',
|
||||
// default: 'process.argv.slice(2)',
|
||||
// desc: 'string arguments passed to worker.' },
|
||||
// { name: 'silent',
|
||||
// type: 'boolean',
|
||||
// desc: 'whether or not to send output to parent\'s stdio.',
|
||||
// default: 'false' } ] } ]
|
||||
|
||||
const processList = (section) => {
|
||||
const list = section.list;
|
||||
const values = [];
|
||||
let current;
|
||||
const stack = [];
|
||||
|
||||
// for now, *just* build the hierarchical list
|
||||
list.forEach((tok) => {
|
||||
const type = tok.type;
|
||||
if (type === 'space') return;
|
||||
if (type === 'list_item_start') {
|
||||
if (!current) {
|
||||
const n = {};
|
||||
values.push(n);
|
||||
current = n;
|
||||
} else {
|
||||
current.options = current.options || [];
|
||||
stack.push(current);
|
||||
const n = {};
|
||||
current.options.push(n);
|
||||
current = n;
|
||||
}
|
||||
return;
|
||||
} else if (type === 'list_item_end') {
|
||||
if (!current) {
|
||||
throw new Error(`invalid list - end without current item\n${
|
||||
JSON.stringify(tok)}\n${
|
||||
JSON.stringify(list)}`);
|
||||
}
|
||||
current = stack.pop();
|
||||
} else if (type === 'text') {
|
||||
if (!current) {
|
||||
throw new Error(`invalid list - text without current item\n${
|
||||
JSON.stringify(tok)}\n${
|
||||
JSON.stringify(list)}`);
|
||||
}
|
||||
current.textRaw = current.textRaw || '';
|
||||
current.textRaw += `${tok.text} `;
|
||||
}
|
||||
});
|
||||
|
||||
// shove the name in there for properties, since they are always
|
||||
// just going to be the value etc.
|
||||
if (section.type === 'property' && values[0]) {
|
||||
values[0].textRaw = `\`${section.name}\` ${values[0].textRaw}`;
|
||||
}
|
||||
|
||||
// now pull the actual values out of the text bits.
|
||||
values.forEach(parseListItem);
|
||||
|
||||
// Now figure out what this list actually means.
|
||||
// depending on the section type, the list could be different things.
|
||||
|
||||
switch (section.type) {
|
||||
case 'ctor':
|
||||
case 'classMethod':
|
||||
case 'method': {
|
||||
// each item is an argument, unless the name is 'return',
|
||||
// in which case it's the return value.
|
||||
section.signatures = section.signatures || [];
|
||||
const sig = {};
|
||||
section.signatures.push(sig);
|
||||
sig.params = values.filter((v) => {
|
||||
if (v.name === 'return') {
|
||||
sig.return = v;
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
});
|
||||
parseSignature(section.textRaw, sig);
|
||||
break;
|
||||
}
|
||||
case 'property': {
|
||||
// there should be only one item, which is the value.
|
||||
// copy the data up to the section.
|
||||
const value = values[0] || {};
|
||||
delete value.name;
|
||||
section.typeof = value.type;
|
||||
delete value.type;
|
||||
Object.keys(value).forEach((k) => {
|
||||
section[k] = value[k];
|
||||
});
|
||||
break;
|
||||
}
|
||||
|
||||
case 'event': {
|
||||
// event: each item is an argument.
|
||||
section.params = values;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
delete section.list;
|
||||
};
|
||||
|
||||
|
||||
// textRaw = "someobject.someMethod(a, [b=100], [c])"
|
||||
const parseSignature = (text, sig) => {
|
||||
let params = text.match(paramExpr);
|
||||
if (!params) return;
|
||||
params = params[1];
|
||||
// the ] is irrelevant. [ indicates optionalness.
|
||||
params = params.replace(/\]/g, '');
|
||||
params = params.split(/,/);
|
||||
params.forEach((p, i, _) => {
|
||||
p = p.trim();
|
||||
if (!p) return;
|
||||
let param = sig.params[i];
|
||||
let optional = false;
|
||||
let def;
|
||||
// [foo] -> optional
|
||||
if (p.charAt(0) === '[') {
|
||||
optional = true;
|
||||
p = p.substr(1);
|
||||
}
|
||||
const eq = p.indexOf('=');
|
||||
if (eq !== -1) {
|
||||
def = p.substr(eq + 1);
|
||||
p = p.substr(0, eq);
|
||||
}
|
||||
if (!param) {
|
||||
param = sig.params[i] = {name: p};
|
||||
}
|
||||
// at this point, the name should match.
|
||||
if (p !== param.name) {
|
||||
console.error('Warning: invalid param "%s"', p);
|
||||
console.error(` > ${JSON.stringify(param)}`);
|
||||
console.error(` > ${text}`);
|
||||
}
|
||||
if (optional) param.optional = true;
|
||||
if (def !== undefined) param.default = def;
|
||||
});
|
||||
};
|
||||
|
||||
|
||||
const parseListItem = (item) => {
|
||||
if (item.options) item.options.forEach(parseListItem);
|
||||
if (!item.textRaw) return;
|
||||
|
||||
// the goal here is to find the name, type, default, and optional.
|
||||
// anything left over is 'desc'
|
||||
let text = item.textRaw.trim();
|
||||
// text = text.replace(/^(Argument|Param)s?\s*:?\s*/i, '');
|
||||
|
||||
text = text.replace(/^, /, '').trim();
|
||||
const retExpr = /^returns?\s*:?\s*/i;
|
||||
const ret = text.match(retExpr);
|
||||
if (ret) {
|
||||
item.name = 'return';
|
||||
text = text.replace(retExpr, '');
|
||||
} else {
|
||||
const nameExpr = /^['`"]?([^'`": {]+)['`"]?\s*:?\s*/;
|
||||
const name = text.match(nameExpr);
|
||||
if (name) {
|
||||
item.name = name[1];
|
||||
text = text.replace(nameExpr, '');
|
||||
}
|
||||
}
|
||||
|
||||
text = text.trim();
|
||||
const defaultExpr = /\(default\s*[:=]?\s*['"`]?([^, '"`]*)['"`]?\)/i;
|
||||
const def = text.match(defaultExpr);
|
||||
if (def) {
|
||||
item.default = def[1];
|
||||
text = text.replace(defaultExpr, '');
|
||||
}
|
||||
|
||||
text = text.trim();
|
||||
const typeExpr = /^\{([^}]+)\}/;
|
||||
const type = text.match(typeExpr);
|
||||
if (type) {
|
||||
item.type = type[1];
|
||||
text = text.replace(typeExpr, '');
|
||||
}
|
||||
|
||||
text = text.trim();
|
||||
const optExpr = /^Optional\.|(?:, )?Optional$/;
|
||||
const optional = text.match(optExpr);
|
||||
if (optional) {
|
||||
item.optional = true;
|
||||
text = text.replace(optExpr, '');
|
||||
}
|
||||
|
||||
text = text.replace(/^\s*-\s*/, '');
|
||||
text = text.trim();
|
||||
if (text) item.desc = text;
|
||||
};
|
||||
|
||||
|
||||
const finishSection = (section, parent) => {
|
||||
if (!section || !parent) {
|
||||
throw new Error(`Invalid finishSection call\n${
|
||||
JSON.stringify(section)}\n${
|
||||
JSON.stringify(parent)}`);
|
||||
}
|
||||
|
||||
if (!section.type) {
|
||||
section.type = 'module';
|
||||
if (parent && (parent.type === 'misc')) {
|
||||
section.type = 'misc';
|
||||
}
|
||||
section.displayName = section.name;
|
||||
section.name = section.name.toLowerCase()
|
||||
.trim().replace(/\s+/g, '_');
|
||||
}
|
||||
|
||||
if (section.desc && Array.isArray(section.desc)) {
|
||||
section.desc.links = section.desc.links || [];
|
||||
section.desc = marked.parser(section.desc);
|
||||
}
|
||||
|
||||
if (!section.list) section.list = [];
|
||||
processList(section);
|
||||
|
||||
// classes sometimes have various 'ctor' children
|
||||
// which are actually just descriptions of a constructor
|
||||
// class signature.
|
||||
// Merge them into the parent.
|
||||
if (section.type === 'class' && section.ctors) {
|
||||
section.signatures = section.signatures || [];
|
||||
const sigs = section.signatures;
|
||||
section.ctors.forEach((ctor) => {
|
||||
ctor.signatures = ctor.signatures || [{}];
|
||||
ctor.signatures.forEach((sig) => {
|
||||
sig.desc = ctor.desc;
|
||||
});
|
||||
sigs.push(...ctor.signatures);
|
||||
});
|
||||
delete section.ctors;
|
||||
}
|
||||
|
||||
// properties are a bit special.
|
||||
// their "type" is the type of object, not "property"
|
||||
if (section.properties) {
|
||||
section.properties.forEach((p) => {
|
||||
if (p.typeof) p.type = p.typeof;
|
||||
else delete p.type;
|
||||
delete p.typeof;
|
||||
});
|
||||
}
|
||||
|
||||
// handle clones
|
||||
if (section.clone) {
|
||||
const clone = section.clone;
|
||||
delete section.clone;
|
||||
delete clone.clone;
|
||||
deepCopy(section, clone);
|
||||
finishSection(clone, parent);
|
||||
}
|
||||
|
||||
let plur;
|
||||
if (section.type.slice(-1) === 's') {
|
||||
plur = `${section.type}es`;
|
||||
} else if (section.type.slice(-1) === 'y') {
|
||||
plur = section.type.replace(/y$/, 'ies');
|
||||
} else {
|
||||
plur = `${section.type}s`;
|
||||
}
|
||||
|
||||
// if the parent's type is 'misc', then it's just a random
|
||||
// collection of stuff, like the "globals" section.
|
||||
// Make the children top-level items.
|
||||
if (section.type === 'misc') {
|
||||
Object.keys(section).forEach((k) => {
|
||||
switch (k) {
|
||||
case 'textRaw':
|
||||
case 'name':
|
||||
case 'type':
|
||||
case 'desc':
|
||||
case 'miscs':
|
||||
return;
|
||||
default:
|
||||
if (parent.type === 'misc') {
|
||||
return;
|
||||
}
|
||||
if (Array.isArray(k) && parent[k]) {
|
||||
parent[k] = parent[k].concat(section[k]);
|
||||
} else if (!parent[k]) {
|
||||
parent[k] = section[k];
|
||||
} else {
|
||||
// parent already has, and it's not an array.
|
||||
return;
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
parent[plur] = parent[plur] || [];
|
||||
parent[plur].push(section);
|
||||
};
|
||||
|
||||
|
||||
// Not a general purpose deep copy.
|
||||
// But sufficient for these basic things.
|
||||
const deepCopy = (src, dest) => {
|
||||
Object.keys(src).filter((k) => !Object.prototype.hasOwnProperty.call(dest, k)).forEach((k) => {
|
||||
dest[k] = deepCopy_(src[k]);
|
||||
});
|
||||
};
|
||||
|
||||
const deepCopy_ = (src) => {
|
||||
if (!src) return src;
|
||||
if (Array.isArray(src)) {
|
||||
const c = new Array(src.length);
|
||||
src.forEach((v, i) => {
|
||||
c[i] = deepCopy_(v);
|
||||
});
|
||||
return c;
|
||||
}
|
||||
if (typeof src === 'object') {
|
||||
const c = {};
|
||||
Object.keys(src).forEach((k) => {
|
||||
c[k] = deepCopy_(src[k]);
|
||||
});
|
||||
return c;
|
||||
}
|
||||
return src;
|
||||
};
|
||||
|
||||
|
||||
// these parse out the contents of an H# tag
|
||||
const eventExpr = /^Event(?::|\s)+['"]?([^"']+).*$/i;
|
||||
const classExpr = /^Class:\s*([^ ]+).*?$/i;
|
||||
const propExpr = /^(?:property:?\s*)?[^.]+\.([^ .()]+)\s*?$/i;
|
||||
const braceExpr = /^(?:property:?\s*)?[^.[]+(\[[^\]]+\])\s*?$/i;
|
||||
const classMethExpr =
|
||||
/^class\s*method\s*:?[^.]+\.([^ .()]+)\([^)]*\)\s*?$/i;
|
||||
const methExpr =
|
||||
/^(?:method:?\s*)?(?:[^.]+\.)?([^ .()]+)\([^)]*\)\s*?$/i;
|
||||
const newExpr = /^new ([A-Z][a-z]+)\([^)]*\)\s*?$/;
|
||||
const paramExpr = /\((.*)\);?$/;
|
||||
|
||||
const newSection = (tok) => {
|
||||
const section = {};
|
||||
// infer the type from the text.
|
||||
const text = section.textRaw = tok.text;
|
||||
if (text.match(eventExpr)) {
|
||||
section.type = 'event';
|
||||
section.name = text.replace(eventExpr, '$1');
|
||||
} else if (text.match(classExpr)) {
|
||||
section.type = 'class';
|
||||
section.name = text.replace(classExpr, '$1');
|
||||
} else if (text.match(braceExpr)) {
|
||||
section.type = 'property';
|
||||
section.name = text.replace(braceExpr, '$1');
|
||||
} else if (text.match(propExpr)) {
|
||||
section.type = 'property';
|
||||
section.name = text.replace(propExpr, '$1');
|
||||
} else if (text.match(classMethExpr)) {
|
||||
section.type = 'classMethod';
|
||||
section.name = text.replace(classMethExpr, '$1');
|
||||
} else if (text.match(methExpr)) {
|
||||
section.type = 'method';
|
||||
section.name = text.replace(methExpr, '$1');
|
||||
} else if (text.match(newExpr)) {
|
||||
section.type = 'ctor';
|
||||
section.name = text.replace(newExpr, '$1');
|
||||
} else {
|
||||
section.name = text;
|
||||
}
|
||||
return section;
|
||||
};
|
||||
Loading…
Add table
Add a link
Reference in a new issue