NAME

    Venus - OO Library

ABSTRACT

    OO Standard Library for Perl 5

VERSION

    2.01

SYNOPSIS

      package main;
    
      use Venus qw(
        catch
        error
        raise
      );
    
      # error handling
      my ($error, $result) = catch {
        error;
      };
    
      # boolean keywords
      if ($result and $result eq false) {
        true;
      }
    
      # raise exceptions
      if (false) {
        raise 'MyApp::Error';
      }
    
      # and much more!
      true ne false;

DESCRIPTION

    This library provides an object-orientation framework and extendible
    standard library for Perl 5, built on top of the Mars architecture with
    classes which wrap most native Perl data types. Venus has a simple
    modular architecture, robust library of classes, methods, and roles,
    supports pure-Perl autoboxing, advanced exception handling, "true" and
    "false" functions, package introspection, command-line options parsing,
    and more. This package will always automatically exports true and false
    keyword functions (unless existing routines of the same name already
    exist in the calling package or its parents), otherwise exports keyword
    functions as requested at import. This library requires Perl 5.18+.

FUNCTIONS

    This package provides the following functions:

 cast

      cast(Any $data, Str $type) (Object)

    The cast function returns the argument provided as an object, promoting
    native Perl data types to data type objects. The optional second
    argument can be the name of the type for the object to cast to
    explicitly.

    Since 1.40

    cast example 1

        package main;
      
        use Venus 'cast';
      
        my $undef = cast;
      
        # bless({value => undef}, "Venus::Undef")

    cast example 2

        package main;
      
        use Venus 'cast';
      
        my @booleans = map cast, true, false;
      
        # (bless({value => 1}, "Venus::Boolean"), bless({value => 0}, "Venus::Boolean"))

    cast example 3

        package main;
      
        use Venus 'cast';
      
        my $example = cast bless({}, "Example");
      
        # bless({value => 1}, "Example")

    cast example 4

        package main;
      
        use Venus 'cast';
      
        my $float = cast 1.23;
      
        # bless({value => "1.23"}, "Venus::Float")

 catch

      catch(CodeRef $block) (Error, Any)

    The catch function executes the code block trapping errors and
    returning the caught exception in scalar context, and also returning
    the result as a second argument in list context.

    Since 0.01

    catch example 1

        package main;
      
        use Venus 'catch';
      
        my $error = catch {die};
      
        $error;
      
        # "Died at ..."

    catch example 2

        package main;
      
        use Venus 'catch';
      
        my ($error, $result) = catch {error};
      
        $error;
      
        # bless({...}, 'Venus::Error')

    catch example 3

        package main;
      
        use Venus 'catch';
      
        my ($error, $result) = catch {true};
      
        $result;
      
        # 1

 caught

      caught(Object $error, Str | Tuple[Str, Str] $identity, CodeRef $block) (Any)

    The caught function evaluates the exception object provided and
    validates its identity and name (if provided) then executes the code
    block provided returning the result of the callback. If no callback is
    provided this function returns the exception object on success and
    undef on failure.

    Since 1.95

    caught example 1

        package main;
      
        use Venus 'catch', 'caught', 'error';
      
        my $error = catch { error };
      
        my $result = caught $error, 'Venus::Error';
      
        # bless(..., 'Venus::Error')

    caught example 2

        package main;
      
        use Venus 'catch', 'caught', 'raise';
      
        my $error = catch { raise 'Example::Error' };
      
        my $result = caught $error, 'Venus::Error';
      
        # bless(..., 'Venus::Error')

    caught example 3

        package main;
      
        use Venus 'catch', 'caught', 'raise';
      
        my $error = catch { raise 'Example::Error' };
      
        my $result = caught $error, 'Example::Error';
      
        # bless(..., 'Venus::Error')

    caught example 4

        package main;
      
        use Venus 'catch', 'caught', 'raise';
      
        my $error = catch { raise 'Example::Error', { name => 'on.test' } };
      
        my $result = caught $error, ['Example::Error', 'on.test'];
      
        # bless(..., 'Venus::Error')

    caught example 5

        package main;
      
        use Venus 'catch', 'caught', 'raise';
      
        my $error = catch { raise 'Example::Error', { name => 'on.recv' } };
      
        my $result = caught $error, ['Example::Error', 'on.send'];
      
        # undef

    caught example 6

        package main;
      
        use Venus 'catch', 'caught', 'error';
      
        my $error = catch { error };
      
        my $result = caught $error, ['Example::Error', 'on.send'];
      
        # undef

    caught example 7

        package main;
      
        use Venus 'catch', 'caught', 'error';
      
        my $error = catch { error };
      
        my $result = caught $error, ['Example::Error'];
      
        # undef

    caught example 8

        package main;
      
        use Venus 'catch', 'caught', 'error';
      
        my $error = catch { error };
      
        my $result = caught $error, 'Example::Error';
      
        # undef

    caught example 9

        package main;
      
        use Venus 'catch', 'caught', 'error';
      
        my $error = catch { error { name => 'on.send' } };
      
        my $result = caught $error, ['Venus::Error', 'on.send'];
      
        # bless(..., 'Venus::Error')

    caught example 10

        package main;
      
        use Venus 'catch', 'caught', 'error';
      
        my $error = catch { error { name => 'on.send.open' } };
      
        my $result = caught $error, ['Venus::Error', 'on.send'], sub {
          $error->stash('caught', true) if $error->is('on.send.open');
          return $error;
        };
      
        # bless(..., 'Venus::Error')

 error

      error(Maybe[HashRef] $args) (Error)

    The error function throws a Venus::Error exception object using the
    exception object arguments provided.

    Since 0.01

    error example 1

        package main;
      
        use Venus 'error';
      
        my $error = error;
      
        # bless({...}, 'Venus::Error')

    error example 2

        package main;
      
        use Venus 'error';
      
        my $error = error {
          message => 'Something failed!',
        };
      
        # bless({message => 'Something failed!', ...}, 'Venus::Error')

 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 Venus;
      
        my $false = false;
      
        # 0

    false example 2

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

 fault

      fault(Str $args) (Fault)

    The fault function throws a Venus::Fault exception object and
    represents a system failure, and isn't meant to be caught.

    Since 1.80

    fault example 1

        package main;
      
        use Venus 'fault';
      
        my $fault = fault;
      
        # bless({message => 'Exception!'}, 'Venus::Fault')

    fault example 2

        package main;
      
        use Venus 'fault';
      
        my $fault = fault 'Something failed!';
      
        # bless({message => 'Something failed!'}, 'Venus::Fault')

 raise

      raise(Str $class | Tuple[Str, Str] $class, Maybe[HashRef] $args) (Error)

    The raise function generates and throws a named exception object
    derived from Venus::Error, or provided base class, using the exception
    object arguments provided.

    Since 0.01

    raise example 1

        package main;
      
        use Venus 'raise';
      
        my $error = raise 'MyApp::Error';
      
        # bless({...}, 'MyApp::Error')

    raise example 2

        package main;
      
        use Venus 'raise';
      
        my $error = raise ['MyApp::Error', 'Venus::Error'];
      
        # bless({...}, 'MyApp::Error')

    raise example 3

        package main;
      
        use Venus 'raise';
      
        my $error = raise ['MyApp::Error', 'Venus::Error'], {
          message => 'Something failed!',
        };
      
        # bless({message => 'Something failed!', ...}, 'MyApp::Error')

 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 Venus;
      
        my $true = true;
      
        # 1

    true example 2

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

FEATURES

    This package provides the following features:

    standard-library

      This library provides a Perl object-oriented standard library with
      value classes and consistently named methods.

      example 1

        package main;
      
        use Venus::Array;
      
        my $array = Venus::Array->new([1..4]);
      
        # $array->all(sub{ $_ > 0 });
        # $array->any(sub{ $_ > 0 });
        # $array->each(sub{ $_ > 0 });
        # $array->grep(sub{ $_ > 0 });
        # $array->map(sub{ $_ > 0 });
        # $array->none(sub{ $_ < 0 });
        # $array->one(sub{ $_ == 0 });
        # $array->random;
      
        use Venus::Hash;
      
        my $hash = Venus::Hash->new({1..8});
      
        # $hash->all(sub{ $_ > 0 });
        # $hash->any(sub{ $_ > 0 });
        # $hash->each(sub{ $_ > 0 });
        # $hash->grep(sub{ $_ > 0 });
        # $hash->map(sub{ $_ > 0 });
        # $hash->none(sub{ $_ < 0 });
        # $hash->one(sub{ $_ == 0 });
        # $hash->random;
      
        $array->count == $hash->count;
      
        # 1

    value-classes

      This library provides value classes which wrap native Perl data types
      and provides methods for operating their values.

      example 1

        package main;
      
        use Venus::Array;
      
        my $array = Venus::Array->new;
      
        # bless({...}, 'Venus::Array')

      example 2

        package main;
      
        use Venus::Boolean;
      
        my $boolean = Venus::Boolean->new;
      
        # bless({...}, 'Venus::Boolean')

      example 3

        package main;
      
        use Venus::Code;
      
        my $code = Venus::Code->new;
      
        # bless({...}, 'Venus::Code')

      example 4

        package main;
      
        use Venus::Float;
      
        my $float = Venus::Float->new;
      
        # bless({...}, 'Venus::Float')

      example 5

        package main;
      
        use Venus::Hash;
      
        my $hash = Venus::Hash->new;
      
        # bless({...}, 'Venus::Hash')

      example 6

        package main;
      
        use Venus::Number;
      
        my $number = Venus::Number->new;
      
        # bless({...}, 'Venus::Number')

      example 7

        package main;
      
        use Venus::Regexp;
      
        my $regexp = Venus::Regexp->new;
      
        # bless({...}, 'Venus::Regexp')

      example 8

        package main;
      
        use Venus::Scalar;
      
        my $scalar = Venus::Scalar->new;
      
        # bless({...}, 'Venus::Scalar')

      example 9

        package main;
      
        use Venus::String;
      
        my $string = Venus::String->new;
      
        # bless({...}, 'Venus::String')

      example 10

        package main;
      
        use Venus::Undef;
      
        my $undef = Venus::Undef->new;
      
        # bless({...}, 'Venus::Undef')

    builtin-autoboxing

      This library provides opt-in pure Perl autoboxing allowing you to
      chain methods calls across objects and values.

      example 1

        package main;
      
        use Venus::String;
      
        my $string = Venus::String->new('hello, world');
      
        $string->box->split(', ')->join(' ')->titlecase->unbox->get;
      
        # Hello World

    utility-classes

      This library provides serveral essential utility classes for
      performing common programming tasks.

      example 1

        package main;
      
        use Venus::Args;
      
        my $args = Venus::Args->new;
      
        # bless({...}, 'Venus::Args')

      example 2

        package main;
      
        use Venus::Box;
      
        my $box = Venus::Box->new;
      
        # bless({...}, 'Venus::Box')

      example 3

        package main;
      
        use Venus::Data;
      
        my $docs = Venus::Data->new->docs;
      
        # bless({...}, 'Venus::Data')

      example 4

        package main;
      
        use Venus::Date;
      
        my $date = Venus::Date->new;
      
        # bless({...}, 'Venus::Date')

      example 5

        package main;
      
        use Venus::Error;
      
        my $error = Venus::Error->new;
      
        # bless({...}, 'Venus::Error')

      example 6

        package main;
      
        use Venus::Json;
      
        my $json = Venus::Json->new;
      
        # bless({...}, 'Venus::Json')

      example 7

        package main;
      
        use Venus::Name;
      
        my $name = Venus::Name->new;
      
        # bless({...}, 'Venus::Name')

      example 8

        package main;
      
        use Venus::Opts;
      
        my $opts = Venus::Opts->new;
      
        # bless({...}, 'Venus::Opts')

      example 9

        package main;
      
        use Venus::Path;
      
        my $path = Venus::Path->new;
      
        # bless({...}, 'Venus::Path')

      example 10

        package main;
      
        use Venus::Data;
      
        my $text = Venus::Data->new->text;
      
        # bless({...}, 'Venus::Data')

      example 11

        package main;
      
        use Venus::Space;
      
        my $space = Venus::Space->new;
      
        # bless({...}, 'Venus::Space')

      example 12

        package main;
      
        use Venus::Throw;
      
        my $throw = Venus::Throw->new;
      
        # bless({...}, 'Venus::Throw')

      example 13

        package main;
      
        use Venus::Try;
      
        my $try = Venus::Try->new;
      
        # bless({...}, 'Venus::Try')

      example 14

        package main;
      
        use Venus::Type;
      
        my $type = Venus::Type->new;
      
        # bless({...}, 'Venus::Type')

      example 15

        package main;
      
        use Venus::Vars;
      
        my $vars = Venus::Vars->new;
      
        # bless({...}, 'Venus::Vars')

      example 16

        package main;
      
        use Venus::Match;
      
        my $match = Venus::Match->new;
      
        # bless({...}, 'Venus::Match')

      example 17

        package main;
      
        use Venus::Process;
      
        my $process = Venus::Process->new;
      
        # bless({...}, 'Venus::Process')

      example 18

        package main;
      
        use Venus::Template;
      
        my $template = Venus::Template->new;
      
        # bless({...}, 'Venus::Template')

      example 19

        package main;
      
        use Venus::Yaml;
      
        my $yaml = Venus::Yaml->new;
      
        # bless({...}, 'Venus::Yaml')

    package-reflection

      This library provides a package reflection class, Venus::Space, which
      can be used to perform meta-programming on package spaces.

      example 1

        package main;
      
        use Venus::Space;
      
        my $space = Venus::Space->new('Venus');
      
        $space->do('tryload')->routines;
      
        # [...]

    exception-handling

      This library provides a framework for raising, i.e. generating and
      throwing, exception objects and catching them.

      example 1

        package MyApp;
      
        use Venus::Class;
      
        with 'Venus::Role::Tryable';
        with 'Venus::Role::Throwable';
        with 'Venus::Role::Catchable';
      
        sub execute {
          my ($self) = @_;
      
          $self->throw->error;
        }
      
        package main;
      
        my $myapp = MyApp->new;
      
        my $error = $myapp->catch('execute');
      
        # bless({...}, 'MyApp::Error');

    composable-standards

      This library provides a library of composable roles which can be used
      to extend core behaviors to custom objects.

      example 1

        package MyApp;
      
        use Venus::Class;
      
        with 'Venus::Role::Dumpable';
        with 'Venus::Role::Stashable';
      
        package main;
      
        my $myapp = MyApp->new;
      
        $myapp->stash(greeting => 'hello world');
      
        $myapp->dump('stash');
      
        # '{"greeting" => "hello world"}'

    pluggable-library

      This library provides a mechanism for extending the standard library,
      i.e. value classes, using plugins which can be automatically
      discovered and invoked. (no monkey-patching necessary)

      example 1

        package Venus::String::Plugin::Base64;
      
        sub new {
          return bless {};
        }
      
        sub execute {
          my ($self, $string, @args) = @_;
      
          require MIME::Base64;
      
          return MIME::Base64::encode_base64($string->value);
        }
      
        package main;
      
        use Venus::String;
      
        my $string = Venus::String->new('hello, world');
      
        $string->base64;
      
        # "aGVsbG8sIHdvcmxk\n"

    template-system

      This library provides a minimalistic templating system.

      example 1

        package main;
      
        use Venus::Template;
      
        my $template = Venus::Template->new(q(
          {{ if user.name }}
          Welcome, {{ user.name }}!
          {{ else user.name }}
          Welcome, friend!
          {{ end user.name }}
        ));
      
        $template->render;
      
        # "Welcome, friend!"

AUTHORS

    Awncorp, awncorp@cpan.org

LICENSE

    Copyright (C) 2000, Al Newkirk.

    This program is free software, you can redistribute it and/or modify it
    under the terms of the Apache license version 2.0.