NAME

Eshu - Fast indentation fixer for C, Perl and XS source files

SYNOPSIS

use Eshu;

# Fix indentation for a specific language
my $fixed_c    = Eshu->indent_c($source);
my $fixed_pl   = Eshu->indent_pl($source);
my $fixed_xs   = Eshu->indent_xs($source);

# Auto-dispatch by language name
my $fixed = Eshu->indent_string($source, lang => 'perl');

# Use spaces instead of tabs
my $fixed = Eshu->indent_c($source,
    indent_char  => ' ',
    indent_width => 4,
);

# Detect language from filename
my $lang = Eshu->detect_lang('lib/Foo.pm');  # 'perl'

DESCRIPTION

Eshu is an XS-powered indentation fixer that rewrites leading whitespace in C, Perl and XS source files. It tracks brace/bracket/paren nesting depth and re-emits each line with correct indentation while leaving the content of each line untouched.

Eshu understands language-specific constructs that affect indentation:

C — strings, comments, preprocessor directives, block nesting

Perl — heredocs, regex, qw()/qq()/q(), s////tr////y///, pod sections, comments

XS — dual-mode scanning (C section above MODULE =, XS section below), XSUB boundaries, label detection (CODE:, OUTPUT:, BOOT:, etc.), C nesting within code body sections

The engine is written in C for speed and operates as a single-pass line-by-line scanner.

METHODS

indent_c

my $out = Eshu->indent_c($source, %opts);

Fix indentation of C source code. Tracks {}, (), [] nesting, handles C strings, character literals, line and block comments, and preprocessor directives.

indent_pl

my $out = Eshu->indent_pl($source, %opts);

Fix indentation of Perl source code. In addition to brace nesting, handles heredocs (<<EOF, <<~EOF, <<'EOF', <<"EOF"), regex literals, qw()/qq()/q() constructs with paired and non-paired delimiters, multi-section operators (s///, tr///, y///), pod sections (=head1 through =cut), and line comments.

indent_xs

my $out = Eshu->indent_xs($source, %opts);

Fix indentation of XS source files. Operates in dual mode: lines above the first MODULE = ... line are processed as C; lines below are processed as XS with XSUB boundary detection, label recognition, and C nesting tracking within code body sections. BOOT: sections use a shallower indentation depth than other labels.

indent_string

my $out = Eshu->indent_string($source, lang => $lang, %opts);

Dispatch to the appropriate engine based on the lang parameter:

c (default) — calls "indent_c"

perl or pl — calls "indent_pl"

xs — calls "indent_xs"

detect_lang

my $lang = Eshu->detect_lang($filename);

Return a language string based on the file extension, suitable for passing to "indent_string". Returns undef for unrecognised extensions.

.c, .h       → 'c'
.xs          → 'xs'
.pl, .pm, .t → 'perl'

OPTIONS

All indentation methods accept the following options as key-value pairs:

indent_char

Character to use for indentation. Either "\t" (tab, the default) or " " (space).

indent_width

Number of characters per indentation level. Defaults to 1 for tabs. Typically set to 2 or 4 when using spaces.

indent_pp

Boolean. When true, indent C preprocessor directives according to their #if/#endif nesting depth. Defaults to 0 (preprocessor directives stay at column 0). Only meaningful for C and XS engines.

CLI

Eshu ships with a command-line tool:

# Fix a file in-place
eshu --fix lib/Foo.pm

# Preview changes as a diff
eshu --diff lib/Foo.pm

# CI check — exit 1 if file would change
eshu --check lib/Foo.pm

# Read stdin, write stdout
cat messy.c | eshu --lang c

# Use 4-space indentation
eshu --spaces 4 --fix src/bar.c

Run eshu --help for the full list of options.

AUTHOR

LNATION <email@lnation.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Eshu

perl -MCPAN -e shell
install Eshu