* adds "section" property to yfm to test dynamic directory construction

* adds debug option * adds `:random()` and `:000` special patterns * replaces utils.filenumber with digits dependency
assemble · Dec 22, 2013 · e96e42d · e96e42d
1 parent 220e0ef
commit e96e42d
Show file tree

Hide file tree

Showing 34 changed files with 7,257 additions and 77 deletions.
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,10 +1,15 @@
+v0.3.2:
+  date: 2013-12-21
+  changes:
+    - adds debug option
+    - adds `:random()` and `:000` special patterns
 v0.3.0:
   date: 2013-11-28
   changes:
-  - "Updates dependencies to work with Grunt 0.4.2"
-  - "Adds `:num` permalink structure, for adding numbers to generated pages"
-  - "Adds `stripnumber` to strip leading numbers from pages. this works well with `:num` for replacing pages that are in order but poorly numbered"
-  - "Adds documentation for updates"
+    - "Updates dependencies to work with Grunt 0.4.2"
+    - "Adds `:num` permalink structure, for adding numbers to generated pages"
+    - "Adds `stripnumber` to strip leading numbers from pages. this works well with `:num` for replacing pages that are in order but poorly numbered"
+    - "Adds documentation for updates"
 v0.1.5:
   date: 2013-10-09
   changes:

diff --git a/Gruntfile.js b/Gruntfile.js
@@ -61,6 +61,53 @@ module.exports = function(grunt) {
         src: 'test/fixtures/pages/**/*.hbs',
         dest: 'test/actual/no_opts_flatten/'
       },
+      // Should flatten, then use 'dest + permalinks structure + permalinks preset' for dest
+      preset_flatten: {
+        options: {
+          ext: '.html',
+          flatten: true,
+          permalinks: {
+            preset: 'pretty',
+            structure: ':section'
+          }
+        },
+        src: 'test/fixtures/pages/**/*.hbs',
+        dest: 'test/actual/preset_flatten/'
+      },
+      // Should add a unique number to each file name, and numbers should be padded with
+      // the specified number of digits
+      digits_specified: {
+        options: {
+          permalinks: {
+            structure: ':section/:basename-:0000:ext'
+          }
+        },
+        files: [
+          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/digits_specified/', ext: '.html'}
+        ]
+      },
+      // Should add a unique number to each file name
+      digits_auto: {
+        options: {
+          permalinks: {
+            structure: ':section/:basename-:num:ext'
+          }
+        },
+        files: [
+          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/digits_auto/', ext: '.html'}
+        ]
+      },
+      // Should add a unique number to each file name
+      random: {
+        options: {
+          permalinks: {
+            structure: ':section/:random(0Aa,9)-:basename:ext'
+          }
+        },
+        files: [
+          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/random/', ext: '.html'}
+        ]
+      },
       // Should modify dest path using preset "pretty"
       preset_pretty: {
         options: {
@@ -95,36 +142,47 @@ module.exports = function(grunt) {
         ]
       },
       // Should modify dest path using permalinks structure
-      structure_date: {
+      structure_basename: {
         options: {
           permalinks: {
-            structure: ':date/index:ext'
+            structure: ':basename:ext'
           }
         },
         files: [
-          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/structure_date/', ext: '.html'}
+          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/structure_basename/', ext: '.html'}
         ]
       },
-      // Should modify dest path using permalinks structure
-      structure_basename: {
+      // Should use a long date format for the path
+      dates: {
         options: {
           permalinks: {
-            structure: ':basename:ext'
+            structure: ':YYYY/:MM/:DD/:basename/index:ext'
           }
         },
         files: [
-          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/structure_basename/', ext: '.html'}
+          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/dates/', ext: '.html'}
         ]
       },
-      // Should use a long date format for the path
-      dates: {
+      // Date patterns should not collide with non-date patterns
+      date_collision: {
         options: {
           permalinks: {
             structure: ':YYYY/:MM/:DD/:basename/index:ext'
           }
         },
         files: [
-          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/dates/', ext: '.html'}
+          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/date_collision/', ext: '.html'}
+        ]
+      },
+      // Should modify dest path using permalinks structure
+      structure_date: {
+        options: {
+          permalinks: {
+            structure: ':date/index:ext'
+          }
+        },
+        files: [
+          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/structure_date/', ext: '.html'}
         ]
       },
       // Should modify dest path using a built-in property from context
@@ -205,7 +263,7 @@ module.exports = function(grunt) {
             structure: ':project/:author',
             patterns: [
               {
-                // should be "permalinks"
+                // should be "assemble-contrib-permalinks"
                 pattern: ':project',
                 replacement: '<%= pkg.name %>'
               },
@@ -220,6 +278,19 @@ module.exports = function(grunt) {
         files: [
           {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/replacement_pattern/', ext: '.html'}
         ]
+      },
+      // Should generate a javascript file with all non-function replacement patterns
+      debug_option: {
+        options: {
+          permalinks: {
+            debug: 'test/actual/replacements.js',
+            preset: 'pretty',
+            structure: ':YYYY/:MM/:DD'
+          }
+        },
+        files: [
+          {expand: true, cwd: 'test/fixtures/pages', src: ['**/*.hbs'], dest: 'test/actual/collections_complex/', ext: '.html'}
+        ]
       }
     },
 

diff --git a/README.md b/README.md
@@ -92,7 +92,7 @@ assemble: {
 
 This plugin comes with a number of built-in replacement patterns that will automatically parse and convert the built-in variables into the appropriate string. Since Assemble provides a number of generic variables for accessing page data, such as `basename`, `ext`, `filename` etc., this plugin simply dynamically builds the replacement patterns from those generic variables.
 
-Barring a few exceptions (`_page`, `data`, `filePair`, `page`, `pageName`), you should be able to use any _applicable_ variable that is on the page context in your replacement patterns.
+Barring a few exceptions (`_page`, `data`, `filePair`, `page`, `pageName`), you should be able to use any _valid_ variable that is on the page context in your replacement patterns.
 
 For example, assuming we have a file, `./templates/overview.hbs`:
 
@@ -104,6 +104,50 @@ For example, assuming we have a file, `./templates/overview.hbs`:
 * `:category`: Slugified version of _the very first category_ for a page.
 
 
+### Special patterns
+
+> A few special replacement patterns were created for this lib.
+
+#### `:num`
+Automatically adds sequential, "padded" numbers based on the length of the pages array in the current target.
+
+For example, given the structure `:num-:basename`:
+
+* 1-9 pages would result in `1-foo.html`, `2-bar.html`, `3-baz.html` and so on.
+* 1,000 pages would result in `0001-foo.html`, `0002-bar.html`, `0003-baz.html`, ... `1000-quux.html`.
+
+#### `:000`
+Adds sequential digits. Similar to `:num`, but the number of digits is determined by the number of zeros defined.
+
+Example:
+
+* `:00` will result in two-digit numbers
+* `:000` will result in three-digit numbers
+* `:00000000` will result in eigth-digit numbers, and so on...
+
+#### `:random(Pattern, Number)`
+Adds randomized characters based on the pattern provided in the parentheses. The first parameter defines the pattern you wish to use, and an optional second parameter defines the number of characters to generate.
+
+For example, `:random(A, 4)` (whitespace insenstive) would result in randomized 4-digit uppercase letters, like, `ZAKH`, `UJSL`... and so on.
+
+**no second parameter**
+
+If a second parameter is not provided, then the  `length()` of the characters used in the first parameter will be used to determine the number of digits to out put. For example:
+
+* `:random(AAAA)` is equivelant to `:random(A, 4)`
+* `:random(AAA0)` and `:random(AA00)` and `:random(A0A0)` are equivelant to `:random(A0, 4)`
+
+**valid characters (and examples)**
+
+* `:random(aa)`: results in double-digit, randomized, lower-case letters (`abcdefghijklmnopqrstuvwxyz`)
+* `:random(AAA)`: results in triple-digit, randomized, upper-case letters (`ABCDEFGHIJKLMNOPQRSTUVWXYZ`)
+* `:random(0, 6)`: results in six-digit, randomized nubmers (`0123456789`)
+* `:random(!, 5)`: results in single-digit randomized, _valid_ non-letter characters (`~!@#$%^&()_+-={}[];\',.`)
+* `:random(A!a0, 9)`: results in nine-digit, randomized characters (any of the above)
+
+_The order in which the characters are provided has no impact on the outcome._
+
+
 #### Custom replacement patterns
 
 If you have some patterns you'd like to implement, if you think they're common enough that they should be built into this plugin, please submit a pull request.
@@ -320,7 +364,6 @@ options: {
 }
 ```
 
-
 ### lang
 Type: `String`
 Default: `en`
@@ -571,6 +614,7 @@ Here are some related projects you might be interested in from the [Assemble](ht
 + [assemble-contrib-contextual](https://github.com/assemble/assemble-contrib-contextual): Generates a JSON file containing the context of each page. Basic plugin to help see what's happening in the build. 
 + [assemble-contrib-decompress](https://github.com/assemble/assemble-contrib-decompress): Assemble plugin for extracting zip, tar and tar.gz archives.  
 + [assemble-contrib-download](https://github.com/assemble/assemble-contrib-download): Assemble plugin for downloading files from GitHub. 
++ [assemble-contrib-i18n](https://github.com/assemble/assemble-contrib-i18n): Plugin for adding i18n support to Assemble projects. 
 + [assemble-contrib-lunr](https://github.com/assemble/assemble-contrib-lunr): Assemble plugin for creating a search engine within your static site using lunr.js. 
 + [assemble-contrib-markdown](https://github.com/assemble/assemble-contrib-markdown): Convert markdown files to HTML using marked.js. This plugin is an alternative to Assemble's markdown Handlebars helpers. Both are useful in different scenarios. 
 + [assemble-contrib-sitemap](https://github.com/assemble/assemble-contrib-sitemap): Sitemap generator plugin for Assemble 
@@ -600,7 +644,7 @@ Released under the MIT license
 
 ***
 
-_This file was generated by [grunt-readme](https://github.com/assemble/grunt-readme) on Saturday, November 30, 2013._
+_This file was generated by [grunt-readme](https://github.com/assemble/grunt-readme) on Saturday, December 21, 2013._
 
 [grunt]: http://gruntjs.com/
 [Getting Started]: https://github.com/gruntjs/grunt/blob/devel/docs/getting_started.md

diff --git a/docs/options.md b/docs/options.md
@@ -74,7 +74,6 @@ options: {
 }
 ```
 
-
 ## lang
 Type: `String`
 Default: `en`

diff --git a/docs/patterns.md b/docs/patterns.md
@@ -25,7 +25,7 @@ assemble: {
 
 This plugin comes with a number of built-in replacement patterns that will automatically parse and convert the built-in variables into the appropriate string. Since Assemble provides a number of generic variables for accessing page data, such as `basename`, `ext`, `filename` etc., this plugin simply dynamically builds the replacement patterns from those generic variables.
 
-Barring a few exceptions (`_page`, `data`, `filePair`, `page`, `pageName`), you should be able to use any _applicable_ variable that is on the page context in your replacement patterns.
+Barring a few exceptions (`_page`, `data`, `filePair`, `page`, `pageName`), you should be able to use any _valid_ variable that is on the page context in your replacement patterns.
 
 For example, assuming we have a file, `./templates/overview.hbs`:
 
@@ -37,6 +37,50 @@ For example, assuming we have a file, `./templates/overview.hbs`:
 * `:category`: Slugified version of _the very first category_ for a page.
 
 
+## Special patterns
+
+> A few special replacement patterns were created for this lib.
+
+### `:num`
+Automatically adds sequential, "padded" numbers based on the length of the pages array in the current target.
+
+For example, given the structure `:num-:basename`:
+
+* 1-9 pages would result in `1-foo.html`, `2-bar.html`, `3-baz.html` and so on.
+* 1,000 pages would result in `0001-foo.html`, `0002-bar.html`, `0003-baz.html`, ... `1000-quux.html`.
+
+### `:000`
+Adds sequential digits. Similar to `:num`, but the number of digits is determined by the number of zeros defined.
+
+Example:
+
+* `:00` will result in two-digit numbers
+* `:000` will result in three-digit numbers
+* `:00000000` will result in eigth-digit numbers, and so on...
+
+### `:random(Pattern, Number)`
+Adds randomized characters based on the pattern provided in the parentheses. The first parameter defines the pattern you wish to use, and an optional second parameter defines the number of characters to generate.
+
+For example, `:random(A, 4)` (whitespace insenstive) would result in randomized 4-digit uppercase letters, like, `ZAKH`, `UJSL`... and so on.
+
+**no second parameter**
+
+If a second parameter is not provided, then the  `length()` of the characters used in the first parameter will be used to determine the number of digits to out put. For example:
+
+* `:random(AAAA)` is equivelant to `:random(A, 4)`
+* `:random(AAA0)` and `:random(AA00)` and `:random(A0A0)` are equivelant to `:random(A0, 4)`
+
+**valid characters (and examples)**
+
+* `:random(aa)`: results in double-digit, randomized, lower-case letters (`abcdefghijklmnopqrstuvwxyz`)
+* `:random(AAA)`: results in triple-digit, randomized, upper-case letters (`ABCDEFGHIJKLMNOPQRSTUVWXYZ`)
+* `:random(0, 6)`: results in six-digit, randomized nubmers (`0123456789`)
+* `:random(!, 5)`: results in single-digit randomized, _valid_ non-letter characters (`~!@#$%^&()_+-={}[];\',.`)
+* `:random(A!a0, 9)`: results in nine-digit, randomized characters (any of the above)
+
+_The order in which the characters are provided has no impact on the outcome._
+
+
 ### Custom replacement patterns
 
 If you have some patterns you'd like to implement, if you think they're common enough that they should be built into this plugin, please submit a pull request.