List::Filter::Storage::YAML - plugin for filter storage via YAML files

   # This is a plugin, not intended for direct use.
   # See: List:Filter:Storage

   use List::Filter::Storage::YAML;
   my $storage = List::Filter::Storage::YAML->new( {
                                     connect_to  => $yaml_file,
                                   } );

    my $filter = List::Filter->new(
     { name         => 'some_search_filter',
         # [... see List::Filter ...]
     } );

   $storage->save( $filter )

   my $named_filter = $storage->lookup( $name );

package List::Filter::Storage::YAML;
use base qw( List::Filter::StorageBase );

use 5.8.0;
use strict;
use warnings;
use Carp;
use Data::Dumper;
use Hash::Util qw( lock_keys unlock_keys );
use File::Path     qw(mkpath);
use File::Basename qw(dirname fileparse);
use Env  qw(HOME);
use YAML qw(DumpFile LoadFile);

our $VERSION = '0.01';

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

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

  $self->SUPER::init( $args );

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

sub lookup {
  my $self = shift;
  my $name = shift;

  my $filter_data = $self->filter_data;

  my $filter;
  if ( my $filter_href = $filter_data->{ $name } ) {

    # convert this data into a filter object.
    my $terms        = $filter_href->{terms};
    my $method       = $filter_href->{method};
    my $description  = $filter_href->{description};
    my $modifiers    = $filter_href->{modifiers};

    my $filter_class = $self->define_filter_class;

    $filter = $filter_class->new(
      { name         => $name,
        terms        => $terms,
        method       => $method,
        description  => $description,
        modifiers    => $modifiers,
      } );

  }

  return $filter;
}

sub save {
  my $self    = shift;
  my $filter  = shift;

  # convert $filter object into a data structure,

  my $filter_name   = $filter->name;

  my $method         = $filter->method;
  my $description    = $filter->description;
  my $terms          = $filter->terms;
  my $modifiers      = $filter->modifiers;

  my $filter_href = {  method       => $method,
                       description  => $description,
                       terms        => $terms,
                       modifiers    => $modifiers,
                     };

  # add it to the internal stash (replaces any existing one of same name)
  my $filter_data = $self->filter_data;
  $filter_data->{ $filter_name } = $filter_href;

  # write all filter_data out to the yaml file.
  my $stash = $self->connect_to;
  #  DumpFile( $stash, $filter_data );

  # exclude filters named with a leading underscore
  my $saves = {};
  foreach my $name (keys %{ $filter_data }) {
    unless ($name =~ m{^_}x) {
      $saves->{ $name } = $filter_data->{ $name };
    }
  }
  DumpFile( $stash, $saves );

  return $filter;
}

# Rather than call this from init, this method is used from the
# filter_data accessor, to conserve memory until the data is
# needed.
sub slurp_yaml_filter_data {
  my $self = shift;

  my $filter_data;
  my $stash = $self->connect_to;
  if (-f $stash) {
    $filter_data = LoadFile("$stash");
    $self->set_filter_data( $filter_data );
  }
  return $filter_data;
}

sub list_filters {
  my $self = shift;
  my $filter_data = $self->filter_data;
  my @names = keys (%{ $filter_data });
  return \@names;
}

sub filter_data {
  my $self = shift;
  my $filter_data = $self->extra->{ filter_data };

  # if filter_data doesn't yet exist, slurp it now
  unless( $filter_data ) {
    $filter_data = $self->slurp_yaml_filter_data;
  }

  return $filter_data;
}

sub set_filter_data {
  my $self = shift;
  my $filter_data = shift;
  $self->extra->{ filter_data } = $filter_data;
  return $filter_data;
}

1;