source: branches/2015/dev_r5021_UKMO1_CICE_coupling/NEMOGCM/EXTERNAL/fcm/lib/Fcm/Keyword/Entries.pm @ 5445

Last change on this file since 5445 was 5445, checked in by davestorkey, 5 years ago

Clear SVN keywords from 2015/dev_r5021_UKMO1_CICE_coupling branch.

File size: 5.8 KB
Line 
1# ------------------------------------------------------------------------------
2# (C) Crown copyright Met Office. All rights reserved.
3# For further details please refer to the file COPYRIGHT.txt
4# which you should have received as part of this distribution.
5# ------------------------------------------------------------------------------
6use strict;
7use warnings;
8
9package Fcm::Keyword::Entries;
10
11use Carp qw{croak};
12use Fcm::Util::ClassLoader;
13
14sub new {
15    my ($class, $args_ref) = @_;
16    return bless(
17        {
18            entry_class             => 'Fcm::Keyword::Entry',
19            entry_by                => {key => {}, value => {}},
20            has_loaded_entries_from => {},
21            loaders                 => [],
22            ($args_ref && ref($args_ref) eq 'HASH' ? %{$args_ref} : ()),
23        },
24        $class,
25    );
26}
27
28################################################################################
29# Returns the class of entries stored by this entries list
30sub get_entry_class {
31    my ($self) = @_;
32    return $self->{entry_class};
33}
34
35################################################################################
36# Returns all entries
37sub get_all_entries {
38    my ($self) = @_;
39    if (!%{$self->{entry_by}{key}}) {
40        # Nothing set, attempt to load entries
41        $self->load_entries();
42    }
43    if (wantarray()) {
44        return values(%{$self->{entry_by}{key}});
45    }
46    else {
47        return [values(%{$self->{entry_by}{key}})];
48    }
49}
50
51################################################################################
52# Methods: get_entry_by_*
53for my $name (
54    ### Returns an entry with a matching key
55    'key',
56    ### Returns an entry with a matching value
57    'value'
58) {
59    no strict qw{refs};
60    my $method = "get_entry_by_$name";
61    *$method = sub {
62        my ($self, $search_key) = @_;
63        if (!defined($search_key)) {
64            return;
65        }
66        my $sk = ($name eq 'key') ? uc($search_key) : $search_key;
67        if (!exists($self->{entry_by}{$name}{$sk})) {
68            $self->load_entries($name, $sk);
69        }
70        if (exists($self->{entry_by}{$name}{$sk})) {
71            return $self->{entry_by}{$name}{$sk};
72        }
73        else {
74            return;
75        }
76    }
77}
78
79################################################################################
80# Adds an entry
81sub add_entry {
82    my ($self, $key, $value, $args_ref) = @_;
83    Fcm::Util::ClassLoader::load($self->get_entry_class());
84    my $entry = $self->get_entry_class()->new({
85        key   => uc($key),
86        value => $value,
87        ($args_ref && ref($args_ref) eq 'HASH' ? %{$args_ref} : ()),
88    });
89    $self->{entry_by}{key}{uc($key)} = $entry;
90    $self->{entry_by}{value}{$value} = $entry;
91    return $entry;
92}
93
94################################################################################
95# Returns the loaders for this entries list
96sub get_loaders {
97    my ($self) = @_;
98    return (wantarray() ? @{$self->{loaders}} : $self->{loaders});
99}
100
101################################################################################
102# Loads entries using its loaders
103sub load_entries {
104    my ($self, $name, $search_key) = @_;
105    LOADER:
106    for my $loader ($self->get_loaders()) {
107        if ($self->{has_loaded_entries_from}{$loader->get_source()}) {
108            next LOADER;
109        }
110        $self->{has_loaded_entries_from}{$loader->get_source()}
111            = $loader->load_to($self);
112        if ($name && exists($self->{entry_by}{$name}{$search_key})) {
113            last LOADER;
114        }
115    }
116}
117
1181;
119__END__
120
121=head1 NAME
122
123Fcm::Keyword::Entries
124
125=head1 SYNOPSIS
126
127    use Fcm::Keyword::Entries;
128
129    my $entries = Fcm::Keyword::Entries->new({
130        entry_class => $entry_class,
131        loaders     => \@loaders,
132    });
133    $entry = $entries->get_entry_by_key($key);
134    $entry = $entries->get_entry_by_value($value);
135
136    for my $entry ($entries->get_entries()) {
137        # ...
138    }
139
140    $entries->add_entry($key, $value);
141
142=head1 DESCRIPTION
143
144This module is used to manipulate FCM keyword entries. It is used by
145L<Fcm::Keyword|Fcm::Keyword> to store keyword entries, which are
146L<Fcm::Keyword::Entry|Fcm::Keyword::Entry> objects.
147
148=head1 METHODS
149
150=over 4
151
152=item C<new({entry_class =E<gt> $entry_class, loaders =E<gt> \@loaders})>
153
154Constructor. The argument should be a reference to hash, where:
155
156I<entry_class> is a string representing the class name of entries in this
157object. The class must be a sub-class of
158L<Fcm::Keyword::Entry|Fcm::Keyword::Entry>. The default is
159"L<Fcm::Keyword::Entry|Fcm::Keyword::Entry>".
160
161I<loaders> is a reference to an array of
162L<Fcm::Keyword::Loader|Fcm::Keyword::Loader> objects, which will be used to
163load entries into this object. The default is an empty array.
164
165=item add_entry($key,$value)
166
167Adds an entry. Returns the added entry. (Keys are converted to uppercases
168automatically.)
169
170=item get_all_entries()
171
172Returns all entries that are currently loaded.
173
174=item get_entry_by_key($key)
175
176Return an entry, whose key matches $key. (Search is case-insensitive.) Returns
177undef if there is no matching entry.
178
179=item get_entry_by_value($value)
180
181Return an entry, whose value matches $value. (Search is case-sensitive.)
182Returns undef if there is no matching entry.
183
184=item get_loaders()
185
186Returns the loaders for loading entries.
187
188=item load_entries()
189
190Loads entries from its loaders, as returned by get_loaders(). This method can
191also be triggered by get_all_entries(), if the entry list is empty, or by
192get_entry_by_key($key) and get_entry_by_value($value) methods, if there is no
193matching entry in the current lookup lists.
194
195=back
196
197=head1 TO DO
198
199Handle duplicated entries in add_entry($key,$value).
200
201=head1 SEE ALSO
202
203L<Fcm::Keyword|Fcm::Keyword>,
204L<Fcm::Keyword::Entry|Fcm::Keyword::Entry>,
205L<Fcm::Keyword::Loader|Fcm::Keyword::Loader>
206
207=head1 COPYRIGHT
208
209E<169> Crown copyright Met Office. All rights reserved.
210
211=cut
Note: See TracBrowser for help on using the repository browser.