Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/benkasminbullock/sane-perl-mode

Fork of cperl-mode.el
https://github.com/benkasminbullock/sane-perl-mode

Last synced: 7 days ago
JSON representation

Fork of cperl-mode.el

Awesome Lists containing this project

README 

        
=encoding UTF-8



=pod



=head1 NAME



sane-perl-mode - a fork of cperl-mode to fix long-standing bugs



=head1 DESCRIPTION



This is a fork of the Emacs Perl-editing mode cperl-mode.el. We made

this to fix some very long-term problems with cperl-mode.



At the moment we're documenting using this README.



=head1 CHANGES FROM CPERL-MODE



This section describes the significant changes to the behaviour of

sane-perl-mode compared to cperl-mode. See also L for

details of bug fixes.



=head2 No error messages each time the m or s key is pressed



In cperl-mode, Emacs produces an error message about matching

parentheses not being found every time the "m" or "s" key is

pressed. In sane-perl-mode, these error messages have been

eliminated. This is the origin of the word "sane" in the name of this

fork.



Whilst labelling cperl-mode and its maintainers as "insane" might be

excessive, it's very difficult to imagine what the people who made

Emacs produce an error message each time the keys m or s are pressed

were thinking about. With Emacs 27, the screen would scroll when the

error messages were produced, so typing "m" or "s" when entering

keywords like C or C would cause the Emacs window to suddenly

scroll. 



This bug has been reported over and over by many people to the

cperl-mode maintainers. BKB pointed the problem out to Ilya

Zakharevich on the usenet newsgroup comp.lang.perl.misc in about 2007

or so, so it's been there for at least fourteen years. However, they

have not taken any action.



Anyway the bug is fixed here. We hope it helps you restore your

sanity.



=head2 Far-right indentation



Indenting the contents of C and C far to the right of the

page can now be altered to indent the contents using the normal

indentation. To switch off the far-right indentation, set the option

C to C in F<.emacs> or its

equivalent with



    (setq sane-perl-indentable-indent nil)



Once this option is set, the "far right" indentation



    my @array = qw!

                      far

                      right

                      indentation

                  !;



will be indented as



    my @array = qw!

        normal

        indentation

    !;



Similarly for regular expressions using the C format.



This fix comes from the L, but it

hadn't been applied in the L fork which sane-perl-mode

originates from, so it's been added on here. Further to the jrockway

fork fix, sane-perl-mode also puts the indentation of the !; at the

end on the left rather than under the final line, as shown above. The

jrockway fork currently does the following:



    my @array = qw!

        normal

        indentation

        !;



=head2 Indent brace bug



The "indent brace bug" happens in cperl-mode when

C is set to a non-zero value. It

causes the opening brace of a subroutine to be indented four spaces:



    sub xyz

        {



instead of



    sub xyz

    {



This is fixed in sane-perl-mode.



=head2 Indentation styles



Sane-Perl-Mode provides various indentation styles via the function



    (sane-perl-set-style "BSD")



and examples of what the indentation styles are supposed to look

like. However, at the time we forked the module, the indentation

actually produced differed in most of the cases from the examples

provided. For example, the example of Whitesmith indentation from the

cperl-mode documentation looks like this:



    if (foo)

        {

            bar

                baz;

        label:

            {

                boon;

            }

        }

    else

        {

            stop;

        }



However, the output of C C

C is as follows:



    if (foo) {

        bar

            baz;

     label:

        {

    	    boon;

        }

    } else {

        stop;

    }



Styles where the cperl-mode documentation example did not match the

output are C, C, C, and C.  C, C,

and C, and the default C were already indenting

as per the documentation. We have altered either the settings or the

example to bring them into agreement.



In cases where we didn't know what to do, we initially followed the

examples and modified the indentation styles to look more like

them. However, as it turned out, at least the K&R and the Whitesmith

indentation of cperl-mode are both fairly wildly different from their

usual meanings, for some reason or another. In these cases the

indentation of sane-perl-mode was altered from cperl-mode's to bring

them closer to where they should have been originally.



=head2 Documentation improvements



Spelling and grammar mistakes have been fixed. Some attempt has been

made to make the tone of the documentation more professional. Much of

the cperl-mode documentation seemed to be designed to deliberately

confuse users, or give opinions rather than facts.



We've also done some work on the one-line documentation which comes

with cperl-mode.



=head2 Changes to defaults



Some of the default behaviours of cperl-mode have been changed.



=head3 Underlining of trailing whitespace



The cperl-mode default of using underscores for displaying trailing

whitespace has been switched off. Trailing whitespace is harmless in

Perl, and hardly merits being highlighted in an exaggerated way,

especially since even whitespace in comments was highlighted. Further,

the underscores were also misleading. For example, after a dollar the

underscore would appear as C<$_> (the default variable) when in fact

there was no C<_> there.



cperl-mode requires a setting



    (setq cperl-invalid-face nil)



to stop it from adding underscores to trailing whitespace. This is

switched off by default in sane-perl-mode. To restore it, add



    (setq sane-perl-invalid-face 'underline)



to F<.emacs>. 



=head3 Untabifying by delete is off



Untabifying by delete (turning a tab character into spaces when

deleting whitespace) was switched off. It's still in the mode as a

user option.



=head3 Font lock mode changes



Emacs has had font-lock-mode on globally by default since 2007, but in

cperl-mode the default for the variable C is to be

turned off. 



In the development of sane-perl-mode, we discovered that the default

inherited from cperl-mode of having C switched

off with Emacs' C on causes some very odd behaviour.



We've thus switched it on as the default. It can still be switched off

using



    (setq sane-perl-font-lock nil)



In this case, C itself will be switched off for the

Perl buffer as well, otherwise the option doesn't really make sense.



=head2 Removal of obsolete and non-core support



=head3 Version control systems



Support for the CVS, RCS, and SCCS version control systems has been

removed.



=head3 Moose and other non-core modules



Support for Moose, Zydeco, and other module-specific keywords has been

removed.



=head3 Opinion-comments removed



Editorial comments about the future of Perl development and other

things have been removed from the mode. Since these are a single

person's opinions, and there have been at least five maintainers of

this mode so far, it's not clear who the opinions belonged to, and it

doesn't make sense to keep them in a mode maintained by other people

who may not share the opinions.



=head3 Removal of commented out and obsolete code



Commented-out code and clearly obsolete code referring to versions of

Emacs from the 1990s have been removed. See also L by

Nayuki.



=head1 TESTING



The tests for the mode run Emacs in batch mode and then compare the

results to expected outputs using Perl's L framework. They

can be run using the Perl utility L as



    prove t/*.t



from the top directory.



Currently the following tests exist:



=over



=item Non far-right indentation



Tests of the C and C non-far-right indentation have been

added in F and F. See L.



=item Invert-if



CPerl mode contains a facility to switch between trailing if and

leading if, as in



     if (condition) {

         something;

     }



and



     something if condition;



Testing of these in Sane Perl mode, renamed

C and

C, is in F



=item Staircase indentation



The staircase indentation bug is a bug where cperl-mode would indent

as follows:



    use constant {

      ONE => 1,

        TWO => 2

    };



Testing of the "staircase indentation" bug is in F. The

indentation of the cperl-mode we originally forked from seems to be

working at the moment.



=item Indentation of braces



The provisional fix of the L is tested in

F



=item Trailing whitespace



Underlining of trailing whitespace is no longer the default but it is

supported as an option. See L. Tests of its functioning, if the user chooses to switch

it back on, is in F.



=item Byte compilation



The errors generated by Emacs on byte-compiling cperl-mode.el have all

been fixed in sane-perl-mode.el. Tests of this are in

F.



=item Parsing links in Pod



Cperl mode displays perl documentation using pod2html, but it uses an

extra stage before displaying it in a help buffer which changes the

links to an Emacs-valid format. There were some problems with parsing

nested Pod commands within links and parsing things of the form

C. These have been fixed in

sane-perl-mode.el. Tests are in F.



=item Example indentations



The test F tests whether sane-perl-mode produces the

same indentation as the example indentations in the document. See

L for details.



=item Semi-colon bug



A test of our fix of the semicolon bug, where C<};> (for example at

the end of a BEGIN block) used to be mistakenly converted into



    }

    ;



on applying C is in F.



=item Support for named captures in regexes



Named captures in regexes of the form



    m/(?.*abc)/



no longer cause a "warning" display.



=item Tests of CPerl-Mode features



We have added some tests of CPerl-Mode features such as its documented

indentation options in F and F, as

regression tests to make sure that this mode doesn't start misbehaving

in unexpected ways. All of the C options need to use

C as the prefix but otherwise should work the same way,

unless otherwise documented. See L for what

options have been changed so far.



=back



=head1 BUGS



Please report bugs at L. There

is also L

if you're not sure whether to report a bug or just ask a question.



=head1 PERLTIDY EQUIVALENTS



This section details similar and equivalent commands between the

L utility and C.



=cut



# Alphabetical order



=pod



=over



=item sane-perl-extra-newline-before-brace



This option is C by default. Setting this to C is equivalent

to C<-bl> or C<--opening-brace-on-new-line> in perltidy.



    (setq sane-perl-extra-newline-before-brace t)



=item sane-perl-indent-left-aligned-comments



This option is C by default. This corresponds to setting C<-ibc> or

C<--indent-block-comments> in perltidy. A C value corresponds to

C<-nibc> in perltidy.



    (setq sane-perl-indent-left-aligned-comments nil)



=item sane-perl-indent-level



This variable's default is C<2>. This corresponds to C<-i=2> or

C<--indent-columns=2> in perltidy. To get the same value as perltidy's

default of 4, use



    (setq sane-perl-indent-level 4)



=item sane-perl-merge-trailing-else



This option is C by default. This corresponds to C<-ce> or

C<--cuddled-else> in perltidy. Setting this to C is equivalent to

C<-nce> or C<--nocuddled-else> in perltidy.



    (setq sane-perl-merge-trailing-else nil)



=back



=head1 SEE ALSO



=head2 cperl-mode



Other significant forks of cperl-mode are as follows:



=over 



=item emacs-mirror



L



The original cperl-mode.el is actively being improved for modern

versions of Emacs in the original Emacs trunk.



=item HaraldJoerg



L



This is a fork of jrockway's cperl-mode fork. The author also

contributes to the original Emacs cperl-mode.el at L.



=item jrockway



L



This was a fork of Ilya Zakharevich's cperl-mode which was originally

about adding Moose keywords, but then graduated to being some kind of

default for a few years as Ilya Z. was not active.



=back



=head2 CPAN modules



(We have assumed that CPAN modules related to Emacs which haven't had

a release for over ten years are defunct and have not included them

here.)



=over



=item L



This contains Emacs lisp scripts to run L and other

facilities.



=back



=head2 Other information



=over



=item L



=item L



=back



=head1 AUTHORS



The person responsible for this fork is Ben Bullock,

, . The authors and

maintainers of the CPerl mode which it forked from are listed in the

source code of the file.



=head1 LICENCE



C is free software: you can redistribute it and/or

modify it under the terms of the GNU General Public License as

published by the Free Software Foundation, either version 3 of the

License, or (at your option) any later version.