package Venus;

use 5.018;

use strict;
use warnings;

# VERSION

our $VERSION = '1.90';

# AUTHORITY

our $AUTHORITY = 'cpan:AWNCORP';

# IMPORTS

sub import {
  my ($self, @args) = @_;

  my $target = caller;

  no strict 'refs';

  my %exports = (
    cast => 1,
    catch => 1,
    error => 1,
    false => 1,
    fault => 1,
    raise => 1,
    true => 1,
  );

  @args = grep defined && !ref && /^[A-Za-z]/ && $exports{$_}, @args;

  my %seen;
  for my $name (grep !$seen{$_}++, @args, 'true', 'false') {
    *{"${target}::${name}"} = $self->can($name) if !$target->can($name);
  }

  return $self;
}

# FUNCTIONS

sub cast (;$$) {
  my ($data, $into) = (@_ ? (@_) : ($_));

  require Venus::Type;

  my $type = Venus::Type->new($data);

  return $into ? $type->cast($into) : $type->deduce;
}

sub catch (&) {
  my ($data) = @_;

  my $error;

  require Venus::Try;

  my @result = Venus::Try->new($data)->error(\$error)->result;

  return wantarray ? ($error ? ($error, undef) : ($error, @result)) : $error;
}

sub error (;$) {
  my ($data) = @_;

  $data //= {};
  $data->{context} //= (caller(1))[3];

  require Venus::Throw;

  return Venus::Throw->new->error($data);
}

sub false () {
  require Venus::False;

  return Venus::False->value;
}

sub fault (;$) {
  my ($data) = @_;

  require Venus::Fault;

  return Venus::Fault->new($data)->throw;
}

sub raise ($;$) {
  my ($self, $data) = @_;

  ($self, my $parent) = (@$self) if (ref($self) eq 'ARRAY');

  $data //= {};
  $data->{context} //= (caller(1))[3];

  $parent = 'Venus::Error' if !$parent;

  require Venus::Throw;

  return Venus::Throw->new(package => $self, parent => $parent)->error($data);
}

sub true () {
  require Venus::True;

  return Venus::True->value;
}

1;


=head1 NAME

Venus - OO Library

=cut

=head1 ABSTRACT

OO Standard Library for Perl 5

=cut

=head1 VERSION

1.90

=cut

=head1 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;

=cut

=head1 DESCRIPTION

This library provides an object-orientation framework and extendible standard
library for Perl 5, built on top of the L<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 C<true> and C<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 C<5.18+>.

=cut

=head1 FUNCTIONS

This package provides the following functions:

=cut

=head2 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.

I<Since C<1.40>>

=over 4

=item cast example 1

  package main;

  use Venus 'cast';

  my $undef = cast;

  # bless({value => undef}, "Venus::Undef")

=back

=over 4

=item cast example 2

  package main;

  use Venus 'cast';

  my @booleans = map cast, true, false;

  # (bless({value => 1}, "Venus::Boolean"), bless({value => 0}, "Venus::Boolean"))

=back

=over 4

=item cast example 3

  package main;

  use Venus 'cast';

  my $example = cast bless({}, "Example");

  # bless({value => 1}, "Example")

=back

=over 4

=item cast example 4

  package main;

  use Venus 'cast';

  my $float = cast 1.23;

  # bless({value => "1.23"}, "Venus::Float")

=back

=cut

=head2 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.

I<Since C<0.01>>

=over 4

=item catch example 1

  package main;

  use Venus 'catch';

  my $error = catch {die};

  $error;

  # "Died at ..."

=back

=over 4

=item catch example 2

  package main;

  use Venus 'catch';

  my ($error, $result) = catch {error};

  $error;

  # bless({...}, 'Venus::Error')

=back

=over 4

=item catch example 3

  package main;

  use Venus 'catch';

  my ($error, $result) = catch {true};

  $result;

  # 1

=back

=cut

=head2 error

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

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

I<Since C<0.01>>

=over 4

=item error example 1

  package main;

  use Venus 'error';

  my $error = error;

  # bless({...}, 'Venus::Error')

=back

=over 4

=item error example 2

  package main;

  use Venus 'error';

  my $error = error {
    message => 'Something failed!',
  };

  # bless({message => 'Something failed!', ...}, 'Venus::Error')

=back

=cut

=head2 false

  false() (Bool)

The false function returns a falsy boolean value which is designed to be
practically indistinguishable from the conventional numerical C<0> value.

I<Since C<0.01>>

=over 4

=item false example 1

  package main;

  use Venus;

  my $false = false;

  # 0

=back

=over 4

=item false example 2

  package main;

  use Venus;

  my $true = !false;

  # 1

=back

=cut

=head2 fault

  fault(Str $args) (Fault)

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

I<Since C<1.80>>

=over 4

=item fault example 1

  package main;

  use Venus 'fault';

  my $fault = fault;

  # bless({message => 'Exception!'}, 'Venus::Fault')

=back

=over 4

=item fault example 2

  package main;

  use Venus 'fault';

  my $fault = fault 'Something failed!';

  # bless({message => 'Something failed!'}, 'Venus::Fault')

=back

=cut

=head2 raise

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

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

I<Since C<0.01>>

=over 4

=item raise example 1

  package main;

  use Venus 'raise';

  my $error = raise 'MyApp::Error';

  # bless({...}, 'MyApp::Error')

=back

=over 4

=item raise example 2

  package main;

  use Venus 'raise';

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

  # bless({...}, 'MyApp::Error')

=back

=over 4

=item raise example 3

  package main;

  use Venus 'raise';

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

  # bless({message => 'Something failed!', ...}, 'MyApp::Error')

=back

=cut

=head2 true

  true() (Bool)

The true function returns a truthy boolean value which is designed to be
practically indistinguishable from the conventional numerical C<1> value.

I<Since C<0.01>>

=over 4

=item true example 1

  package main;

  use Venus;

  my $true = true;

  # 1

=back

=over 4

=item true example 2

  package main;

  use Venus;

  my $false = !true;

  # 0

=back

=cut

=head1 FEATURES

This package provides the following features:

=cut

=over 4

=item standard-library

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

B<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

=back

=over 4

=item value-classes

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

B<example 1>

  package main;

  use Venus::Array;

  my $array = Venus::Array->new;

  # bless({...}, 'Venus::Array')

B<example 2>

  package main;

  use Venus::Boolean;

  my $boolean = Venus::Boolean->new;

  # bless({...}, 'Venus::Boolean')

B<example 3>

  package main;

  use Venus::Code;

  my $code = Venus::Code->new;

  # bless({...}, 'Venus::Code')

B<example 4>

  package main;

  use Venus::Float;

  my $float = Venus::Float->new;

  # bless({...}, 'Venus::Float')

B<example 5>

  package main;

  use Venus::Hash;

  my $hash = Venus::Hash->new;

  # bless({...}, 'Venus::Hash')

B<example 6>

  package main;

  use Venus::Number;

  my $number = Venus::Number->new;

  # bless({...}, 'Venus::Number')

B<example 7>

  package main;

  use Venus::Regexp;

  my $regexp = Venus::Regexp->new;

  # bless({...}, 'Venus::Regexp')

B<example 8>

  package main;

  use Venus::Scalar;

  my $scalar = Venus::Scalar->new;

  # bless({...}, 'Venus::Scalar')

B<example 9>

  package main;

  use Venus::String;

  my $string = Venus::String->new;

  # bless({...}, 'Venus::String')

B<example 10>

  package main;

  use Venus::Undef;

  my $undef = Venus::Undef->new;

  # bless({...}, 'Venus::Undef')

=back

=over 4

=item builtin-autoboxing

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

B<example 1>

  package main;

  use Venus::String;

  my $string = Venus::String->new('hello, world');

  $string->box->split(', ')->join(' ')->titlecase->unbox->get;

  # Hello World

=back

=over 4

=item utility-classes

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

B<example 1>

  package main;

  use Venus::Args;

  my $args = Venus::Args->new;

  # bless({...}, 'Venus::Args')

B<example 2>

  package main;

  use Venus::Box;

  my $box = Venus::Box->new;

  # bless({...}, 'Venus::Box')

B<example 3>

  package main;

  use Venus::Data;

  my $docs = Venus::Data->new->docs;

  # bless({...}, 'Venus::Data')

B<example 4>

  package main;

  use Venus::Date;

  my $date = Venus::Date->new;

  # bless({...}, 'Venus::Date')

B<example 5>

  package main;

  use Venus::Error;

  my $error = Venus::Error->new;

  # bless({...}, 'Venus::Error')

B<example 6>

  package main;

  use Venus::Json;

  my $json = Venus::Json->new;

  # bless({...}, 'Venus::Json')

B<example 7>

  package main;

  use Venus::Name;

  my $name = Venus::Name->new;

  # bless({...}, 'Venus::Name')

B<example 8>

  package main;

  use Venus::Opts;

  my $opts = Venus::Opts->new;

  # bless({...}, 'Venus::Opts')

B<example 9>

  package main;

  use Venus::Path;

  my $path = Venus::Path->new;

  # bless({...}, 'Venus::Path')

B<example 10>

  package main;

  use Venus::Data;

  my $text = Venus::Data->new->text;

  # bless({...}, 'Venus::Data')

B<example 11>

  package main;

  use Venus::Space;

  my $space = Venus::Space->new;

  # bless({...}, 'Venus::Space')

B<example 12>

  package main;

  use Venus::Throw;

  my $throw = Venus::Throw->new;

  # bless({...}, 'Venus::Throw')

B<example 13>

  package main;

  use Venus::Try;

  my $try = Venus::Try->new;

  # bless({...}, 'Venus::Try')

B<example 14>

  package main;

  use Venus::Type;

  my $type = Venus::Type->new;

  # bless({...}, 'Venus::Type')

B<example 15>

  package main;

  use Venus::Vars;

  my $vars = Venus::Vars->new;

  # bless({...}, 'Venus::Vars')

B<example 16>

  package main;

  use Venus::Match;

  my $match = Venus::Match->new;

  # bless({...}, 'Venus::Match')

B<example 17>

  package main;

  use Venus::Process;

  my $process = Venus::Process->new;

  # bless({...}, 'Venus::Process')

B<example 18>

  package main;

  use Venus::Template;

  my $template = Venus::Template->new;

  # bless({...}, 'Venus::Template')

B<example 19>

  package main;

  use Venus::Yaml;

  my $yaml = Venus::Yaml->new;

  # bless({...}, 'Venus::Yaml')

=back

=over 4

=item package-reflection

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

B<example 1>

  package main;

  use Venus::Space;

  my $space = Venus::Space->new('Venus');

  $space->do('tryload')->routines;

  # [...]

=back

=over 4

=item exception-handling

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

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

=back

=over 4

=item composable-standards

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

B<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"}'

=back

=over 4

=item 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)

B<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"

=back

=over 4

=item template-system

This library provides a minimalistic templating system.

B<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!"

=back

=head1 AUTHORS

Awncorp, C<awncorp@cpan.org>

=head1 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.

=cut