Merge pull request #42 from darcyclarke/develop

Add information about using DSS parsers

README.md

@@ -1,10 +1,17 @@
 # DSS
-**@version 1.0**
-**@logo [DSS](http://f.cl.ly/items/1J353X3U172A1u3r2K3b/dss-logo.png)**
+**version 1.0.1**
+- **[Official Logo](http://f.cl.ly/items/1J353X3U172A1u3r2K3b/dss-logo.png)**
+- **[NPM Repository](https://npmjs.org/package/dss)**
 
-**DSS**, Documented Style Sheets, is a parser and style guide that creates  UI documentation objects from properly commented CSS, LESS, STYLUS, SASS and SCSS files.
+**DSS**, Documented Style Sheets, is a comment styleguide and parser for CSS, LESS, STYLUS, SASS and SCSS code.
 
-### Example Comment Block
+## Generating Documentation
+
+In most cases, you will want to include the **DSS** parser in a build step that will generate documentation files automatically. **[grunt-dss](https://github.com/darcyclarke/grunt-dss)** is the official **DSS** `grunt` task which does just that.
+
+## Parser Example
+
+#### Example Comment Block
 
 ```css
 /**
@@ -37,7 +44,18 @@
 // 
 ````
 
-### Example Generated Object
+#### Example Parser Implementation
+
+```javscript
+var lines = fs.readFileSync('styles.css'),
+    options = {},
+    callback = function(parsed){
+      console.log(parsed);
+    };
+dss.parse(lines, options, callback);
+````
+
+#### Example Generated Object
 
 ```javascript
 {
@@ -71,3 +89,20 @@
   }
 }
 ````
+
+## Modifying Parsers
+
+**DSS**, by default, includes 4 parsers for the name, description, states and markup of a comment block. You can add to or override these default parsers using the following:
+
+```javascript
+// Matches @link
+dss.parser('link', function(i, line, block){
+
+  // Replace link with HTML wrapped version
+  var exp = /(b(https?|ftp|file)://[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/ig;
+  line.replace(exp, "<a href='$1'>$1</a>");
+  return line;
+   
+});
+````
+

dss.js

@@ -349,6 +349,61 @@ var dss = (function(){
 
   };
 
+  // Describe detection pattern
+  _dss.detector(function(line){
+    if(typeof line !== 'string')
+      return false;
+    var reference = line.split("\n\n").pop();
+    return !!reference.match(/.*@/);
+  });
+
+  // Describe parsing a name
+  _dss.parser('name', function(i, line, block, file){
+    return line;
+  });
+
+  // Describe parsing a description
+  _dss.parser('description', function(i, line, block, file){
+    return line;
+  });
+
+  // Describe parsing a state
+  _dss.parser('state', function(i, line, block, file){
+    var state = line.split(' - ');
+    return {
+      name: (state[0]) ? _dss.trim(state[0]) : '',
+      escaped: (state[0]) ? _dss.trim(state[0].replace('.', ' ').replace(':', ' pseudo-class-')) : '',
+      description: (state[1]) ? _dss.trim(state[1]) : ''
+    };
+  });
+
+  // Describe parsing markup
+  _dss.parser('markup', function(i, line, block, file){
+    var markup = block.split('').splice(i, block.length).join('');
+
+    markup = (function(markup){
+      var ret = [];
+      markup.split('\n').forEach(function(line){
+        var pattern = '*',
+            index = line.indexOf(pattern);
+
+        if(index > 0 && index < 10)
+          line = line.split('').splice((index + pattern.length), line.length).join('');
+
+        line = dss.trim(line);
+        if(line && line != '@markup')
+          ret.push(line);
+
+      });
+      return ret.join('');
+    })(markup);
+
+    return {
+      example: markup,
+      escaped: markup.replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    };
+  });
+
   // Return function
   return _dss;
 

package.json

@@ -1,8 +1,8 @@
 {
-  "name": "DSS",
+  "name": "dss",
   "description": "Documented Style Sheets",
-  "version": "1.0.0",
-  "homepage": "https://github.com/darcyclarke/DSS",
+  "version": "1.0.1",
+  "homepage": "https://github.com/darcyclarke/dss",
   "author": {
     "name": "darcyclarke",
     "email": "darcy@darcyclarke.me",
@@ -10,15 +10,15 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/darcyclarke/DSS"
+    "url": "https://github.com/darcyclarke/dss"
   },
   "bugs": {
-    "url": "https://github.com/darcyclarke/DSS/issues"
+    "url": "https://github.com/darcyclarke/dss/issues"
   },
   "licenses": [
     {
       "type": "MIT",
-      "url": "https://github.com/darcyclarke/DSS/blob/master/LICENSE-MIT"
+      "url": "https://github.com/darcyclarke/dss/blob/master/LICENSE-MIT"
     }
   ],
   "main": "dss.js",