Implement peg.js or gonzales-pe for parsing

[darcyclarke]

We need more robust and fool-proof parsing. Currently, the implementation is pretty benign (lots of regex matching, normalizing strings, half-hazard .replace() calls and an overall very rudimentary version of a syntax tree).

I was trying to write unit tests last week to address some issues/inconsistencies I saw with the latest updates I made (as #67 also notes) and I couldn't help but take note of other projects that provide better syntax trees and parsing. At this point I'm leaning towards gonzales-pe over a more barebones approach with peg.js.

Open to ideas/suggestions here.

Peg.js would allow us to define more robust parsing but it feels like I'd be duplicating a lot of the efforts of gonzales-pe to get enhancements, we eventually want, like mixin and variables support (#45).

[mattdrose]

SassDoc is using CDocParser. I like that it uses C comment block standards, so that it's easy to control what comments are being parsed.

[renegare]

+1

I'm probably not using dss in the best of ways but if we had an AST output(?) it would help with this scenario where I'm would like to extract variables for a given comment block, where a single file contains multiple comment blocks:

  describe('multi declaration of variables', function() {
        beforeEach(function(done) {
            dss.parse([
                '/**',
                ' * @name Colours',
                ' * @description Some nice colours',
                ' * @variables',
                '*/',
                '$primary-color: red;',
                '$secondary-color: blue;',
                '$tertiary-color: green;',

                '/**',
                ' * @name Grid dims',
                ' * @description Grid widths',
                ' * @variables',
                '*/',
                '$grid-gutter-width: 10px;',
                '$grid-cols: 10;',
                '$grid-col-width: 30px;'
            ].join("\n"), {}, function(parsed) {
                parsedData = parsed;
                done();
            });
        });

        it('should list variables in block', function() {
            parsedData.should.eql({
                blocks: [
                    {
                        name: 'Colours',
                        description: 'Some nice colours',
                        variables: [
                            {name: 'primary-color', value: 'red'},
                            {name: 'secondary-color', value: 'blue'},
                            {name: 'tertiary-color', value: 'green'}
                        ]
                    },
                    {
                        name: 'Grid dims',
                        description: 'Grid widths',
                        variables: [
                            {name: 'grid-gutter-width', value: '10px'},
                            {name: 'grid-cols', value: '10'},
                            {name: 'grid-col-width', value: '30px'}
                        ]
                    }
                ]
            });
        });
    });