Merge branch 'develop'

Conflicts:
	LICENSE
	README.md

.gitignore

@@ -2,6 +2,7 @@
 coverage/
 docs/
 node_modules/
+test/actual/
 
 *.log
 .*.swp

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Shannon Moeller
+Copyright (c) 2014 Shannon Moeller <me@shannonmoeller.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -19,55 +19,56 @@ Documentation blocks follow the conventions of other standard tools such as JSDo
 ## AST
 
 - Root
-  - `type` _`String`_ - Always "Document".
-  - `blocks` _`Array.<Code|Comment>`_
+  - `type` `{String}` - Always `"Document"`.
+  - `blocks` `{Array.<Code|Comment>}`
 - Code
-  - `type` _`String`_ - Always "Code".
-  - `body` _`String`_
+  - `type` `{String}` - Always `"Code"`.
+  - `body` `{String}`
 - Comment
-  - `type` _`String`_ - Always "Comment".
-  - `description` _`String`_
-  - `tags` _`Array.<Tag>`_
+  - `type` `{String}` - Always `"Comment"`.
+  - `description` `{String}`
+  - `tags` `{Array.<Tag>}`
 - Tag
-  - `tag` _`String`_
-  - `type` _`String`_
-  - `name` _`String`_
-  - `description` _`String`_
+  - `tag` `{String}`
+  - `type` `{String}`
+  - `name` `{String}`
+  - `description` `{String}`
 
 ## API
 
 ### `new Tunic([options])`
 
-- `options` `Object` Optional grammar overrides.
-  - `extension` _`RegExp`_ - Matches the file extension or extensions which are handled by this parser.
-  - `blockIndent` _`RegExp`_ - Matches any leading characters that are valid as DocBlock indentation, such as whitespace or asterisks. Used for normalization.
-  - `blockParse` _`RegExp`_ - Matches the content of a DocBlock, where the first capturing group is the content without the start and end comment characters. Used for normalization.
-  - `blockSplit` _`RegExp`_ - Splits code and docblocks into alternating chunks.
-  - `tagParse` _`RegExp`_ - Matches the various parts of a tag where parts are captured in the following order:
+- `options` `{Object}` - Optional grammar overrides.
+  - `options.property` `{RegExp}` - Name of property that the AST should be assigned to on Vinyl files. _Default: `"ast"`._
+  - `options.extension` `{RegExp}` - Matches the file extension or extensions which are handled by this parser.
+  - `options.blockIndent` `{RegExp}` - Matches any leading characters that are valid as DocBlock indentation, such as whitespace or asterisks. Used for normalization.
+  - `options.blockParse` `{RegExp}` - Matches the content of a DocBlock, where the first capturing group is the content without the start and end comment characters. Used for normalization.
+  - `options.blockSplit` `{RegExp}` - Splits code and docblocks into alternating chunks.
+  - `options.tagParse` `{RegExp}` - Matches the various parts of a tag where parts are captured in the following order:
     - 1: `tag`
     - 2: `type`
     - 3: `name`
     - 4: `description`
-  - `tagSplit` _`RegExp`_ - Matches characters used to split description and tags from each other.
-  - `namedTags` _`Array.<String>`_ - Which tags should be considered "named" tags. Non-named tags will have their name prepended to the description and set to `undefined`.
-  - `namespaceSplit` _`RexExp`_ - Splits namespaces.
-  - `namespaceTags` _`Object.<String,RegExp>`_ - Which tags should be used to generate navigation trees, and how to split them (eg. `/\b\.\b/` for `.`, or `/\b::\b/` for `::`). The word boundaries (`\b`) are important as it allows splitters to be escaped.
+  - `options.tagSplit` `{RegExp}` - Matches characters used to split description and tags from each other.
+  - `options.namedTags` `{Array.<String>}` - Which tags should be considered "named" tags. Non-named tags will have their name prepended to the description and set to `undefined`.
 
 Creates a reusable parser based on the given options. Defaults to parsing C-style comment blocks.
 
-#### `tunic([options]) : Tunic`
+### `tunic([options]) : Tunic`
 
-Functional shorthand, if that's how you operate.
+Functional shorthand of the constructor, if that's how you operate.
 
-### `.parse(block) : AST`
+### `#parse(block) : AST`
 
-- `block` `String` Block of code containing comments to parse.
+- `block` `{String}` - Block of code containing comments to parse.
 
 Generates a sensible syntax tree format of doc-blocks and surrounding code.
 
-### Stream
+### `#pipe(stream) : Stream`
 
-Tunic is a [Transform Stream](http://nodejs.org/api/stream.html#stream_class_stream_transform), working in object mode, compatible with `String`, `Buffer`, and [Vinyl](https://github.com/wearefractal/vinyl). Strings and buffers are parsed and the resulting AST is emitted as data. Vinyl objects are augmented with the AST stored as the `.tunic` property.
+- `stream` `{Readable}` - Readable stream.
+
+Tunic is a [Transform Stream](http://nodejs.org/api/stream.html#stream_class_stream_transform), working in object mode, compatible with `String`, `Buffer`, and [Vinyl](https://github.com/wearefractal/vinyl). Strings and buffers are parsed and the resulting AST is emitted as data. Vinyl objects are augmented with the AST stored as the `.ast` property.
 
 ## Example
 
@@ -99,11 +100,12 @@ Tunic is a [Transform Stream](http://nodejs.org/api/stream.html#stream_class_str
 
 ### Streams
 
-    var gulp = require('gulp'),
+    var toga = require('toga'),
         tunic = require('tunic');
 
-    gulp.src('./lib/**/*.js')
-        .pipe(tunic()); // adds `.tunic` property to `file` object
+    toga.src('./lib/**/*.js')
+        .pipe(tunic()) // generates and adds `.ast` property to `file` object
+        .pipe(toga.dest('./docs'));
 
 ## Test
 
@@ -115,9 +117,11 @@ Tunic is a [Transform Stream](http://nodejs.org/api/stream.html#stream_class_str
 
 Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.
 
-## License
+----
+
+© 2014 Shannon Moeller <me@shannonmoeller.com>
 
-MIT
+Licensed under [MIT](http://shannonmoeller.com/mit.txt)
 
 [coveralls-img]: http://img.shields.io/coveralls/togajs/tunic/master.svg?style=flat-square
 [coveralls-url]: https://coveralls.io/r/togajs/tunic

gulpfile.js

@@ -4,10 +4,10 @@ var gulp = require('gulp'),
 	paths = {
 		gulp: 'gulpfile.js',
 		src: 'index.js',
-		test: 'test/**/*.spec.js'
+		test: 'test/**/*.{e2e,spec}.js'
 	};
 
-gulp.task('default', ['lint', 'test']);
+gulp.task('default', ['test']);
 
 gulp.task('lint', function () {
 	var jscs = require('gulp-jscs'),
@@ -28,7 +28,7 @@ gulp.task('cover', function () {
 		.pipe(istanbul());
 });
 
-gulp.task('test', ['cover'], function () {
+gulp.task('test', ['lint', 'cover'], function () {
 	var istanbul = require('gulp-istanbul'),
 		mocha = require('gulp-mocha');
 

index.js

@@ -3,9 +3,9 @@
 /**
  * # Tunic
  *
- * The stupid doc-block parser. Generates an abstract syntax tree based on a
- * customizable regular-expression grammar. Defaults to C-style comment blocks,
- * so it supports JavaScript, PHP, C++, and even CSS right out of the box.
+ * Generates an abstract syntax tree based on a customizable regular-expression
+ * grammar. Defaults to C-style comment blocks, so it supports JavaScript, PHP,
+ * C++, and even CSS right out of the box.
  *
  * Tags are parsed greedily. If it looks like a tag, it's a tag. What you do
  * with them is completely up to you. Render something human-readable, perhaps?
@@ -18,14 +18,39 @@ var proto,
 
 	/**
 	 * Line matching patterns.
-	 *
-	 * @type {Object.<String,RegExp>}
 	 */
 	matchLines = {
 		any: /^/gm,
 		edge: /^[\t ]*[\r\n]|[\r\n][\t ]*$/g,
 		empty: /^$/gm,
 		trailing: /^\s*[\r\n]+|[\r\n]+\s*$/g
+	},
+
+	/**
+	 * Default options.
+	 */
+	defaults = {
+		extension: /.\w+$/,
+		blockIndent: /^[\t \*]/gm,
+		blockParse: /^[\t ]*\/\*\*(?!\/)([\s\S]*?)\s*\*\//m,
+		blockSplit: /(^[\t ]*\/\*\*(?!\/)[\s\S]*?\s*\*\/)/m,
+		property: 'ast',
+		tagParse: /^(\w+)[\t \-]*(\{[^\}]+\})?[\t \-]*(\[[^\]]*\]\*?|\S*)?[\t \-]*([\s\S]+)?$/m,
+		tagSplit: /^[\t ]*@/m,
+		namedTags: [
+			'module',
+			'imports',
+			'exports',
+			'class',
+			'extends',
+			'method',
+			'arg',
+			'argument',
+			'param',
+			'parameter',
+			'prop',
+			'property'
+		]
 	};
 
 /**
@@ -34,11 +59,12 @@ var proto,
  *
  * @constructor
  * @param {Object} options
+ * @param {RegExp} options.extension
  * @param {RegExp} options.blockIndent
  * @param {RegExp} options.blockParse
  * @param {RegExp} options.blockSplit
- * @param {RegExp} options.extension
  * @param {Array.<String>} options.namedTags
+ * @param {String} options.property
  * @param {RegExp} options.tagParse
  * @param {RegExp} options.tagSplit
  */
@@ -51,42 +77,13 @@ function Tunic(options) {
 	 * @property options
 	 * @type {Object}
 	 */
-	this.options = mixin({}, this.defaults, options);
+	this.options = mixin({}, defaults, options);
 
 	Transform.call(this, { objectMode: true });
 }
 
 proto = inherits(Tunic, Transform);
 
-/**
- * @property defaults
- * @type {Object}
- */
-proto.defaults = {
-	extension: /.\w+$/,
-
-	blockIndent: /^[\t \*]/gm,
-	blockParse: /^[\t ]*\/\*\*(?!\/)([\s\S]*?)\s*\*\//m,
-	blockSplit: /(^[\t ]*\/\*\*(?!\/)[\s\S]*?\s*\*\/)/m,
-
-	tagParse: /^(\w+)[\t \-]*(\{[^\}]+\})?[\t \-]*(\[[^\]]*\]\*?|\S*)?[\t \-]*([\s\S]+)?$/m,
-	tagSplit: /^[\t ]*@/m,
-
-	namedTags: [
-		'imports',
-		'exports',
-		'class',
-		'extends',
-		'method',
-		'arg',
-		'argument',
-		'param',
-		'parameter',
-		'prop',
-		'property'
-	]
-};
-
 /**
  * @method parse
  * @param {String} chunk
@@ -216,21 +213,23 @@ proto.unwrap = function (block) {
  * @param {Function} cb
  */
 proto._transform = function (file, enc, cb) {
-	var extension = this.options.extension;
-
-	// String or Buffer
-	if (typeof file === 'string' || file instanceof Buffer) {
-		this.push(this.parse(file.toString()));
-		return cb();
-	}
+	var options = this.options,
+		extension = options.extension;
 
-	// Vinyl
-	if (file.contents != null && extension.test(file.path)) {
-		file.tunic = this.parse(file.contents.toString());
+	if (file != null) {
+		if (typeof file === 'string' || file instanceof Buffer) {
+			// String or Buffer
+			file = this.parse(file);
+		}
+		else if (file.contents != null && extension.test(file.path)) {
+			// Vinyl
+			file[options.property] = this.parse(file.contents);
+		}
 	}
 
 	this.push(file);
-	return cb();
+
+	cb();
 };
 
 module.exports = Tunic;

package.json

@@ -5,11 +5,10 @@
   "keywords": [
     "tunic",
     "parser",
-    "documentation",
     "docblock",
-    "doctrine",
     "docs",
-    "doc"
+    "doc",
+    "dox"
   ],
   "homepage": "https://github.com/togajs/tunic",
   "bugs": "https://github.com/togajs/tunic/issues",
@@ -36,9 +35,8 @@
     "gulp-jscs": "^1.1.2",
     "gulp-jshint": "^1.8.4",
     "gulp-mocha": "^1.0.0",
-    "gulp-watch": "^1.0.2",
     "jshint-stylish": "^0.4.0",
-    "vinyl-fs": "^0.3.7"
+    "toga": "^0.2.2"
   },
   "engines": {
     "node": ">= 0.10"