NAME

Octets::To::Unicode - модуль и утилиты ru-perltidy и ru-utf8 для распознавания кодировки текста (в том числе в файлах) и его декодирования.

VERSION

0.01

SYNOPSIS

    use Octets::To::Unicode;
    
    my $unicode = decode "Стар Трек";
    my ($unicode, $encoding) = decode "Стар Трек";
    my $unicode = decode $octets_in_cp1251_or_maybe_in_utf8, [qw/cp1251 utf-8/];
    
    my $encoding = detect $octets;
    my $encoding = detect $octets, [qw/cp1251 utf-8/];
    
    my ($file_text_in_unicode, $encoding) = file_decode "path/to/file", ["cp1251", "koi8-r"];
    file_encode "path/to/file2", "koi8-r", $file_text_in_unicode;

Использование утилит:

    # Отформатировать указанные файлы perltidy:
    $ ru-perltidy file1 file2

    # Указать кодировку:
    $ ru-perltidy file1 file2 -e utf-8,cp1251

    # Форматирует только изменённые файлы в репозитории git:
    $ ru-perltidy

    # Форматирует изменённые файлы в ветке (на случай, если забыл отформатировать перед комитом):
    $ ru-perltidy --in-branch

    # Указать расширения файлов:
    $ ru-perltidy --ext 'pl,pm,'
    
    # Обработать файлы в директориях:
    $ ru-perltidy --in-dir .,/tmp/mydir

    # Выполнить операцию с файлами:
    $ ru-utf8 file1 file2 -c 'perltidy $f -st > $o'
    
    # Переменные, которые можно использовать:
    $ ru-utf8 file1 file2 -c 'echo $f $o $e $x'
    $ ru-utf8 file1 file2 -o -c 'echo $f1 $o1 $e1 $x1 - $f2 $o2 $e2 $x2'
    
    # Кроме команды шелла можно использовать ещё код perl:
    $ ru-utf8 file1 file2 -s 'print "$f $o $e $x -- $unicode\n"'
    $ ru-utf8 file1 file2 -o -s 'print "@f @o @e @x"'
    
    # Определить кодировку файлов и перекодировать их в koi8-r:
    $ ru-encode -t koi8-r

DESCRIPTION

Пакет включает в себя утилиты:

и модуль perl:

Octets::To::Unicode предоставляет необходимое множество утилит для определения кодировки текста и его декодирования, а так же — работы с файлами.

В 2000-х определилась тенденция переводить проекты в национальных кодировках в utf-8. Однако не везде их перевели одним махом, а решили рубить собаке хвост постепенно. В результате во многих проектах часть файлов c кодом в utf-8, а часть — в национальной кодировке (cp1251, например).

Ещё одной проблемой могут служить урлы с эскейп-последоваительностями. Например, https://ru.wikipedia.org/wiki/Молчание#Золото преобразуется в мессенджере, куда эту ссылку можно скопировать, в https://ru.wikipedia.org/wiki/%D0%9C%D0%BE%D0%BB%D1%87%D0%B0%D0%BD%D0%B8%D0%B5#%D0%97%D0%BE%D0%BB%D0%BE%D1%82%D0%BE. Причём один мессенджер переведёт русские символы в utf-8, другой — в cp1251, третий — в koi8-r.

Чтобы решить эти две проблемы в приложениях и был написан этот модуль.

SUBROUTINES/METHODS

bohemy

$num = bohemy $unicode;

Возвращает числовую характеристику похожести текста на русский.

Алгоритм основан на наблюдении, что в русском языке слово начинается на прописную или строчную букву, а затем состоит из строчных букв.

Таким образом, числовая характеристика, это сумма длин русско-похожих слов с разницей суммы длин русско-непохожих.

Принимает параметр:

decode

$unicode = decode $octets, $encodings;
($unicode, $encoding) = decode $octets, $encodings;

Возвращает декодированный текст в скалярном контексте, а в списочном, ещё и определённую кодировку.

Если ни одна из кодировок не подошла, то вместо юникода в первом параметре возвращаются октеты, а вместо кодировки - undef:

    ($octets, $encoding_is_undef) = decode $octets, [];

Принимает параметры:

detect

$encoding = detect $octets, $encodings;

Возвращает определённую кодировку или undef.

Параметры такие же как у "decode".

file_find

    @files = file_find $path_to_directory;

Ищет файлы в директориях рекурсивно и возвращает список путей к ним.

Принимает параметр:

file_read

    $octets = file_read $path;

Считывает файл.

Возвращает текст в октетах.

Выбрасывает исключение, если открыть файл не удалось.

Принимает параметр:

file_write

    file_write $path, $octets_or_unicode;

Перезаписывает файл строкой.

Ничего не возвращает.

Выбрасывает исключение, если открыть файл не удалось.

Принимает параметры:

file_decode

$unicode = file_decode $path, $encodings;
($unicode, $encoding) = file_decode $path, $encodings;

Возвращает декодированный текст из файла в скалярном контексте, а в списочном, ещё и определённую кодировку.

Если ни одна из кодировок не подошла, то вместо юникода в первом параметре возвращаются октеты, а вместо кодировки - undef:

    ($octets, $encoding_is_undef) = file_decode $path, [];

Принимает параметры:

file_encode

file_encode $path, $encoding, $unicode;

Переписывает текст в файле в указанной кодировке.

Принимает параметры:

test_file

$is_file = test_file $file, $exts, $interpreters;

Тестирует файл на соответствие указанным расширениям, а если расширения нет, то на соответсвие интерпретаторов к указанному в первой строке файла начинающейся на #!.

Принимает параметры:

test_files

@files = test_files $files, $exts, $interpreters;

Тестирует файлы на соответствие указанным расширениям или интерпретаторам.

Принимает параметры:

change_files

@files = change_files();

Возвращает изменённые файлы в репозитории git.

change_files

@files = change_files_in_branch();

Возвращает изменённые файлы в ветке.

INSTALL

Установить можно любым менеджером perl со CPAN, например:

    $ sudo cpm install -g Octets::To::Unicode

DEPENDENCIES

Зависит от модулей:

и от perltidy опционально:

RELEASE

Релиз на CPAN осуществляется так:

LINKS

AUTHOR

Yaroslav O. Kosmina darviarush@mail.ru

LICENSE

GPLv3