Updated to KSS-Node 2.0 functionality

README.md

@@ -1,57 +1,53 @@
 # gulp-kss
 
-Gulp plugin for KSS ([Knyle Stype Sheets](http://warpspire.com/kss/)) documentation generation.
+Gulp plugin for KSS ([Knyle Style Sheets](http://warpspire.com/kss/)) documentation generation.
 
-This plugin is based on [kss-node](https://github.com/hughsk/kss-node) and generates a styleguide based on code documentation. The plugin is mainly a fork of `kss-nodes`'s bin script, not how a beautiful gulp plugin should look like, but it works. 
-
-This plugin currently lacks tests.
+This plugin is based on [kss-node](https://github.com/hughsk/kss-node) and generates a styleguide based on code documentation. It builds upon the original [gulp-kss](https://github.com/philj/gulp-kss) by PhilJ but integrates newer node-kss features including custom properties, handlebars helpers, and more.
 
 ## Install
 
 ```
-npm install gulp-kss
+git clone https://github.com/kedruff/gulp-kss.git
+npm install
 ```
 
 ## Usage
 
 Pipe all source files you want to document through `gulp-kss`, also the ones which are usually imported.
 
-In addition to that you need to create a concated and compiled version of your styles at `public/style.css`. 
-
 ```javascript
-var gulp = require('gulp');
-var gulpless = require('gulp-less');
-var gulpkss = require('gulp-kss');
-var gulpconcat = require('gulp-concat');
-
-gulp.src(['styles/**/*.less'])
-    .pipe(gulpkss({
-        overview: __dirname + '/styles/styleguide.md'
-    }))
+gulp.src( ['array/*.scss', 'ofSource/*.scss', 'sass/files/*.scss'] )
+    .pipe( gulpkss({
+        template: './node_modules/kss/lib/template',
+        multiline: true,
+        typos: false
+        custom: [],
+        helpers: '',
+        css: [],
+        js: []
+    }) )
     .pipe(gulp.dest('styleguide/'));
 
-// Concat and compile all your styles for correct rendering of the styleguide.
-gulp.src('styles/main.less')
-    .pipe(gulpless())
-    .pipe(gulpconcat('public/style.css'))
-    .pipe(gulp.dest('styleguide/'));
 ```
-
 ## Options
 
-* `overview`: Absolute path to markdown file which is used for styleguide home page
-* `templateDirectory`: Absolute path to template directory, by default `kss-node` default template is used.
-* `kss`: Options supported by [`kss-node`](https://github.com/hughsk/kss-node/wiki/Module-API#wiki-options)
+* **template**: A path relative to your `gulpfile.js` containing a custom template (Default: `./node_modules/kss/lib/template/`)
+* **destination**: A path relative to your `gulpfile.js` where you would your compiled guide to live (Default: `./docs/styleguide/`)
+* **multiline** : As far as the parser is concerned, all but the last two paragraphs (separated by two line breaks) in a block are considered to be part of the description. In the case you don't have any modifiers but a large description it'll try to pick up this scenario. This setting's enabled by default, but you can disable it by adding multiline: false to your options.
+* **typos**: Thanks to [natural](https://github.com/NaturalNode/natural), `kss-node` can parse keywords phonetically rather then by their string value. In short: make a typo and the library will do its best to read it anyway. Enable this by setting typos to true in the options object.
+* **custom**: A custom property name when parsing KSS comments
+* **helpers**: Specify the location of custom [handlebars helpers](http://bit.ly/kss-helpers) (Default: `./lib/template/helpers`)
+* **css**: Specify the URL of a CSS file to include in the style guide
+* **js**: Specify the URL of a JavaScript file to include in the style guide
 
 ## LICENSE
 
 (MIT License)
 
-Copyright (c) 2014 DigitalWerft [email protected]
+Copyright (c) 2015 Capital One Financial (Kevin Druff)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-

handlebarHelpers.js

@@ -1,55 +1,31 @@
 var kss = require('kss')
 
-module.exports = function (handlebars, styleguide) {
-    /**
-     * Equivalent to the {#if} block helper with multiple arguments.
-     */
-    handlebars.registerHelper('ifAny', function() {
-        var argLength = arguments.length - 2,
-            content = arguments[argLength + 1],
-            success = true;
-
-        for (var i = 0; i < argLength; i += 1) {
-            if (!arguments[i]) {
-                success = false;
-                break;
-            }
-        }
-
-        return success ? content.fn(this) : content.inverse(this);
-    });
-
-    /**
-     * Returns a single section, found by its reference number
-     * @param  {String|Number} reference The reference number to search for.
-     */
-    handlebars.registerHelper('section', function(reference) {
+module.exports = function (handlebars, styleguide, cache) {
+    handlebars.registerHelper('section', function(reference, options) {
         var section = styleguide.section(reference);
-        if (!section) return false;
 
-        return arguments[arguments.length-1](section.data);
+        return section ? options.fn(section.data) : false;
     });
 
     /**
      * Loop over a section query. If a number is supplied, will convert into
      * a query for all children and descendants of that reference.
      * @param  {Mixed} query The section query
      */
-    handlebars.registerHelper('eachSection', function(query) {
-        var sections,
-            i, l, buffer = "";
-        query = (typeof query === 'string') ? query : query.toString();
+    handlebars.registerHelper('eachSection', function(query, options) {
+        var buffer = '',
+            sections,
+            i, l;
 
-        if (!query.match(/x|\*/g)) {
-            query = new RegExp('^' + query + '$|^' + query + "\\..*");
+        if (!query.match(/\bx\b|\*/g)) {
+            query = query + '.*';
         }
         sections = styleguide.section(query);
-
         if (!sections) return '';
 
         l = sections.length;
         for (i = 0; i < l; i += 1) {
-            buffer += arguments[arguments.length-1].fn(sections[i].data);
+            buffer += options.fn(sections[i].data);
         }
 
         return buffer;
@@ -58,93 +34,174 @@ module.exports = function (handlebars, styleguide) {
     /**
      * Loop over each section root, i.e. each section only one level deep.
      */
-    handlebars.registerHelper('eachRoot', function() {
-        var sections,
-            i, l, buffer = "";
+    handlebars.registerHelper('eachRoot', function(options) {
+        var buffer = '',
+            sections,
+            i, l;
 
         sections = styleguide.section('x');
         if (!sections) return '';
 
         l = sections.length;
         for (i = 0; i < l; i += 1) {
-            buffer += arguments[arguments.length-1].fn(sections[i].data);
+            buffer += options.fn(sections[i].data);
         }
 
         return buffer;
     });
 
+    /**
+     * Equivalent to "if the given reference is numeric". e.g:
+     *
+     * {{#ifNumeric reference}}
+     *   REFERENCES LIKE 4.0 OR 4.1.14
+     *  {{else}}
+     *   ANYTHING ELSE
+     * {{/ifNumeric}}
+     */
+    handlebars.registerHelper('ifNumeric', function(reference, options) {
+        return (typeof reference == 'number' || typeof reference == 'string' && reference.match(/^[\.\d]+$/)) ? options.fn(this) : options.inverse(this);
+    });
+
+    /**
+     * Equivalent to "if the current reference is X". e.g:
+     *
+     * {{#ifReference 'base.headings'}}
+     *   IF CURRENT REFERENCE IS base.headings ONLY
+     *  {{else}}
+     *   ANYTHING ELSE
+     * {{/ifReference}}
+     */
+    handlebars.registerHelper('ifReference', function(reference, options) {
+        return (this.reference && reference == this.reference) ? options.fn(this) : options.inverse(this);
+    });
+
+    /**
+     * Equivalent to "unless the current reference is X". e.g:
+     *
+     * {{#unlessReference 'base.headings'}}
+     *   ANYTHING ELSE
+     *  {{else}}
+     *   IF CURRENT REFERENCE IS base.headings ONLY
+     * {{/unlessReference}}
+     */
+    handlebars.registerHelper('unlessReference', function(reference, options) {
+        return (!this.reference || reference != this.reference) ? options.fn(this) : options.inverse(this);
+    });
+
     /**
      * Equivalent to "if the current section is X levels deep". e.g:
      *
-     * {{#refDepth 1}}
+     * {{#ifDepth 1}}
      *   ROOT ELEMENTS ONLY
      *  {{else}}
      *   ANYTHING ELSE
-     * {{/refDepth}}
+     * {{/ifDepth}}
      */
-    handlebars.registerHelper('whenDepth', function(depth, context) {
-        if (!(context && this.refDepth)) {
-            return '';
-        }
-        if (depth == this.refDepth) {
-            return context.fn(this);
-        }
-        if (context.inverse) {
-            return context.inverse(this);
-        }
+    handlebars.registerHelper('ifDepth', function(depth, options) {
+        return (this.depth && depth == this.depth) ? options.fn(this) : options.inverse(this);
+    });
+
+    /**
+     * Equivalent to "unless the current section is X levels deep". e.g:
+     *
+     * {{#unlessDepth 1}}
+     *   ANYTHING ELSE
+     *  {{else}}
+     *   ROOT ELEMENTS ONLY
+     * {{/unlessDepth}}
+     */
+    handlebars.registerHelper('unlessDepth', function(depth, options) {
+        return (!this.depth || depth != this.depth) ? options.fn(this) : options.inverse(this);
     });
 
     /**
      * Similar to the {#eachSection} helper, however will loop over each modifier
-     * @param  {Object} section Supply a section object to loop over it's modifiers. Defaults to the current section.
+     * @param  {Object} section Supply a section object to loop over its modifiers. Defaults to the current section.
      */
-    handlebars.registerHelper('eachModifier', function(section) {
-        var modifiers, i, l, buffer = '';
+    handlebars.registerHelper('eachModifier', function() {
+        var modifiers,
+            options = arguments[arguments.length - 1],
+            buffer = '',
+            i, l;
 
-        // Default to current modifiers, but allow supplying a custom section
-        if (section.data) modifiers = section.data.modifiers;
-        modifiers = modifiers || this.modifiers || false;
+        // Default to current modifiers, but allow supplying a custom section.
+        modifiers = (arguments.length > 1 && arguments[0].data) ? arguments[0].data.modifiers : this.modifiers;
 
-        if (!modifiers) return {};
+        if (!modifiers) return '';
 
         l = modifiers.length;
         for (i = 0; i < l; i++) {
-            buffer += arguments[arguments.length-1].fn(modifiers[i].data || '');
+            buffer += options.fn(modifiers[i].data || '');
         }
         return buffer;
     });
 
     /**
-     * Outputs a modifier's markup, if possible.
-     * @param  {Object} modifier Specify a particular modifier object. Defaults to the current modifier.
+     * Similar to the {#eachSection} helper, however will loop over each parameter
+     * @param  {Object} section Supply a section object to loop over its parameters. Defaults to the current section.
      */
-    handlebars.registerHelper('modifierMarkup', function(modifier) {
-        modifier = arguments.length < 2 ? this : modifier || this || false;
+    handlebars.registerHelper('eachParameter', function() {
+        var parameters,
+            options = arguments[arguments.length - 1],
+            buffer = '',
+            i, l;
 
-        if (!modifier) {
-            return false;
-        }
+        // Default to current parameters, but allow supplying a custom section.
+        parameters = (arguments.length > 1 && arguments[0].data) ? arguments[0].data.parameters : this.parameters;
 
-        // Maybe it's actually a section?
-        if (modifier.modifiers) {
-            return new handlebars.SafeString(
-                modifier.markup
-            );
-        }
+        if (!parameters) return '';
 
-        // Otherwise return the modifier markup
-        return new handlebars.SafeString(
-            new kss.KssModifier(modifier).markup()
-        );
+        l = parameters.length;
+        for (i = 0; i < l; i++) {
+            buffer += options.fn(parameters[i].data || '');
+        }
+        return buffer;
     });
 
     /**
-     * Quickly avoid escaping strings
-     * @param  {String} arg The unescaped HTML
+     * Outputs the current section's or modifier's markup.
      */
-    handlebars.registerHelper('html', function(arg) {
-        return new handlebars.SafeString(arg || '');
-    });
+    handlebars.registerHelper('markup', function() {
+        var section,
+            modifier = false,
+            template,
+            partial,
+            data;
+
+        if (!this) {
+            return '';
+        }
+
+        // Determine if the element is a section object or a modifier object.
+        if (this.modifiers) {
+            // If this is the section object, use the default markup without a modifier class.
+            section = new kss.KssSection(this);
+        }
+        else {
+            // If this is the markup object, find the modifier class and the section object.
+            modifier = new kss.KssModifier(this);
+            section = modifier.section();
+        }
 
+        // Load the information about this section's markup partial.
+        partial = cache.partial[section.reference()];
+
+        // Prepare the sample data for the partial.
+        data = JSON.parse(JSON.stringify(partial.data));
+        if (data.modifier_class) {
+            data.modifier_class += modifier ? ' ' + modifier.className() : '';
+        }
+        else {
+            data.modifier_class = modifier ? modifier.className() : '';
+        }
+
+        // Compile the section's markup partial into a template.
+        template = handlebars.compile('{{> "' + partial.name + '"}}');
+        // We don't wrap the rendered template in "new handlebars.SafeString()" since
+        // we want the ability to display it as a code sample with {{ }} and as
+        // rendered HTML with {{{ }}}.
+        return template(data);
+    });
     return handlebars;
 };