Perltidy

Official perltidy style

Koha has an official perltidy style that should always be used (see the Coding Guidelines: PERL1:Perltidy).

You can find the Koha perltidy configuration file, .perltidyrc, in the root directory of the Koha repository.

It was added on 2023-06-08 by bug 30002.

Setup

From the root of the Koha repository, specify the perltidy configuration file to use:

$ perltidy -pro=/home/path/to/.perltidyrc

Transition and best practices

Only perltidy modified code

For historical Koha code: only perltidy the specific code block that you are modifying...and no more! (um.. unless it's really really fugly :p)

In other words, please don't perltidy entire files or send patches that contain perltidy changes to code other than the code-block being modified.

If you really do need to perltidy entire files, then these should be submitted as a separate patch in the bug (the same as when fixing indentation - see the Coding Guidelines: Indentation).

It will be a slow transition

We are currently taking a gently/slowly approach as the Koha codebase transitions to the official perltidy style.

Using perltidy in your editor

The Brief Perltidy Tutorial has a section on using perltidy on selected text.

Visual Studio Code (VSCode)

If you are using VSCode for Koha development, you are most likely using the Perl extension.

This extension allows you to tidy code using perltidy.

Configuration

To configure VSCode to use perltidy:

1. Go to File > Preferences > Settings.
2. Search for perltidy and you will be presented with the Perl:Perltidy and Perl:Perltidy Args options.
3. Make sure Perl:Perltidy points to a valid executable (usually just perltidy is good enough, but you might need to adjust for different operating systems).
4. For Perl:Perltidy Args, edit settings.json and make sure it looks like:

    "perl.perltidyArgs": [
        "-pro=/home/path/to/.perltidyrc"
    ]

Usage

Select a code region and use Ctrl+k Ctrl+f.

Geany

Configuration

To configure Geany to use perltidy:

1. Go to Edit > Format > Send Selection to > Set Custom Commands
2. Set a custom command to use perltidy by clicking Add, then:
   • Command: perltidy --pro=/home/path/to/.perltidyrc
   • Label: perltidy

Usage

1. Select part of your file or script
2. Now you can perltidy using the menu or the keyboard shortcut:
   • Edit > Format > Send Selection to > perltidy
   • Use the keyboard shortcut assigned to the entry. Example Ctrl+1.

VIM

Configuration

To configure VIM to use perltidy, add the following line to your .vimrc:

vmap <F8> :!perltidy -q<CR>

Koha testing docker

You do not need to configure VIM to use perltidy, it is already configured in KTD.

Usage

Switch to visual mode (Ctrl+v), select a block, then press F8.

Koha testing docker

Switch to visual mode (Ctrl+v), select a block, then type :Tidy.