/ 
Sub-Genius-0.314006
River stage zero No dependents
/ stubby

NAME

stubby - Command-line tool for generating and inspecting Perl programs derived from Sub::Genius plans

SYNOPSIS

stubby is a development and tooling utility for working with Sub::Genius. It can generate Perl code, enumerate valid execution orders, visualize plans, and pre-cache compiled automata.

Generate code that depends on Sub::Genius

Generate a Perl script that invokes Sub::Genius at runtime. The example below redirects output to ./spawn-combine.pl:

$ stubby init --run once \
    -p "subA subB subC" \
    > ./spawn-combine.pl

The generated script includes use Sub::Genius (); and executes the plan dynamically.

Generate code with no dependency on Sub::Genius

Generate a fully expanded, dependency-free Perl script. The execution order is made explicit and Sub::Genius is not required at runtime:

$ stubby init --run nodeps \
    -p "init ( subA & subB ) middle ( subC & subD ) fin" \
    > ./spawn-combine.pl

Note: although this necessarily causes the PRE to be compiled and cached, the generated code does not use Sub::Genius ();. In this mode, caching only serves to speed up the stubby invocation itself.

For intentional or distributable caching, see the precache subcommand below.

Pre-cache PREs (a compiler-like step)

The precache subcommand compiles a PRE into a minimized DFA and stores it in the cache directory. On success, it prints the absolute path to the cache file:

$ CACHEFILE=$(stubby precache \
    -p "init ( subA & subB ) middle ( subC & subD ) fin")

$ echo "Cache file is ${CACHEFILE}"

PREs may also be supplied from a file:

$ CACHEFILE=$(stubby precache \
    -f ./my-preplan.preplan \
    -d ./cache)

The following file contents produce the same checksum and cache entry as the inline PRE above:

init
  ( subA & subB )
middle
  ( subC & subD )
fin

Sub::Genius normalizes PREs aggressively (stripping whitespace, comments, and adding explicit symbol delimiters) so semantically equivalent PREs produce the same cache key.

DESCRIPTION

stubby is a general-purpose command-line tool intended to support development, debugging, and distribution of applications built on Sub::Genius.

It provides several subcommands, each addressing a different stage of the workflow.

Subcommands Overview

export

Dumps the minimized DFA produced from a PRE in GraphViz dot format. This is useful for visualization with tools such as xdot, dot, circo, or other GraphViz renderers.

init

Generates boilerplate Perl code to help start a script, module, or project that uses Sub::Genius. Depending on options, the generated code may invoke Sub::Genius dynamically or be fully dependency-free.

list

Enumerates all valid execution orders (strings) accepted by the PRE. This is useful for verifying correctness assumptions and understanding the full range of sequentially consistent orderings.

precache

Compiles a PRE into a DFA and stores it in the cache directory, allowing Sub::Genius to skip the potentially expensive PRE-to-DFA conversion step at runtime.

OPTIONS FOR SUBCOMMAND export

-f | --prefile path/to/PRE.preplan

Read the PRE from a file. Mutually exclusive with -p|--preplan.

-p | --preplan PRE

Provide the PRE directly on the command line. Mutually exclusive with -f|--prefile.

OPTIONS FOR SUBCOMMAND init

The init subcommand does not enumerate execution orders. Instead, it extracts symbol names from the PRE (or list of subroutines) and generates Perl code stubs suitable for manual editing.

-x | --run

Selects the execution style embedded in the generated code. Default is once.

Supported values:

once

Generate code that invokes Sub::Genius::run_once.

any

Generate code that invokes Sub::Genius::run_any.

all

Generate code that invokes Sub::Genius::run_once inside a loop to iterate over all valid execution orders.

nodeps

Generate code with no dependency on Sub::Genius. All subroutine calls are explicit and sequentialized.

-p | --preplan

Provide the PRE inline.

When used with once, any, or all, the PRE is parsed only to extract symbol names; no DFA is built.

When used with nodeps, the PRE is necessarily compiled and a valid sequential ordering is emitted.

-f | --prefile

Read the PRE from a file. Mutually exclusive with -p|--preplan.

OPTIONS FOR SUBCOMMAND list

-f | --prefile path/to/PRE.preplan

Read the PRE from a file. Mutually exclusive with -p|--preplan.

-p | --preplan PRE

Provide the PRE directly on the command line.

OPTIONS FOR SUBCOMMAND precache

The precache subcommand explicitly prepares cached DFAs for reuse. This is especially useful for large or highly shuffled PREs.

-d | --cachedir path/to/cachedir

Directory in which to store cached DFAs. Passed directly to the cachedir parameter of Sub::Genius-new>.

-f | --prefile path/to/PRE.preplan

Read the PRE from a file. Mutually exclusive with -p|--preplan.

-p | --preplan PRE

Provide the PRE directly on the command line.

--force

Force regeneration of the cache entry even if a matching checksum already exists in the cache directory.

SEE ALSO

Sub::Genius, Sub::Genius::Util, Sub::Genius::Example

BUGS

Probably. If you find one, it is almost certainly real.

COPYRIGHT AND LICENSE

Same terms as Perl itself.

AUTHOR

OODLER 577 <oodler@cpan.org>