NAME

    Earth - FP Framework

ABSTRACT

    FP Framework for Perl 5

VERSION

    0.03

SYNOPSIS

      package main;
    
      use Earth;
    
      wrap 'Digest::SHA', 'SHA';
    
      call(SHA(), 'sha1_hex');
    
      # "da39a3ee5e6b4b0d3255bfef95601890afd80709"

DESCRIPTION

    Earth is a functional-programming framework for Perl 5. Perl is a
    multi-paradigm programming language that also supports functional
    programming, but, Perl has an intentionally limited standard library
    with an emphasis on providing library support via the CPAN which is
    overwhelmingly object-oriented. This makes developing in a functional
    style difficult as you'll eventually need to rely on a CPAN library
    that requires you to switch over to object-oriented programming. Earth
    facilitates functional programming for Perl 5 by providing functions
    which enable indirect routine dispatching, allowing the execution of
    both functional and object-oriented code.

FUNCTIONS

    This package provides the following functions:

 args

      args(Any @args) (HashRef)

    The args function takes a list of arguments and returns a hashref.

    Since 0.04

    args example 1

        # given: synopsis
      
        args(content => 'example');
      
        # {content => "example"}

    args example 2

        # given: synopsis
      
        args({content => 'example'});
      
        # {content => "example"}

    args example 3

        # given: synopsis
      
        args('content');
      
        # {content => undef}

    args example 4

        # given: synopsis
      
        args('content', 'example', 'algorithm');
      
        # {content => "example", algorithm => undef}

 call

      call(Str | Object | CodeRef $self, Any @args) (Any)

    The call function dispatches function and method calls to a package and
    returns the result.

    Since 0.01

    call example 1

        # given: synopsis
      
        call(SHA, 'sha1_hex');
      
        # "da39a3ee5e6b4b0d3255bfef95601890afd80709"

    call example 2

        # given: synopsis
      
        call('Digest::SHA', 'sha1_hex');
      
        # "da39a3ee5e6b4b0d3255bfef95601890afd80709"

    call example 3

        # given: synopsis
      
        call(\SHA, 'new');
      
        # bless(do{\(my $o = '...')}, 'Digest::SHA')

    call example 4

        # given: synopsis
      
        wrap 'Digest';
      
        call(Digest('SHA'), 'reset');
      
        # "da39a3ee5e6b4b0d3255bfef95601890afd80709"

 can

      can(Str | Object | CodeRef $self, Str $name) (CodeRef)

    The can function checks if the object or class has a routine matching
    the name provided, and if so returns a coderef for that routine.

    Since 0.02

    can example 1

        # given: synopsis
      
        my $coderef = can(SHA(1), 'sha1_hex');
      
        # sub { ... }

 chain

      chain(Str | Object | CodeRef $self, Str | ArrayRef[Str] @args) (Any)

    The chain function chains function and method calls to a package (and
    return values) and returns the result.

    Since 0.01

    chain example 1

        # given: synopsis
      
        my $hex = chain(\SHA, 'new', 'sha1_hex');
      
        # "d3aed913fdc7f277dddcbde47d50a8b5259cb4bc"

    chain example 2

        # given: synopsis
      
        my $hex = chain(\SHA, 'new', ['add', 'hello'], 'sha1_hex');
      
        # "f47b0cd4b6336d07ab117d7ee3f47566c9799f23"

    chain example 3

        # given: synopsis
      
        wrap 'Digest';
      
        my $hex = chain(Digest('SHA'), ['add', 'hello'], 'sha1_hex');
      
        # "8575ce82b266fdb5bc98eb43488c3b420577c24c"

 error

      error(Str $message, Int $offset, Int $limit) (Any)

    The error function dies with the error message provided and prints a
    stacktrace. If $limit or $offset are provided, those options will
    constrain the output of the stacktrace.

    Since 0.04

    error example 1

        # given: synopsis
      
        error;
      
        # "Exception!"

    error example 2

        # given: synopsis
      
        error('Exception!');
      
        # "Exception!"

    error example 3

        # given: synopsis
      
        error('Exception!', 0, 1);
      
        # "Exception!"

 false

      false() (Bool)

    The false function returns a falsy boolean value which is designed to
    be practically indistinguishable from the conventional numerical 0
    value.

    Since 0.01

    false example 1

        package main;
      
        use Earth;
      
        my $false = false;
      
        # 0

    false example 2

        package main;
      
        use Earth;
      
        my $true = !false;
      
        # 1

 make

      make(Str $package, Any @args) (Any)

    The make function "calls" the new routine on the invocant and returns
    the result which should be a package string or an object.

    Since 0.01

    make example 1

        # given: synopsis
      
        my $string = make(SHA);
      
        # bless(do{\(my $o = '...')}, 'Digest::SHA')

    make example 2

        # given: synopsis
      
        my $string = make(Digest, 'SHA');
      
        # bless(do{\(my $o = '...')}, 'Digest::SHA')

 roll

      roll(Str $name, Any @args) (Any)

    The roll function takes a list of arguments, assuming the first
    argument is invokable, and reorders the list such that the routine name
    provided comes after the invocant (i.e. the 1st argument), creating a
    list acceptable to the "call" function.

    Since 0.02

    roll example 1

        package main;
      
        use Earth;
      
        my @list = roll('sha1_hex', SHA);
      
        # ("Digest::SHA", "sha1_hex")

    roll example 2

        package main;
      
        use Earth;
      
        my @list = roll('sha1_hex', call(SHA(1), 'reset'));
      
        # (bless(do{\(my $o = '...')}, 'Digest::SHA'), "sha1_hex")

 then

      then(Str | Object | CodeRef $self, Any @args) (Any)

    The then function proxies the call request to the "call" function and
    returns the result as a list, prepended with the invocant.

    Since 0.02

    then example 1

        package main;
      
        use Earth;
      
        my @list = then(SHA, 'sha1_hex');
      
        # ("Digest::SHA", "da39a3ee5e6b4b0d3255bfef95601890afd80709")

 true

      true() (Bool)

    The true function returns a truthy boolean value which is designed to
    be practically indistinguishable from the conventional numerical 1
    value.

    Since 0.01

    true example 1

        package main;
      
        use Earth;
      
        my $true = true;
      
        # 1

    true example 2

        package main;
      
        use Earth;
      
        my $false = !true;
      
        # 0

 wrap

      wrap(Str $package, Str $alias) (CodeRef)

    The wrap function installs a wrapper function in the calling package
    which when called either returns the package string if no arguments are
    provided, or calls "make" on the package with whatever arguments are
    provided and returns the result. Unless an alias is provided as a
    second argument, special characters are stripped from the package to
    create the function name.

    Since 0.01

    wrap example 1

        # given: synopsis
      
        my $coderef = wrap('Digest::SHA');
      
        # my $digest = DigestSHA();
      
        # "Digest::SHA"

    wrap example 2

        # given: synopsis
      
        my $coderef = wrap('Digest::SHA');
      
        # my $digest = DigestSHA(1);
      
        # bless(do{\(my $o = '...')}, 'Digest::SHA')

    wrap example 3

        # given: synopsis
      
        my $coderef = wrap('Digest::SHA', 'SHA');
      
        # my $digest = SHA;
      
        # "Digest::SHA"

    wrap example 4

        # given: synopsis
      
        my $coderef = wrap('Digest::SHA', 'SHA');
      
        # my $digest = SHA(1);
      
        # bless(do{\(my $o = '...')}, 'Digest::SHA')

AUTHORS

    Awncorp, awncorp@cpan.org