The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Earth-0.04
River stage zero No dependents
++
/ Earth

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