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.