NAME

    Venus - OO Library

ABSTRACT

    OO Standard Library for Perl 5

VERSION

    0.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 Moo with classes which
    wrap most native Perl data types. Venus has a simple modular
    architecture, robust library of classes and methods, supports pure-Perl
    autoboxing, advanced exception handling, "true" and "false" keywords,
    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), otherwise exports keyword functions as requested
    at import.

FUNCTIONS

    This package provides the following functions:

 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; # Venus::Error

    catch example 3

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

 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;

    error example 2

        package main;
      
        use Venus 'error';
      
        my $error = error {
          message => 'Something failed!',
        };

 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;

    false example 2

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

 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';

    raise example 2

        package main;
      
        use Venus 'raise';
      
        my $error = raise ['MyApp::Error', 'Venus::Error'];

    raise example 3

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

 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;

    true example 2

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

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;

    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;

      example 2

        package main;
      
        use Venus::Boolean;
      
        my $boolean = Venus::Boolean->new;

      example 3

        package main;
      
        use Venus::Code;
      
        my $code = Venus::Code->new;

      example 4

        package main;
      
        use Venus::Float;
      
        my $float = Venus::Float->new;

      example 5

        package main;
      
        use Venus::Hash;
      
        my $hash = Venus::Hash->new;

      example 6

        package main;
      
        use Venus::Number;
      
        my $number = Venus::Number->new;

      example 7

        package main;
      
        use Venus::Regexp;
      
        my $regexp = Venus::Regexp->new;

      example 8

        package main;
      
        use Venus::Scalar;
      
        my $scalar = Venus::Scalar->new;

      example 9

        package main;
      
        use Venus::String;
      
        my $string = Venus::String->new;

      example 10

        package main;
      
        use Venus::Undef;
      
        my $undef = Venus::Undef->new;

    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;

      example 2

        package main;
      
        use Venus::Box;
      
        my $box = Venus::Box->new;

      example 3

        package main;
      
        use Venus::Data;
      
        my $docs = Venus::Data->new->docs;

      example 4

        package main;
      
        use Venus::Date;
      
        my $date = Venus::Date->new;

      example 5

        package main;
      
        use Venus::Error;
      
        my $error = Venus::Error->new;

      example 6

        package main;
      
        use Venus::Json;
      
        my $json = Venus::Json->new;

      example 7

        package main;
      
        use Venus::Name;
      
        my $name = Venus::Name->new;

      example 8

        package main;
      
        use Venus::Opts;
      
        my $opts = Venus::Opts->new;

      example 9

        package main;
      
        use Venus::Path;
      
        my $path = Venus::Path->new;

      example 10

        package main;
      
        use Venus::Data;
      
        my $text = Venus::Data->new->text;

      example 11

        package main;
      
        use Venus::Space;
      
        my $space = Venus::Space->new;

      example 12

        package main;
      
        use Venus::Throw;
      
        my $throw = Venus::Throw->new;

      example 13

        package main;
      
        use Venus::Try;
      
        my $try = Venus::Try->new;

      example 14

        package main;
      
        use Venus::Type;
      
        my $type = Venus::Type->new;

      example 15

        package main;
      
        use Venus::Vars;
      
        my $vars = Venus::Vars->new;

    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::Throwable';
        with 'Venus::Role::Catchable';
      
        sub execute {
          my ($self) = @_;
      
          $self->throw->error;
        }
      
        package main;
      
        my $myapp = MyApp->new;
      
        $myapp->catch('execute'); # catch 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;

AUTHORS

    Cpanery, cpanery@cpan.org

LICENSE

    Copyright (C) 2021, Cpanery

    Read the "license"
    <https://github.com/cpanery/venus/blob/master/LICENSE> file.

PROJECT

    https://venus.cpanery.com

    https://github.com/cpanery/venus/wiki

    https://github.com/cpanery/venus/issues

    https://cpanery.com