From db62d9e7b443f3e2a565fef6e3c567f166b5cfd5 Mon Sep 17 00:00:00 2001 From: Michael Mathews Date: Mon, 27 Dec 2010 15:18:44 +0000 Subject: [PATCH] Added events, added parse handlers, added plugins and markdown plugin support. --- LICENSE.md | 18 +- README.md | 6 +- build/build.properties | 4 +- build/templates/package.json | 10 +- conf.json | 10 +- main.js | 309 ++-- modules/common/events.js | 88 ++ modules/evilstreak/markdown.js | 1446 +++++++++++++++++++ modules/jsdoc/doclet.js | 47 +- modules/jsdoc/opts/parser.js | 2 +- modules/jsdoc/src/handlers.js | 17 + modules/jsdoc/src/parser.js | 641 ++++---- modules/jsdoc/src/scanner.js | 19 +- modules/jsdoc/tag.js | 23 +- modules/jsdoc/tag/dictionary/definitions.js | 2 +- modules/jsdoc/tag/validator.js | 2 +- modules/normal/template.js | 199 --- package.json | 7 +- plugins/markdown.js | 15 + templates/default/publish.js | 31 +- templates/default/tmpl/index.html | 2 +- test/{runall.js => runner.js} | 0 test/t/jsdoc/src/parser.js | 76 +- 23 files changed, 2205 insertions(+), 769 deletions(-) create mode 100644 modules/common/events.js create mode 100644 modules/evilstreak/markdown.js create mode 100644 modules/jsdoc/src/handlers.js delete mode 100644 modules/normal/template.js create mode 100644 plugins/markdown.js rename test/{runall.js => runner.js} (100%) diff --git a/LICENSE.md b/LICENSE.md index 554781df..fa9cdedc 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -25,7 +25,7 @@ with JSDoc 3. Each is provided under its own license and has source available from other locations. Rhino ------ +---- Rhino is open source and licensed by Mozilla under the MPL 1.1 or later/GPL 2.0 or later licenses. @@ -36,7 +36,7 @@ You can obtain the source code for Rhino from the Mozilla web site at http://www.mozilla.org/rhino/download.html json2xml (modules/goessner/json2xml) --------- +---- json2xml is copyright (c) Stefan Goessner 2006 @@ -47,7 +47,7 @@ http://goessner.net/ http://goessner.net/download/prj/jsonxml/ Node (modules/common/assert, modules/common/util) -------- +---- Node is Copyright 2009, 2010 Ryan Lienhart Dahl. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy @@ -71,7 +71,7 @@ IN THE SOFTWARE. https://github.com/ry/node JSONSchema Validator (modules/sitepen/jsonschema) --------------------- +---- JSONSchema is copyright (c) 2007 Kris Zyp SitePen (www.sitepen.com) @@ -80,8 +80,16 @@ http://www.sitepen.com/blog/2010/03/02/commonjs-utilities/ Licensed under the MIT license. +markdown-js (modules/evilstreak/markdown) +---- + +markdown-js is released under the MIT license. +http://www.opensource.org/licenses/mit-license.php + +http://github.com/evilstreak/markdown-js + Mustache (templates/lib/janl/mustache.js) -------------------- +---- Mustache is Copyright (c) 2009 Chris Wanstrath (Ruby) diff --git a/README.md b/README.md index 00d71c5b..37e1bb5e 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ directory. To test that the installed app is working, execute the following: - $ java -jar jsdoc.jar -T + $ java -jar jsdoc.jar --test Usage ----- @@ -25,11 +25,11 @@ Usage This example assumes your working directory is the JSDoc project base directory... - $ java -jar jsdoc.jar -d stdout yourSourceCode.js + $ java -jar jsdoc.jar yourSourceCodeFile.js For help regarding the supported commandline options use -h. - $ java -jar jsdoc.jar -h + $ java -jar jsdoc.jar --help See --- diff --git a/build/build.properties b/build/build.properties index 2369ee6c..9ca61ffb 100644 --- a/build/build.properties +++ b/build/build.properties @@ -1,2 +1,2 @@ -app.name=jsdoc-3 -app.version=0.0.0 +app.name=jsdoc +app.version=3.0.0alpha1 diff --git a/build/templates/package.json b/build/templates/package.json index de87c4c8..746ac786 100644 --- a/build/templates/package.json +++ b/build/templates/package.json @@ -2,7 +2,7 @@ "name": "@app.name@", "version": "@app.version@", "revision": "@timestamp@", - "description": "An automatic documentation generator for javascript", + "description": "An automatic documentation generator for javascript.", "keywords": [ "documentation", "javascript" ], "licenses": [ { @@ -16,7 +16,13 @@ "url": "http://github.com/micmath/JSDoc" } ], - "bugs": "http://jsdoc.lighthouseapp.com/", + "contributors" : [ + { + "name": "Michael Mathews", + "email": "micmath@gmail.com", + "web": "http://micmath.ws" + } + ], "maintainers": [ { "name": "Michael Mathews", diff --git a/conf.json b/conf.json index c04cd46c..df0cdadd 100644 --- a/conf.json +++ b/conf.json @@ -1,3 +1,11 @@ { - "permitUnknownTags": false + "tags": { + "allowUnknownTags": false + }, + "source": { + "includePattern": ".+\\.js(doc)?$" + }, + "plugins": [ + "plugins/markdown.js" + ] } \ No newline at end of file diff --git a/main.js b/main.js index cecab2e7..9bb8fe81 100644 --- a/main.js +++ b/main.js @@ -1,156 +1,171 @@ /** - * @project JSDoc - * @copyright 2010 (c) Michael Mathews - * @license See LICENSE.md file included in this distribution. + * @overview JSDoc/main.js + * @copyright 2010, 2011 (c) Michael Mathews + * @license See LICENSE.md file included in this distribution. */ -//// bootstrap - /** @global */ - const BASEDIR = arguments[0].replace(/([\/\\])main\.js$/, '$1'); // jsdoc.jar sets argument[0] to the abspath to main.js - - /** @global */ - function require(id) { // like commonjs - var path = require.base + id + '.js', - fileContent = ''; - - try { - var file = new java.io.File(path), - scanner = new java.util.Scanner(file).useDelimiter("\\Z"), - fileContent = String( scanner.next() ); - } - catch(e) { - print(e); - } - - try { - var f = new Function('require', 'exports', 'module', fileContent), - exports = require.cache[path] || {}, - module = { id: id, uri: path }; - - require.cache[id] = exports; - f.call({}, require, exports, module); - } - catch(e) { - print('Unable to require source code from "' + path + '": ' + e); - } - return exports; - } - require.base = BASEDIR + '/modules/'; // assume all module paths are relative to here - require.cache = {}; // cache module exports. Like: {id: exported} - -//// +//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~// -//// main + +/** @global */ +const BASEDIR = arguments[0].replace(/([\/\\])main\.js$/, '$1'); // jsdoc.jar sets argument[0] to the abspath to main.js + +/** @global */ +function require(id) { // like commonjs + var path = require.base + id + '.js', + fileContent = ''; + + try { + var file = new java.io.File(path), + scanner = new java.util.Scanner(file).useDelimiter("\\Z"), + fileContent = String( scanner.next() ); + } + catch(e) { + print('Unable to read source code from "' + path + '": ' + e); + } - /** @global */ - env = { - run: { - start: new Date(), - finish: null - }, - args: arguments.slice(1), // jsdoc.jar sets argument[0] to the abspath to main.js, user args follow - conf: {}, // TODO: populate from file BASEDIR+'/conf.json' - opts: {} - }; - - try { main(); } - finally { env.run.finish = new Date(); } - - /** @global */ - function print(/*...*/) { - for (var i = 0, leni = arguments.length; i < leni; i++) { - java.lang.System.out.println('' + arguments[i]); - } - } - - /** @global */ - function dump(/*...*/) { - for (var i = 0, leni = arguments.length; i < leni; i++) { - print( require('common/dumper').dump(arguments[i]) ); - } - - } + try { + var f = new Function('require', 'exports', 'module', fileContent), + exports = require.cache[path] || {}, + module = { id: id, uri: path }; + + require.cache[id] = exports; + f.call({}, require, exports, module); + } + catch(e) { + print('Unable to require source code from "' + path + '": ' + e.toSource()); + } + return exports; +} +require.base = BASEDIR + '/modules/'; // assume all module paths are relative to here +require.cache = {}; // cache module exports. Like: {id: exported} + + +//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~// - /** @global */ - function include(filepath) { - try { - load(BASEDIR + filepath); - } - catch (e) { - print('Cannot include "' + BASEDIR + filepath + '": '+e); - } - } - /** @global */ - function exit(v) { - java.lang.System.exit(v); - } - - function main() { - var sourceFiles, - docs, - jsdoc = { - opts: { - parser: require('jsdoc/opts/parser') - }, - src: { - scanner: require('jsdoc/src/scanner'), - parser: require('jsdoc/src/parser') - } - }; - - try { - env.conf = JSON.parse( require('common/fs').read(BASEDIR+'conf.json') ); - } - catch (e) { - throw('Configuration file cannot be evaluated. '+e); - } - - env.opts = jsdoc.opts.parser.parse(env.args); - - if (env.opts.help) { - print( jsdoc.optParser.help() ); - exit(0); - } - else if (env.opts.test) { - include('test/runall.js'); - exit(0); - } - - if (env.opts._.length > 0) { // are there any source files to scan? - sourceFiles = jsdoc.src.scanner.scan(env.opts._, (env.opts.recurse? 10 : undefined)); -//dump('sourceFiles...', sourceFiles); - docs = jsdoc.src.parser.parse(sourceFiles, env.opts.encoding); -//dump('jsdoc.docs...', docs); - if (env.opts.template) { - include('templates/'+env.opts.template+'/publish.js'); - if (typeof publish === 'function') { - publish(docs, {}); - } +/** @global */ +env = { + run: { + start: new Date(), + finish: null + }, + args: arguments.slice(1), // jsdoc.jar sets argument[0] to the abspath to main.js, user args follow + conf: {}, // TODO: populate from file BASEDIR+'/conf.json' + opts: {} +}; + +/** @global */ +app = { + jsdoc: { + scanner: new (require('jsdoc/src/scanner').Scanner)(), + parser: new (require('jsdoc/src/parser').Parser)() + } +} + +try { main(); } +finally { env.run.finish = new Date(); } + +/** @global */ +function print(/*...*/) { + for (var i = 0, leni = arguments.length; i < leni; i++) { + java.lang.System.out.println('' + arguments[i]); + } +} + +/** @global */ +function dump(/*...*/) { + for (var i = 0, leni = arguments.length; i < leni; i++) { + print( require('common/dumper').dump(arguments[i]) ); + } +} + +/** @global */ +function include(filepath) { + try { + load(BASEDIR + filepath); + } + catch (e) { + print('Cannot include "' + BASEDIR + filepath + '": '+e); + } +} + +/** @global */ +function exit(v) { + java.lang.System.exit(v); +} + + +//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~// + + +/** @global */ +function main() { + var sourceFiles, + docs, + jsdoc = { + opts: { + parser: require('jsdoc/opts/parser') } -// -// if (env.opts.validate) { -// var jsonSchema = require('sitepen/jsonSchema'); -// var jsdocSchema = require('jsdoc/schema').jsdocSchema; -// var validation = jsonSchema.validate(jsdoc.srcParser.result.toObject(), jsdocSchema); -// print('Validation: ' + validation.toSource()); -// } -// -// if (!env.opts.destination || env.opts.destination.indexOf('stdout') === 0) { -// print( jsdoc.srcParser.result.toString(env.opts.destination) ); -// } -// else if (env.opts.template) { -// try { -// load(BASEDIR+'/templates/'+env.opts.template+'/publish.js'); -// } -// catch (e) { -// print('Cannot load the specified template: templates/'+env.opts.template+'/publish.js: '+e); -// } -// -// publish(jsdoc.srcParser.result.toObject(), {}); -// } - } - } - -//// \ No newline at end of file + }; + + try { + env.conf = JSON.parse( require('common/fs').read(BASEDIR+'conf.json') ); + } + catch (e) { + throw('Configuration file cannot be evaluated. '+e); + } + + env.opts = jsdoc.opts.parser.parse(env.args); + + if (env.opts.help) { + print( jsdoc.opts.parser.help() ); + exit(0); + } + else if (env.opts.test) { + include('test/runner.js'); + exit(0); + } + + // allow user-defined plugins to register listeners + if (env.conf.plugins) { + for (var i = 0, leni = env.conf.plugins.length; i < leni; i++) { + include(env.conf.plugins[i]); + } + } + + if (env.opts._.length > 0) { // are there any files to scan and parse? + + // allow filtering of found source files + if (env.conf.source && env.conf.source.includePattern) { + var includeRegexp = new RegExp(env.conf.source.includePattern); + app.jsdoc.scanner.on('sourceFileFound', function(e) { + if ( !includeRegexp.test(e.fileName) ) { + return false; + } + }); + } + + sourceFiles = app.jsdoc.scanner.scan(env.opts._, (env.opts.recurse? 10 : undefined)); + + require('jsdoc/src/handlers'); + + docs = app.jsdoc.parser.parse(sourceFiles, env.opts.encoding); + +//dump(docs); +//exit(0); + + env.opts.template = env.opts.template || 'default'; + + // should define a global "publish" function + include('templates/' + env.opts.template + '/publish.js'); + + if (typeof publish === 'function') { + publish( + docs, + { destination: env.opts.destination } + ); + } + } +} \ No newline at end of file diff --git a/modules/common/events.js b/modules/common/events.js new file mode 100644 index 00000000..91ff89f7 --- /dev/null +++ b/modules/common/events.js @@ -0,0 +1,88 @@ +/** + @module common/events + @author Michael Mathews + @license Apache License 2.0 - See file 'LICENSE.md' in this project. + */ +(function() { + /** + @function module:common/events.mixin + @param {*} o The object to recieve the EventEmitter members. + */ + exports.mixin = function(o) { + for ( var p in EventEmitter ) { + o[p] = EventEmitter[p]; + } + } + + /** + @mixin module:common/events.EventEmitter + */ + var EventEmitter = { + /** + @function module:common/events.EventEmitter.on + @param {string} type + @param {function} handler + @returns this + */ + on: function(type, handler, context) { + if ( !type || !handler ) { + return; + } + if ( !context ) { context = this; } + + if ( !this.__bindings ) { this.__bindings = {}; } + // TODO check here for hasOwnProperty? + if ( !this.__bindings[type] ) { this.__bindings[type] = []; } + + var call = function(e) { + return handler.call(context, e); + }; + this.__bindings[type].push( {handler: handler, call: call} ); + + return this; // chainable + }, + + /** + @function module:common/events.EventEmitter.fire + @param {string} type + @param {object} [eventData] + @returns this + */ + fire: function(eventType, eventData) { + if ( !eventType || !this.__bindings || !this.__bindings[eventType] ) { + return; + } + + // run handlers in first-in-first-run order + for (var i = 0, leni = this.__bindings[eventType].length; i < leni; i++) { + if ( false === this.__bindings[eventType][i].call(eventData) ) { + if (eventData) { eventData.defaultPrevented = true; } + } + } + + return this; // chainable + }, + + /** + @function module:common/events.EventEmitter.removeListener + @param {string} type + @param {function} handler + */ + removeListener: function(type, handler) { + if ( !type || !handler || !this.__bindings || !this.__bindings[type] ) { + return; + } + + var i = this.__bindings[type].length; + while ( i-- ) { + if ( this.__bindings[type][i].handler === handler ) { + this.__bindings[type].splice(i, 1); + } + } + + if (this.__bindings[type].length === 0) { + delete this.__bindings[type]; + } + } + }; +})(); \ No newline at end of file diff --git a/modules/evilstreak/markdown.js b/modules/evilstreak/markdown.js new file mode 100644 index 00000000..cdfbeb65 --- /dev/null +++ b/modules/evilstreak/markdown.js @@ -0,0 +1,1446 @@ +// Released under MIT license +// Copyright (c) 2009-2010 Dominic Baggott +// Copyright (c) 2009-2010 Ash Berlin + +(function( expose ) { + +/** + * class Markdown + * + * Markdown processing in Javascript done right. We have very particular views + * on what constitutes 'right' which include: + * + * - produces well-formed HTML (this means that em and strong nesting is + * important) + * + * - has an intermediate representation to allow processing of parsed data (We + * in fact have two, both as [JsonML]: a markdown tree and an HTML tree). + * + * - is easily extensible to add new dialects without having to rewrite the + * entire parsing mechanics + * + * - has a good test suite + * + * This implementation fulfills all of these (except that the test suite could + * do with expanding to automatically run all the fixtures from other Markdown + * implementations.) + * + * ##### Intermediate Representation + * + * *TODO* Talk about this :) Its JsonML, but document the node names we use. + * + * [JsonML]: http://jsonml.org/ "JSON Markup Language" + **/ +var Markdown = expose.Markdown = function Markdown(dialect) { + switch (typeof dialect) { + case "undefined": + this.dialect = Markdown.dialects.Gruber; + break; + case "object": + this.dialect = dialect; + break; + default: + if (dialect in Markdown.dialects) { + this.dialect = Markdown.dialects[dialect]; + } + else { + throw new Error("Unknown Markdown dialect '" + String(dialect) + "'"); + } + break; + } + this.em_state = []; + this.strong_state = []; + this.debug_indent = ""; +} + +/** + * parse( markdown, [dialect] ) -> JsonML + * - markdown (String): markdown string to parse + * - dialect (String | Dialect): the dialect to use, defaults to gruber + * + * Parse `markdown` and return a markdown document as a Markdown.JsonML tree. + **/ +expose.parse = function( source, dialect ) { + // dialect will default if undefined + var md = new Markdown( dialect ); + return md.toTree( source ); +} + +/** + * toHTML( markdown ) -> String + * toHTML( md_tree ) -> String + * - markdown (String): markdown string to parse + * - md_tree (Markdown.JsonML): parsed markdown tree + * + * Take markdown (either as a string or as a JsonML tree) and run it through + * [[toHTMLTree]] then turn it into a well-formated HTML fragment. + **/ +expose.toHTML = function toHTML( source ) { + var input = expose.toHTMLTree( source ); + + return expose.renderJsonML( input ); +} + +/** + * toHTMLTree( markdown, [dialect] ) -> JsonML + * toHTMLTree( md_tree ) -> JsonML + * - markdown (String): markdown string to parse + * - dialect (String | Dialect): the dialect to use, defaults to gruber + * - md_tree (Markdown.JsonML): parsed markdown tree + * + * Turn markdown into HTML, represented as a JsonML tree. If a string is given + * to this function, it is first parsed into a markdown tree by calling + * [[parse]]. + **/ +expose.toHTMLTree = function toHTMLTree( input, dialect ) { + // convert string input to an MD tree + if ( typeof input ==="string" ) input = this.parse( input, dialect ); + + // Now convert the MD tree to an HTML tree + + // remove references from the tree + var attrs = extract_attr( input ), + refs = {}; + + if ( attrs && attrs.references ) { + refs = attrs.references; + } + + var html = convert_tree_to_html( input, refs ); + merge_text_nodes( html ); + return html; +} + +var mk_block = Markdown.mk_block = function(block, trail, line) { + // Be helpful for default case in tests. + if ( arguments.length == 1 ) trail = "\n\n"; + + var s = new String(block); + s.trailing = trail; + // To make it clear its not just a string + s.toSource = function() { + return "Markdown.mk_block( " + + uneval(block) + + ", " + + uneval(trail) + + ", " + + uneval(line) + + " )" + } + + if (line != undefined) + s.lineNumber = line; + + return s; +} + +function count_lines( str ) { + var n = 0, i = -1;; + while ( ( i = str.indexOf('\n', i+1) ) != -1) n++; + return n; +} + +// Internal - split source into rough blocks +Markdown.prototype.split_blocks = function splitBlocks( input, startLine ) { + // [\s\S] matches _anything_ (newline or space) + var re = /([\s\S]+?)($|\n(?:\s*\n|$)+)/g, + blocks = [], + m; + + var line_no = 1; + + if ( ( m = (/^(\s*\n)/)(input) ) != null ) { + // skip (but count) leading blank lines + line_no += count_lines( m[0] ); + re.lastIndex = m[0].length; + } + + while ( ( m = re(input) ) != null ) { + blocks.push( mk_block( m[1], m[2], line_no ) ); + line_no += count_lines( m[0] ); + } + + return blocks; +} + +/** + * Markdown#processBlock( block, next ) -> undefined | [ JsonML, ... ] + * - block (String): the block to process + * - next (Array): the following blocks + * + * Process `block` and return an array of JsonML nodes representing `block`. + * + * It does this by asking each block level function in the dialect to process + * the block until one can. Succesful handling is indicated by returning an + * array (with zero or more JsonML nodes), failure by a false value. + * + * Blocks handlers are responsible for calling [[Markdown#processInline]] + * themselves as appropriate. + * + * If the blocks were split incorrectly or adjacent blocks need collapsing you + * can adjust `next` in place using shift/splice etc. + * + * If any of this default behaviour is not right for the dialect, you can + * define a `__call__` method on the dialect that will get invoked to handle + * the block processing. + */ +Markdown.prototype.processBlock = function processBlock( block, next ) { + var cbs = this.dialect.block, + ord = cbs.__order__; + + if ( "__call__" in cbs ) { + return cvs.__call__.call(this, block, next); + } + + for ( var i = 0; i < ord.length; i++ ) { + //D:this.debug( "Testing", ord[i] ); + var res = cbs[ ord[i] ].call( this, block, next ); + if ( res ) { + //D:this.debug(" matched"); + if ( !res instanceof Array || ( res.length > 0 && !( res[0] instanceof Array ) ) ) + this.debug(ord[i], "didn't return a proper array"); + //D:this.debug( "" ); + return res; + } + } + + // Uhoh! no match! Should we throw an error? + return []; +} + +Markdown.prototype.processInline = function processInline( block ) { + return this.dialect.inline.__call__.call( this, String( block ) ); +} + +/** + * Markdown#toTree( source ) -> JsonML + * - source (String): markdown source to parse + * + * Parse `source` into a JsonML tree representing the markdown document. + **/ +// custom_tree means set this.tree to `custom_tree` and restore old value on return +Markdown.prototype.toTree = function toTree( source, custom_root ) { + var blocks = source instanceof Array + ? source + : this.split_blocks( source ); + + // Make tree a member variable so its easier to mess with in extensions + var old_tree = this.tree; + try { + this.tree = custom_root || this.tree || [ "markdown" ]; + + blocks: + while ( blocks.length ) { + var b = this.processBlock( blocks.shift(), blocks ); + + // Reference blocks and the like won't return any content + if ( !b.length ) continue blocks; + + this.tree.push.apply( this.tree, b ); + } + return this.tree; + } + finally { + if ( custom_root ) + this.tree = old_tree; + } + +} + +// Noop by default +Markdown.prototype.debug = function () { + var args = Array.prototype.slice.call( arguments); + args.unshift(this.debug_indent); + print.apply( print, args ); +} + +Markdown.prototype.loop_re_over_block = function( re, block, cb ) { + // Dont use /g regexps with this + var m, + b = block.valueOf(); + + while ( b.length && (m = re(b) ) != null) { + b = b.substr( m[0].length ); + cb.call(this, m); + } + return b; +} + +/** + * Markdown.dialects + * + * Namespace of built-in dialects. + **/ +Markdown.dialects = {}; + +/** + * Markdown.dialects.Gruber + * + * The default dialect that follows the rules set out by John Gruber's + * markdown.pl as closely as possible. Well actually we follow the behaviour of + * that script which in some places is not exactly what the syntax web page + * says. + **/ +Markdown.dialects.Gruber = { + block: { + atxHeader: function atxHeader( block, next ) { + var m = block.match( /^(#{1,6})\s*(.*?)\s*#*\s*(?:\n|$)/ ); + + if ( !m ) return undefined; + + var header = [ "header", { level: m[ 1 ].length }, m[ 2 ] ]; + + if ( m[0].length < block.length ) + next.unshift( mk_block( block.substr( m[0].length ), block.trailing, block.lineNumber + 2 ) ); + + return [ header ]; + }, + + setextHeader: function setextHeader( block, next ) { + var m = block.match( /^(.*)\n([-=])\2\2+(?:\n|$)/ ); + + if ( !m ) return undefined; + + var level = ( m[ 2 ] === "=" ) ? 1 : 2; + var header = [ "header", { level : level }, m[ 1 ] ]; + + if ( m[0].length < block.length ) + next.unshift( mk_block( block.substr( m[0].length ), block.trailing, block.lineNumber + 2 ) ); + + return [ header ]; + }, + + code: function code( block, next ) { + // | Foo + // |bar + // should be a code block followed by a paragraph. Fun + // + // There might also be adjacent code block to merge. + + var ret = [], + re = /^(?: {0,3}\t| {4})(.*)\n?/, + lines; + + // 4 spaces + content + var m = block.match( re ); + + if ( !m ) return undefined; + + block_search: + do { + // Now pull out the rest of the lines + var b = this.loop_re_over_block( + re, block.valueOf(), function( m ) { ret.push( m[1] ) } ); + + if (b.length) { + // Case alluded to in first comment. push it back on as a new block + next.unshift( mk_block(b, block.trailing) ); + break block_search; + } + else if (next.length) { + // Check the next block - it might be code too + var m = next[0].match( re ); + + if ( !m ) break block_search; + + // Pull how how many blanks lines follow - minus two to account for .join + ret.push ( block.trailing.replace(/[^\n]/g, '').substring(2) ); + + block = next.shift(); + } + else + break block_search; + } while (true); + + return [ [ "code_block", ret.join("\n") ] ]; + }, + + horizRule: function horizRule( block, next ) { + // this needs to find any hr in the block to handle abutting blocks + var m = block.match( /^(?:([\s\S]*?)\n)?[ \t]*([-_*])(?:[ \t]*\2){2,}[ \t]*(?:\n([\s\S]*))?$/ ); + + if ( !m ) { + return undefined; + } + + var jsonml = [ [ "hr" ] ]; + + // if there's a leading abutting block, process it + if ( m[ 1 ] ) { + jsonml.unshift.apply( jsonml, this.processBlock( m[ 1 ], [] ) ); + } + + // if there's a trailing abutting block, stick it into next + if ( m[ 3 ] ) { + next.unshift( mk_block( m[ 3 ] ) ); + } + + return jsonml; + }, + + // There are two types of lists. Tight and loose. Tight lists have no whitespace + // between the items (and result in text just in the
  • ) and loose lists, + // which have an empty line between list items, resulting in (one or more) + // paragraphs inside the
  • . + // + // There are all sorts weird edge cases about the original markdown.pl's + // handling of lists: + // + // * Nested lists are supposed to be indented by four chars per level. But + // if they aren't, you can get a nested list by indenting by less than + // four so long as the indent doesn't match an indent of an existing list + // item in the 'nest stack'. + // + // * The type of the list (bullet or number) is controlled just by the + // first item at the indent. Subsequent changes are ignored unless they + // are for nested lists + // + lists: (function( ) { + // Use a closure to hide a few variables. + var any_list = "[*+-]|\\d\\.", + bullet_list = /[*+-]/, + number_list = /\d+\./, + // Capture leading indent as it matters for determining nested lists. + is_list_re = new RegExp( "^( {0,3})(" + any_list + ")[ \t]+" ), + indent_re = "(?: {0,3}\\t| {4})"; + + // TODO: Cache this regexp for certain depths. + // Create a regexp suitable for matching an li for a given stack depth + function regex_for_depth( depth ) { + + return new RegExp( + // m[1] = indent, m[2] = list_type + "(?:^(" + indent_re + "{0," + depth + "} {0,3})(" + any_list + ")\\s+)|" + + // m[3] = cont + "(^" + indent_re + "{0," + (depth-1) + "}[ ]{0,4})" + ); + } + function expand_tab( input ) { + return input.replace( / {0,3}\t/g, " " ); + } + + // Add inline content `inline` to `li`. inline comes from processInline + // so is an array of content + function add(li, loose, inline, nl) { + if (loose) { + li.push( [ "para" ].concat(inline) ); + return; + } + // Hmmm, should this be any block level element or just paras? + var add_to = li[li.length -1] instanceof Array && li[li.length - 1][0] == "para" + ? li[li.length -1] + : li; + + // If there is already some content in this list, add the new line in + if (nl && li.length > 1) inline.unshift(nl); + + for (var i=0; i < inline.length; i++) { + var what = inline[i], + is_str = typeof what == "string"; + if (is_str && add_to.length > 1 && typeof add_to[add_to.length-1] == "string" ) + { + add_to[ add_to.length-1 ] += what; + } + else { + add_to.push( what ); + } + } + } + + // contained means have an indent greater than the current one. On + // *every* line in the block + function get_contained_blocks( depth, blocks ) { + + var re = new RegExp( "^(" + indent_re + "{" + depth + "}.*?\\n?)*$" ), + replace = new RegExp("^" + indent_re + "{" + depth + "}", "gm"), + ret = []; + + while ( blocks.length > 0 ) { + if ( re( blocks[0] ) ) { + var b = blocks.shift(), + // Now remove that indent + x = b.replace( replace, ""); + + ret.push( mk_block( x, b.trailing, b.lineNumber ) ); + } + break; + } + return ret; + } + + // passed to stack.forEach to turn list items up the stack into paras + function paragraphify(s, i, stack) { + var list = s.list; + var last_li = list[list.length-1]; + + if (last_li[1] instanceof Array && last_li[1][0] == "para") { + return; + } + if (i+1 == stack.length) { + // Last stack frame + // Keep the same array, but replace the contents + last_li.push( ["para"].concat( last_li.splice(1) ) ); + } + else { + var sublist = last_li.pop(); + last_li.push( ["para"].concat( last_li.splice(1) ), sublist ); + } + } + + // The matcher function + return function( block, next ) { + var m = block.match( is_list_re ); + if ( !m ) return undefined; + + function make_list( m ) { + var list = bullet_list( m[2] ) + ? ["bulletlist"] + : ["numberlist"]; + + stack.push( { list: list, indent: m[1] } ); + return list; + } + + + var stack = [], // Stack of lists for nesting. + list = make_list( m ), + last_li, + loose = false, + ret = [ stack[0].list ]; + + // Loop to search over block looking for inner block elements and loose lists + loose_search: + while( true ) { + // Split into lines preserving new lines at end of line + var lines = block.split( /(?=\n)/ ); + + // We have to grab all lines for a li and call processInline on them + // once as there are some inline things that can span lines. + var li_accumulate = ""; + + // Loop over the lines in this block looking for tight lists. + tight_search: + for (var line_no=0; line_no < lines.length; line_no++) { + var nl = "", + l = lines[line_no].replace(/^\n/, function(n) { nl = n; return "" }); + + // TODO: really should cache this + var line_re = regex_for_depth( stack.length ); + + m = l.match( line_re ); + //print( "line:", uneval(l), "\nline match:", uneval(m) ); + + // We have a list item + if ( m[1] !== undefined ) { + // Process the previous list item, if any + if ( li_accumulate.length ) { + add( last_li, loose, this.processInline( li_accumulate ), nl ); + // Loose mode will have been dealt with. Reset it + loose = false; + li_accumulate = ""; + } + + m[1] = expand_tab( m[1] ); + var wanted_depth = Math.floor(m[1].length/4)+1; + //print( "want:", wanted_depth, "stack:", stack.length); + if ( wanted_depth > stack.length ) { + // Deep enough for a nested list outright + //print ( "new nested list" ); + list = make_list( m ); + last_li.push( list ); + last_li = list[1] = [ "listitem" ]; + } + else { + // We aren't deep enough to be strictly a new level. This is + // where Md.pl goes nuts. If the indent matches a level in the + // stack, put it there, else put it one deeper then the + // wanted_depth deserves. + var found = stack.some(function(s, i) { + if ( s.indent != m[1] ) return false; + list = s.list; // Found the level we want + stack.splice(i+1); // Remove the others + //print("found"); + return true; // And stop looping + }); + + if (!found) { + //print("not found. l:", uneval(l)); + wanted_depth++; + if (wanted_depth <= stack.length) { + stack.splice(wanted_depth); + //print("Desired depth now", wanted_depth, "stack:", stack.length); + list = stack[wanted_depth-1].list; + //print("list:", uneval(list) ); + } + else { + //print ("made new stack for messy indent"); + list = make_list(m); + last_li.push(list); + } + } + + //print( uneval(list), "last", list === stack[stack.length-1].list ); + last_li = [ "listitem" ]; + list.push(last_li); + } // end depth of shenegains + nl = ""; + } + + // Add content + if (l.length > m[0].length) { + li_accumulate += nl + l.substr( m[0].length ); + } + } // tight_search + + if ( li_accumulate.length ) { + add( last_li, loose, this.processInline( li_accumulate ), nl ); + // Loose mode will have been dealt with. Reset it + loose = false; + li_accumulate = ""; + } + + // Look at the next block - we might have a loose list. Or an extra + // paragraph for the current li + var contained = get_contained_blocks( stack.length, next ); + + // Deal with code blocks or properly nested lists + if (contained.length > 0) { + // Make sure all listitems up the stack are paragraphs + stack.forEach( paragraphify, this ); + + last_li.push.apply( last_li, this.toTree( contained, [] ) ); + } + + var next_block = next[0] && next[0].valueOf() || ""; + + if ( next_block.match(is_list_re) || next_block.match( /^ / ) ) { + block = next.shift(); + + // Check for an HR following a list: features/lists/hr_abutting + var hr = this.dialect.block.horizRule( block, next ); + + if (hr) { + ret.push.apply(ret, hr); + break; + } + + // Make sure all listitems up the stack are paragraphs + stack.forEach( paragraphify , this ); + + loose = true; + continue loose_search; + } + break; + } // loose_search + + return ret; + } + })(), + + blockquote: function blockquote( block, next ) { + if ( !block.match( /^>/m ) ) + return undefined; + + var jsonml = []; + + // separate out the leading abutting block, if any + if ( block[ 0 ] != ">" ) { + var lines = block.split( /\n/ ), + prev = []; + + // keep shifting lines until you find a crotchet + while ( lines.length && lines[ 0 ][ 0 ] != ">" ) { + prev.push( lines.shift() ); + } + + // reassemble! + block = lines.join( "\n" ); + jsonml.push.apply( jsonml, this.processBlock( prev.join( "\n" ), [] ) ); + } + + // if the next block is also a blockquote merge it in + while ( next.length && next[ 0 ][ 0 ] == ">" ) { + var b = next.shift(); + block += block.trailing + b; + block.trailing = b.trailing; + } + + // Strip off the leading "> " and re-process as a block. + var input = block.replace( /^> ?/gm, '' ), + old_tree = this.tree; + jsonml.push( this.toTree( input, [ "blockquote" ] ) ); + + return jsonml; + }, + + referenceDefn: function referenceDefn( block, next) { + var re = /^\s*\[(.*?)\]:\s*(\S+)(?:\s+(?:(['"])(.*?)\3|\((.*?)\)))?\n?/; + // interesting matches are [ , ref_id, url, , title, title ] + + if ( !block.match(re) ) + return undefined; + + // make an attribute node if it doesn't exist + if ( !extract_attr( this.tree ) ) { + this.tree.splice( 1, 0, {} ); + } + + var attrs = extract_attr( this.tree ); + + // make a references hash if it doesn't exist + if ( attrs.references === undefined ) { + attrs.references = {}; + } + + var b = this.loop_re_over_block(re, block, function( m ) { + + if ( m[2] && m[2][0] == '<' && m[2][m[2].length-1] == '>' ) + m[2] = m[2].substring( 1, m[2].length - 1 ); + + var ref = attrs.references[ m[1].toLowerCase() ] = { + href: m[2] + }; + + if (m[4] !== undefined) + ref.title = m[4]; + else if (m[5] !== undefined) + ref.title = m[5]; + + } ); + + if (b.length) + next.unshift( mk_block( b, block.trailing ) ); + + return []; + }, + + para: function para( block, next ) { + // everything's a para! + return [ ["para"].concat( this.processInline( block ) ) ]; + } + } +} + +Markdown.dialects.Gruber.inline = { + __call__: function inline( text, patterns ) { + // Hmmm - should this function be directly in Md#processInline, or + // conversely, should Md#processBlock be moved into block.__call__ too + var out = [ ], + m, + // Look for the next occurange of a special character/pattern + re = new RegExp( "([\\s\\S]*?)(" + (patterns.source || patterns) + ")", "g" ), + lastIndex = 0; + + //D:var self = this; + //D:self.debug("processInline:", uneval(text) ); + function add(x) { + //D:self.debug(" adding output", uneval(x)); + if (typeof x == "string" && typeof out[out.length-1] == "string") + out[ out.length-1 ] += x; + else + out.push(x); + } + + while ( ( m = re.exec(text) ) != null) { + if ( m[1] ) add( m[1] ); // Some un-interesting text matched + else m[1] = { length: 0 }; // Or there was none, but make m[1].length == 0 + + var res; + if ( m[2] in this.dialect.inline ) { + res = this.dialect.inline[ m[2] ].call( + this, + text.substr( m.index + m[1].length ), m, out ); + } + // Default for now to make dev easier. just slurp special and output it. + res = res || [ m[2].length, m[2] ]; + + var len = res.shift(); + // Update how much input was consumed + re.lastIndex += ( len - m[2].length ); + + // Add children + res.forEach(add); + + lastIndex = re.lastIndex; + } + + // Add last 'boring' chunk + if ( text.length > lastIndex ) + add( text.substr( lastIndex ) ); + + return out; + }, + + "\\": function escaped( text ) { + // [ length of input processed, node/children to add... ] + // Only esacape: \ ` * _ { } [ ] ( ) # * + - . ! + if ( text.match( /^\\[\\`\*_{}\[\]()#\+.!\-]/ ) ) + return [ 2, text[1] ]; + else + // Not an esacpe + return [ 1, "\\" ]; + }, + + "![": function image( text ) { + // ![Alt text](/path/to/img.jpg "Optional title") + // 1 2 3 4 <--- captures + var m = text.match( /^!\[(.*?)\][ \t]*\([ \t]*(\S*)(?:[ \t]+(["'])(.*?)\3)?[ \t]*\)/ ); + + if ( m ) { + if ( m[2] && m[2][0] == '<' && m[2][m[2].length-1] == '>' ) + m[2] = m[2].substring( 1, m[2].length - 1 ); + + m[2] == this.dialect.inline.__call__.call( this, m[2], /\\/ )[0]; + + var attrs = { alt: m[1], href: m[2] || "" }; + if ( m[4] !== undefined) + attrs.title = m[4]; + + return [ m[0].length, [ "img", attrs ] ]; + } + + // ![Alt text][id] + m = text.match( /^!\[(.*?)\][ \t]*\[(.*?)\]/ ); + + if ( m ) { + // We can't check if the reference is known here as it likely wont be + // found till after. Check it in md tree->hmtl tree conversion + return [ m[0].length, [ "img_ref", { alt: m[1], ref: m[2].toLowerCase(), text: m[0] } ] ]; + } + + // Just consume the '![' + return [ 2, "![" ]; + }, + + "[": function link( text ) { + // [link text](/path/to/img.jpg "Optional title") + // 1 2 3 4 <--- captures + var m = text.match( /^\[([\s\S]*?)\][ \t]*\([ \t]*(\S+)(?:[ \t]+(["'])(.*?)\3)?[ \t]*\)/ ); + + if ( m ) { + if ( m[2] && m[2][0] == '<' && m[2][m[2].length-1] == '>' ) + m[2] = m[2].substring( 1, m[2].length - 1 ); + + // Process escapes only + m[2] = this.dialect.inline.__call__.call( this, m[2], /\\/ )[0]; + + var attrs = { href: m[2] || "" }; + if ( m[4] !== undefined) + attrs.title = m[4]; + + return [ m[0].length, [ "link", attrs, m[1] ] ]; + } + + // [Alt text][id] + // [Alt text] [id] + // [id] + m = text.match( /^\[([\s\S]*?)\](?: ?\[(.*?)\])?/ ); + + if ( m ) { + // [id] case, text == id + if ( m[2] === undefined || m[2] === "" ) m[2] = m[1]; + + // We can't check if the reference is known here as it likely wont be + // found till after. Check it in md tree->hmtl tree conversion. + // Store the original so that conversion can revert if the ref isn't found. + return [ + m[ 0 ].length, + [ + "link_ref", + { + ref: m[ 2 ].toLowerCase(), + original: m[ 0 ] + }, + m[ 1 ] + ] + ]; + } + + // Just consume the '[' + return [ 1, "[" ]; + }, + + + "<": function autoLink( text ) { + var m; + + if ( ( m = text.match( /^<(?:((https?|ftp|mailto):[^>]+)|(.*?@.*?\.[a-zA-Z]+))>/ ) ) != null ) { + if ( m[3] ) { + return [ m[0].length, [ "link", { href: "mailto:" + m[3] }, m[3] ] ]; + + } + else if ( m[2] == "mailto" ) { + return [ m[0].length, [ "link", { href: m[1] }, m[1].substr("mailto:".length ) ] ]; + } + else + return [ m[0].length, [ "link", { href: m[1] }, m[1] ] ]; + } + + return [ 1, "<" ]; + }, + + "`": function inlineCode( text ) { + // Inline code block. as many backticks as you like to start it + // Always skip over the opening ticks. + var m = text.match( /(`+)(([\s\S]*?)\1)/ ); + + if ( m && m[2] ) + return [ m[1].length + m[2].length, [ "inlinecode", m[3] ] ]; + else { + // TODO: No matching end code found - warn! + return [ 1, "`" ]; + } + }, + + " \n": function lineBreak( text ) { + return [ 3, [ "linebreak" ] ]; + } + +} + +// Meta Helper/generator method for em and strong handling +function strong_em( tag, md ) { + + var state_slot = tag + "_state", + other_slot = tag == "strong" ? "em_state" : "strong_state"; + + function CloseTag(len) { + this.len_after = len; + this.name = "close_" + md; + } + + return function ( text, orig_match ) { + + if (this[state_slot][0] == md) { + // Most recent em is of this type + //D:this.debug("closing", md); + this[state_slot].shift(); + + // "Consume" everything to go back to the recrusion in the else-block below + return[ text.length, new CloseTag(text.length-md.length) ]; + } + else { + // Store a clone of the em/strong states + var other = this[other_slot].slice(), + state = this[state_slot].slice(); + + this[state_slot].unshift(md); + + //D:this.debug_indent += " "; + + // Recurse + var res = this.processInline( text.substr( md.length ) ); + //D:this.debug_indent = this.debug_indent.substr(2); + + var last = res[res.length - 1]; + + //D:this.debug("processInline from", tag + ": ", uneval( res ) ); + + var check = this[state_slot].shift(); + if (last instanceof CloseTag) { + res.pop(); + // We matched! Huzzah. + var consumed = text.length - last.len_after; + return [ consumed, [ tag ].concat(res) ]; + } + else { + // Restore the state of the other kind. We might have mistakenly closed it. + this[other_slot] = other; + this[state_slot] = state; + + // We can't reuse the processed result as it could have wrong parsing contexts in it. + return [ md.length, md ]; + } + } + } // End returned function +} + +Markdown.dialects.Gruber.inline["**"] = strong_em("strong", "**"); +Markdown.dialects.Gruber.inline["__"] = strong_em("strong", "__"); +Markdown.dialects.Gruber.inline["*"] = strong_em("em", "*"); +Markdown.dialects.Gruber.inline["_"] = strong_em("em", "_"); + + +// Build default order from insertion order. +Markdown.buildBlockOrder = function(d) { + var ord = []; + for ( var i in d ) { + if ( i == "__order__" || i == "__call__" ) continue; + ord.push( i ); + } + d.__order__ = ord; +} + +// Build patterns for inline matcher +Markdown.buildInlinePatterns = function(d) { + var patterns = []; + + for ( var i in d ) { + if (i == "__call__") continue; + var l = i.replace( /([\\.*+?|()\[\]{}])/g, "\\$1" ) + .replace( /\n/, "\\n" ); + patterns.push( i.length == 1 ? l : "(?:" + l + ")" ); + } + + patterns = patterns.join("|"); + //print("patterns:", uneval( patterns ) ); + + var fn = d.__call__; + d.__call__ = function(text, pattern) { + if (pattern != undefined) + return fn.call(this, text, pattern); + else + return fn.call(this, text, patterns); + } +} + +// Helper function to make sub-classing a dialect easier +Markdown.subclassDialect = function( d ) { + function Block() {}; + Block.prototype = d.block; + function Inline() {}; + Inline.prototype = d.inline; + + return { block: new Block(), inline: new Inline() }; +} + +Markdown.buildBlockOrder ( Markdown.dialects.Gruber.block ); +Markdown.buildInlinePatterns( Markdown.dialects.Gruber.inline ); + +Markdown.dialects.Maruku = Markdown.subclassDialect( Markdown.dialects.Gruber ); + +Markdown.dialects.Maruku.block.document_meta = function document_meta( block, next ) { + // we're only interested in the first block + if ( block.lineNumber > 1 ) return undefined; + + // document_meta blocks consist of one or more lines of `Key: Value\n` + if ( ! block.match( /^(?:\w+:.*\n)*\w+:.*$/ ) ) return undefined; + + // make an attribute node if it doesn't exist + if ( !extract_attr( this.tree ) ) { + this.tree.splice( 1, 0, {} ); + } + + var pairs = block.split( /\n/ ); + for ( p in pairs ) { + var m = pairs[ p ].match( /(\w+):\s*(.*)$/ ), + key = m[ 1 ].toLowerCase(), + value = m[ 2 ]; + + this.tree[ 1 ][ key ] = value; + } + + // document_meta produces no content! + return []; +} + +Markdown.dialects.Maruku.block.block_meta = function block_meta( block, next ) { + // check if the last line of the block is an meta hash + var m = block.match( /(^|\n) {0,3}\{:\s*((?:\\\}|[^\}])*)\s*\}$/ ); + if ( !m ) return undefined; + + // process the meta hash + var attr = process_meta_hash( m[ 2 ] ); + + // if we matched ^ then we need to apply meta to the previous block + if ( m[ 1 ] === "" ) { + var node = this.tree[ this.tree.length - 1 ], + hash = extract_attr( node ); + + // if the node is a string (rather than JsonML), bail + if ( typeof node === "string" ) return undefined; + + // create the attribute hash if it doesn't exist + if ( !hash ) { + hash = {}; + node.splice( 1, 0, hash ); + } + + // add the attributes in + for ( a in attr ) { + hash[ a ] = attr[ a ]; + } + + // return nothing so the meta hash is removed + return []; + } + + // pull the meta hash off the block and process what's left + var b = block.replace( /\n.*$/, "" ), + result = this.processBlock( b, [] ); + + // get or make the attributes hash + var hash = extract_attr( result[ 0 ] ); + if ( !hash ) { + hash = {}; + result[ 0 ].splice( 1, 0, hash ); + } + + // attach the attributes to the block + for ( a in attr ) { + hash[ a ] = attr[ a ]; + } + + return result; +} + +Markdown.dialects.Maruku.block.definition_list = function definition_list( block, next ) { + // one or more terms followed by one or more definitions, in a single block + var tight = /^((?:[^\s:].*\n)+):\s+([^]+)$/, + list = [ "dl" ]; + + // see if we're dealing with a tight or loose block + if ( ( m = block.match( tight ) ) ) { + // pull subsequent tight DL blocks out of `next` + var blocks = [ block ]; + while ( next.length && tight.exec( next[ 0 ] ) ) { + blocks.push( next.shift() ); + } + + for ( var b = 0; b < blocks.length; ++b ) { + var m = blocks[ b ].match( tight ), + terms = m[ 1 ].replace( /\n$/, "" ).split( /\n/ ), + defns = m[ 2 ].split( /\n:\s+/ ); + + // print( uneval( m ) ); + + for ( var i = 0; i < terms.length; ++i ) { + list.push( [ "dt", terms[ i ] ] ); + } + + for ( var i = 0; i < defns.length; ++i ) { + // run inline processing over the definition + list.push( [ "dd" ].concat( this.processInline( defns[ i ].replace( /(\n)\s+/, "$1" ) ) ) ); + } + } + } + else { + return undefined; + } + + return [ list ]; +} + +Markdown.dialects.Maruku.inline[ "{:" ] = function inline_meta( text, matches, out ) { + if ( !out.length ) { + return [ 2, "{:" ]; + } + + // get the preceeding element + var before = out[ out.length - 1 ]; + + if ( typeof before === "string" ) { + return [ 2, "{:" ]; + } + + // match a meta hash + var m = text.match( /^\{:\s*((?:\\\}|[^\}])*)\s*\}/ ); + + // no match, false alarm + if ( !m ) { + return [ 2, "{:" ]; + } + + // attach the attributes to the preceeding element + var meta = process_meta_hash( m[ 1 ] ), + attr = extract_attr( before ); + + if ( !attr ) { + attr = {}; + before.splice( 1, 0, attr ); + } + + for ( var k in meta ) { + attr[ k ] = meta[ k ]; + } + + // cut out the string and replace it with nothing + return [ m[ 0 ].length, "" ]; +} + +Markdown.buildBlockOrder ( Markdown.dialects.Maruku.block ); +Markdown.buildInlinePatterns( Markdown.dialects.Maruku.inline ); + +function extract_attr( jsonml ) { + return jsonml instanceof Array + && jsonml.length > 1 + && typeof jsonml[ 1 ] === "object" + && !( jsonml[ 1 ] instanceof Array ) + ? jsonml[ 1 ] + : undefined; +} + +function process_meta_hash( meta_string ) { + var meta = split_meta_hash( meta_string ), + attr = {}; + + for ( var i = 0; i < meta.length; ++i ) { + // id: #foo + if ( /^#/.test( meta[ i ] ) ) { + attr.id = meta[ i ].substring( 1 ); + } + // class: .foo + else if ( /^\./.test( meta[ i ] ) ) { + // if class already exists, append the new one + if ( attr['class'] ) { + attr['class'] = attr['class'] + meta[ i ].replace( /./, " " ); + } + else { + attr['class'] = meta[ i ].substring( 1 ); + } + } + // attribute: foo=bar + else if ( /=/.test( meta[ i ] ) ) { + var s = meta[ i ].split( /=/ ); + attr[ s[ 0 ] ] = s[ 1 ]; + } + } + + return attr; +} + +function split_meta_hash( meta_string ) { + var meta = meta_string.split( "" ), + parts = [ "" ], + in_quotes = false; + + while ( meta.length ) { + var letter = meta.shift(); + switch ( letter ) { + case " " : + // if we're in a quoted section, keep it + if ( in_quotes ) { + parts[ parts.length - 1 ] += letter; + } + // otherwise make a new part + else { + parts.push( "" ); + } + break; + case "'" : + case '"' : + // reverse the quotes and move straight on + in_quotes = !in_quotes; + break; + case "\\" : + // shift off the next letter to be used straight away. + // it was escaped so we'll keep it whatever it is + letter = meta.shift(); + default : + parts[ parts.length - 1 ] += letter; + break; + } + } + + return parts; +} + +/** + * renderJsonML( jsonml[, options] ) -> String + * - jsonml (Array): JsonML array to render to XML + * - options (Object): options + * + * Converts the given JsonML into well-formed XML. + * + * The options currently understood are: + * + * - root (Boolean): wether or not the root node should be included in the + * output, or just its children. The default `false` is to not include the + * root itself. + */ +expose.renderJsonML = function( jsonml, options ) { + options = options || {}; + // include the root element in the rendered output? + options.root = options.root || false; + + var content = []; + + if ( options.root ) { + content.push( render_tree( jsonml ) ); + } + else { + jsonml.shift(); // get rid of the tag + if ( jsonml.length && typeof jsonml[ 0 ] === "object" && !( jsonml[ 0 ] instanceof Array ) ) { + jsonml.shift(); // get rid of the attributes + } + + while ( jsonml.length ) { + content.push( render_tree( jsonml.shift() ) ); + } + } + + return content.join( "\n\n" ); +} + +function render_tree( jsonml ) { + // basic case + if ( typeof jsonml === "string" ) { + return jsonml.replace( /&/g, "&" ) + .replace( //g, ">" ); + } + + var tag = jsonml.shift(), + attributes = {}, + content = []; + + if ( jsonml.length && typeof jsonml[ 0 ] === "object" && !( jsonml[ 0 ] instanceof Array ) ) { + attributes = jsonml.shift(); + } + + while ( jsonml.length ) { + content.push( arguments.callee( jsonml.shift() ) ); + } + + var tag_attrs = ""; + for ( var a in attributes ) { + tag_attrs += " " + a + '="' + attributes[ a ] + '"'; + } + + // be careful about adding whitespace here for inline elements + return "<"+ tag + tag_attrs + ">" + content.join( "" ) + ""; +} + +function convert_tree_to_html( tree, references ) { + // shallow clone + var jsonml = tree.slice( 0 ); + + // Clone attributes if the exist + var attrs = extract_attr( jsonml ); + if ( attrs ) { + jsonml[ 1 ] = {}; + for ( var i in attrs ) { + jsonml[ 1 ][ i ] = attrs[ i ]; + } + attrs = jsonml[ 1 ]; + } + + // basic case + if ( typeof jsonml === "string" ) { + return jsonml; + } + + // convert this node + switch ( jsonml[ 0 ] ) { + case "header": + jsonml[ 0 ] = "h" + jsonml[ 1 ].level; + delete jsonml[ 1 ].level; + break; + case "bulletlist": + jsonml[ 0 ] = "ul"; + break; + case "numberlist": + jsonml[ 0 ] = "ol"; + break; + case "listitem": + jsonml[ 0 ] = "li"; + break; + case "para": + jsonml[ 0 ] = "p"; + break; + case "markdown": + jsonml[ 0 ] = "html"; + if ( attrs ) delete attrs.references; + break; + case "code_block": + jsonml[ 0 ] = "pre"; + var i = attrs ? 2 : 1; + var code = [ "code" ]; + code.push.apply( code, jsonml.splice( i ) ); + jsonml[ i ] = code; + break; + case "inlinecode": + jsonml[ 0 ] = "code"; + break; + case "img": + jsonml[ 1 ].src = jsonml[ 1 ].href; + delete jsonml[ 1 ].href; + break; + case "linebreak": + jsonml[0] = "br"; + break; + case "link": + jsonml[ 0 ] = "a"; + break; + case "link_ref": + jsonml[ 0 ] = "a"; + + // grab this ref and clean up the attribute node + var ref = references[ attrs.ref ]; + + // if the reference exists, make the link + if ( ref ) { + delete attrs.ref; + + // add in the href and title, if present + attrs.href = ref.href; + if ( ref.title ) { + attrs.title = ref.title; + } + + // get rid of the unneeded original text + delete attrs.original; + } + // the reference doesn't exist, so revert to plain text + else { + return attrs.original; + } + break; + } + + // convert all the children + var i = 1; + + // deal with the attribute node, if it exists + if ( attrs ) { + // if there are keys, skip over it + for ( var key in jsonml[ 1 ] ) { + i = 2; + } + // if there aren't, remove it + if ( i === 1 ) { + jsonml.splice( i, 1 ); + } + } + + for ( ; i < jsonml.length; ++i ) { + jsonml[ i ] = arguments.callee( jsonml[ i ], references ); + } + + return jsonml; +} + + +// merges adjacent text nodes into a single node +function merge_text_nodes( jsonml ) { + // skip the tag name and attribute hash + var i = extract_attr( jsonml ) ? 2 : 1; + + while ( i < jsonml.length ) { + // if it's a string check the next item too + if ( typeof jsonml[ i ] === "string" ) { + if ( i + 1 < jsonml.length && typeof jsonml[ i + 1 ] === "string" ) { + // merge the second string into the first and remove it + jsonml[ i ] += jsonml.splice( i + 1, 1 )[ 0 ]; + } + else { + ++i; + } + } + // if it's not a string recurse + else { + arguments.callee( jsonml[ i ] ); + ++i; + } + } +} + +} )( (function() { + if ( typeof exports === "undefined" ) { + window.markdown = {}; + return window.markdown; + } + else { + return exports; + } +} )() ); diff --git a/modules/jsdoc/doclet.js b/modules/jsdoc/doclet.js index b4ebbf11..9acfcd95 100644 --- a/modules/jsdoc/doclet.js +++ b/modules/jsdoc/doclet.js @@ -6,8 +6,12 @@ @license Apache License 2.0 - See file 'LICENSE.md' in this project. */ (function() { - var Tag = require('jsdoc/tag').Tag, - tagDictionary = require('jsdoc/tag/dictionary'); + var jsdoc = { + tag: { + Tag: require('jsdoc/tag').Tag, + dictionary: require('jsdoc/tag/dictionary') + } + }; /** @constructor @@ -27,13 +31,11 @@ for (var i = 0, leni = newTags.length; i < leni; i++) { this.addTag(newTags[i].title, newTags[i].text); } - - this.applyTags(this.tags); } exports.Doclet.prototype.addTag = function(title, text) { - var tagDef = tagDictionary.lookUp(title), - newTag = new Tag(title, text, {}); + var tagDef = jsdoc.tag.dictionary.lookUp(title), + newTag = new jsdoc.tag.Tag(title, text, {}); if (tagDef.onTagged) { if (tagDef.onTagged(this, newTag) !== false) { // onTagged handler prevents tag being added bt returning false @@ -43,26 +45,22 @@ else { this.tags.push(newTag); } + + applyTag.call(this, newTag); } - exports.Doclet.prototype.applyTags = function(tags) { - var tag; - - for (var i = 0, leni = tags.length; i < leni; i++) { - tag = tags[i]; - - if (tag.title === 'name') { - this.name = tag.value; - } - - if (tag.title === 'kind') { - this.kind = tag.value; - } - - if (tag.title === 'description') { - this.description = tag.value; - } - } + function applyTag(tag) { + if (tag.title === 'name') { + this.name = tag.value; + } + + if (tag.title === 'kind') { + this.kind = tag.value; + } + + if (tag.title === 'description') { + this.description = tag.value; + } } /** @@ -75,7 +73,6 @@ docletSrc = unwrap(docletSrc); tagSrcs = split(docletSrc); -//dump('tagSrcs', tagSrcs); for each(tagSrc in tagSrcs) { tags.push( {title: tagSrc.title, text: tagSrc.text} ); diff --git a/modules/jsdoc/opts/parser.js b/modules/jsdoc/opts/parser.js index 982f7f9d..cdaf121f 100644 --- a/modules/jsdoc/opts/parser.js +++ b/modules/jsdoc/opts/parser.js @@ -13,7 +13,7 @@ ourOptions, defaults = { template: 'default', - destination: 'jsdoc.xml' + destination: 'console' }; argsParser.addOption('t', 'template', true, 'The name of the template to use. Default: the "default" template'); diff --git a/modules/jsdoc/src/handlers.js b/modules/jsdoc/src/handlers.js new file mode 100644 index 00000000..0388a928 --- /dev/null +++ b/modules/jsdoc/src/handlers.js @@ -0,0 +1,17 @@ +(function() { + var Doclet = require('jsdoc/doclet').Doclet; + + app.jsdoc.parser.on('jsdocCommentFound', function(e) { + var newDoclet = new Doclet(e.comment, e.node, e.filename); + + if (newDoclet) { + e = { doclet: newDoclet }; + this.fire('newDoclet', e); + + if (!e.defaultPrevented) { + this.addResult(newDoclet); + } + } + }); + +})(); \ No newline at end of file diff --git a/modules/jsdoc/src/parser.js b/modules/jsdoc/src/parser.js index 25cac524..d2d5d1a6 100644 --- a/modules/jsdoc/src/parser.js +++ b/modules/jsdoc/src/parser.js @@ -1,307 +1,356 @@ /** - * @module jsdoc/src/parser + @module jsdoc/src/parser + @requires module:common/events + @requires module:jsdoc/doclet */ (function() { - var Token = Packages.org.mozilla.javascript.Token, - Doclet = require('jsdoc/doclet').Doclet, - _parseResult = []; - - exports.result = function() { - return _parseResult; - } - - /** - */ - function visitNode(node) { - var commentSrc = '', - thisDoclet = null, - thisDocletName = '', - thisDocletPath = ''; - - // look for all comments that have names provided - if (node.type === Token.SCRIPT && node.comments) { - for each(var comment in node.comments.toArray()) { - if (comment.commentType === Token.CommentType.JSDOC) { - commentSrc = '' + comment.toSource(); - - if (commentSrc) { - thisDoclet = new Doclet(commentSrc, node, currentSourceName); - - if (thisDoclet) { - _parseResult.push(thisDoclet); - } - -// if ( thisDoclet.hasTag('name') && thisDoclet.hasTag('kind') ) { -// jsdoc.doclets.addDoclet(thisDoclet); -// if (thisDoclet.tagValue('kind') === 'module') { -// jsdoc.name.setCurrentModule( thisDoclet.tagValue('path') ); -// } -// } - } - } - } - } - - // use the nocode option to shortcut all the following blah blah - if (env.opts.nocode) { return true; } -// -// // like function foo() {} -// if (node.type == Token.FUNCTION && String(node.name) !== '') { -// commentSrc = (node.jsDoc)? String(node.jsDoc) : ''; -// -// if (commentSrc) { -// thisDoclet = jsdoc.doclet.makeDoclet(commentSrc, node, currentSourceName); -// thisDocletName = thisDoclet.tagValue('name'); -// -// if (!thisDoclet.hasTag('kind')) { // guess kind from the source code -// thisDoclet.addTag('kind', 'method') -// } -// -// if (!thisDocletName) { // guess name from the source code -// nodeName = jsdoc.name.resolveInner(node.name, node, thisDoclet); -// thisDoclet.setName(nodeName); -// jsdoc.doclets.addDoclet(thisDoclet); -// } -// jsdoc.name.refs.push([node, thisDoclet]); -// } -// else { // an uncommented function? -// // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list -// thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', node, currentSourceName); -// -// nodeName = jsdoc.name.resolvePath(node.name, node, thisDoclet); -// thisDoclet.setName(nodeName); -// jsdoc.name.refs.push([ -// node, -// thisDoclet -// ]); -// } -// -// return true; -// } -// -// // like foo = function(){} or foo: function(){} -// if (node.type === Token.ASSIGN || node.type === Token.COLON) { -// -// var nodeName = nodeToString(node.left), -// nodeKind = ''; -// commentSrc = node.jsDoc || node.left.jsDoc; -// -// if (commentSrc) { -// commentSrc = '' + commentSrc; -// -// thisDoclet = jsdoc.doclet.makeDoclet(commentSrc, node, currentSourceName); -// thisDocletName = thisDoclet.tagValue('name'); -// nodeKind = thisDoclet.tagValue('kind'); -// -// if (!thisDoclet.hasTag('kind')) { // guess kind from the source code -// if (node.right.type == Token.FUNCTION) { // assume it's a method -// thisDoclet.addTag('kind', 'method'); -// } -// else { -// thisDoclet.addTag('kind', 'property'); -// } -// } -// -// if (!thisDocletName) { // guess name from the source code -// nodeName = jsdoc.name.resolvePath(nodeName, node, thisDoclet); -// -// thisDoclet.setName(nodeName); -// jsdoc.doclets.addDoclet(thisDoclet); -// } -// jsdoc.name.refs.push([node.right, thisDoclet]); -// } -// else { // an uncommented objlit or anonymous function? -// -// // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list -// -// thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', node, currentSourceName); -// nodeName = jsdoc.name.resolvePath(nodeName, node, thisDoclet); -// -// thisDoclet.setName(nodeName); -// jsdoc.name.refs.push([ -// node.right, -// thisDoclet -// ]); -// } -// return true; -// } -// -// // like var foo = function(){} or var bar = {} -// if (node.type == Token.VAR || node.type == Token.LET || node.type == Token.CONST) { -// var counter = 0, -// nodeKind; -// -// if (node.variables) for each (var n in node.variables.toArray()) { -// -// if (n.target.type === Token.NAME) { -// var val = n.initializer; -// -// commentSrc = (counter++ === 0 && !n.jsDoc)? node.jsDoc : n.jsDoc; -// if (commentSrc) { -// thisDoclet = jsdoc.doclet.makeDoclet('' + commentSrc, node, currentSourceName); -// thisDocletPath = thisDoclet.tagValue('path'); -// thisDocletName = thisDoclet.tagValue('name'); -// -// if (!thisDoclet.hasTag('kind') && val) { // guess kind from the source code -// if (val.type == Token.FUNCTION) { -// thisDoclet.addTag('kind', 'method'); -// } -// else { -// thisDoclet.addTag('kind', 'property'); -// } -// } -// -// if (!thisDocletName) { -// thisDocletName = n.target.string; -// if (!thisDocletPath) { // guess path from the source code -// thisDocletPath = jsdoc.name.resolveInner(thisDocletName, node, thisDoclet); -// thisDoclet.setName(thisDocletPath); -// } -// else { -// thisDoclet.setName(thisDocletName); -// } -// jsdoc.doclets.addDoclet(thisDoclet); -// } -// -// if (val) { jsdoc.name.refs.push([val, thisDoclet]); } -// } -// else { // an uncommented objlit or anonymous function? -// var nodeName = nodeToString(n.target); -// // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list -// thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', n.target, currentSourceName); -// -// nodeName = jsdoc.name.resolveInner(nodeName, n.target, thisDoclet); -// thisDoclet.setName(nodeName); -// -// if (val) jsdoc.name.refs.push([val, thisDoclet]); -// } -// } -// -// } -// return true; -// } -// - return true; - } - - var currentSourceName = ''; - - /** - */ - exports.parseSource = function(source, sourceName) { - currentSourceName = sourceName; - var ast = getParser().parse(source, sourceName, 1); - - ast.visit( - new Packages.org.mozilla.javascript.ast.NodeVisitor({ - visit: visitNode - }) - ); - - currentSourceName = ''; - - return _parseResult; - } - - /** - */ - exports.clear = function() { - _parseResult = []; - } - - /** - */ - exports.parse = function(sourceFiles, encoding) { - var ast = getParser(), - fs = require('common/fs'), - sourceCode = '', - filename = '', - jsUriScheme = 'javascript:'; - - if (arguments.length === 0) { - throw 'module:jsdoc/parser.parseFiles requires argument sourceFiles(none provided).'; - } - - if (typeof sourceFiles === 'string') { sourceFiles = [sourceFiles]; } - - for (i = 0, leni = sourceFiles.length; i < leni; i++) { - if (sourceFiles[i].indexOf(jsUriScheme) === 0) { - sourceCode = sourceFiles[i].substr(jsUriScheme.length); - filename = '[[string' + i + ']]'; - } - else { - filename = sourceFiles[i]; + var Token = Packages.org.mozilla.javascript.Token, + Doclet = require('jsdoc/doclet').Doclet, + currentParser = null, + currentSourceName = ''; + + /** + @constructor module:jsdoc/src/parser.Parser + @mixesIn module:common/events.EventEmitter + */ + var Parser = exports.Parser = function() { + this._resultBuffer = []; + } + require('common/events').mixin(exports.Parser.prototype); + + /** + @event jsdocCommentFound + @param e + @param {string} e.comment The raw text of the JSDoc comment that will be parsed. + This value may be modified in place by your event handler. + @param {string} e.file The name of the file containing the comment. + @defaultAction The comment text will be used to create a new Doclet. + Returning false from your handler will prevent this. + */ + + /** + @event newDoclet + @param e + @param {string} e.doclet The new doclet that will be added to the results. + The properties of this value may be modified in place by your event handler. + @defaultAction The new doclet will be added to the parsers result set. + Returning false from your handler will prevent this. + */ + + /** + @method module:jsdoc/src/parser.Parser#parse + @param {Array} sourceFiles + @param {string} [encoding=utf8] + @fires jsdocCommentFound + @fires newDoclet + */ + Parser.prototype.parse = function(sourceFiles, encoding) { + var sourceCode = '', + filename = '', + jsUriScheme = 'javascript:'; + + if (arguments.length === 0) { + throw 'module:jsdoc/parser.parseFiles requires argument sourceFiles(none provided).'; + } + + if (typeof sourceFiles === 'string') { sourceFiles = [sourceFiles]; } + + for (i = 0, leni = sourceFiles.length; i < leni; i++) { + if (sourceFiles[i].indexOf(jsUriScheme) === 0) { + sourceCode = sourceFiles[i].substr(jsUriScheme.length); + filename = '[[string' + i + ']]'; + } + else { + filename = sourceFiles[i]; try { - sourceCode = fs.read(filename, encoding); + sourceCode = require('common/fs').read(filename, encoding); } catch(e) { print('FILE READ ERROR: in module:jsdoc/parser.parseFiles: "' + filename + '" ' + e); continue; } - } - - exports.parseSource(sourceCode, filename); - } - - return _parseResult; - } - - /** - @private - @function getParser - */ - function getParser() { - var cx = Packages.org.mozilla.javascript.Context.getCurrentContext(); - - var ce = new Packages.org.mozilla.javascript.CompilerEnvirons(); - ce.setRecordingComments(true); - ce.setRecordingLocalJsDocComments(true); - ce.initFromContext(cx); - return new Packages.org.mozilla.javascript.Parser(ce, ce.getErrorReporter()); - } - - /** - @private - @function nodeToString - @param {org.mozilla.javascript.ast.AstNode} node - @returns {string} - */ - // credit: ringojs ninjas - function nodeToString(node) { - var str; - - if (node.type === Token.GETPROP) { - str = [nodeToString(node.target), node.property.string].join('.'); - } - else if (node.type === Token.NAME) { - str = node.string; - } - else if (node.type === Token.STRING) { - str = node.value; - } - else if (node.type === Token.THIS) { - str = 'this'; - } - else if (node.type === Token.GETELEM) { - str = node.toSource(); // like: Foo['Bar'] - } - else { - str = getTypeName(node); - } - - return '' + str; - }; - - /** - @private - @function getTypeName - @param {org.mozilla.javascript.ast.AstNode} node - @returns {string} - */ - // credit: ringojs ninjas - function getTypeName(node) { - return node ? ''+Packages.org.mozilla.javascript.Token.typeToName(node.getType()) : '' ; - } - + } + + currentParser = this; + parseSource(sourceCode, filename); + currentParser = null; + } + + return this._resultBuffer; + } + + /** + @method module:jsdoc/src/parser.Parser#results + @returns {Array} The accumulated results of any calls to parse. + */ + Parser.prototype.results = function() { + return this._resultBuffer; + } + + /** + @method module:jsdoc/src/parser.Parser#addResult + */ + Parser.prototype.addResult = function(o) { + this._resultBuffer.push(o); + } + + /** + @method module:jsdoc/src/parser.Parser#clearResults + @desc Empty any accumulated results of calls to parse. + */ + Parser.prototype.clearResults = function() { + this._resultBuffer = []; + } + + /** + @private + @function parseSource + */ + function parseSource(source, sourceName) { + currentSourceName = sourceName; + + var ast = parserFactory().parse(source, sourceName, 1); + + ast.visit( + new Packages.org.mozilla.javascript.ast.NodeVisitor({ + visit: visitNode + }) + ); + + currentSourceName = ''; + } + + /** + @private + @function visitNode + */ + function visitNode(node) { + var commentSrc = '', + thisDoclet = null;//, + //thisDocletName = '', + //thisDocletPath = ''; + + // look for all comments that have names provided + if (node.type === Token.SCRIPT && node.comments) { + for each(var comment in node.comments.toArray()) { + if (comment.commentType === Token.CommentType.JSDOC) { + if (commentSrc = '' + comment.toSource()) { + var e = { + comment: commentSrc, + filename: currentSourceName, + node: node + }; + currentParser.fire('jsdocCommentFound', e, currentParser); + +// if ( thisDoclet.hasTag('name') && thisDoclet.hasTag('kind') ) { +// jsdoc.doclets.addDoclet(thisDoclet); +// if (thisDoclet.tagValue('kind') === 'module') { +// jsdoc.name.setCurrentModule( thisDoclet.tagValue('path') ); +// } +// } + } + } + } + } + + // use the nocode option to shortcut all the following blah blah + if (env.opts.nocode) { return true; } +// +// // like function foo() {} +// if (node.type == Token.FUNCTION && String(node.name) !== '') { +// commentSrc = (node.jsDoc)? String(node.jsDoc) : ''; +// +// if (commentSrc) { +// thisDoclet = jsdoc.doclet.makeDoclet(commentSrc, node, currentSourceName); +// thisDocletName = thisDoclet.tagValue('name'); +// +// if (!thisDoclet.hasTag('kind')) { // guess kind from the source code +// thisDoclet.addTag('kind', 'method') +// } +// +// if (!thisDocletName) { // guess name from the source code +// nodeName = jsdoc.name.resolveInner(node.name, node, thisDoclet); +// thisDoclet.setName(nodeName); +// jsdoc.doclets.addDoclet(thisDoclet); +// } +// jsdoc.name.refs.push([node, thisDoclet]); +// } +// else { // an uncommented function? +// // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list +// thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', node, currentSourceName); +// +// nodeName = jsdoc.name.resolvePath(node.name, node, thisDoclet); +// thisDoclet.setName(nodeName); +// jsdoc.name.refs.push([ +// node, +// thisDoclet +// ]); +// } +// +// return true; +// } +// +// // like foo = function(){} or foo: function(){} +// if (node.type === Token.ASSIGN || node.type === Token.COLON) { +// +// var nodeName = nodeToString(node.left), +// nodeKind = ''; +// commentSrc = node.jsDoc || node.left.jsDoc; +// +// if (commentSrc) { +// commentSrc = '' + commentSrc; +// +// thisDoclet = jsdoc.doclet.makeDoclet(commentSrc, node, currentSourceName); +// thisDocletName = thisDoclet.tagValue('name'); +// nodeKind = thisDoclet.tagValue('kind'); +// +// if (!thisDoclet.hasTag('kind')) { // guess kind from the source code +// if (node.right.type == Token.FUNCTION) { // assume it's a method +// thisDoclet.addTag('kind', 'method'); +// } +// else { +// thisDoclet.addTag('kind', 'property'); +// } +// } +// +// if (!thisDocletName) { // guess name from the source code +// nodeName = jsdoc.name.resolvePath(nodeName, node, thisDoclet); +// +// thisDoclet.setName(nodeName); +// jsdoc.doclets.addDoclet(thisDoclet); +// } +// jsdoc.name.refs.push([node.right, thisDoclet]); +// } +// else { // an uncommented objlit or anonymous function? +// +// // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list +// +// thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', node, currentSourceName); +// nodeName = jsdoc.name.resolvePath(nodeName, node, thisDoclet); +// +// thisDoclet.setName(nodeName); +// jsdoc.name.refs.push([ +// node.right, +// thisDoclet +// ]); +// } +// return true; +// } +// +// // like var foo = function(){} or var bar = {} +// if (node.type == Token.VAR || node.type == Token.LET || node.type == Token.CONST) { +// var counter = 0, +// nodeKind; +// +// if (node.variables) for each (var n in node.variables.toArray()) { +// +// if (n.target.type === Token.NAME) { +// var val = n.initializer; +// +// commentSrc = (counter++ === 0 && !n.jsDoc)? node.jsDoc : n.jsDoc; +// if (commentSrc) { +// thisDoclet = jsdoc.doclet.makeDoclet('' + commentSrc, node, currentSourceName); +// thisDocletPath = thisDoclet.tagValue('path'); +// thisDocletName = thisDoclet.tagValue('name'); +// +// if (!thisDoclet.hasTag('kind') && val) { // guess kind from the source code +// if (val.type == Token.FUNCTION) { +// thisDoclet.addTag('kind', 'method'); +// } +// else { +// thisDoclet.addTag('kind', 'property'); +// } +// } +// +// if (!thisDocletName) { +// thisDocletName = n.target.string; +// if (!thisDocletPath) { // guess path from the source code +// thisDocletPath = jsdoc.name.resolveInner(thisDocletName, node, thisDoclet); +// thisDoclet.setName(thisDocletPath); +// } +// else { +// thisDoclet.setName(thisDocletName); +// } +// jsdoc.doclets.addDoclet(thisDoclet); +// } +// +// if (val) { jsdoc.name.refs.push([val, thisDoclet]); } +// } +// else { // an uncommented objlit or anonymous function? +// var nodeName = nodeToString(n.target); +// // this thing may have commented members, so keep a ref to the thing but don't add it to the doclets list +// thisDoclet = jsdoc.doclet.makeDoclet('[[undocumented]]', n.target, currentSourceName); +// +// nodeName = jsdoc.name.resolveInner(nodeName, n.target, thisDoclet); +// thisDoclet.setName(nodeName); +// +// if (val) jsdoc.name.refs.push([val, thisDoclet]); +// } +// } +// +// } +// return true; +// } +// + return true; + } + + /** + @private + @function parserFactory + */ + function parserFactory() { + var cx = Packages.org.mozilla.javascript.Context.getCurrentContext(); + + var ce = new Packages.org.mozilla.javascript.CompilerEnvirons(); + ce.setRecordingComments(true); + ce.setRecordingLocalJsDocComments(true); + ce.initFromContext(cx); + return new Packages.org.mozilla.javascript.Parser(ce, ce.getErrorReporter()); + } + + /** + @private + @function nodeToString + @param {org.mozilla.javascript.ast.AstNode} node + @returns {string} + */ + // credit: ringojs ninjas + function nodeToString(node) { + var str; + + if (node.type === Token.GETPROP) { + str = [nodeToString(node.target), node.property.string].join('.'); + } + else if (node.type === Token.NAME) { + str = node.string; + } + else if (node.type === Token.STRING) { + str = node.value; + } + else if (node.type === Token.THIS) { + str = 'this'; + } + else if (node.type === Token.GETELEM) { + str = node.toSource(); // like: Foo['Bar'] + } + else { + str = getTypeName(node); + } + + return '' + str; + }; + + /** + @private + @function getTypeName + @param {org.mozilla.javascript.ast.AstNode} node + @returns {string} + */ + // credit: ringojs ninjas + function getTypeName(node) { + return node ? ''+Packages.org.mozilla.javascript.Token.typeToName(node.getType()) : '' ; + } + })(); \ No newline at end of file diff --git a/modules/jsdoc/src/scanner.js b/modules/jsdoc/src/scanner.js index 74e222e2..ac5c1b81 100644 --- a/modules/jsdoc/src/scanner.js +++ b/modules/jsdoc/src/scanner.js @@ -11,13 +11,22 @@ fs: require('common/fs') }; + /** + @constructor + */ + exports.Scanner = function() { + } + require('common/events').mixin(exports.Scanner.prototype); + /** Recursively searches the given searchPaths for js files. @param {Array.} searchPaths @param {number} [depth=1] + @fires sourceFileFound */ - exports.scan = function(searchPaths, depth) { - var filePaths = []; + exports.Scanner.prototype.scan = function(searchPaths, depth) { + var filePaths = [], + that = this; searchPaths = searchPaths || []; depth = depth || 1; @@ -26,9 +35,11 @@ filePaths = filePaths.concat(common.fs.ls($, depth)); }); - // TODO: allow user-defined filtering of files filePaths = filePaths.filter(function($) { - return /.+\.js(doc)?$/i.test($); + var e = { fileName: $ }; + that.fire('sourceFileFound', e); + + return !e.defaultPrevented; }); return filePaths; diff --git a/modules/jsdoc/tag.js b/modules/jsdoc/tag.js index 5c422828..f9a4ef1e 100644 --- a/modules/jsdoc/tag.js +++ b/modules/jsdoc/tag.js @@ -9,19 +9,23 @@ */ (function() { - var dictionary = require('jsdoc/tag/dictionary'), - validator = require('jsdoc/tag/validator'), - tagType = require('jsdoc/tag/type'); + var jsdoc = { + tag: { + dictionary: require('jsdoc/tag/dictionary'), + validator: require('jsdoc/tag/validator'), + type: require('jsdoc/tag/type') + } + }; /** @constructor Tag */ exports.Tag = function(tagTitle, tagBody, meta) { - var tagDef = dictionary.lookUp(tagTitle), + var tagDef = jsdoc.tag.dictionary.lookUp(tagTitle), meta = meta || {}; - this.title = dictionary.normalise( trim(tagTitle) ); - this.text = trim(tagBody, tagDef.preservesWhitespace); + this.title = jsdoc.tag.dictionary.normalise( trim(tagTitle) ); + this.text = trim(tagBody, tagDef.keepsWhitespace); if (this.text) { if (tagDef.canHaveType) { @@ -33,9 +37,7 @@ /*?boolean*/ optional, /*?boolean*/ nullable, /*?boolean*/ variable - ] = tagType.parse(this.text); - - + ] = jsdoc.tag.type.parse(this.text); if (typeNames.length) { this.value.type = { @@ -45,6 +47,7 @@ variable: variable }; } + if (remainingText) { if (tagDef.canHaveName) { var [tagName, tagDesc, tagOptional, tagDefault] = parseTagText(remainingText); @@ -64,7 +67,7 @@ } } - validator.validate(this, meta); + jsdoc.tag.validator.validate(this, meta); } function trim(text, newlines) { diff --git a/modules/jsdoc/tag/dictionary/definitions.js b/modules/jsdoc/tag/dictionary/definitions.js index 84d04e49..4934c21b 100644 --- a/modules/jsdoc/tag/dictionary/definitions.js +++ b/modules/jsdoc/tag/dictionary/definitions.js @@ -38,7 +38,7 @@ }); dictionary.defineTag('example', { - preservesWhitespace: true, + keepsWhitespace: true, mustHaveValue: true }); diff --git a/modules/jsdoc/tag/validator.js b/modules/jsdoc/tag/validator.js index cd248a34..1963f85c 100644 --- a/modules/jsdoc/tag/validator.js +++ b/modules/jsdoc/tag/validator.js @@ -15,7 +15,7 @@ exports.validate = function(tag, meta) { var tagDef = dictionary.lookUp(tag.title); - if (!tagDef && !env.conf.permitUnknownTags) { + if (!tagDef && !env.conf.tags.allowUnknownTags) { throw new UnknownTagError(tag.title, meta); } diff --git a/modules/normal/template.js b/modules/normal/template.js deleted file mode 100644 index 667e8762..00000000 --- a/modules/normal/template.js +++ /dev/null @@ -1,199 +0,0 @@ -/** - * Normal Template - */ - -var TOKEN_RE = new RegExp("(\{[\=\:\#\/].+?\})"), - COMMAND_RE = new RegExp("^\{[\:\/\=]"); - -var xpath = function (path) { - if (path === '$last') { - return "$last"; - } - - if (/\||;|\$|~/.test(path)) { - throw new Error("Invalid characters in path '" + path + "'"); - } - - path = path.replace(/\//g, ".").replace(/'|"/, ""); - - if (path == ".") { - return "d"; - } else if (/^\./.test(path)) { - return "data" + path; - } else { - return "d." + path; - } -} - -/** - * Template filters. Add your own to this dictionary. - */ -exports.filters = { - str: function (val) { // used to override default filtering. - return val.toString(); - }, - strip: function (val) { - return val.toString().replace(/<([^>]+)>/g, ""); - }, - html: function (val) { - return val.toString().replace(/&/g, "&").replace(/>/g, ">"). - replace(//g, ">"). - replace(/ 0)) '); - stack.unshift("a" + depth + "[i" + depth + "]"); - code.push('for (var i' + depth + ' = 0,l' + depth + ' = a' + depth + '.length; i' + depth + ' < l' + depth + '; i' + depth + '++) {$last = (i' + depth + ' == l' + depth + '-1); d = a' + depth + '[i' + depth + '];'); - continue; - - case "else": - case "e": - tag = nesting.pop(); - if (tag) { - code.push('} else {'); - nesting.push(tag); - } else { - throw new Error("Unbalanced 'else' tag"); - } - continue; - - case "lb": // output left curly bracket '{' - code.push('res.push("{");'); - continue; - - case "rb": // output right curly bracket '}' - code.push('res.push("}");'); - continue; - - case "!": // comment - continue; - } - } else if (token[1] == "/") { // close tag - if (token[2] == ":") { - var cmd = token.substring(3, token.length-1).split(" ")[0]; - - switch (cmd) { - case "if": - tag = nesting.pop(); - if (tag == "if") { - code.push('};'); - } else { - throw new Error("Unbalanced 'if' close tag" + (tag ? ", expecting '" + tag + "' close tag" : "")); - } - continue; - - case "select": - case "s": - tag = nesting.pop(); - if (tag == "select") { - stack.shift(); - code.push('};d = ' + stack[0] + ';'); - } else { - throw new Error("Unbalanced 'select' close tag" + (tag ? ", expecting '" + tag + "' close tag" : "")); - } - continue; - - case "reduce": - case "r": - tag = nesting.pop(); - if (tag == "reduce") { - stack.shift(); - code.push('}; $last = false; d = ' + stack[0] + ';'); - } else { - throw new Error("Unbalanced 'reduce' close tag" + (tag ? ", expecting '" + tag + "' close tag" : "")); - } - continue; - } - } - } else if (token[1] == "=") { // interpolation - var parts = token.substring(2, token.length-1).split(" "), - pre = "", post = ""; - for (var j = 0; j < parts.length-1; j++) { - pre += "filters." + parts[j] + "("; post += ")"; - } - if (pre == "") { - if (filters.defaultfilter) { - pre = "df("; post = ")"; - } - } - code.push('v = ' + xpath(parts[j]) + ';if (v != undefined) res.push(' + pre + 'v' + post +');'); - continue; - } - } - - // plain text - code.push('res.push("' + token.replace(/\\/g, "\\\\").replace(/\r/g, "").replace(/\n/g, "\\n").replace(/"/g, '\\"') + '");'); - } - - tag = nesting.pop(); - if (tag) { - throw new Error("Unbalanced '" + tag + "' tag, is not closed"); - } - - code.push('return res.join("");'); - - var func = new Function("data", "filters", code.join("")); - - return function (data) { return func(data, filters) }; -} \ No newline at end of file diff --git a/package.json b/package.json index 261111ec..123fdb05 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { - "name": "jsdoc-3", - "version": "0.0.0", - "revision": "2010-07-28-0024", + "name": "jsdoc", + "version": "3.0.0alpha1", + "revision": "2010-12-27-1223", "description": "An automatic documentation generator for javascript", "keywords": [ "documentation", "javascript" ], "licenses": [ @@ -16,7 +16,6 @@ "url": "http://github.com/micmath/JSDoc" } ], - "bugs": "http://jsdoc.lighthouseapp.com/", "maintainers": [ { "name": "Michael Mathews", diff --git a/plugins/markdown.js b/plugins/markdown.js new file mode 100644 index 00000000..8901987c --- /dev/null +++ b/plugins/markdown.js @@ -0,0 +1,15 @@ +/** + @overview Translate doclet descriptions from MarkDown into HTML. + */ + +(function() { + + var markdown = require('evilstreak/markdown'); + + app.jsdoc.parser.on('newDoclet', function(e) { + if (e.doclet.description) { + e.doclet.description = markdown.toHTML(e.doclet.description); + } + }); + +})(); \ No newline at end of file diff --git a/templates/default/publish.js b/templates/default/publish.js index 494620ba..0ba21a8e 100644 --- a/templates/default/publish.js +++ b/templates/default/publish.js @@ -4,25 +4,40 @@ publish = function(docs, opts) { var out = '', - template = readFile(BASEDIR + 'templates/default/tmpl/index.html'); + templates = { + index: readFile(BASEDIR + 'templates/default/tmpl/index.html') + }; - var summarize = function () { + function summarize () { return function(text, render) { - text = render(text); - /^(.*?(\.|\n|\r|$))/.test(text); - return RegExp.$1; + var summary = trim(text); + + summary = render(text); + summary = summary.replace(/<\/?p>/gi, ''); // text may be HTML + + /^(.*?(\.$|\.\s|\n|\r|$|
    ))/.test(summary); + return RegExp.$1? RegExp.$1 : summary; } }; + + function trim(text) { + return text.replace(/^\s+|\s+$/g, ''); + } out = Mustache.to_html( - template, + templates.index, { docs: docs, summarize: summarize } ); - - print(out); + + if (opts.destination === 'console') { + print(out); + } + else { + print('The only -d destination option currently supported is "console"!'); + } } })(); \ No newline at end of file diff --git a/templates/default/tmpl/index.html b/templates/default/tmpl/index.html index c88a2d67..de8d78b7 100644 --- a/templates/default/tmpl/index.html +++ b/templates/default/tmpl/index.html @@ -12,7 +12,7 @@
      {{#docs}}
    • - {{kind}} {{name}}{{#description}} - {{#summarize}}{{description}}{{/summarize}}{{/description}} + {{kind}} {{name}}{{#description}} - {{#summarize}}{{{description}}}{{/summarize}}{{/description}}
      • {{/docs}}
    diff --git a/test/runall.js b/test/runner.js similarity index 100% rename from test/runall.js rename to test/runner.js diff --git a/test/t/jsdoc/src/parser.js b/test/t/jsdoc/src/parser.js index 18d9862e..184c8c6b 100644 --- a/test/t/jsdoc/src/parser.js +++ b/test/t/jsdoc/src/parser.js @@ -3,73 +3,31 @@ var src = { parser: require('jsdoc/src/parser')}; test('There is a src/parser module.', function() { - assert.notEqual(typeof src, 'undefined', 'The src/parser module should be defined.'); assert.equal(typeof src, 'object', 'The src/parser module should be an object.'); }); - test('The src/parser module has a "parse" function.', function() { - assert.notEqual(typeof src.parser.parse, 'undefined', 'The src.parser.parse method should be defined.'); - assert.equal(typeof src.parser.parse, 'function', 'The src.parser.parse method should be a function.'); + test('The src/parser module has a "Parser" constructor.', function() { + assert.equal(typeof src.parser.Parser, 'function', 'The src.parser.Parser member should be a function.'); }); - test('The src/parser module has a "parseSource" function.', function() { - assert.notEqual(typeof src.parser.parseSource, 'undefined', 'The src.parser.parseSource method should be defined.'); - assert.equal(typeof src.parser.parseSource, 'function', 'The src.parser.parseSource method should be a function.'); + test('The src/parser module has a "Parser#parse" function.', function() { + assert.equal(typeof src.parser.Parser.prototype.parse, 'function', 'The src.parser.Parser#parse member should be a function.'); }); - test('The src/parser module has a "result" function.', function() { - assert.notEqual(typeof src.parser.result, 'undefined', 'The src.parser.result method should be defined.'); - assert.equal(typeof src.parser.result, 'function', 'The src.parser.result method should be a function.'); + test('The src/parser module has a "results" function.', function() { + assert.equal(typeof src.parser.Parser.prototype.results, 'function', 'The src.parser.Parser#results member should be a function.'); }); - test('The src/parser module has a "clear" function.', function() { - assert.notEqual(typeof src.parser.clear, 'undefined', 'The src.parser.clear method should be defined.'); - assert.equal(typeof src.parser.clear, 'function', 'The src.parser.clear method should be a function.'); - }); - - test('The src/parser.result function can return the result array.', function() { - var docs = src.parser.result; - - assert.notEqual(typeof docs, 'undefined', 'The src.parser.result method should return a result.'); - assert.equal(docs.length, 0, 'The src.parser.result method should return an array of 0 results if there has been nothing parsed yet.'); - }); - - test('The src/parser.parseSource function can parse js source code containing a jsdoc comment.', function() { - var sourceCode = '/** @name foo */'; + test('The src/parser.Parser#parse function fires jsdocCommentFound events when parsing source code containing a jsdoc comment.', function() { + var sourceCode = 'javascript:/** @name bar */', + jsdocCounter = 0; + + (new src.parser.Parser()) + .on('jsdocCommentFound', function(e) { + jsdocCounter++; + }) + .parse(sourceCode); - var docs = src.parser.parseSource(sourceCode, '/bar/foo.js'); - - assert.notEqual(typeof docs, 'undefined', 'The src.parser.parseSource method should return a result.'); - assert.equal(docs.length, 1, 'The src.parser.parseSource method should return an array of 1 result if there is 1 jsdoc comment.'); - assert.notEqual(typeof docs[0].tags, 'undefined', 'The result array returned by src.parser.parseSource should be a collection of Doclets with Tags.'); - }); - - test('The src/parser.clear function can empty the result array.', function() { - src.parser.clear(); - var docs = src.parser.result; - - assert.equal(docs.length, 0, 'The src.parser.result method should return an array of 0 results if clear was called.'); - }); - - test('The src/parser.parse function can parse js source code containing a doc comment.', function() { - var sourceCode = 'javascript:/** @name bar */'; - - src.parser.clear(); - var docs = src.parser.parse([sourceCode]); - - assert.notEqual(typeof docs, 'undefined', 'The src.parser.parse method should return a result.'); - assert.equal(docs.length, 1, 'The src.parser.parse method should return an array of 1 result if there is 1 jsdoc comment.'); - assert.notEqual(typeof docs[0].tags, 'undefined', 'The result array returned by src.parser.parse should be a collection of Doclets with Tags.'); - }); - - test('The src/parser.parse function can cope with source code containing no jsdoc comments.', function() { - var sourceCode = 'javascript:var blah;'; - - src.parser.clear(); - var docs = src.parser.parse([sourceCode]); - - assert.notEqual(typeof docs, 'undefined', 'The src.parser.parse method should return a result.'); - assert.equal(docs.length, 0, 'The src.parser.parse method should return an array of 0 Doclets if there are no jsdocc omments.'); - }); - + assert.equal(jsdocCounter, 1, 'The Parser#parse method should fire jsdocCommentFound once if there is 1 jsdoc comment.'); + }); })(); \ No newline at end of file