The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Liveman-3.1
River stage zero No dependents
/ Liveman

NAME

Liveman - compiler from markdown to tests and documentation

VERSION

3.1

SYNOPSIS

File lib/Example.md:

        Дважды два:
        \```perl
        2*2  # -> 2+2
        \```

Test:

        use Liveman;
        
        my $liveman = Liveman->new(prove => 1);
        
        # Компилировать lib/Example.md файл в t/example.t 
        # и добавить pod-документацию в lib/Example.pm
        $liveman->transform("lib/Example.md");
        
        $liveman->{count}   # => 1
        -f "t/example.t"    # => 1
        -f "lib/Example.pm" # => 1
        
        # Компилировать все lib/**.md файлы со временем модификации, превышающим соответствующие тестовые файлы (t/**.t):
        $liveman->transforms;
        $liveman->{count}   # => 0
        
        # Компилировать без проверки времени модификации
        Liveman->new(compile_force => 1)->transforms->{count} # => 1
        
        # Запустить тесты с yath:
        my $yath_return_code = $liveman->tests->{exit_code};
        
        $yath_return_code           # => 0
        -f "cover_db/coverage.html" # => 1
        
        # Ограничить liveman этими файлами для операций, преобразований и тестов (без покрытия):
        my $liveman2 = Liveman->new(files => [], force_compile => 1);

DESCRIPTION

The problem with modern projects is that documentation is divorced from testing. This means that the examples in the documentation may not work, and the documentation itself may lag behind the code.

Liveman compiles lib/**.md files into t/**.t files and adds documentation in the module's __END__ section to the lib/**.pm files.

Use the liveman command to compile test documentation in your project directory and run the tests:

liveman

Run it coated.

The -o option opens a code coverage report by tests in the browser (coverage report file: cover_db/coverage.html).

Liveman replaces our $VERSION = "..."; in lib/**.pm from lib/**.md from the VERSION section if it exists.

If the minil.toml file exists, then Liveman will read name from it and copy the file with that name and .md extension into README.md.

If you need the documentation in .md to be written in one language, and pod in another, then at the beginning of .md you need to indicate !from:to (from which language to translate, for example, for this file: !ru:en).

Headings (lines starting with #) are not translated. Also, do not translate blocks of code. And the translation itself is carried out paragraph by paragraph.

Files with translations are stored in the i18n directory, for example, lib/My/Module.md -> i18n/My/Module.ru-en.po. Translation is carried out using the trans utility (it must be installed on the system). Translation files can be corrected, because if the translation is already in the file, then it is taken.

Warning! Be careful and review git diff after editing .md so as not to lose the corrected translations in .po.

TYPES OF TESTS

Section codes without a specified programming language or with perl are written as code in the file t/**.t. And a comment with an arrow (# -> ) turns into a Test::More test.

is

Compare two equivalent expressions:

        "hi!" # -> "hi" . "!"
        "hi!" # → "hi" . "!"

is_deeply

Compare two expressions for structures:

        ["hi!"] # --> ["hi" . "!"]
        "hi!" # ⟶ "hi" . "!"

is with extrapolate-string

Compare expression with extrapolated string:

        my $exclamation = "!";
        "hi!2" # => hi${exclamation}2
        "hi!2" # ⇒ hi${exclamation}2

is with nonextrapolate-string

Compare an expression with a non-extrapolated string:

        'hi${exclamation}3' # \> hi${exclamation}3
        'hi${exclamation}3' # ↦ hi${exclamation}3

like

Tests the regular expression included in the expression:

        'abbc' # ~> b+
        'abc'  # ↬ b+

unlike

It checks the regular expression excluded from the expression:

        'ac' # <~ b+
        'ac' # ↫ b+

EMBEDDING FILES

Each test runs in a temporary directory, which is deleted and created when the test runs.

The format of this directory is /tmp/.liveman/project/path-to-test/.

The section of code on the line with the md file prefix File path: will be written to a file when tested at runtime.

The code section in the md file prefix line File path is: will be compared to the file using the Test::More::is method.

File experiment/test.txt:

        hi!

The experiment/test.txt file is:

        hi!

Attention! An empty line between the prefix and the code is not allowed!

These prefixes can be in both English and Russian.

METHODS

new (%param)

Constructor. Has arguments:

1. files (array_ref) - list of md files for the transforms and tests methods.
2. open (boolean) — open the coverage in the browser. If the opera browser is installed on your computer, the opera command will be used to open it. Otherwise - xdg-open.
3. force_compile (boolean) - do not check the modification time of md files.
4. options - add parameters on the command line for verification or proof.
5. prove - use proof (the prove command to run tests), rather than the yath command.

test_path ($md_path)

Get the path to the t/**.t file from the path to the lib/**.md file:

        Liveman->new->test_path("lib/PathFix/RestFix.md") # => t/path-fix/rest-fix.t

transform ($md_path, [$test_path])

Compiles a lib/**.md file into a t/**.t file.

It also replaces the pod documentation in the __END__ section in the lib/**.pm file and creates a lib/**.pm file if it does not exist.

The lib/Example.pm file is:

        package Example;
        
        1;
        
        __END__
        
        =encoding utf-8
        
        Дважды два:
        
                2*2  # -> 2+2

The file lib/Example.pm was created from the file lib/Example.md, as described in the SINOPSIS section of this document.

transforms ()

Compile lib/**.md files into t/**.t files.

All if $self->{files} is not set, or $self->{files}.

tests ()

Run tests (t/**.t files).

All if $self->{files} is not set, or $self->{files} only.

AUTHOR

Yaroslav O. Kosmina mailto:dart@cpan.org

LICENSE

⚖ GPLv3

COPYRIGHT

The Liveman module is copyright © 2023 Yaroslav O. Kosmina. Rusland. All rights reserved.