view release on metacpan or  search on metacpan

lib/Encode/Safename.pm  view on Meta::CPAN

package Encode::Safename;

use 5.006;
use strict;
use warnings FATAL => 'all';
use utf8;

use Parse::Lex;

use base qw(Encode::Encoding);

use constant {
    COND_ENCODE => 'ENCODE',
    COND_DECODE => 'DECODE',
};

__PACKAGE__->Define(qw(safename));

=head1 NAME

Encode::Safename - An encoding for safe filenames.

=head1 VERSION

Version 0.05

=cut

our $VERSION = '0.05';

=head1 SYNOPSIS

An encoding to encode filenames to safe filenames, that is filenames
that are valid on all filesystems.

    use Encode qw(decode encode);
    use Encode::Safename;

    $encoded = encode('safename', 'Foo Bar Baz.txt');
    # $encoded is now '{f}oo_{b}ar_{b}az.txt'
    $decoded = decode('safename', $encoded);
    # $decoded is now 'Foo Bar Baz.txt'

=head1 DESCRIPTION

A filename is encoded as follows:

=over 4

=item *

A range of uppercase characters is changed to lowercase characters,
and put between braces.

    'F'   -> '{F}'
    'FOO' -> '{foo}'

=item *

A range of spaces is changed to underscores.

    ' '   -> '_'
    '   ' -> '___'

=item *

A range of safe characters (characters that are valid on all filesystems,
excluding braces, parentheses, and underscores) is left unchanged.

    'f'   -> 'f'
    'foo' -> 'foo'

=item *

All other characters are changed to their Unicode codepoint in hexadecimal
notation, and put between parentheses.

    ':'  -> '(3a)'
    ':?' -> '(3a)(3f)'

=back

Combined, this gives the following:

    'FOO: Bar Baz.txt' -> '{foo}(3a)_{b}ar_{b}az.txt'

=head1 METHODS

=head2 _process LEXER, STRING

Applies LEXER to STRING.  Returns both the processed and unprocessed
parts.

For internal use only!

=cut

Parse::Lex->inclusive('ENCODE', 'DECODE');
my $_lexer = Parse::Lex->new(
    # uppercase characters
    'ENCODE:E_UPPER' => (
        '[A-Z]+',