From 670320d27106de3db5d89d45e2482ecc3f149cfc Mon Sep 17 00:00:00 2001 From: Stephen Harris Date: Tue, 31 May 2016 12:15:45 +0100 Subject: [PATCH] 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 | 24 ++++ README.md | 12 ++ tasks/wp_readme_to_markdown.js | 8 +- test/expected/readme-post-convert-filter.md | 127 ++++++++++++++++++++ test/expected/readme-pre-convert-filter.md | 127 ++++++++++++++++++++ test/wp_readme_to_markdown_test.js | 20 +++ 6 files changed, 317 insertions(+), 1 deletion(-) create mode 100644 test/expected/readme-post-convert-filter.md create mode 100644 test/expected/readme-pre-convert-filter.md diff --git a/Gruntfile.js b/Gruntfile.js index eb5b3b4..edbd6ac 100644 --- a/Gruntfile.js +++ b/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. diff --git a/README.md b/README.md index ac6418c..7277f73 100644 --- a/README.md +++ b/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 diff --git a/tasks/wp_readme_to_markdown.js b/tasks/wp_readme_to_markdown.js index a19c83d..84fddb3 100644 --- a/tasks/wp_readme_to_markdown.js +++ b/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 ); diff --git a/test/expected/readme-post-convert-filter.md b/test/expected/readme-post-convert-filter.md new file mode 100644 index 0000000..f54adc9 --- /dev/null +++ b/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 `` 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**. + +`` + +== My Additional Header == + +Header is not converted as it is added after conversion. \ No newline at end of file diff --git a/test/expected/readme-pre-convert-filter.md b/test/expected/readme-pre-convert-filter.md new file mode 100644 index 0000000..3499e2f --- /dev/null +++ b/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 `` 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**. + +`` + +## My Additional Header ## + + My additional text \ No newline at end of file diff --git a/test/wp_readme_to_markdown_test.js b/test/wp_readme_to_markdown_test.js index 66cfc7d..838533d 100644 --- a/test/wp_readme_to_markdown_test.js +++ b/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(); + }, };