Zeno's Notes


2 notes

Creating a Padre plugin and uploading it to CPAN in 7 simple steps

Last week, Gabor published a screencast on how to create a basic plug-in for Padre. Today I will continue a little bit along that direction, and give an example for a plug-in that improves handling a certain file type in Padre.


YAML is a lightweight file format used for data serialization and configuration files. You can think of it as an (often better) replacement for XML. I have not used YAML a lot yet, but recently came across it several times: It is used for configuring CPAN and CPAN::Reporter::Smoker, and also by Padre itself, for setting up syntax highlighting.

Padre has, through Scintilla, syntax highlighting support for YAML, which is nice. However, it does not support any further functions for YAML. For example, the keyboard shortcut Shift-Control-C to toggle comment in/out the current line (or selection) is deactivated for YAML files.

The solution: a YAML plugin

To reproduce those steps, you need to have Padre and Dist::Zilla installed on your system. Other than that, you only need basic knowledge of modern Perl, the rest will be explained. If something is not explained, please send me an e-mail and I will fix it.

Here is what I did to create the YAML plugin (explanations follow):

  1. dzil Padre-Plugin-YAML; cd Padre-Plugin-YAML
  2. create dist.ini and Changes file
  3. edit lib/Padre/Plugin/YAML.pm
  4. create lib/Padre/Document/YAML.pm
  5. dzil install or sudo dzil install
  6. enable YAML plugin in Padre’s plugin manager (see screenshot below)
  7. dzil release - don’t perform that step; do that with your own plugin ;-)

While you repeat these steps, you may adapt your actions to actually implement a new plugin for your favourite document type …


So what is happening here?

1. creates the skeleton of the distribution (CPAN package, usually containing one or more Perl modules).

2. Changes is the usual changelog file, nothing particularly interesting here. dist.ini is the central configuration file for Dist::Zilla. The dzil command will take this file (and the source code) to create all the other important but boring files that are necessary for a good CPAN module.

name             = Padre-Plugin-YAML
author           = Zeno Gantner 
license          = Perl_5
version          = 0.01
copyright_holder = Zeno Gantner


homepage         = http://padre.perlide.org
repository       = http://svn.perlide.org/padre/trunk/Padre-Plugin-YAML/

Padre            = 0.81


The fields should be pretty self-explanatory. If you have several authors, you can add several author lines, and add the additional authors to the copyright_holder entry. The section [@PadrePlugin] contains fields specific to Dist::Zilla’s extension for Padre plugins, but in this case this is only the pointer to the Padre homepage, and the URL where the plugin source code can be found. If you write your own plugin and do not use the Padre subversion repository. The last entry specifies the from which version on Padre will be able to use this plugin. If your plugin requires additional CPAN modules, specify them here is well.

3. lib/Padre/Plugin/YAML.pm is the plugin class. Click on the link to see its contents. All important functionality is defined by methods:

  • plugin_name contains the name of the plugin as it will show up in Padre’s plugin manager and in the plugin menu.
  • padre_interfaces defines the interface versions the plugin implements, so that the plugin manager knows whether it can load the plugin.
  • registered_documents contains a mapping from MIME types as defined in Padre::MimeTypes to class names. The referenced classes will be responsible for additional functionality for the given MIME type, and should be of course included with the plugin. In our case, it is Padre::Document::YAML, which is described in the next step.
  • plugin_icon can be used to set an icon which wíll be displayed in the plugin manager. If you add an icon to your plugin, make sure it is properly licensed, and explain the licensing in a README file in the directory where the icons are.
  • menu_plugin_simple defines the plugin menu. Gabor covered this in his screencast in detail.

The POD of Padre::Plugin contains descriptions of several other methods of that class. Note that strings which will be showed to the user usually are enclosed in Wx::gettext() calls. This is necessary for translating the plugin. I will explain this in a later blog post.

4. lib/Padre/Document/YAML.pm is the document class mentioned before. Click on the link to see its contents.

  • task_functions, task_outline, and task_syntax can be used to refer to appropriate classes for the advanced features function list, outline, and syntax checking (see next screenshot). We ignore them for now.
  • comment_lines_str tells Padre how a comment line starts for this kind of file. There are some document types that only have bracket comments, e.g. XML or HTML. For those cases, the function takes two arguments, the first for the start of the comment, the second for the end.

Again, the documentation of the parent class contains further information.

5. That’s it already. Install your shiny new plugin, and (6.) enable it in the Padre plugin manager:

7. If you have a PAUSE account and have developed a new plugin instead of the YAML plugin, you can upload your creation to CPAN with  dzil release.

Why not include it directly with Padre?

If there are no additional dependencies, easy things like shell script or YAML support may be better placed in Padre itself than in separate plug-ins. However, if you have advanced features like the outline, syntax checking, etc., it is very likely that you will use additional CPAN modules. Padre is already quite heavy when it comes to module dependencies, so it is better to have the additional dependencies in an external distribution that users may install in case they need it.

Make your own plugin

So now that you have learned how to do it, go ahead and create a plugin for your favourite programming language/file type. If your plugin could be useful for others, consider uploading it to CPAN. Many plugins are in the Padre subversion repository; this would be a natural place to also host new Padre plugins, and to lure others into contributing to your plugin.


Of course, syntax highlighting and toggling comments is not the only functionality you want for a file type. There are several possible extensions to the YAML plugin, and will do them step by step when I have the time, and blog about it:

  1. Translate the plugin’s messages into other languages.
  2. Autocompletion
  3. Syntax checking
  4. Document outline

If you want answers right now to these questions, then have a look at the source code of the LaTeX plugin. Otherwise, stay tuned for more detailed explanations …

Besides continuing the development of the YAML plugin, there are several other aspects that I want to cover here in the future:

  1. How to add support for an entirely new file type: The YAML MIME type is already recognized by Padre. But what to do if this is not the case?
  2. A few file types have some syntax highlighting support in Padre, but it could be nicer. How can this be fixed?

Finally, if something is not clear in this howto, or if you have other questions or feedback, do not hesitate to leave a comment here or send me an e-mail: zenog@cpan.org

modified June 29, 2011: added links to POD of Padre::Plugin and Padre::Document

Filed under YAML editor feature ide modern perl padre perl plugin programming dzil Dist::Zilla CPAN PAUSE module

  1. zenoga posted this