/ 
Sub-Genius-0.314006
River stage zero No dependents
/ Sub::Genius::Util

NAME

Sub::Genius::Util - Utilities for generating and inspecting Perl code from Sub::Genius plans

SYNOPSIS

use Sub::Genius::Util;

# Generate a standalone Perl script from a plan
print Sub::Genius::Util->plan2nodeps(
    plan => q{ A & B & C }
);

This module is primarily intended for use by tooling such as stubby, but its methods may also be invoked directly when exploring, debugging, or materializing Sub::Genius plans.

DESCRIPTION

Sub::Genius::Util provides helper routines that operate on top of Sub::Genius to make execution plans concrete and inspectable.

Where Sub::Genius focuses on expressing and executing concurrency semantics, this module focuses on:

  • Generating Perl code from declarative plans

  • Materializing execution order explicitly

  • Bootstrapping scripts or modules from plans

  • Eliminating runtime dependency on Sub::Genius when desired

The utilities in this module are most commonly used during development, experimentation, or build-time code generation, rather than in long-running production systems.

Generated Subroutine Shape

When generating Perl code that corresponds to plan symbols, each subroutine is emitted with a conventional structure compatible with Sub::Genius::run_once:

sub C {
  my $scope      = shift;    # execution context
  state $mystate = {};       # persistent state (coroutine-style)
  my    $myprivs = {};       # lexical scratch space

  # --- implementation goes here ---
  print qq{Sub C: placeholder\n};

  return $scope;
}

This reflects the core Sub::Genius execution model, where a mutable $scope hash reference is threaded through the execution plan.

METHODS

subs2perl

Sub::Genius::Util->subs2perl(...);

Generates Perl subroutine stubs corresponding to the symbols implied by a plan.

This method exists to support tooling that initializes scripts or modules intended to be executed under Sub::Genius. The generated code is a starting point and is expected to be edited by hand.

plan2nodeps

Sub::Genius::Util->plan2nodeps( plan => $pre );

Given a PRE, generates a standalone Perl script that explicitly encodes the execution order implied by the plan.

The resulting script:

  • Does not depend on Sub::Genius at runtime

  • Contains explicit subroutine calls

  • Passes a $scope variable between calls

Example:

perl -MSub::Genius::Util \
     -e 'print Sub::Genius::Util->plan2nodeps(
           plan => q{A&B&C&D}
         )' > my-script.pl

This produces code equivalent to what Sub::Genius::run_once would execute dynamically, but fully spelled out:

my $scope = {};
$scope = C($scope);
$scope = A($scope);
$scope = D($scope);
$scope = B($scope);
$scope = E($scope);

The exact order depends on the chosen valid serialization.

precache

my $sg = Sub::Genius::Util->precache(%opts);

Invokes Sub::Genius caching facilities and returns an initialized Sub::Genius instance.

This method centralizes cache-related setup and ensures that PREs are compiled only once unless explicitly forced. It is primarily intended for build-time or tooling workflows.

DESIGN NOTES

This module is intentionally narrow in scope.

It does not attempt to abstract away the mechanics of Sub::Genius or hide how execution plans are linearized. Instead, it aims to make those mechanics explicit and inspectable.

If you find yourself calling these utilities repeatedly at runtime, it is worth reconsidering whether code generation is the appropriate tool for that use case.

SEE ALSO

Sub::Genius, Sub::Genius::Example, stubby

COPYRIGHT AND LICENSE

Same terms as Perl itself.

AUTHOR

OODLER 577 <oodler@cpan.org>