$Id: README 200 2017-05-01 08:51:48Z minus $
##############################################################################
#                                                                            #
#                                                                            #
# THIS FILE DESCRIBES PRINCIPLES WORKING WITH CTKlib                         #
#                                                                            #
# NOTE: THE FILE IS WRITTEN IN RUSSIAN. WORK IS UNDERWAY TO TRANSLATE IT     #
# INTO ENGLISH. IN THE NEXT RELEASE, EVERYTHING WILL CHANGE.                 #
#                                                   THANK FOR UNDERSTANDING. #
#                                                                            #
##############################################################################

NAME
    CTKlib - Command-line ToolKit library (CTK). Command line interface (CLI)

VERSION
    Version 1.18

SYNOPSIS

    use CTK;

    use CTK qw/ ...TAGS... /

    use CTK qw/ ...VARIABLES, FUNCTIONS AND PROCEDURES... /

ABSTRACT
    Проект CTKlib содержит несколько библиотек работы с механизмами обслуживающие командную строку

    SVN: http://svn.serzik.com/CTKlib/trunk
         svn co http://svn.serzik.com/CTKlib/trunk CTKlib

DESCRIPTION

The project ... blah-blah-blah

Библиотека, призванная объеденить в себе основной инструментарий для создания роботов.
CTK включает в себя механиз работы с командной строкой, отправки почты, соединения с БД,
соединения с HTTP/FTP/SSH и прочими серверами с целью передачи информации и выполнения удаленных
команд... и много-много других утилит, встроенных в один проект, который достаточно использовать
с помощью вызова use CTK

CTK состоит из 2-х ветвей - из утилитарной (процедурной) и функциональной (объектной). Утилитарная
ветвь обеспечивает доступ к часто используемым функциям, которые можно условно разделить на группы.
Это функции работы с датой и временем, функции конвертирования форматов, базовые функции работы с
файлами и директориями, а также другие функции, которые всегда можно найти в пакете CTK::Util.

Функциональная же ветвь, позволяет оперировать макрообъектами, каждый условный класс таких объектов
носит свое имя: CTK::Arc (работа с архивами), CTK::File (работа с файлами), CTK::Net (работа с сетевыми
ресурсами) и т.д. Все методы этих классов вызываются через главный объект CTK: $c? например:

    package main;
    use CTK qw/ $DATADIR /
    ...
    1;
    package my::mainlib;
    my $c = new CTK; # Строим главный объект
    ...
    $c->frm( -in => CTK::catfile($CTK::DATADIR,'in') );
    ...
    1;

В приведенном примере произойдет удаление содержимого каталога in в каталоге данных $CTK::DATADIR.

Импорт значения $CTK::DATADIR управляется в главном модуле машей программы или же при явном вызове, напроимер:

    package my::mainlib;
    use CTK qw/ $DATADIR /
    my $c = new CTK; # Строим главный объект
    ...
    $c->frm( -in => CTK::catfile($DATADIR,'in') );
    ...
    1;

VARIABLES, FUNCTIONS AND PROCEDURES

    Глобальные переменные

    $TM        - Счетчик времени
    $EXEDIR    - Директория где лежит вызываемый скрипт
    $DATADIR   - Директория для данных (пользовательский каталог)
    $CONFDIR   - Директория конфигурации (пользовательский каталог)
    $CONFFILE  - Главный конфигурационный файл
    $LOGDIR    - Директория где лежит логфайл
    $LOGFILE   - Сам файл лога
    %OPT       - Список опций командной строки
    @OPTSYSDEF - Список опций по умолчанию, можно переопределять пользователем

    Базовые функции

    say        - Функция say как в perl 6
    debug      - Отладка - экран и лог если установлены опции -ld или -d
    tms        - Таймштамп. Стандартный вывод времени
    exception  - Процедура обработки исключений
    testmode   - Функция возвращает результат тестового режима, используется в булевом контексте
    debugmode  - Функция возвращает результат режима отладки, используется в булевом и INT контексте
    logmode    - Функция возвращает результат режима логирования, используется в булевом контексте

TAGS

    ALL     - импортируются все глобальные переменные и все базовые функции

    BASE    - импортируются основные глобальные переменные и все базовые функции

    VARS    - импортируются все глобальные переменные

    FUNC, FUNCS, SUB, SUBS - импортируются все базовые функции

OPTIONS

    Опции, или иными сломами пары имя-значение глобального хеша %OPT нужны для вашей программы,
    но стоит учесть тот немаловажный факт, что некоторые из них используется и самым модулем CTK
    и потому являются зарезервированными. К таким зарезервированным именам опций относится
    следующий набор опций:

        debug
        log
        signature
        testmode

    Эти опции определены в стандартном массиве @OPTSYSDEF

Пакетная работа с архивами

    fextract - извлечение файлов из архивов с двумя способами: внешним и внутренним.

    Внешний способ является приоритетным, т.к. снижает нагрузку на скрипт. Внешний способ базируется
    на системном вызове той программы, которая определяется по расширению файла архива.

    Внутренний способ более ресурсоемкий и хорош в случае когда имеется четкое представление какой
    архив подлежит обработке и насколько он велик.

    # Извлечение файлов внешним способом
    $c->fextract(
            -in     => CTK::catfile($CTK::DATADIR,'in'),  # путь до файлов архивов
            -out    => CTK::catfile($CTK::DATADIR,'out'), # путь к папке для извлеченных файлов
            -method => 'ext',           # Указатель что речь идет о внешнем извлечении, можно опустить
            -list   => qr/rar/,         # Маска (ругулярное выражение) на отбор файлов каталога IN
            -arcdef => $config->{arc},  # Секция определений из конфигурационного файла, Hashref
        );

    # Извлечение файлов внутренним способом
    $c->fextract(
            -in     => CTK::catfile($CTK::DATADIR,'in'),  # путь до файлов архивов
            -out    => CTK::catfile($CTK::DATADIR,'out'), # путь к папке для извлеченных файлов
            -method => 'zip',           # Указатель что речь идет о внешнем извлечении, можно опустить
            -list   => qr/zip/,         # Маска (ругулярное выражение) на отбор файлов каталога IN
            -arcdef => $config->{arc},  # Секция определений из конфигурационного файла, Hashref
        );

    fcompress - сжатие файлов, внешним способом.

    # Сжатие файла внешним способом
    $c->fcompress(
            -in     => CTK::catfile($CTK::DATADIR,'in'),  # путь до файлов для сжатия
            -out    => CTK::catfile($CTK::DATADIR,'out','ttt.rar'), # Конечное имя файла архива
            -list   => qr//,           # Маска (ругулярное выражение) на отбор файлов каталога IN
            -arcdef => $config->{arc}, # Секция определений из конфигурационного файла, Hashref
        );

    Внутренний способ не реализован ввиду непрактичного использования.

Пакетная работа с файлами

    fsplit - Разрезание файлов по строкам. Используется только текстовый режим достпуа.

    Для того чтобы очень большие файлы разбивать на строки, существует функция fsplit, которая
    сделает это!

    $c->fsplit(
            -in     => CTK::catfile($CTK::DATADIR,'in'),  # путь до файлов для обработки
            -out    => CTK::catfile($CTK::DATADIR,'out'), # путь до итоговых файлов после обработки
            -n      => 100, # количество строк на которые необходимо разбивать файлы
            -format => '[FILENAME]_%03d.[FILEEXT]', # Формат каждого итогового файла
            -list   => qr//, # Маска (ругулярное выражение) на отбор файлов каталога IN
        );

    fcopy, fcp - Копирование файлов

    $c->fcopy(
            -in     => CTK::catfile($CTK::DATADIR,'in'),  # путь до файлов для обработки
            -out    => CTK::catfile($CTK::DATADIR,'out'), # путь до итоговых файлов после обработки
            -format => '[FILE].copy', # Формат каждого итогового файла
            -list   => qr//, # Маска (ругулярное выражение) на отбор файлов каталога IN
        );

    fmove, fmv - Перенос файла

    $c->fmv(
            -in     => CTK::catfile($CTK::DATADIR,'in'),  # путь до файлов для обработки
            -out    => CTK::catfile($CTK::DATADIR,'out'), # путь до итоговых файлов после обработки
            -format => '[FILE].copy', # Формат каждого итогового файла
            -list   => qr//, # Маска (ругулярное выражение) на отбор файлов каталога IN
        );

    fdelete, fdel, frm - Удаление файла

    $c->frm(
            -in     => CTK::catfile($CTK::DATADIR,'in'), # путь до файлов для обработки
            -list   => qr//, # Маска (ругулярное выражение) на отбор файлов каталога IN
        );

Пакетная работа с удаленными сетевыми ресурсами

    Для работы с удаленными системами требуется хэш коннекта. Для работы с FTP такой хэш выглядит как:

    my %ftpct = (
        ftphost     => '192.168.1.1',
        ftpuser     => 'login',
        ftppassword => 'password',
        ftpdir      => '~/activa', #activa
        #ftpattr     => {},
    );

    my %httpct = (
        method     => 'GET',
        url        => 'http://yandex.ru/robots.txt',
        #login      => 'login',
        #password   => 'password',
        #utf8       => 1,
    );

    my %uaopt = (
        agent                   => "Mozilla/4.0",
        max_redirect            => 10,
        requests_redirectable   => ['GET','HEAD','POST'],
        keep_alive              => 1,
        env_proxy               => 1,
    );

    Далее по тексту будет использоваться он

    fetch, get, download - Получение файлов, их скачка

    $c->fetch(
            -connect  => {%ftpct},   # Данные соединения
            -protocol => 'ftp',      # Протокол работы, в частности, FTP
            -dir      => $DATADIR,   # Директория (полный путь) где будут лежать принятые файлы
            -cmd      => 'copyuniq', # Команда: copy / copyuniq / move / moveuniq
            -mode     => 'bin',      # Режим доступа к файлам: ascii / binary (bin)
            -list     => qr//,       # Маска (ругулярное выражение) на отбор файлов из источника
        );

    my $stat = $c->fetch(
            -connect  => {%httpct},  # Данные соединения
            -uaopt    => {%uaopt},   # Опции UserAgent (необязательны)
            -protocol => 'http',     # Протокол работы, в частности, HTTP, может быть HTTPS
            -dir      => $DATADIR,   # Директория (полный путь) где будут лежать принятые файлы (необязательно)
            #-file    => '123.html', # Имя файла (необязательно)
            #-uacode  => sub { },    # Исполняемый код для обэекта LWP::UserAgent (первый параметр)
            #-reqcode => sub { },    # Исполняемый код для обэекта HTTP::Request (первый параметр)
            #-rescode => sub { },    # Исполняемый код для обэекта HTTP::Response (первый параметр)
        );
    debug("STATUS: ",$stat);

    # Простой способ получения текстовых страниц сайтов
    my $html = $c->fetch(
            -connect  => {
                    method     => 'GET',
                    url        => 'http://yandex.ru/robots.txt',
                },
            -protocol => 'http',
            #-utf8     => 1,
        );
    debug("DATA:\n\n",$html,"\n");

    Если опустить имя файла и директорию, то вывод будет передан в переменную $stat.

    ВАЖНОЕ ЗАМЕЧАНИЕ!!! Этот путь приема (скачивания) файлов работает только с небольшими файлами,
    для загрузки больших объемов лучим решением будет использование сторонних программ, таких как
    wget, fetch, lwp-download и других аналогов.

    Наглядным примером использования uacode, reqcode и rescode, будет вывод заголовков сл. образом:

        -rescode => sub { debug(CTK::Net::_debug_http(@_))  },

    Функция CTK::Net::_debug_http возвращает подробную информацию о запросе.

    Команды бывают:

    copy        - Копирование файла
    copyuniq    - Копирование только уникальных файлов
    move        - Перемещение файла
    moveuniq    - Перемещение только уникальных файлов

    store, put, upload - Отправка файлов, их загрузка

    $c->store(
            -connect  => {%ftpct},   # Данные соединения
            -protocol => 'ftp',      # Протокол работы, в частности, FTP
            -dir      => $DATADIR,   # Директория (полный путь) где лежат файлы для отправки
            -cmd      => 'copyuniq', # Команда: copy / copyuniq / move / moveuniq
            -mode     => 'bin',      # Режим доступа к файлам: ascii / binary (bin)
            -file     => 'sg1.bat',  # Список или имя файлов или маска отбора
        );

Работа с базами данных и хранилищами

    Для работы необходимо подключить модуль CTK::DBI в том пакете, откуда будут производиться вызовы.

    # Соединение с БД mysql
    my $oracle = new CTK::DBI(
            -dsn  => 'DBI:mysql:database=mvcskel;host=192.168.100.1',
            -user => 'login',
            -pass => 'password',
        );
    debug($oracle->field("select sysdate() from dual"));

    # Соединение с БД Oracle
    if (testmode) {
        my $oracle = new CTK::DBI(
            -dsn  => $config->{oracle}{prodt}{dsn},
            -user => $config->{oracle}{prodt}{user},
            -pass => $config->{oracle}{prodt}{password},
        );
        debug($oracle->field("select sysdate from dual"));
    }

Отправка писем

    my $send = CTK::sendmail(
        -to         => (testmode() ? $config->{sendmail}{testmail} : $config->{sendmail}{to}),
        -cc         => $config->{sendmail}{cc},
        -from       => $config->{sendmail}{from},
        -type       => $config->{sendmail}{type},
        -smtp       => $config->{sendmail}{smtp},
        -subject    => 'моя тема',
        -message    => 'мое сообщение',
        -attach => [
                {Type=>'text/plain', Path=>$CTK::LOGFILE, Filename=>'log.txt', Disposition=>'attachment',},
                {Type=>'text/plain', Data=>'document 1 content', Filename=>'doc1.txt', Disposition=>'attachment',},
                {Type=>'text/plain', Data=>'document 2 content', Filename=>'doc2.txt', Disposition=>'attachment',},
            ],
    );
    debug($send ? 'письмо ушло :)' : 'письмо НЕ ушло :(');

Шифрование и защины, криптография

    gpg_decript - Дешифрование файлов с помощью утилиты GPG (GnuPG)

    Сайт проекта: http://www.gnupg.org/ (GPG4Win - http://gpg4win.org/)

    Дешифрование ведется по уже установленным файлам ключей

    $c->gpg_decript(
            -in      => CTK::catfile($DATADIR,'in','test.txt.asc'), # путь до файлов для рашифровки
            -out     => CTK::catfile($DATADIR,'out','test.txt'),    # путь до файла после обработки
            -gpghome => '', # ЗАРЕЗЕРВИРОВАНО
            -certdir => '', # путь до каталога с сертификатами. По умолчанию каталог ./data/cert
            -pubkey  => '', # Путь до файла публичного (открытого) ключа. По умолчанию ./data/cert/public.key
            -privkey => '', # Путь до файла приватного (закрытого) ключа. По умолчанию ./data/cert/private.key
            -pass    => '', # Пароль для закрытого ключа. По умолчанию - спросит
        );

Работа с командной строкой

    cli_prompt - Вызов командной строки, запрос на ввод строкойвой переменной

    my $v = $c->cli_prompt('Your name:', 'anonymous');
    debug( "Your name: $v" );

    Первым параметром указывается приглашение, вторым - значение по умолчанию

    cli_prompt3 - Вызов cli_prompt последовательно 3 раза для целей корректного введения значения

    my $v = $c->cli_prompt3('Your name:');
    debug( "Your name: $v" );

    Первым параметром указывается приглашение, вторым - значение по умолчанию

    cli_select - Вызов спсика для выбора значения из него. Используется таже командная строка но
    с той лишь разницей что ожидается определенное значение из предложенного списка этих значений

    my $v = $c->cli_select('Your select:',[qw/foo bar baz/],'bar');
    debug( "Your select: $v" );

    Первым параметром указывается строка приглашения на ввод значения, вторым параметром - ссылка на
    массив содержащий список значений и третий параметр - значение по умолчанию.

    cli_select3 - Вызов cli_select последовательно 3 раза для целей корректного введения значения

    my $v = $c->cli_select3('Your select:',[qw/foo bar baz/],'foo');
    debug( "Your select: $v" );

    Первым параметром указывается строка приглашения на ввод значения, вторым параметром - ссылка на
    массив содержащий список значений и третий параметр - значение по умолчанию.


EXAMPLES

Статья по Moose: http://ni-al.ru/index.php/Perl::Moose::Conept

Получение списка всех утилитарных экспортированных функций

perl -MCTK::Util -e "print join qq/\n/, sort {$a cmp $b} @{$CTK::Util::EXPORT_TAGS{ATOM}}" | gclip

ENVIRONMENT
    No environment variables are used.

BUGS
    Please report them.

SEE ALSO
    "Perl", ...

DIAGNOSTICS
    The usual warnings if it cannot read or write the files involved.

HISTORY
    See CHANGES file

TODO
    See TODO file

LICENSE
    See LICENSE file

THANKS
    Thanks to me for ...

AUTHOR
    Sergey Lepenkov (Serz Minus) http://www.serzik.com <minus@mail333.com>.

COPYRIGHTS
    Copyright (C) 1998-2017 D&D Corporation. All Rights Reserved