List::Filter::Internal - internal methods for parameter qualification, etc.

  use List::Filter::Internal;
  my $lfi = List::Filter::Internal->new( { default_stash => $default_stash } );
  my $storage = $lfi->qualify_storage( $args->{ storage } );

  # alternate (preferred?), creates:
  #   $HOME/.list-filter/filters.yaml
  my $lfi = List::Filter::Internal->new();
  my $storage = $lfi->qualify_storage_from_namespace(
                        $args->{ storage },
                        'filter',
                       );

package List::Filter::Internal;
use base qw( Class::Base );

use 5.8.0;
use strict;
use warnings;
my $DEBUG = 0;
use Carp qw(carp croak cluck confess);
use Data::Dumper;
use Hash::Util qw( lock_keys unlock_keys );
use Env qw( HOME );

use File::Path     qw(mkpath);
use File::Basename qw(fileparse basename dirname);
use File::Copy     qw(copy move);

our $VERSION = '0.01';

# Note:
# "new" is inherited from Class::Base.
# It calls the following "init" routine automatically.

sub init {
  my $self = shift;
  my $args = shift;
  unlock_keys( %{ $self } );

  # define new attributes
  my $attributes = {
           ### fill-in name/value pairs of attributes here
           # name          => $args->{ name },
           default_stash   => $args->{ default_stash },

           };

  # add attributes to object
  my @fields = (keys %{ $attributes });
  @{ $self }{ @fields } = @{ $attributes }{ @fields };    # hash slice

  lock_keys( %{ $self } );
  return $self;
}

### if $storage is an aref, then it should contain scalars and hrefs.
### if it contains another aref, it should toss an error, or at least a
### warning: that's an indication of a typo, e.g. "storage => [ $storage ]".

sub qualify_storage {
  my $self          = shift;
  my $storage       = shift;
  my $default_stash = $self->default_stash;

  $storage = qualify_storage_guts( $storage, $default_stash );

  return $storage;
}

sub qualify_storage_from_namespace {
  my $self          = shift;
  my $storage       = shift;
  my $namespace     = shift;

  my $default_stash = $self->define_yaml_default( $namespace );

  $storage = qualify_storage_guts( $storage, $default_stash );

  return $storage;
}


# qualify_storage_guts is an internally used sub (yes, in the
# Internal.pm module), which exists because if both of the front
# end methods call a sub, then "caller(1)" can point at the place
# where either were called.  (If one method were to call the other,
# then it'd be a more complicated problem).
sub qualify_storage_guts {
  my  $storage       = shift;
  my  $default_stash = shift;
  my ($package, $file, $line) = caller(1);

  if (not ( ref $storage eq 'ARRAY' )) {
    $storage = [ $storage ];
  } else { # we've (probably) got an aref...
    # But no arefs are allowed inside the main aref
    foreach my $entry ( @{ $storage } ) {
      if ( ref $entry eq 'ARRAY' ) {
        confess "The storage parameter should not be an aref inside an aref, in $file at line $line";
      }
    }
  }

  # Make sure there's a defined entry in the aref, or use the default
  if ( defined( $storage->[0] ) ) {  # just the first one -- no point in going hogwild
    $storage = $storage;
  } else {
    $storage = [ $default_stash ];
    # # make sure the directory exists
    # mkpath( dirname( $default_stash ) ) or croak "Could not create location for $default_stash: $!";
  }
  return $storage;
}

sub define_yaml_default {
  my $self      = shift;
  my $basename  = shift;

  # Using plural for default filename
  my $filename = $basename . 's'; # i18n? what's that?

  my $default = "$HOME/.list-filter/$filename.yaml";
  mkpath( dirname($default) );

#  my $storage = [ $default ];
#  $self->set_storage( $storage );
#  $self->set_write_storage ( $default );
  return $default;
}

sub default_stash {
  my $self = shift;
  my $default_stash = $self->{ default_stash };
  return $default_stash;
}

sub set_default_stash {
  my $self = shift;
  my $default_stash = shift;
  $self->{ default_stash } = $default_stash;
  return $default_stash;
}




1;