NAME

Liveman - compiler from Markdown to tests and documentation

VERSION

3.6

SYNOPSIS

File lib/Example.md:

Twice two:
\```perl
2*2  # -> 2+2
\```

Test:

use Liveman;

my $liveman = Liveman->new(prove => 1);

$liveman->transform("lib/Example.md");

$liveman->{count}    # -> 1
-f "t/example.t"     # -> 1
-f "lib/Example.pod" # -> 1

$liveman->transforms;
$liveman->{count}   # -> 0

Liveman->new(compile_force => 1)->transforms->{count} # -> 1

my $prove_return_code = $liveman->tests->{exit_code};

$prove_return_code          # -> 0
-f "cover_db/coverage.html" # -> 1

DESCRIPION

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

LiveMan compiles Lib/**.md to files t/**.t And adds the documentation to the __END__ module to the files lib/**.pm.

Use the `Liveman 'command to compilation of documentation for tests in the catalog of your project and start tests:

liveman

Run it with a coating.

The -o option opens a report on covering code with tests in a browser (coating report file:cover_db/coverage.html).

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

If the * minil.toml * file exists, then Liveman will read NAME from it and copy the file with this name and extension.md in readme.md.

If you need the documentation in .md to be written in one language, andpod is on the other, 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 on #) - are not translated. Also, without translating the code blocks. And the translation itself is carried out by paragraphs.

Files with transfers are added to the i18n catalog, for example, lib/My/Module.md -> i18n/My/Module.ru-en.po. Translation is carried out by the Trans utility (it should be installed in the system). Translation files can be adjusted, because if the transfer is already in the file, then it is taken.

Attention! Be careful and after editing .md look at git diff so as not to lose corrected translations in .po.

Note: trans -R will show a list of languages that can be indicated in !from:to on the first line of the document.

The predecessor of liveman is Lhttps://github.com/darviarush/miu.

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.

Supported tests:

->, → – comparison of scalars;
-->, ⟶ – comparison of structures;
=>, ⇒ – comparison with the interpolated string;
\>, ↦ – comparison with a non-interpolated string;
^=>, ⤇ – comparison of the beginning of the scalar with the interpolated string;
$=>, ➾ – comparison of the end of the scalar with the interpolated string;
*=>, ⥴ – comparison of the middle of the scalar with the interpolated string;
^->, ↣ – comparison of the beginning of a scalar with a non-interpolated string;
$->, ⇥ – comparison of the end of a scalar with a non-interpolated string;
*->, ⥵ – comparison of the middle of a scalar with a non-interpolated string;
~>, ↬ – matching a scalar with a regular expression ($code =~ /.../);
<~, ↫ – negative matching of a scalar with a regular expression ($code !~ /.../);
@->, ↯ – comparison of the beginning of the exception with a non-interpolated string;
@=>, ⤯ – comparison of the beginning of the exception with the interpolated string;
@~>, ⇝ – matching an exception with a regular expression (defined $@ && $@ =~ /.../);
<~@, ⇜ – negative matching of an exception with a regular expression (defined $@ && $@ !~ /.../);

`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 the expression with an extrapolated line:

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

`is` with nonextrapolate-string

Compare the expression with an unexpected line:

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

`like`

The scalar must be comparable to a regular expression:

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

`unlike`

The scalar must not match the regular expression:

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

`like` begins with extrapolate-string

The scalar must begin with an extrapolated term:

my $var = 'b';

'abbc' # ^=> a$var
'abc'  # ⤇ a$var

`like` ends with extrapolate-string

The scalar must end with an extrapolated term:

my $var = 'c';

'abbc' # $=> b$var
'abc'  # ➾ b$var

`like` inners with extrapolate-string

The scalar must contain the extrapolated term:

my $var = 'x';

'abxc'  # *=> b$var
'abxs'  # ⥴ b$var

`like` begins with nonextrapolate-string

The scalar must begin with a non-extrapolated term:

'abbc' # ^-> ab
'abc'  # ↣ ab

`like` ends with nonextrapolate-string

The scalar must end with a non-extrapolated term:

'abbc' # $-> bc
'abc'  # ⇥ bc

`like` inners with nonextrapolate-string

The scalar must contain a non-extrapolated term:

'abbc' # *-> bb
'abc'  # ⥵ b

`like` throw begins with nonextrapolate-string

The exception must start with the non-extrapolated term:

1/0 # @-> Illegal division by zero
1/0 # ↯ Illegal division by zero

`like` throw begins with extrapolate-string

The exception must start with the extrapolated timing:

my $by = 'by';

1/0 # @=> Illegal division $by zero
1/0 # ⤯ Illegal division $by zero

`like` throw

The exception must be matched to the regular expression:

1/0 # @~> division\s*by\s*zero
1/0 # ⇝ division\s*by\s*zero

`unlike` throw

The exception doesn't have to be matched by the regular expression (but it should be):

1/0 # <~@ auto
1/0 # ⇜ auto

EMBEDDING FILES

Each test is performed in a temporary catalog, which is removed and created when starting the dough.

The format of this catalog: /tmp/.liveman/project/path-to-test/.

The code section in the line with the MD-file prefix File path: is written to the file when testing during execution.

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

experiment/test.txt file:

hi!

experiment/test.txt file is:

hi!

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

These prefixes can be both in English and in Russian (File [path] (https://metacpan.org/pod/path): and File [path] (https://metacpan.org/pod/path) is:).

METHODS

new (%param)

Constructor. Has arguments:

1. Files (array_ref)-a list of MD files for thetransforms and tests.
2. open (boolean) - open the coating in the browser. If the computer is installed on the computer Opera, the Opera command will be used to open. Otherwise-xdg-open.
3. force_compile (boolean)-do not check the time of modification of MD files.
4. options - Add the parameters on the command line for verification or evidence.
5. prove - use the proof (team prove to start tests), and not the yath command.

test_path ($md_path)

Get the way to t/**.t-file from the way tolib/**.md-file:

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

transform ($md_path, [$test_path])

Compiles lib/**.md-file int/**.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 exists, otherwise it creates a lib/**.pod file.

When transform was called in SYNOPSYS, a file lib/Example.pod was created.

The lib/Example.pod file is:

Twice two:

	2*2  # -> 2+2

Let's create lib/Example.pm and call transform:

open my $fh, ">", "lib/Example.pm" or die $!;
print $fh q{package Example;

1;};
close $fh;

my $liveman = Liveman->new(prove => 1);

$liveman->transform("lib/Example.md");

The lib/Example.pm file is:

package Example;

1;

__END__

=encoding utf-8

Twice two:

	2*2  # -> 2+2

transforms ()

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

That's all, if $self->{files} is not installed, or $self->{files}.

tests ()

Launch tests (t/**.t-files).

That's all, if $self->{files} is not installed, or $self->{files} only.

load_po ($md, $from, $to)

Reads the PO-file.

save_po ()

Saves the PO-file.

trans ($text, $lineno)

The function translates the text from one language to another using the Trans utility.

trans_paragraph ($paragraph, $lineno)

It also breaks through paragraphs.

DEPENDENCIES IN CPANFILE

In your library, which you will test Liveman, you will need to indicate additional dependencies for tests in cpanfile:

on 'test' => sub {
    requires 'Test::More', '0.98';

    requires 'Carp';
    requires 'File::Basename';
    requires 'File::Path';
    requires 'File::Slurper';
    requires 'File::Spec';
    requires 'Scalar::Util';
};

It will also be good to indicate and the Liveman in the development section:

on 'develop' => sub {
    requires 'Minilla', 'v3.1.19';
    requires 'Data::Printer', '1.000004';
    requires 'Liveman', '1.0';
};

AUTHOR

Yaroslav O. Kosmina mailto:dart@cpan.org

LICENSE

⚖ GPLv3

COPYRIGHT

To install Liveman, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Liveman

CPAN shell

perl -MCPAN -e shell
install Liveman

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPION

TYPES OF TESTS

is

is_deeply

is with extrapolate-string

is with nonextrapolate-string

like

unlike

like begins with extrapolate-string

like ends with extrapolate-string

like inners with extrapolate-string

like begins with nonextrapolate-string

like ends with nonextrapolate-string

like inners with nonextrapolate-string

like throw begins with nonextrapolate-string

like throw begins with extrapolate-string

like throw

unlike throw