perltidy for Sublime Text 2/3

PerlTidy is a plugin for Sublime Text 2/3, which integrates the command line application perltidy into Sublime Text. It indents and reformats Perl source code to make it easier to read.

Quick start

• Ensure, you have a Perl interpreter and perltidy installed (hint: apt-get install perltidy, yum install perltidy, cpan[m] Perl::Tidy, ppm install Perl-Tidy)
• Install this plugin in Sublime Text via Package Control, git or from ZIP (in Sublime Text the plugin is named PerlTidy, not SublimePerlTidy)
• Open a Perl source file and hit Control+Shift+t

Read on for detailed installation, usage, configuration and customization instructions.

Table of contents

• Installation
• Usage
• Configuration
• Troubleshooting
• Miscellaneous
• TODOs
• Say thanks
• Changes

Installation

• With Sublime Package Control: The easiest way to install PerlTidy is through Sublime Package Control. If you're not using it yet, get it. Seriously.

Once you have installed Package Control, restart Sublime Text and bring up the Command Palette (press Control+Shift+P on Linux/Windows, Command+Shift+P on OS X, or select Tools->Command Palette... from menu). Select Package Control: Install Package, wait till latest package list has been fetched, then select PerlTidy from the list of available packages.

• With Git: Clone the repository in your Sublime Text Packages directory. Please note that the destination directory must be PerlTidy.

  git clone https://github.com/vifo/SublimePerlTidy PerlTidy
  

The advantage of using either Package Control or git is, that the plugin will be automatically kept up-to-date with the latest version.

• From ZIP: Download the latest version as a ZIP archive and copy the directory “SublimePerlTidy-master” from the archive to your Sublime Text Packages directory. Rename directory “SublimePerlTidy-master” to “PerlTidy”.

The Packages directory locations are listed below. If using Sublime Text 3, be sure to replace “2” with “3” in directory names. Alternatively, selecting Preferences->Browse Packages... from Sublime Text menu will get you to the Packages directory also.

Usage

After PerlTidy installation, open a Perl file of your choice and:

• hit Control+Shift+t
• or open Command Palette, start typing “perltidy”, select “PerlTidy: Tidy” and hit return

to reformat the entire file. PerlTidy also works on selections. Give it a try.

Configuration

Though usage of PerlTidy is quite simple and PerlTidy will do its very best to Just Work™, most aspects can be configured to suite your needs.

perltidy locations

PerlTidy will try to locate perltidy by:

1. Checking the user setting “perltidy_cmd” for a (valid) user supplied perltidy location.

2. Searching for “perltidy” (“perltidy.bat” on Windows) within directories specified in environment variable PATH.

3. Searching for perltidy in platform specific default locations. These are:

• On Windows (in given order):

Default Strawberry Perl installation location C:\Strawberry, i.e.:

"perltidy_cmd": [ "C:\\Strawberry\\perl\\bin\\perl.exe", "C:\\Strawberry\\perl\\site\\bin\\perltidy" ]

Default ActivePerl 64-bit installation location C:\Perl64, i.e.:

"perltidy_cmd": [ "C:\\Perl64\\bin\\perl.exe", "C:\\Perl64\\site\\bin\\perltidy" ]

Default ActivePerl 32-bit installation location C:\Perl, i.e.:

"perltidy_cmd": [ "C:\\Perl\\bin\\perl.exe", "C:\\Perl\\site\\bin\\perltidy" ]

Default Cygwin installation location C:\cygwin, i.e.:

"perltidy_cmd": [ "C:\\cygwin\\bin\\perl.exe", "/usr/local/bin/perltidy" ]

• On Linux and OS X:

/usr/bin/perltidy, /usr/local/bin/perltidy (which will most likely be in your PATH anyway), i.e.:

"perltidy_cmd": [ "/usr/bin/perltidy" ]

Let PerlTidy try to locate perltidy first. If this does not work, adjust user setting “perltidy_cmd” as needed.

perltidy options

By default, PerlTidy uses perltidy options as suggested in Damian Conway's Perl Best Practices (PBP). Though I don't agree with all of the perltidy settings in the PBP set, using them results in slightly better readable Perl code, than using perltidy's defaults. Since perltidy already supports the PBP set using the command line switch -pbp or --perl-best-practices, introducing just another set of options seems unnecessary.

So the default PerlTidy options are:

"perltidy_options": [ "-pbp" ]

which, at least with a recent perltidy version is effectively the same as:

"perltidy_options": [
    "-l=78", "-i=4", "-ci=4", "-vt=2", "-cti=0", "-pt=1", "-bt=1", "-sbt=1", "-bbt=1", "-nsfs", "-nolq",
    "-wbb=\"% + - * / x != == >= <= =~ !~ < > | & = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=\"",
    "-st", "-se"
]

Ermmm, what?! Fear not, here are the explanations (and differences with perltidy defaults):

You may override any of the above settings by changing user setting “perltidy_options” in your preferences, preferably including the -pbp option like this:

"perltidy_options": [ "-pbp", "-l=120" ]

Please refer to the official perltidy Documentation and the perltidy Style Guide for an explanation of all options available.

Key bindings

Defaults to Control+Shift+t on all platforms. Feel free to change this in Preferences->Key Bindings - User by adding and adjusting following lines:

// PerlTidy key bindings
{
    "keys": ["ctrl+shift+t"],
    "command": "perl_tidy",
    "context": [ { "key": "selector", "operator": "equal", "operand": "source.perl", "match_all": true } ]
}

Other settings

If you'd like to override specific settings, open Preferences->Settings - User and add/adjust the following lines:

// Specify full path to perltidy and optionally the Perl interpreter. If not
// specified, will search PATH for perltidy and fall back to platform default
// locations.
//
// Please note, that with Strawberry Perl/ActivePerl on Windows, you have to
// either specify the full path to the Perl interpreter AND the perltidy file
// (NOT "perltidy.bat"), OR the full path to the batch wrapper file
// "perltidy.bat". The former is preferred, we don't need the batch wrapper.
//
// Windows/Strawberry Perl/ActivePerl:
//"perltidy_cmd": [ "C:\\Strawberry\\perl\\bin\\perl.exe", "C:\\Strawberry\\perl\\site\\bin\\perltidy" ]
//"perltidy_cmd": [ "C:\\Perl\\bin\\perl.exe", "C:\\Perl\\site\\bin\\perltidy" ]
//
// Windows/Cygwin:
//"perltidy_cmd": [ "C:\\cygwin\\bin\\perl.exe", "/usr/local/bin/perltidy" ]
//
// Linux/OS X with non-standard location or explicit Perl interpreter:
//"perltidy_cmd": "/opt/perl/bin/perltidy"
//"perltidy_cmd": [ "/opt/perl-5.18.0/bin/perl", "/opt/perl-5.16.3/site/bin/perltidy" ]

// Specify possible perltidyrc files to search for within current project. The
// first matching perltidyrc will be used. Absolute paths may also be used, if
// you have a global perltidyrc. Defaults to [ ".perltidyrc", "perltidyrc" ].
//"perltidy_rc_paths": [ ".perltidyrc", "perltidyrc" ]
//"perltidy_rc_paths": [ "C:\\Users\\USERNAME\\AppData\\Roaming\\perltidyrc" ]

// Specify perltidy options. Defaults to: [ "-pbp" ]
//"perltidy_options": [ "-pbp" ]

// Specify, whether perltidy options given in "perltidy_options" take
// precedence over options found in perltidyrc files. Defaults to "false"
// (note: default value was "true" up to version 0.4.0). Adjust to "true" to
// reverse this order.
//"perltidy_options_take_precedence": false

// Log level for perltidy operations. Set to 1 to enable informational
// messages and to 2 for full debugging. Defaults to 0, so only warnings and
// errors will be displayed on the console.
//"perltidy_log_level": 0

// If, for some reason, you'd like to disable PerlTidy entirely, set
// "perltidy_enabled" to false. Defaults to true.
//"perltidy_enabled": true

Per project settings

You may override any of these settings per project, by adding a section named “settings” with overridden settings to your project file:

{
    "folders": [
        {
            "path": "..."
        }
    ],
    "settings": {
        "perltidy_log_level": 2,
        "perltidy_options": [ "-pbp", "-l=120", "-w" ]
    }
}

Troubleshooting

During normal operation, PerlTidy will emit warnings and errors to the Sublime Text console (open with Control+` or select View->Show Console from menu). In order to enable additional diagnostic messages, adjust user setting “perltidy_log_level” as follows:

• 0 == Warnings and error messages only. This is the default.

• 1 == Print system commands used for tidying up content and perltidyrc file paths used (if any).

• 2 == Full debugging. In addition to the above, print where PerlTidy searches for perltidy and/or perltidyrc.

Common Pitfalls

Windows Error 193

You are running Strawberry Perl/ActivePerl on Windows, and have set a custom path to perltidy via user setting “perltidy_cmd”. While trying to run, PerlTidy bails out with the following error message on the ST console:

PerlTidy: Unable to run perltidy: "C:\Strawberry\perl\site\bin\perltidy" ...
PerlTidy: OS error was: WindowsError(193, '...')
PerlTidy: Maybe you have specified the path to "perltidy" instead of "perltidy.bat" in your "perltidy_cmd"?

You have specified the path to the raw Perl “perltidy” file (without extension), instead of the batch wrapper file “perltidy.bat”. Windows is unable to execute the former file directly. Yes, typing “perltidy” in cmd.exe will work, but only due to the way, how cmd.exe handles files without an extension: it will try extensions specified in environment variable PATHEXT, eventually find the file “perltidy.bat” and run it.

TL;DR: Assuming you are running a vanilla Strawberry Perl/ActivePerl installation: adjust user setting “perltidy_cmd” to one of the following:

"perltidy_cmd": [ "C:\\Strawberry\\perl\\bin\\perl.exe", "C:\\Strawberry\\perl\\site\\bin\\perltidy" ]    # for Strawberry Perl
"perltidy_cmd": [ "C:\\Perl64\\bin\\perl.exe", "C:\\Perl64\\site\\bin\\perltidy" ]                        # for ActivePerl 64-bit
"perltidy_cmd": [ "C:\\Perl\\bin\\perl.exe", "C:\\Perl\\site\\bin\\perltidy" ]                            # for ActivePerl 32-bit

or, if you really need to use the batch wrapper for some (non-obvious) reasons, to:

"perltidy_cmd": "C:\\Strawberry\\perl\\site\\bin\\perltidy.bat"       # for Strawberry Perl
"perltidy_cmd": "C:\\Perl64\\site\\bin\\perltidy.bat                  # for ActivePerl 64-bit
"perltidy_cmd": "C:\\Perl\\site\\bin\\perltidy.bat"                   # for ActivePerl 32-bit

or just let PerlTidy figure out where perltidy is located by not setting “perltidy_cmd” at all.

Reporting bugs

In order to make bug hunting easier, please ensure, that you always run the latest version of PerlTidy. Apart from this, please ensure, that you've set PerlTidy log level to maximum ("perltidy_log_level": 2 in user settings), in order to get all debugging information possible. Also please include the following information, when submitting an issue:

• Operating system name (i.e. “Windows XP SP3”, not “Windows”)

• Operating system architecture (i.e. 32-bit, 64-bit)

• Sublime Text build number (open Help->About)

• Output from Sublime Text console

To gather this information quickly, open ST console, type in the following Python code as-is (in one line) and include its output in your issue:

from __future__ import print_function, unicode_literals;import platform, sublime, datetime;print('-' * 78);print('Date/time: {0}'.format(datetime.datetime.utcnow().strftime('%Y-%m-%d %H:%M:%S +0000')));print('Sublime Text version: {0}'.format(sublime.version()));print('Platform: {0}'.format(sublime.platform()));print('CPU architecture: {0}'.format(sublime.arch()));print('OS info: {0}'.format(repr(platform.platform())));print('-' * 78)

Miscellaneous

Standalone perltidy executable for Windows

If you're running Sublime Text on Windows and don't like to install a complete Perl interpreter just for using perltidy, grab the standalone perltidy executable from here and adjust your settings:

"perltidy_cmd": [ "C:\\WHEREVER_YOU_HAVE_DOWNLOADED_THE_EXE_TO\\perltidy-20121207-x86.exe" ]

This executable has been built with ActiveState ActivePerl 5.16.3.1603 x86 using PAR::Packer. It contains the Perl interpreter as well as the latest version of perltidy, including all required dependencies in a self contained executable (thus the size of 4.5 MB).

Please note: this executable works for me and is provided as-is, with no support whatsoever. If it also works for you, great! If not, please don't complain, but get a Perl interpreter and perltidy for Windows instead. Even better: fix errors, repackage (maybe using helper script “helpers/build_perltidy_20121207_x86.pl” as a starting point) and provide final executable to me for hosting on S3.

TODOs

• Implement automatic tidying of Perl files upon save. Until then, ST2-CommandOnSave might be an option to achieve this.

Say thanks

I spend a lot of my scarce free time working on this plugin, and would appreciate any support you'd care to offer. If using this plugin makes your coding life easier and more productive and you'd like to thank me, please consider:

• making a donation via PayPal
• star this plugin on GitHub
• twitter, blog or in general spread the word.

Please note that you don't have to do any of the above in order for me to continue to work on this plugin. I will continue to do so, for as long as it interests me and inasmuch I have free time to spend. Similarly, a donation made in this way probably won't make me work on this plugin harder, unless I get so many donations that I can consider working on it full time (which at least for now seems unlikely at best).

Thank You!

Changes

Only latest changes are listed here. Refer to full change log for all changes.

v0.4.5 2014-01-05 22:15:00 +0100

• Remove packages.json. Package Control versioning now done via git tags/semantic versioning.
• Stripped leading “v” from all tags.

v0.4.4 2014-01-03 09:30:00 +0100

• Bump version number in order to fix #22.