view release on metacpan or  search on metacpan

lib/Sub/Genius/Util.pm  view on Meta::CPAN

    return $sq;
}

1;

=encoding UTF-8

=head1 NAME

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

=head1 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
L<stubby>, but its methods may also be invoked directly when exploring,
debugging, or materializing Sub::Genius plans.

=head1 DESCRIPTION

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

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

=over 4

=item *
Generating Perl code from declarative plans

=item *
Materializing execution order explicitly

=item *
Bootstrapping scripts or modules from plans

=item *
Eliminating runtime dependency on Sub::Genius when desired

=back

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

=head2 Generated Subroutine Shape

When generating Perl code that corresponds to plan symbols, each
subroutine is emitted with a conventional structure compatible with
C<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
C<$scope> hash reference is threaded through the execution plan.

=head1 METHODS

=head2 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.

=head2 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:

=over 4

=item *
Does not depend on L<Sub::Genius> at runtime

=item *
Contains explicit subroutine calls

=item *
Passes a C<$scope> variable between calls

=back

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
C<Sub::Genius::run_once> would execute dynamically, but fully spelled
out:

    my $scope = {};
    $scope = C($scope);
    $scope = A($scope);