NAME
    Scalar::Lazy - Yet another lazy evaluation in Perl

VERSION
    $Id: README,v 0.3 2008/06/01 17:09:08 dankogai Exp dankogai $

SYNOPSIS
      use Scalar::Lazy;
      my $scalar = lazy { 1 };
      print $scalar; # you don't have to force

      # Y-combinator made easy
      my $zm = sub { my $f = shift;
                     sub { my $x = shift; 
                           lazy { $f->($x->($x)) }
                       }->(sub { my $x = shift; 
                                 lazy { $f->($x->($x)) }
                             })};
      my $fact = $zm->(sub { my $f = shift;
                             sub { my $n = shift;
                                   $n < 2  ? 1 : $n * $f->($n - 1) } });
      print $fact->(10); # 3628800

DISCUSSION
    The classical way to implement lazy evaluation in an eager-evaluating
    languages (including perl, of course) is to wrap the value with a
    closure:

      sub delay{
        my $value = shift;
        sub { $value }
      }
      my $l = delay(42);

    Then evaluate the closure whenever you need it.

      my $v = $l->();

    Marking the variable lazy can be easier with prototypes:

      sub delay(&){ $_[0] }
      my $l = delay { 42 }

    But forcing the value is pain in the neck.

    This module makes it easier by making the value auto-forcing.

  HOW IT WORKS
    Check the source. That's what the source is for.

    There are various CPAN modules that does what this does. But I found
    others too complicated. Hey, the whole code is only 25 lines long!
    (Well, was until 0.03) Nicely fits in a good-old terminal screen.

    The closest module is Scalar::Defer, a brainchild of Audrey Tang. But I
    didn't like the way it (ab)?uses namespace.

    Data::Thunk depends too many modules.

    And Data::Lazy is overkill.

    All I needed was auto-forcing and this module does just that.

EXPORT
    "lazy" and "delay".

FUNCTIONS
  lazy
      lazy { value }

    is really:

      Scalar::Lazy->new(sub { value });

    You can optionally set the second parameter. If set, the value becomes
    constant. The folloing example illustrates the difference.

      my $x = 0;
      my $once = lazy { ++$x } 'init'; # $once is always 1
      is $once, 1, 'once';
      is $once, 1, 'once';
      my $succ = lazy { ++$x }; # $succ always increments $x
      isnt $succ, 1, 'succ';
      is $succ, 3, 'succ';

  delay
    an alias to "lazy".

METHODS
  new
    Makes a lazy variable which auto-forces on demand.

  force
    You don't really need to call this method (that's the whole point of
    this module!) but if you want, you can

      my $l = lazy { 1 };
      my $v = $l->force;

AUTHOR
    Dan Kogai, "<dankogai at dan.co.jp>"

BUGS
    Please report any bugs or feature requests to "bug-scalar-lazy at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scalar-Lazy>. I will be
    notified, and then you'll automatically be notified of progress on your
    bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc Scalar::Lazy

    You can also look for information at:

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Scalar-Lazy>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/Scalar-Lazy>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/Scalar-Lazy>

    *   Search CPAN

        <http://search.cpan.org/dist/Scalar-Lazy>

ACKNOWLEDGEMENTS
    Highly inspired by Scalar::Defer by Audrey Tang.

COPYRIGHT & LICENSE
    Copyright 2008 Dan Kogai, all rights reserved.

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

