NAME Venus - OO Library ABSTRACT OO Standard Library for Perl 5 VERSION 2.50 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 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+. CAPABILITIES The following is a short list of capabilities: * Perl 5.18.0+ * Zero Dependencies * Fast Object-Orientation * Robust Standard Library * Intuitive Value Classes * Pure Perl Autoboxing * Convenient Utility Classes * Simple Package Reflection * Flexible Exception Handling * Composable Standards * Pluggable (no monkeypatching) * Proxyable Methods * Type Assertions * Type Coercions * Value Casting * Boolean Values * Complete Documentation * Complete Test Coverage 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 2.32 args example 1 package main; use Venus 'args'; my $args = args(content => 'example'); # {content => "example"} args example 2 package main; use Venus 'args'; my $args = args({content => 'example'}); # {content => "example"} args example 3 package main; use Venus 'args'; my $args = args('content'); # {content => undef} args example 4 package main; use Venus 'args'; my $args = args('content', 'example', 'algorithm'); # {content => "example", algorithm => undef} assert assert(Any $data, Str $expr) (Any) The assert function builds a Venus::Assert object and returns the result of a "validate" in Venus::Assert operation. Since 2.40 assert example 1 package main; use Venus 'assert'; my $assert = assert(1234567890, 'number'); # 1234567890 assert example 2 package main; use Venus 'assert'; my $assert = assert(1234567890, 'float'); # Exception! (isa Venus::Assert::Error) box box(Any $data) (Box) The box function returns a Venus::Box object for the argument provided. Since 2.32 box example 1 package main; use Venus 'box'; my $box = box({}); # bless({value => bless({value => {}}, 'Venus::Hash')}, 'Venus::Box') box example 2 package main; use Venus 'box'; my $box = box([]); # bless({value => bless({value => []}, 'Venus::Array')}, 'Venus::Box') call call(Str | Object | CodeRef $data, Any @args) (Any) The call function dispatches function and method calls to a package and returns the result. Since 2.32 call example 1 package main; use Venus 'call'; require Digest::SHA; my $result = call(\'Digest::SHA', 'new'); # bless(do{\(my $o = '...')}, 'digest::sha') call example 2 package main; use Venus 'call'; require Digest::SHA; my $result = call('Digest::SHA', 'sha1_hex'); # "da39a3ee5e6b4b0d3255bfef95601890afd80709" call example 3 package main; use Venus 'call'; require Venus::Hash; my $result = call(sub{'Venus::Hash'->new(@_)}, {1..4}); # bless({value => {1..4}}, 'Venus::Hash') call example 4 package main; use Venus 'call'; require Venus::Box; my $result = call(Venus::Box->new(value => {}), 'merge', {1..4}); # bless({value => bless({value => {1..4}}, 'Venus::Hash')}, 'Venus::Box') 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') 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 2.32 chain example 1 package main; use Venus 'chain'; my $result = chain('Venus::Path', ['new', 't'], 'exists'); # 1 chain example 2 package main; use Venus 'chain'; my $result = chain('Venus::Path', ['new', 't'], ['test', 'd']); # 1 check check(Any $data, Str $expr) (Bool) The check function builds a Venus::Assert object and returns the result of a "check" in Venus::Assert operation. Since 2.40 check example 1 package main; use Venus 'check'; my $check = check(rand, 'float'); # true check example 2 package main; use Venus 'check'; my $check = check(rand, 'string'); # false cop cop(Str | Object | CodeRef $self, Str $name) (CodeRef) The cop function attempts to curry the given subroutine on the object or class and if successful returns a closure. Since 2.32 cop example 1 package main; use Venus 'cop'; my $coderef = cop('Digest::SHA', 'sha1_hex'); # sub { ... } cop example 2 package main; use Venus 'cop'; require Digest::SHA; my $coderef = cop(Digest::SHA->new, 'digest'); # sub { ... } 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') json json(Str $call, Any $data) (Any) The json function builds a Venus::Json object and will either "decode" in Venus::Json or "encode" in Venus::Json based on the argument provided and returns the result. Since 2.40 json example 1 package main; use Venus 'json'; my $decode = json 'decode', '{"codename":["Ready","Robot"],"stable":true}'; # { codename => ["Ready", "Robot"], stable => 1 } json example 2 package main; use Venus 'json'; my $encode = json 'encode', { codename => ["Ready", "Robot"], stable => true }; # '{"codename":["Ready","Robot"],"stable":true}' load load(Any $name) (Space) The load function loads the package provided and returns a Venus::Space object. Since 2.32 load example 1 package main; use Venus 'load'; my $space = load 'Venus::Scalar'; # bless({value => 'Venus::Scalar'}, 'Venus::Space') log log(Any @args) (Log) The log function prints the arguments provided to STDOUT, stringifying complex values, and returns a Venus::Log object. Since 2.40 log example 1 package main; use Venus 'log'; my $log = log; # bless({...}, 'Venus::Log') # log time, rand, 1..9; # 00000000 0.000000, 1..9 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 2.32 make example 1 package main; use Venus 'make'; my $made = make('Digest::SHA'); # bless(do{\(my $o = '...')}, 'Digest::SHA') make example 2 package main; use Venus 'make'; my $made = make('Digest', 'SHA'); # bless(do{\(my $o = '...')}, 'Digest::SHA') merge merge(HashRef @args) (HashRef) The merge function returns a hash reference which is a merger of all of the hashref arguments provided. Since 2.32 merge example 1 package main; use Venus 'merge'; my $merged = merge({1..4}, {5, 6}); # {1..6} merge example 2 package main; use Venus 'merge'; my $merged = merge({1..4}, {5, 6}, {7, 8, 9, 0}); # {1..9, 0} perl perl(Str $call, Any $data) (Any) The perl function builds a Venus::Dump object and will either "decode" in Venus::Dump or "encode" in Venus::Dump based on the argument provided and returns the result. Since 2.40 perl example 1 package main; use Venus 'perl'; my $decode = perl 'decode', '{stable=>bless({},\'Venus::True\')}'; # { stable => 1 } perl example 2 package main; use Venus 'perl'; my $encode = perl 'encode', { stable => true }; # '{stable=>bless({},\'Venus::True\')}' 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') 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 2.32 roll example 1 package main; use Venus 'roll'; my @list = roll('sha1_hex', 'Digest::SHA'); # ('Digest::SHA', 'sha1_hex'); roll example 2 package main; use Venus 'roll'; my @list = roll('sha1_hex', call(\'Digest::SHA', 'new')); # (bless(do{\(my $o = '...')}, 'Digest::SHA'), 'sha1_hex'); space space(Any $name) (Space) The space function returns a Venus::Space object for the package provided. Since 2.32 space example 1 package main; use Venus 'space'; my $space = space 'Venus::Scalar'; # bless({value => 'Venus::Scalar'}, 'Venus::Space') 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 2.32 then example 1 package main; use Venus 'then'; my @list = then('Digest::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 Venus; my $true = true; # 1 true example 2 package main; use Venus; my $false = !true; # 0 unpack unpack(Any @args) (Unpack) The unpack function builds and returns a Venus::Unpack object. Since 2.40 unpack example 1 package main; use Venus 'unpack'; my $unpack = unpack; # bless({...}, 'Venus::Unpack') # $unpack->checks('string'); # false # $unpack->checks('undef'); # false unpack example 2 package main; use Venus 'unpack'; my $unpack = unpack rand; # bless({...}, 'Venus::Unpack') # $unpack->check('number'); # false # $unpack->check('float'); # true venus venus(Str $name, Any @args) (Any) The venus function build a Venus package via the "chain" function based on the name provided and returns an instance of that package. Since 2.40 venus example 1 package main; use Venus 'venus'; my $space = venus 'space'; # bless({value => 'Venus'}, 'Venus::Space') venus example 2 package main; use Venus 'venus'; my $space = venus 'space', ['new', 'venus/string']; # bless({value => 'Venus::String'}, 'Venus::Space') venus example 3 package main; use Venus 'venus'; my $space = venus 'code'; # bless({value => sub{...}}, 'Venus::Code') work work(CodeRef $callback) (Process) The work function builds a Venus::Process object, forks the current process using the callback provided via the "work" in Venus::Process operation, and returns an instance of Venus::Process representing the current process. Since 2.40 work example 1 package main; use Venus 'work'; my $parent = work sub { my ($process) = @_; # in forked process ... $process->exit; }; # bless({...}, 'Venus::Process') wrap wrap(Str $data, Str $name) (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 2.32 wrap example 1 package main; use Venus 'wrap'; my $coderef = wrap('Digest::SHA'); # sub { ... } # my $digest = DigestSHA(); # "Digest::SHA" # my $digest = DigestSHA(1); # bless(do{\(my $o = '...')}, 'Digest::SHA') wrap example 2 package main; use Venus 'wrap'; my $coderef = wrap('Digest::SHA', 'SHA'); # sub { ... } # my $digest = SHA(); # "Digest::SHA" # my $digest = SHA(1); # bless(do{\(my $o = '...')}, 'Digest::SHA') yaml yaml(Str $call, Any $data) (Any) The yaml function builds a Venus::Yaml object and will either "decode" in Venus::Yaml or "encode" in Venus::Yaml based on the argument provided and returns the result. Since 2.40 yaml example 1 package main; use Venus 'yaml'; my $decode = yaml 'decode', "---\nname:\n- Ready\n- Robot\nstable: true\n"; # { name => ["Ready", "Robot"], stable => 1 } yaml example 2 package main; use Venus 'yaml'; my $encode = yaml 'encode', { name => ["Ready", "Robot"], stable => true }; # '---\nname:\n- Ready\n- Robot\nstable: true\n' FEATURES This package provides the following features: venus-args This library contains a Venus::Args class which provides methods for accessing @ARGS items. venus-array This library contains a Venus::Array class which provides methods for manipulating array data. venus-assert This library contains a Venus::Assert class which provides a mechanism for asserting type constraints and coercion. venus-boolean This library contains a Venus::Boolean class which provides a representation for boolean values. venus-box This library contains a Venus::Box class which provides a pure Perl boxing mechanism. venus-class This library contains a Venus::Class class which provides a class builder. venus-cli This library contains a Venus::Cli class which provides a superclass for creating CLIs. venus-code This library contains a Venus::Code class which provides methods for manipulating subroutines. venus-config This library contains a Venus::Config class which provides methods for loading Perl, YAML, and JSON configuration data. venus-data This library contains a Venus::Data class which provides methods for extracting DATA sections and POD block. venus-date This library contains a Venus::Date class which provides methods for formatting, parsing, and manipulating dates. venus-dump This library contains a Venus::Dump class which provides methods for reading and writing dumped Perl data. venus-error This library contains a Venus::Error class which represents a context-aware error (exception object). venus-false This library contains a Venus::False class which provides the global false value. venus-fault This library contains a Venus::Fault class which represents a generic system error (exception object). venus-float This library contains a Venus::Float class which provides methods for manipulating float data. venus-gather This library contains a Venus::Gather class which provides an object-oriented interface for complex pattern matching operations on collections of data, e.g. array references. venus-hash This library contains a Venus::Hash class which provides methods for manipulating hash data. venus-json This library contains a Venus::Json class which provides methods for reading and writing JSON data. venus-log This library contains a Venus::Log class which provides methods for logging information using various log levels. venus-match This library contains a Venus::Match class which provides an object-oriented interface for complex pattern matching operations on scalar values. venus-meta This library contains a Venus::Meta class which provides configuration information for Venus derived classes. venus-mixin This library contains a Venus::Mixin class which provides a mixin builder. venus-name This library contains a Venus::Name class which provides methods for parsing and formatting package namespaces. venus-number This library contains a Venus::Number class which provides methods for manipulating number data. venus-opts This library contains a Venus::Opts class which provides methods for handling command-line arguments. venus-path This library contains a Venus::Path class which provides methods for working with file system paths. venus-process This library contains a Venus::Process class which provides methods for handling and forking processes. venus-prototype This library contains a Venus::Prototype class which provides a simple construct for enabling prototype-base programming. venus-random This library contains a Venus::Random class which provides an object-oriented interface for Perl's pseudo-random number generator. venus-regexp This library contains a Venus::Regexp class which provides methods for manipulating regexp data. venus-replace This library contains a Venus::Replace class which provides methods for manipulating regexp replacement data. venus-scalar This library contains a Venus::Scalar class which provides methods for manipulating scalar data. venus-search This library contains a Venus::Search class which provides methods for manipulating regexp search data. venus-space This library contains a Venus::Space class which provides methods for parsing and manipulating package namespaces. venus-string This library contains a Venus::String class which provides methods for manipulating string data. venus-template This library contains a Venus::Template class which provides a templating system, and methods for rendering template. venus-test This library contains a Venus::Test class which aims to provide a standard for documenting Venus derived software projects. venus-throw This library contains a Venus::Throw class which provides a mechanism for generating and raising error objects. venus-true This library contains a Venus::True class which provides the global true value. venus-try This library contains a Venus::Try class which provides an object-oriented interface for performing complex try/catch operations. venus-type This library contains a Venus::Type class which provides methods for casting native data types to objects. venus-undef This library contains a Venus::Undef class which provides methods for manipulating undef data. venus-unpack This library contains a Venus::Unpack class which provides methods for validating, coercing, and otherwise operating on lists of arguments. venus-vars This library contains a Venus::Vars class which provides methods for accessing %ENV items. venus-yaml This library contains a Venus::Yaml class which provides methods for reading and writing YAML data. 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.