Add pre_convert and post_convert options for specifying a callback to…

… filter the original readme(.txt) content and the converted read(.md) content. Closes #16.

Gruntfile.js

@@ -75,6 +75,30 @@ module.exports = function(grunt) {
           'tmp/readme-screenshots-disabled.md': 'test/fixtures/readme.txt',
 		},
       },
+      with_appended_header_pre_convert: {
+		files: {
+          'tmp/readme-pre-convert-filter.md': 'test/fixtures/readme.txt',
+		},
+		options: {
+          screenshot_url: 'http://ps.w.org/{plugin}/assets/{screenshot}.png',
+          pre_convert: function( readme ) {
+              readme += "\n== My Additional Header ==\n\n My additional text";
+              return readme;
+          }
+		}
+      },
+      with_appended_header_post_convert: {
+		files: {
+          'tmp/readme-post-convert-filter.md': 'test/fixtures/readme.txt',
+		},
+		options: {
+          screenshot_url: 'http://ps.w.org/{plugin}/assets/{screenshot}.png',
+          post_convert: function( readme ) {
+              readme += "\n== My Additional Header ==\n\nHeader is not converted as it is added after conversion.";
+              return readme;
+          }
+		}
+      },
     },
 
     // Unit tests.

README.md

@@ -50,6 +50,18 @@ There are placeholders to available for use in the URL structure. `{plugin}` is
 
 **\*** Actual URL of the wordpress.org hosted screenshots can vary. Please see [#14](https://github.com/stephenharris/wp-readme-to-markdown/issues/14) for details.
 
+#### pre_convert
+Type: `function`    
+Default value: `noop`
+
+A function which filters the value of the original readme file before it is converted. You should return the (modified) content. Returning a `false` value has the same effect as not providing a callback at all: the original readme file content is used.
+
+#### pre_convert
+Type: `function`    
+Default value: `noop`
+
+A function which filters the value of the converted readme content immediately before it is written to file. You should return the (modified) content. Returning a `false` value has the same effect as not providing a callback at all: the converted readme content is written to file unchanged.
+
 ### Usage Examples
 
 #### Default Options

tasks/wp_readme_to_markdown.js

@@ -16,7 +16,9 @@ module.exports = function(grunt) {
  grunt.registerMultiTask('wp_readme_to_markdown', 'Converts WP readme.txt file to markdown (readme.md)', function() {
 
 	var options = this.options({
-		screenshot_url: false
+		screenshot_url: false,
+		pre_convert: function( readme ){},
+		post_convert: function( readme ){}
 	});
 
 	grunt.verbose.writeflags( options );
@@ -36,6 +38,8 @@ module.exports = function(grunt) {
 			return grunt.file.read(filepath);
 		}).join(grunt.util.normalizelf(' '));
 
+		readme = options.pre_convert(readme) || readme;
+
 		/* The following is a ported version of {@see https://github.com/benbalter/WP-Readme-to-Github-Markdown}*/
 
 		//Convert Headings
@@ -116,6 +120,8 @@ module.exports = function(grunt) {
 			return "\n\t" + lines.join("\n\t") + "\n"; //trailing newline is unnecessary but adds some symmetry.
 		});
 
+		readme = options.post_convert(readme) || readme;
+
 		// Write the destination file.
 		grunt.file.write( f.dest, readme );
 

test/expected/readme-post-convert-filter.md

@@ -0,0 +1,127 @@
+# Plugin Name #
+**Contributors:** [stephenharris](https://profiles.wordpress.org/stephenharris)  
+**Donate link:** http://example.com/  
+**Tags:** comments, spam  
+**Requires at least:** 3.0.1  
+**Tested up to:** 3.4  
+**Stable tag:** 4.3  
+**License:** GPLv2 or later  
+**License URI:** http://www.gnu.org/licenses/gpl-2.0.html  
+
+Here is a short description of the plugin.  This should be no more than 150 characters.  No markup here.
+
+## Description ##
+
+This is the long description.  No limit, and you can use Markdown (as well as in the following sections).
+
+For backwards compatibility, if this section is missing, the full length of the short description will be used, and
+Markdown parsed.
+
+A few notes about the sections above:
+
+*   "Contributors" is a comma separated list of wp.org/wp-plugins.org usernames
+*   "Tags" is a comma separated list of tags that apply to the plugin
+*   "Requires at least" is the lowest version that the plugin will work on
+*   "Tested up to" is the highest version that you've *successfully used to test the plugin*. Note that it might work on
+higher versions... this is just the highest one you've verified.
+*   Stable tag should indicate the Subversion "tag" of the latest stable version, or "trunk," if you use `/trunk/` for
+stable.
+
+    Note that the `readme.txt` of the stable tag is the one that is considered the defining one for the plugin, so
+if the `/trunk/readme.txt` file says that the stable tag is `4.3`, then it is `/tags/4.3/readme.txt` that'll be used
+for displaying information about the plugin.  In this situation, the only thing considered from the trunk `readme.txt`
+is the stable tag pointer.  Thus, if you develop in trunk, you can update the trunk `readme.txt` to reflect changes in
+your in-development version, without having that information incorrectly disclosed about the current stable version
+that lacks those changes -- as long as the trunk's `readme.txt` points to the correct stable tag.
+
+    If no stable tag is provided, it is assumed that trunk is stable, but you should specify "trunk" if that's where
+you put the stable version, in order to eliminate any doubt.
+
+## Installation ##
+
+This section describes how to install the plugin and get it working.
+
+e.g.
+
+1. Upload `plugin-name.php` to the `/wp-content/plugins/` directory
+1. Activate the plugin through the 'Plugins' menu in WordPress
+1. Place `<?php do_action('plugin_name_hook'); ?>` in your templates
+
+## Frequently Asked Questions ##
+
+### A question that someone might have ###
+
+An answer to that question.
+
+### What about foo bar? ###
+
+Answer to foo bar dilemma.
+
+## Screenshots ##
+
+### 1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from ###
+![This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from](http://ps.w.org/plugin-name/assets/screenshot-1.png)
+
+the /assets directory or the directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets 
+directory take precedence. For example, `/assets/screenshot-1.png` would win over `/tags/4.3/screenshot-1.png` 
+(or jpg, jpeg, gif).
+### 2. This is the second screen shot ###
+![This is the second screen shot](http://ps.w.org/plugin-name/assets/screenshot-2.png)
+
+
+## Changelog ##
+
+### 1.0 ###
+* A change since the previous version.
+* Another change.
+
+### 0.5 ###
+* List versions from most recent at top to oldest at bottom.
+
+## Upgrade Notice ##
+
+### 1.0 ###
+Upgrade notices describe the reason a user should upgrade.  No more than 300 characters.
+
+### 0.5 ###
+This version fixes a security related bug.  Upgrade immediately.
+
+* Item 1 changed
+* Changes: 1, 2, 3
+
+## Arbitrary section ##
+
+You may provide arbitrary sections, in the same format as the ones above.  This may be of use for extremely complicated
+plugins where more information needs to be conveyed that doesn't fit into the categories of "description" or
+"installation."  Arbitrary sections will be shown below the built-in sections outlined above.
+
+This is testing handling of semicolons: The first part SHOULD NOT be wrapped in asterisks. That should happen in the header section only.
+
+## A brief Markdown Example ##
+
+Ordered list:
+
+1. Some feature
+1. Another feature
+1. Something else about the plugin
+
+Unordered list:
+
+* something
+* something else
+* third thing
+
+Here's a link to [WordPress](http://wordpress.org/ "Your favorite software") and one to [Markdown's Syntax Documentation][markdown syntax].
+Titles are optional, naturally.
+
+[markdown syntax]: http://daringfireball.net/projects/markdown/syntax
+            "Markdown is what the parser uses to process much of the readme file"
+
+Markdown uses email style notation for blockquotes and I've been told:
+> Asterisks for *emphasis*. Double it up  for **strong**.
+
+`<?php code(); // goes in backticks ?>`
+
+== My Additional Header ==
+
+Header is not converted as it is added after conversion.

test/expected/readme-pre-convert-filter.md

@@ -0,0 +1,127 @@
+# Plugin Name #
+**Contributors:** [stephenharris](https://profiles.wordpress.org/stephenharris)  
+**Donate link:** http://example.com/  
+**Tags:** comments, spam  
+**Requires at least:** 3.0.1  
+**Tested up to:** 3.4  
+**Stable tag:** 4.3  
+**License:** GPLv2 or later  
+**License URI:** http://www.gnu.org/licenses/gpl-2.0.html  
+
+Here is a short description of the plugin.  This should be no more than 150 characters.  No markup here.
+
+## Description ##
+
+This is the long description.  No limit, and you can use Markdown (as well as in the following sections).
+
+For backwards compatibility, if this section is missing, the full length of the short description will be used, and
+Markdown parsed.
+
+A few notes about the sections above:
+
+*   "Contributors" is a comma separated list of wp.org/wp-plugins.org usernames
+*   "Tags" is a comma separated list of tags that apply to the plugin
+*   "Requires at least" is the lowest version that the plugin will work on
+*   "Tested up to" is the highest version that you've *successfully used to test the plugin*. Note that it might work on
+higher versions... this is just the highest one you've verified.
+*   Stable tag should indicate the Subversion "tag" of the latest stable version, or "trunk," if you use `/trunk/` for
+stable.
+
+    Note that the `readme.txt` of the stable tag is the one that is considered the defining one for the plugin, so
+if the `/trunk/readme.txt` file says that the stable tag is `4.3`, then it is `/tags/4.3/readme.txt` that'll be used
+for displaying information about the plugin.  In this situation, the only thing considered from the trunk `readme.txt`
+is the stable tag pointer.  Thus, if you develop in trunk, you can update the trunk `readme.txt` to reflect changes in
+your in-development version, without having that information incorrectly disclosed about the current stable version
+that lacks those changes -- as long as the trunk's `readme.txt` points to the correct stable tag.
+
+    If no stable tag is provided, it is assumed that trunk is stable, but you should specify "trunk" if that's where
+you put the stable version, in order to eliminate any doubt.
+
+## Installation ##
+
+This section describes how to install the plugin and get it working.
+
+e.g.
+
+1. Upload `plugin-name.php` to the `/wp-content/plugins/` directory
+1. Activate the plugin through the 'Plugins' menu in WordPress
+1. Place `<?php do_action('plugin_name_hook'); ?>` in your templates
+
+## Frequently Asked Questions ##
+
+### A question that someone might have ###
+
+An answer to that question.
+
+### What about foo bar? ###
+
+Answer to foo bar dilemma.
+
+## Screenshots ##
+
+### 1. This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from ###
+![This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from](http://ps.w.org/plugin-name/assets/screenshot-1.png)
+
+the /assets directory or the directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets 
+directory take precedence. For example, `/assets/screenshot-1.png` would win over `/tags/4.3/screenshot-1.png` 
+(or jpg, jpeg, gif).
+### 2. This is the second screen shot ###
+![This is the second screen shot](http://ps.w.org/plugin-name/assets/screenshot-2.png)
+
+
+## Changelog ##
+
+### 1.0 ###
+* A change since the previous version.
+* Another change.
+
+### 0.5 ###
+* List versions from most recent at top to oldest at bottom.
+
+## Upgrade Notice ##
+
+### 1.0 ###
+Upgrade notices describe the reason a user should upgrade.  No more than 300 characters.
+
+### 0.5 ###
+This version fixes a security related bug.  Upgrade immediately.
+
+* Item 1 changed
+* Changes: 1, 2, 3
+
+## Arbitrary section ##
+
+You may provide arbitrary sections, in the same format as the ones above.  This may be of use for extremely complicated
+plugins where more information needs to be conveyed that doesn't fit into the categories of "description" or
+"installation."  Arbitrary sections will be shown below the built-in sections outlined above.
+
+This is testing handling of semicolons: The first part SHOULD NOT be wrapped in asterisks. That should happen in the header section only.
+
+## A brief Markdown Example ##
+
+Ordered list:
+
+1. Some feature
+1. Another feature
+1. Something else about the plugin
+
+Unordered list:
+
+* something
+* something else
+* third thing
+
+Here's a link to [WordPress](http://wordpress.org/ "Your favorite software") and one to [Markdown's Syntax Documentation][markdown syntax].
+Titles are optional, naturally.
+
+[markdown syntax]: http://daringfireball.net/projects/markdown/syntax
+            "Markdown is what the parser uses to process much of the readme file"
+
+Markdown uses email style notation for blockquotes and I've been told:
+> Asterisks for *emphasis*. Double it up  for **strong**.
+
+`<?php code(); // goes in backticks ?>`
+
+## My Additional Header ##
+
+ My additional text

test/wp_readme_to_markdown_test.js

@@ -86,4 +86,24 @@ exports.wp_readme_to_markdown = {
 
     test.done();
   },
+
+  with_appended_header_pre_convert: function( test ){
+    test.expect(1);
+
+    var actual = grunt.file.read('tmp/readme-pre-convert-filter.md');
+    var expected = grunt.file.read('test/expected/readme-pre-convert-filter.md');
+    test.equal(actual, expected );
+
+    test.done();
+  },
+
+  with_appended_header_post_convert: function( test ){
+    test.expect(1);
+
+    var actual = grunt.file.read('tmp/readme-post-convert-filter.md');
+    var expected = grunt.file.read('test/expected/readme-post-convert-filter.md');
+    test.equal(actual, expected );
+
+    test.done();
+  },
 };