view release on metacpan or  search on metacpan

lib/Data/Hive.pm  view on Meta::CPAN

#pod
#pod =head1 METHODS
#pod
#pod =head2 hive path methods
#pod
#pod All lowercase methods are used to travel down hive paths.
#pod
#pod When you call C<< $hive->some_name >>, the return value is another Data::Hive
#pod object using the same store as C<$hive> but with a starting path of
#pod C<some_name>.  With that hive, you can descend to deeper hives or you can get
#pod or set its value.
#pod
#pod Once you've reached the path where you want to perform a lookup or alteration,
#pod you call an all-uppercase method.  These are detailed below.
#pod
#pod =head2 hive access methods
#pod
#pod These methods are thin wrappers around required modules in L<Data::Hive::Store>
#pod subclasses.  These methods all basically call a method on the store with the
#pod same (but lowercased) name and pass it the hive's path.
#pod
#pod =head3 NEW
#pod
#pod This constructs a new hive object.  Note that the name is C<NEW> and not
#pod C<new>!  The C<new> method is just another method to pick a hive path part.
#pod
#pod The following are valid arguments for C<NEW>.
#pod
#pod =begin :list
#pod
#pod = store
#pod
#pod a L<Data::Hive::Store> object, or one with a compatible interface; this will be
#pod used as the hive's backend storage driver;  do not supply C<store_class> or
#pod C<store_args> if C<store> is supplied
#pod
#pod = store_class
#pod
#pod This names a class from which to instantiate a storage driver.  The classname
#pod will have C<Data::Hive::Store::> prepended; to avoid this, prefix it with a '='
#pod (C<=My::Store>).  A plus sign can be used instead of an equal sign, for
#pod historical reasons.
#pod
#pod = store_args
#pod
#pod If C<store_class> has been provided instead of C<store>, this argument may be
#pod given as an arrayref of arguments to pass (dereferenced) to the store class's
#pod C<new> method.
#pod
#pod =end :list
#pod
#pod =cut

sub NEW {
  my ($invocant, $arg) = @_;
  $arg ||= {};

  my @path = @{ $arg->{path} || [] };

  my $class = ref $invocant ? ref $invocant : $invocant;
  my $self = bless { path => \@path } => $class;

  if ($arg->{store_class}) {
    die "don't use 'store' with 'store_class' and 'store_args'"
      if $arg->{store};

    $arg->{store_class} = "Data::Hive::Store::$arg->{store_class}"
      unless $arg->{store_class} =~ s/^[+=]//;

    $self->{store} = $arg->{store_class}->new(@{ $arg->{store_args} || [] });
  } elsif ($arg->{store}) {
    $self->{store} = $arg->{store};
  } else {
    Carp::croak "can't create a hive with no store";
  }

  return $self;
}

#pod =head3 GET
#pod
#pod   my $value = $hive->some->path->GET( $default );
#pod
#pod The C<GET> method gets the hive value.  If there is no defined value at the
#pod path and a default has been supplied, the default will be returned instead.
#pod
#pod C<$default> should be a simple scalar or a subroutine.  If C<$default> is a
#pod subroutine, it will be called to compute the default only if needed.  The
#pod behavior for other types of defaults is undefined.
#pod
#pod =head4 overloading
#pod
#pod Hives are overloaded for stringification and numification so that they behave
#pod like their value when used without an explicit C<GET>.  This behavior is
#pod deprecated and will be removed in a future release.  Always use C<GET> to get
#pod the value of a hive.
#pod
#pod =cut

use overload (
  q{""}    => sub {
    Carp::carp "using hive as string for implicit GET is deprecated";
    shift->GET(@_);
  },
  q{0+}    => sub {
    Carp::carp "using hive as number for implicit GET is deprecated";
    shift->GET(@_);
  },
  fallback => 1,
);

sub GET {
  my ($self, $default) = @_;
  my $value = $self->STORE->get($self->{path});
  return defined $value     ? $value
       : ! defined $default ? undef
       : ref $default       ? scalar $default->()
       :                      $default;
}

#pod =head3 SET