1#========================================================================
2#
3# Badger::Filesystem::Base
4#
5# DESCRIPTION
6#   Base class for Badger::Filesystem modules implementing some common
7#   functionality.
8#
9# AUTHOR
10#   Andy Wardley   <abw@wardley.org>
11#
12#========================================================================
13
14package Badger::Filesystem::Base;
15
16use Badger::Class
17    version     => 0.01,
18    base        => 'Badger::Base',
19    debug       => 0,
20    import      => 'class',
21    messages    => {
22        no_option_method => 'No method defined to handle %s option',
23    };
24
25our @VDN_FIELDS = qw( volume directory name );
26our @VD_FIELDS  = qw( volume directory );
27our @OPTIONS    = qw( encoding codec );
28
29
30sub init_path {
31    my ($self, $config) = @_;
32    my ($path, $vol, $dir, $name);
33    my $fs = $self->filesystem;
34
35    $self->debug("init_path() ", $self->dump_data($config)) if DEBUG;
36
37    if ($config->{ path }) {
38        # split path into volume, directory, name
39        # set colume,
40        $path = $self->{ path } = $fs->join_dir( $config->{ path } );
41        @$self{@VDN_FIELDS} = $fs->split_path($path);
42    }
43    elsif ($self->{ name } = $config->{ name }) {
44        @$self{@VD_FIELDS} = ($vol, $dir) = map { defined($_) ? $_ : '' } @$config{ @VD_FIELDS };
45        $self->{ path } = $fs->join_path($vol, $dir, $self->{ name });
46    }
47    else {
48        $self->error_msg( missing => 'path or name' );
49    }
50
51    return $self;
52}
53
54sub init_options {
55    my ($self, $config) = @_;
56    my $opts = $self->{ options } = { };
57    my $method;
58
59    foreach my $name (@OPTIONS) {
60        if ($config->{ $name }) {
61            $method = $self->can($name)
62                || return $self->error_msg( no_option_method => $name );
63            $method->( $self, $config->{ $name } );
64        }
65    }
66
67    return $self;
68}
69
70sub codec {
71    my $self = shift;
72    if (@_) {
73        require Badger::Codecs;
74        $self->{ options }->{ codec } = Badger::Codecs->codec(@_);
75    }
76    return $self->{ options }->{ codec };
77}
78
79sub encoding {
80    my $self = shift;
81    if (@_) {
82        my $layer = shift;
83        # be generous in what you accept...
84        $layer = ":$layer" unless $layer =~ /^:/;
85        $self->{ options }->{ encoding } = $layer;
86    }
87    return $self->{ options }->{ encoding };
88}
89
90
911;
92
93=head1 NAME
94
95Badger::Filesystem::Base - common functionality for Badger::Filesystem modules
96
97=head1 SYNOPSIS
98
99    package Badger::Filesystem::SomeOtherModule;
100    use base 'Badger::Filesystem::Base'
101    # now this module inherits the base class functionality
102
103=head1 DESCRIPTION
104
105C<Badger::Filesystem::Base> is a base class module that defines some common
106functionality shared by L<Badger::Filesystem> and L<Badger::Filesystem::Path>
107(which itself is the base class for L<Badger::Filesystem::Directory> and
108L<Badger::Filesystem::File>.
109
110=head1 METHODS
111
112=head2 init_path(\%config)
113
114Initialisation method which examines the filesystem path specified as a
115parameter and splits it into volume, directory and name.
116
117=head2 init_options(\%config)
118
119Initialisation method which handles the C<encoding> and C<codec> options.
120
121=head2 encoding($enc)
122
123This method can be used to get or set the default encoding for a file.
124
125    $file->encoding(':utf8');
126
127The encoding will affect all operations that read data from, or write data
128to the file.
129
130The method can also be used to get or set the default encoding for a
131directory or filesystem.  In this case the option specifies the default
132encoding for file contained therein.
133
134    $directory->encoding(':utf8');
135    $file = $directory->file('foo.txt');        # has :utf8 encoding set
136
137=head2 codec()
138
139This method can be used to get or set the codec used to serialise data to
140and from a file via the L<data()> method.  The codec should be specified
141by name, using any of the names that L<Badger::Codecs> recognises or can
142load.
143
144    $file->codec('storable');
145
146    # first save the data to file
147    $file->data($some_data_to_save);
148
149    # later... load the data back out
150    my $data = $file->data;
151
152You can use chained codec specifications if you want to pass the data
153through more than one codec.
154
155    $file->code('storable+base64');
156
157See L<Badger::Codecs> for further information on codecs.
158
159As with L<encoding()>, this method can also be used to get or set the default
160codec for a directory or filesystem.
161
162    $directory->codec('json');
163    $file = $directory->file('foo.json');       # has json codec set
164
165=head1 AUTHOR
166
167Andy Wardley L<http://wardley.org/>
168
169=head1 COPYRIGHT
170
171Copyright (C) 2009 Andy Wardley. All rights reserved.
172
173=head1 SEE ALSO
174
175L<Badger::Filesystem>,
176L<Badger::Filesystem::Path>,
177L<Badger::Filesystem::Directory>,
178L<Badger::Filesystem::File>.
179
180=cut
181
182