NAME

Pod::Elemental::Transformer::ExampleRunner - include/run examples scripts in your documentation without copy/paste

VERSION

version 0.002

SYNOPSIS

Tell ExampleRunner what to run. Insert =example into your pod.

`[-Transformer]` in your `weaver.ini`:

 [-Transformer]
 transformer  = ExampleRunner
 command      =example

along with [PodWeaver] in your dist.ini if you're Dist::Zilla inclined.

or `use` it in a script

  my $xform = Pod::Elemental::Transformer::ExampleRunner->new({qw[ command example script_path script/ ]});
  $xform->transform_node($pod_elemental_document);

see example/examplerunner-doc

`=example` commands in your pod

You can include script source or output in your pod, with a pod command like:

 =example source showoff

for this dist, that would become something like:

#see ./example/showoff

  #! /usr/bin/perl -w
  #FOR: showing off the features of ExampleRunner
  #...use libraries 
  use MyApp::Example;
  
  my $app = MyApp::Example->new();
  use SomeLib qw[ frobulate ];
  
  #... read config files and do other stuff
  
  print frobulate(); 
  
  # an example of your module being used along with SomeLib
  for (@SomeLib::Plugins) { 
      print "Setting up plugin: $_\n";
      my $plugin_obj = SomeLib->factory( $_ );
      #...feed $plugin_obj
      $app->accept_frobulation( $_ => $plugin_obj->frobulate() );
  }
  $app->run(); # is now able to serve pre-frobulated results
  
  #...

#end of listing

and if you wanted to run the script, and capture it's output, you'd use

 =example run showoff

which would look something like this:

#running ./example/showoff

  behold the awesome power of SomeLib's frobulate implementation
  Setting up plugin: funky
  Oh my! MyApp::Example::accept_frobulation is happening!
  Setting up plugin: fresh
  Oh my! MyApp::Example::accept_frobulation is happening!
  Oh my! MyApp::Example::run is happening!

KEEPING IT PUNCHY...

Often your example scripts will contain lots of boring setup code, by yadaing this code out your examples stay runnable, and your docs stay focused on the features you're trying to explain...

If you want to just hide a couple of lines, use an inline-yada (consecutive lines lines matching yada_pattern)... For more lengthy chunks of boring stuff use a multi-line yadas (delimited with yada_{start,end})

... with inline-`yada`s

If a library wants you to pass in lots of options, and you need those options to make your example work, then keep them in your example script, but tell ExampleRunner that they're boring and it'll yada them out.

 my $foo = ComplexLibrary->new({
    plugins => {
        often => {                                          # boring 
            scratchdir => '/tmp/',                          # boring 
            with       => [ qw[ --extra --support-large ]]  # boring 
        },                                                  # boring 
        sneaky => {                                         # boring 
            mask_user => 1,                                 # boring 
            show_full_name => 0,                            # boring 
        },                                                  # boring 
        options => {                                        # boring 
            no_laoder => 0                                  # boring 
        }                                                   # boring 
    }
 });
 # now we move on to code that's actually from my distribution... damn you ComplexLibrary!

and you'll get this in the pod:

 my $foo = ComplexLibrary->new({
    plugins => {
        #...
    }
 });
 # aah, that's a lot less cruft in my pod!

... with a multi-line `yada`s

Now, that's a lot of # boring in your script too, so you might want a multi-line yada instead, like this:

 my $foo = ComplexLibrary->new({
    plugins => {
        # {{{ ExampleRunnerHide ComplexLibrary requires lots of arguments!
        often => { 
            scratchdir => '/tmp/', 
            with       => [ qw[ --extra --support-large ]] 
        }, 
        sneaky => { 
            mask_user => 1, 
            show_full_name => 0, 
        }, 
        options => { 
            no_laoder => 0 
        } 
        # ExampleRunnerShow }}}
    }
 });
 # now we move on to code that's actually from my distribution... damn you ComplexLibrary!

you'll still get:

 my $foo = ComplexLibrary->new({
    plugins => {
        # ... ComplexLibrary requires lots of arguments!
    }
 });
 # now more of this example is to do with my code than with ComplexLibrary's setup

If your yada_start or yada_pattern captures something, it'll be tacked on after the yada marker.

Multiple consecutive lines matching yada_pattern will be collapsed down to one yada using the last <stuff> captured

... `SYNOPSIS` example without `yada`s

Here is example/showoff without the yada blocks collapsed...

#running ./example/cat example/showoff

  #! /usr/bin/perl -w
  #FOR: showing off the features of ExampleRunner
  use strict;             # boring
  use warnings;           # boring
  use lib 'somelib/lib';  # boring use libraries 
  use MyApp::Example;
  
  my $app = MyApp::Example->new();
  use SomeLib qw[ frobulate ];
  
  # {{{ ExampleRunnerHide read config files and do other stuff
  
  # the stuff in this block ( from yada_start to yada_end )
  # will be stripped out of the source listed in your POD
  # this way you can hide stuff that's not really that interesting
  # things like setting up stubs that let your example run without real libs
  #   (for example, SomeLib doesn't really export frobulate)
  
  sub frobulate {
          "behold the awesome power of SomeLib's frobulate implementation\n"
      }
  
  =pod 
  
  you can do things in your examples that would require lots of tedious
  configuration (say of a mysql server) that you really don't want to 
  force on your readers.
  
  They get to see the a couple of runs of your scripts without having to
  install everything, configure mysql and then find out your modules' not 
  as cool as they thought.
  
  And, you don't have to re-run the scripts and copy/paste their output
  every time you change them
  
  =cut 
  
  # ExampleRunnerShow }}}
  
  print frobulate(); 
  
  # an example of your module being used along with SomeLib
  for (@SomeLib::Plugins) { 
      print "Setting up plugin: $_\n";
      my $plugin_obj = SomeLib->factory( $_ );
      
      $plugin_obj->configure( SomeLib->configuration_for_plugin( $_ ) ); # boring
      $plugin_obj->init; # boring feed $plugin_obj
      $app->accept_frobulation( $_ => $plugin_obj->frobulate() );
  }
  $app->run(); # is now able to serve pre-frobulated results
  
  # {{{ ExampleRunnerHide
  # 
  #   This script is exclusive and non-transferrable property of yada yada 
  #   yada yada yada yada yada yada yada 
  #
  # ExampleRunnerShow }}}

man, tl;dr!

MORE EXAMPLES

you might want to check out the awesome scripts in the example/ directory for this dist:

#running ./example/list-examples

  list-examples              lists the files in example/ (this script!)
  cat                        runs cat on files - meow!
  something-bad-happened     to demonstrate what happens when ExampleRunner runs something that dies and spews stuff to STDERR
  not-runnable               demonstrate what happens when a script can't be run
  examplerunner-doc          format the pod in ExampleRunner with ExampleRunner 
  somelib-examples           demonstrate ExampleRunner being used as more than one command on the same document
  showoff                    showing off the features of ExampleRunner

which obviously came from this script:

#see ./example/list-examples

  :
  #FOR: lists the files in example/ (this script!)
  grep '#FOR:'  $( find example/ -type f ) | perl -ne 'next if /Binary file/;s{example/}{}; printf qq[%-25s %s], split /:#FOR:/'

#end of listing

/somelib in this dist is a fake distribution with docs ...

CONFIGURATION

These are the options you can set, and their defaults... you'd use these in your weaver.ini:

 [-Transformer]
 transformer  = ExampleRunner
 script_path  = example/                                ; where I'll look for scripts to run/include
 command      = example                                 ; which pod command I'll expand
 indent       = '  '                                    ; the indent I'll add to source/output
 
 ; multi-line yada blocks
 yada_start   = # {{{ ExampleRunnerHide(?: ([^\n]+))?   ; start token, captures comment to be kept in pod
 yada_end     = # ExampleRunnerShow }}}                 ; end token 
 
 ; single-line yada blocks
 yada_pattern = # boring(?: ([^\n]+))?                  ; many lines matching these are considered a single yada
 
 ; all yadas are replaced with this, followed by the captures from above
 yada_replace = #...

DIAGNOSTICS

If you find an empty block in place of your script's output, it could be one of...

permission denied

If you forget to make your scripts executable you'll get the message in the POD

# Couldn't run ./example/not-runnable: Permission denied

things going pear shaped in your script

If your perl script dies you'll likely just get an empty section where the script was (since STDERR is ignored), you see something similar happening in this script:

#see ./example/something-bad-happened

  :
  #FOR: to demonstrate what happens when ExampleRunner runs something that dies and spews stuff to STDERR
  echo "oh noes!" >&2;
  exit 1

#end of listing

#running ./example/something-bad-happened

## something-bad-happened exited with 1

EXTENDING

If you find this library even remotely useful, you're likely to want it to do a little more than just running/inlining scripts... or maybe you'll want to disable something...

All the behaviours are in separate subs...

=example foo is dispatched to $self->_foo, and the rest of the command is passed on so you can add new sub-commands by just adding a method to your subclass. the thing _foo returns is spliced back into the document.

You can re-use the yada support by calling $self->remove_yadas_from($string), or remove it by replacing it with sub { return $_[1] } .

FOLKS WHO HELPED OUT

Some of this is stolen from Pod::Elemental::Transformer::List, but that doesn't mean rjbs has anything to do with the horrible ideas behind this module.

both Apocalypse and kentln were helpful with the running ExampleRunner on ExampleRunner's docs during distribution confusion I had ...

BUGS

Please report any bugs or feature requests to bug-pod-elemental-transformer-examplerunner@rt.cpan.org or through the web interface at: http://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Elemental-Transformer-ExampleRunner

AUTHOR

FOOLISH <FOOLISH@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install Pod::Elemental::Transformer::ExampleRunner, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Pod::Elemental::Transformer::ExampleRunner

CPAN shell

perl -MCPAN -e shell
install Pod::Elemental::Transformer::ExampleRunner

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

[-Transformer] in your weaver.ini:

or use it in a script

=example commands in your pod

KEEPING IT PUNCHY...

... with inline-yadas

... with a multi-line yadas

... SYNOPSIS example without yadas

MORE EXAMPLES

CONFIGURATION

DIAGNOSTICS

permission denied

things going pear shaped in your script

EXTENDING

FOLKS WHO HELPED OUT

BUGS

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions

`[-Transformer]` in your `weaver.ini`:

or `use` it in a script

`=example` commands in your pod

... with inline-`yada`s

... with a multi-line `yada`s

... `SYNOPSIS` example without `yada`s