Installation

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.

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:

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:

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:

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:

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

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:

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.