NAME

Regexp::Common::Emacs -- regexps for some Emacs filenames

SYNOPSIS

 use Regexp::Common 'Emacs', 'no_defaults';
 if ($str =~ /$RE{Emacs}{backup}/) {
    # ...
 }

 # regexp
 my $re1 = $RE{Emacs}{lockfile};

 # subroutine style to get regexp
 use Regexp::Common 'RE_Emacs_autosave';
 my $re2 = RE_Emacs_autosave();

DESCRIPTION

This module is regexps matching filenames used by Emacs. They're designed to operate only on the filename without a directory part, so

    foo.txt            good
    /dir/foo.txt       bad

Basename-only is because the directory and/or volume part is system dependent and best left to something like splitpath() from File::Spec. The basename is as per readdir() if scanning a directory.

See Regexp::Common for basic operation of Regexp::Common.

Patterns

$RE{Emacs}{backup}

Match an Emacs backup filename, with no directory part. This is filenames like

    foo.txt~          single
    foo.txt.~123~     numbered

The -keep option captures are

    $1    whole string
    $2    originating filename "foo.txt"
    $3    backup number "123", or undef if single

Options can restrict to numbered or single backups.

$RE{Emacs}{backup}{-numbered}

Match only numbered backup files, not single ones.

    foo.txt.~123~     matched
    foo.txt~          not matched

$RE{Emacs}{backup}{-notnumbered}

Match only single backup files, not numbered ones.

    foo.txt~          matched
    foo.txt.~123~     not matched

-numbered and -notnumbered are mutually exclusive. A given backup file matches just one of the two.

A file such as foo.txt.~123~ is presumed to be a numbered backup. It could be a single backup from foo.txt.~123, but files named that way ought to be unusual.

$RE{Emacs}{backup}{-single}

Match backup files and assume that they are always single backups. This pattern is anything ending ~.

    foo.txt~          matched
    foo.txt.~123~     matched, $2 = foo.txt.~123

This is the same as the default $RE{Emacs}{backup>, but the -keep originating name in $2 becomes everything before the ending ~, with no number part distinguished.

Emacs makes a backup file when first changing a file. The default is a single backup foo.txt~. The version-control variable can be set for rolling numbered backups foo.txt.~1~, foo.txt.~2~, foo.txt.~3~ etc.

See the GNU Emacs Manual section "Single or Numbered Backups" (node "Backup Names") and function backup-file-name-p for the name pattern.

For reference, the mount program (see mount(8)) uses /etc/mtab~ as a lockfile. mtab~ would be reckoned an Emacs backup file by the patterns here.

$RE{Emacs}{lockfile}

Match an Emacs lockfile filename, with no directory part. This is a filename like

    .#foo.txt

The -keep option captures are

    $1       whole string
    $2       originating filename "foo.txt"

Emacs creates a lockfile to prevent two users or two running copies of Emacs from editing the same file simultaneously. On a Unix-like system a lockfile is normally a symlink to a non-existent target with user and PID. That means ignoring dangling symlinks will also ignore Emacs lockfiles -- if that's easier than checking filenames.

See the GNU Emacs Manual section "Protection against Simultaneous Editing" (node "Interlocking") and C source code fill_in_lock_file_name() for the name construction.

$RE{Emacs}{autosave}

Match an Emacs autosave filename, with no directory part. This is a filename like

    #foo.txt#

The -keep option captures are

    $1       whole string
    $2       originating filename "foo.txt"

Emacs creates an autosave file with the content of a file buffer which has been edited and not yet saved. The autosave file can be used to recover those edits in the event of a system crash (M-x recover-session or individual M-x recover-file or M-x recover-this-file).

See the GNU Emacs Manual section "Auto-Save Files" (node "Auto-Saving") and function auto-save-file-name-p for the pattern.

$RE{Emacs}{skipfile}

Match Emacs-related filenames which can generally be skipped. This means a backup, lockfile or autosave as above.

    foo.txt~             backup
    foo.txt.~123~        backup
    .#foo.txt            lockfile
    #foo.txt#            autosave

With the -keep option the only capture is

    $1       whole string

For example to exclude Emacs bits when reading a directory,

    opendir DH, '/some/dir' or die $!;
    while (my $filename = readdir DH) {
      next if $filename =~ $RE{Emacs}{skipfile};
      print "$filename\n";
    }
    closedir DH;

IMPORTS

This module should be loaded through the Regexp::Common mechanism, see "Loading specific sets of patterns." in Regexp::Common. Remember that loading an add-on pattern like this module also loads all the builtin patterns by default.

    # Emacs plus all builtins
    use Regexp::Common 'Emacs';

If you want only $RE{Emacs} then add no_defaults (or list specific desired builtins).

    # Emacs alone
    use Regexp::Common 'Emacs', 'no_defaults';

SEE ALSO

Regexp::Common

HOME PAGE

http://user42.tuxfamily.org/regexp-common-other/index.html

LICENSE

Copyright 2012, 2013, 2014, 2015 Kevin Ryde

Regexp-Common-Other 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, or (at your option) any later version.

Regexp-Common-Other is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Regexp-Common-Other. If not, see <http://www.gnu.org/licenses/>.