diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fe85941 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +.* +*.vim +*.sw[po] +*.code-workspace +coverage +node_modules +npm-debug.log diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..51a0206 --- /dev/null +++ b/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2016-2019, Alex A. Naanou +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/doc.js b/doc.js new file mode 100644 index 0000000..009c268 --- /dev/null +++ b/doc.js @@ -0,0 +1,137 @@ +/********************************************************************** +* +* doc.js +* +* Basic JavaScript self-documentation utils +* +***********************************************/ /* c8 ignore next 2 */ +((typeof define)[0]=='u'?function(f){module.exports=f(require)}:define) +(function(require){ var module={} // make module AMD/node compatible... +/*********************************************************************/ + +module.TAB_SIZE = 4 + +module.LEADING_TABS = 1 + + +// Normalize code indent... +// +// normalizeIndent(text) +// -> text +// +// +// This will remove common indent from each line of text, this is useful +// for printing function code of functions that were defined at deep +// levels of indent. +// +// This will ignore the indent of the first line. +// +// If the last line is indented higher or equal to the rest of the text +// we will use leading_tabs (defaults to LEADING_TABS) to indent the +// rest of the text. +// This will indent the following styles correctnly: +// +// |function(a, b){ |function(a, b){ +// | return a + b } | return a + b +// | |} +// +// +// NOTE: this will trim out both leading and trailing white-space. +// NOTE: this is generally code-agnostic with one sigificant +// exception -- normalizeIndent(..) will break code written +// in Whitespace. +// +// XXX BUG? +// `a `a `a +// | b -> |b expected? | b +// | c` | c` | c` +// while: +// `a `a +// | b -> | b as expected. +// | c` | c` +// this leads to functions like the following to get messed up: +// |function(a){ +// | return a +// | || 'moo' } +// +// XXX is this the right place for this??? +// ...when moving take care that ImageGrid's core.doc uses this... +var normalizeIndent = +module.normalizeIndent = +function(text, {tab_size=module.TAB_SIZE, leading_tabs=module.LEADING_TABS, pad_tabs=0}={}){ + leading_tabs *= tab_size + var padding = ' '.repeat(pad_tabs*tab_size) + // prepare text... + var tab = ' '.repeat(tab_size || 0) + text = tab != '' ? + text.replace(/\t/g, tab) + : text + // trim the tail and remove leading blank lines... + var lines = text.trimEnd().split(/\n/) + while(lines.length > 0 + && lines[0].trim() == ''){ + // XXX we have two options here: + // - indent everyline including the first non-blank + // - do not indent anything (current) + // ...not sure which is best... + leading_tabs = 0 + lines.shift() } + // count common indent... + var l = lines + .reduce(function(l, e, i){ + var indent = e.length - e.trimLeft().length + return e.trim().length == 0 + // ignore 0 indent of first line... + || (i == 0 && indent == 0) ? + l + // last line... + : i == lines.length-1 + && indent >= l ? + // XXX feels a bit overcomplicated... + (l < 0 ? + // last of two with 0 indent on first -> indent... + Math.max(indent - leading_tabs, 0) + // ignore leading_tabs if lower indent... + : Math.min(l, Math.max(indent - leading_tabs, 0))) + // initial state... + : l < 0 ? + indent + // min... + : Math.min(l, indent) }, -1) || 0 + // normalize... + return padding + +lines + .map(function(line, i){ + return i == 0 ? + line + : line.slice(l) }) + .join('\n'+ padding) + .trim() } + + +// shorthand more suted for text... +var normalizeTextIndent = +module.normalizeTextIndent = +function(text, opts={leading_tabs: 0}){ + return module.normalizeIndent(text, opts) } + + +// template string tag versions of the above... +var doc = +module.doc = +function(strings, ...values){ + return normalizeIndent(strings + .map(function(s, i){ return s + (values[i] || '') }) + .join('')) } + +var text = +module.text = +function(strings, ...values){ + return normalizeTextIndent(strings + .map(function(s, i){ return s + (values[i] || '') }) + .join('')) } + + + +/********************************************************************** +* vim:set ts=4 sw=4 nowrap : */ return module }) diff --git a/package.json b/package.json new file mode 100644 index 0000000..8c51434 --- /dev/null +++ b/package.json @@ -0,0 +1,19 @@ +{ + "name": "ig-doc", + "version": "1.0.0", + "description": "Basic JavaScript self-documentation utils", + "main": "doc.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/flynx/doc.js.git" + }, + "author": "Alex A. Naanou (alex.nanou@gmail.com)", + "license": "BSD-3-Clause", + "bugs": { + "url": "https://github.com/flynx/doc.js/issues" + }, + "homepage": "https://github.com/flynx/doc.js#readme" +}