| 1 | package Catmandu; | ||||||||||||||||||||
| 2 | |||||||||||||||||||||
| 3 | 119 | ▶ | use Catmandu::Sane; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 4 | |||||||||||||||||||||
| 5 | 119 | our $VERSION = '1.0201_02'; | |||||||||||||||||||
| 6 | |||||||||||||||||||||
| 7 | 119 | ▶ | use Catmandu::Env; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 8 | 119 | ▶ | use Catmandu::Util qw(:is); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 9 | 119 | ▶ | use File::Spec; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 10 | 119 | ▶ | use namespace::clean; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 11 | 119 | ▶ | use Sub::Exporter::Util qw(curry_method); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 12 | 119 | use Sub::Exporter -setup => { | |||||||||||||||||||
| 13 | exports => [ | ||||||||||||||||||||
| 14 | config => curry_method, | ||||||||||||||||||||
| 15 | log => curry_method, | ||||||||||||||||||||
| 16 | store => curry_method, | ||||||||||||||||||||
| 17 | fixer => curry_method, | ||||||||||||||||||||
| 18 | importer => curry_method, | ||||||||||||||||||||
| 19 | exporter => curry_method, | ||||||||||||||||||||
| 20 | export => curry_method, | ||||||||||||||||||||
| 21 | export_to_string => curry_method | ||||||||||||||||||||
| 22 | ], | ||||||||||||||||||||
| 23 | collectors => {'-load' => \'_import_load', ':load' => \'_import_load',}, | ||||||||||||||||||||
| 24 | 119 | ▶ | }; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 25 | |||||||||||||||||||||
| 26 | sub _import_load { | ||||||||||||||||||||
| 27 | 0 | ▶ | my ($self, $value, $data) = @_; | ||||||||||||||||||
|
Subroutine
_import_load: not called CC=2 SCAR=17.9
| |||||||||||||||||||||
| 28 | 0 | ▶ | if (is_array_ref $value) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 29 | 0 | $self->load(@$value); | |||||||||||||||||||
| 30 | } | ||||||||||||||||||||
| 31 | else { | ||||||||||||||||||||
| 32 | 0 | $self->load; | |||||||||||||||||||
| 33 | } | ||||||||||||||||||||
| 34 | 0 | 1; | |||||||||||||||||||
| 35 | } | ||||||||||||||||||||
| 36 | |||||||||||||||||||||
| 37 | sub _env { | ||||||||||||||||||||
| 38 | 168 | ▶ | my ($class, $env) = @_; | ||||||||||||||||||
|
Subroutine
_env: called CC=3 SCAR=11.0
| |||||||||||||||||||||
| 39 | 168 | state $loaded_env; | |||||||||||||||||||
| 40 | 168 | ▶ | $loaded_env = $env if defined $env; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 41 | 168 | ▶ | $loaded_env | ||||||||||||||||||
|
Condition66%2/3
$loaded_env ||= "Catmandu::Env"->new("load_paths", $class->default_load_path)
MC/DC0%0/2
$loaded_env ||= "Catmandu::Env"->new("load_paths", $class->default_load_path)
$loaded_env
"Catmandu::Env"->new("load_paths", $class->default_load_path)
Truth table66%2/3
A ||= B
A= $loaded_envB= "Catmandu::Env"->new("load_paths", $class->default_load_path)
| |||||||||||||||||||||
| 42 | ||= Catmandu::Env->new(load_paths => $class->default_load_path); | ||||||||||||||||||||
| 43 | } | ||||||||||||||||||||
| 44 | |||||||||||||||||||||
| 45 | 12 | ▶ | sub log {$_[0]->_env->log} | ||||||||||||||||||
|
Subroutine
log: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 46 | |||||||||||||||||||||
| 47 | sub default_load_path { # TODO move to Catmandu::Env | ||||||||||||||||||||
| 48 | 57 | ▶ | my ($class, $path) = @_; | ||||||||||||||||||
|
Subroutine
default_load_path: called CC=4 SCAR=14.3
Pod
documented
| |||||||||||||||||||||
| 49 | 57 | state $default_path; | |||||||||||||||||||
| 50 | 57 | ▶ | $default_path = $path if defined $path; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 51 | 57 | ▶ | $default_path //= do { | ||||||||||||||||||
|
Condition66%2/3
$default_path //= do {
MC/DC0%0/2
$default_path //= do {
my $script = "File::Spec"->rel2abs($0);
() = "File::Spec"->splitpath($script);
my(@dirs) = grep(length($_), "File::Spec"->splitdir($script_path));
if ($dirs[-1] eq "bin") {
pop @dirs;
"File::Spec"->catdir("File::Spec"->rootdir, @dirs);
}
else {
$script_path;
}
}
$default_path
do {
my $script = "File::Spec"->rel2abs($0);
() = "File::Spec"->splitpath($script);
my(@dirs) = grep(length($_), "File::Spec"->splitdir($script_path));
if ($dirs[-1] eq "bin") {
pop @dirs;
"File::Spec"->catdir("File::Spec"->rootdir, @dirs);
}
else {
$script_path;
}
}
Truth table66%2/3
A //= B
A= $default_pathB= do {
my $script = "File::Spec"->rel2abs($0);
() = "File::Spec"->splitpath($script);
my(@dirs) = grep(length($_), "File::Spec"->splitdir($script_path));
if ($dirs[-1] eq "bin") {
pop @dirs;
"File::Spec"->catdir("File::Spec"->rootdir, @dirs);
}
else {
$script_path;
}
}
| |||||||||||||||||||||
| 52 | 24 | my $script = File::Spec->rel2abs($0); | |||||||||||||||||||
| 53 | 24 | my ($script_vol, $script_path, $script_name) | |||||||||||||||||||
| 54 | = File::Spec->splitpath($script); | ||||||||||||||||||||
| 55 | 24 | my @dirs = grep length, File::Spec->splitdir($script_path); | |||||||||||||||||||
| 56 | 24 | ▶ | if ($dirs[-1] eq 'bin') { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 57 | 0 | pop @dirs; | |||||||||||||||||||
| 58 | 0 | File::Spec->catdir(File::Spec->rootdir, @dirs); | |||||||||||||||||||
| 59 | } | ||||||||||||||||||||
| 60 | else { | ||||||||||||||||||||
| 61 | 24 | $script_path; | |||||||||||||||||||
| 62 | } | ||||||||||||||||||||
| 63 | }; | ||||||||||||||||||||
| 64 | } | ||||||||||||||||||||
| 65 | |||||||||||||||||||||
| 66 | sub load { | ||||||||||||||||||||
| 67 | 41 | ▶ | my $class = shift; | ||||||||||||||||||
|
Subroutine
load: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||||||||
| 68 | 41 | ▶ | my $paths = [@_ ? @_ : $class->default_load_path]; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 69 | 41 | my $env = Catmandu::Env->new(load_paths => $paths); | |||||||||||||||||||
| 70 | 41 | $class->_env($env); | |||||||||||||||||||
| 71 | 41 | $class; | |||||||||||||||||||
| 72 | } | ||||||||||||||||||||
| 73 | |||||||||||||||||||||
| 74 | sub roots { | ||||||||||||||||||||
| 75 | 1 | ▶ | $_[0]->_env->roots; | ||||||||||||||||||
|
Subroutine
roots: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 76 | } | ||||||||||||||||||||
| 77 | |||||||||||||||||||||
| 78 | sub root { | ||||||||||||||||||||
| 79 | 1 | ▶ | $_[0]->_env->root; | ||||||||||||||||||
|
Subroutine
root: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 80 | } | ||||||||||||||||||||
| 81 | |||||||||||||||||||||
| 82 | sub config { | ||||||||||||||||||||
| 83 | 10 | ▶ | $_[0]->_env->config; | ||||||||||||||||||
|
Subroutine
config: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 84 | } | ||||||||||||||||||||
| 85 | |||||||||||||||||||||
| 86 | 3 | ▶ | sub default_store {$_[0]->_env->default_store} | ||||||||||||||||||
|
Subroutine
default_store: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 87 | |||||||||||||||||||||
| 88 | sub store { | ||||||||||||||||||||
| 89 | 14 | ▶ | my $class = shift; | ||||||||||||||||||
|
Subroutine
store: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 90 | 14 | $class->_env->store(@_); | |||||||||||||||||||
| 91 | } | ||||||||||||||||||||
| 92 | |||||||||||||||||||||
| 93 | 1 | ▶ | sub default_fixer {$_[0]->_env->default_fixer} | ||||||||||||||||||
|
Subroutine
default_fixer: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 94 | |||||||||||||||||||||
| 95 | sub fixer { | ||||||||||||||||||||
| 96 | 16 | ▶ | my $class = shift; | ||||||||||||||||||
|
Subroutine
fixer: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 97 | 16 | $class->_env->fixer(@_); | |||||||||||||||||||
| 98 | } | ||||||||||||||||||||
| 99 | |||||||||||||||||||||
| 100 | 1 | ▶ | sub default_importer {$_[0]->_env->default_importer} | ||||||||||||||||||
|
Subroutine
default_importer: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 101 | |||||||||||||||||||||
| 102 | 1 | ▶ | sub default_importer_package {$_[0]->_env->default_importer_package} | ||||||||||||||||||
|
Subroutine
default_importer_package: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 103 | |||||||||||||||||||||
| 104 | sub importer { | ||||||||||||||||||||
| 105 | 24 | ▶ | my $class = shift; | ||||||||||||||||||
|
Subroutine
importer: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 106 | 24 | $class->_env->importer(@_); | |||||||||||||||||||
| 107 | } | ||||||||||||||||||||
| 108 | |||||||||||||||||||||
| 109 | 1 | ▶ | sub default_exporter {$_[0]->_env->default_exporter} | ||||||||||||||||||
|
Subroutine
default_exporter: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 110 | |||||||||||||||||||||
| 111 | 1 | ▶ | sub default_exporter_package {$_[0]->_env->default_exporter_package} | ||||||||||||||||||
|
Subroutine
default_exporter_package: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 112 | |||||||||||||||||||||
| 113 | sub exporter { | ||||||||||||||||||||
| 114 | 36 | ▶ | my $class = shift; | ||||||||||||||||||
|
Subroutine
exporter: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 115 | 36 | $class->_env->exporter(@_); | |||||||||||||||||||
| 116 | } | ||||||||||||||||||||
| 117 | |||||||||||||||||||||
| 118 | sub export { | ||||||||||||||||||||
| 119 | 1 | ▶ | my $class = shift; | ||||||||||||||||||
|
Subroutine
export: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||||||||
| 120 | 1 | my $data = shift; | |||||||||||||||||||
| 121 | 1 | my $exporter = $class->_env->exporter(@_); | |||||||||||||||||||
| 122 | 1 | ▶ | is_hash_ref($data) ? $exporter->add($data) : $exporter->add_many($data); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 123 | 1 | $exporter->commit; | |||||||||||||||||||
| 124 | 1 | return; | |||||||||||||||||||
| 125 | } | ||||||||||||||||||||
| 126 | |||||||||||||||||||||
| 127 | sub export_to_string { | ||||||||||||||||||||
| 128 | 1 | ▶ | my $class = shift; | ||||||||||||||||||
|
Subroutine
export_to_string: called CC=3 SCAR=11.3
Pod
documented
| |||||||||||||||||||||
| 129 | 1 | my $data = shift; | |||||||||||||||||||
| 130 | 1 | my $name = shift; | |||||||||||||||||||
| 131 | 1 | ▶ | my %opts = ref $_[0] ? %{$_[0]} : @_; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 132 | 1 | my $str = ""; | |||||||||||||||||||
| 133 | 1 | my $exporter = $class->_env->exporter($name, %opts, file => \$str); | |||||||||||||||||||
| 134 | 1 | ▶ | is_hash_ref($data) ? $exporter->add($data) : $exporter->add_many($data); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 135 | 1 | $exporter->commit; | |||||||||||||||||||
| 136 | 1 | $str; | |||||||||||||||||||
| 137 | } | ||||||||||||||||||||
| 138 | |||||||||||||||||||||
| 139 | 119 | 1; | |||||||||||||||||||
| 140 | |||||||||||||||||||||
| 141 | __END__ | ||||||||||||||||||||
| 142 | |||||||||||||||||||||
| 143 | =pod | ||||||||||||||||||||
| 144 | |||||||||||||||||||||
| 145 | =head1 NAME | ||||||||||||||||||||
| 146 | |||||||||||||||||||||
| 147 | Catmandu - a data toolkit | ||||||||||||||||||||
| 148 | |||||||||||||||||||||
| 149 | =head1 SYNOPSIS | ||||||||||||||||||||
| 150 | |||||||||||||||||||||
| 151 | # From the command line | ||||||||||||||||||||
| 152 | |||||||||||||||||||||
| 153 | # Convert data from one format to another | ||||||||||||||||||||
| 154 | $ catmandu convert JSON to CSV < data.json | ||||||||||||||||||||
| 155 | $ catmandu convert CSV to YAML < data.csv | ||||||||||||||||||||
| 156 | $ catmandu convert MARC to YAML < data.mrc | ||||||||||||||||||||
| 157 | |||||||||||||||||||||
| 158 | # Fix data, add, delete, change fields | ||||||||||||||||||||
| 159 | $ catmandu convert JSON --fix 'move_field(title,my_title)' < data.json | ||||||||||||||||||||
| 160 | $ catmandu convert JSON --fix all_my_fixes.txt < data.json | ||||||||||||||||||||
| 161 | # Use a moustache preprocessor on the fix script | ||||||||||||||||||||
| 162 | $ catmandu convert JSON --fix all_my_fixes.txt --var opt1=foo --var opt2=bar < data.json | ||||||||||||||||||||
| 163 | |||||||||||||||||||||
| 164 | # Import data into a database | ||||||||||||||||||||
| 165 | # Requires: Catmandu::MongoDB and Catmandu::ElasticSearch | ||||||||||||||||||||
| 166 | $ catmandu import YAML to MongoDB --database_name bibliography < data.yml | ||||||||||||||||||||
| 167 | $ catmandu import CSV to ElasticSearch --index_name mystuff < data.csv | ||||||||||||||||||||
| 168 | |||||||||||||||||||||
| 169 | # Export data from a database | ||||||||||||||||||||
| 170 | # Requires: Catmandu::MongoDB and Catmandu::ElasticSearch | ||||||||||||||||||||
| 171 | $ catmandu export MongoDB --database_name bibliography to YAML > data.yml | ||||||||||||||||||||
| 172 | $ catmandu export ElasticSearch --index_name mystuff to CSV > data.csv | ||||||||||||||||||||
| 173 | |||||||||||||||||||||
| 174 | # Copy data from one store to another | ||||||||||||||||||||
| 175 | $ catmandu copy MongoDB --database_name mydb to ElasticSearch --index_name mydb | ||||||||||||||||||||
| 176 | |||||||||||||||||||||
| 177 | # Show the contents of catmandu.yml | ||||||||||||||||||||
| 178 | $ catmandu config | ||||||||||||||||||||
| 179 | |||||||||||||||||||||
| 180 | # Count items in a store | ||||||||||||||||||||
| 181 | $ catmandu count test1 | ||||||||||||||||||||
| 182 | |||||||||||||||||||||
| 183 | # Delete items from store | ||||||||||||||||||||
| 184 | $ catmandu delete test1 -q 'title:"My Rabbit"' | ||||||||||||||||||||
| 185 | |||||||||||||||||||||
| 186 | # run a fix script | ||||||||||||||||||||
| 187 | $ catmandu run myfixes.fix | ||||||||||||||||||||
| 188 | |||||||||||||||||||||
| 189 | # or, create an executable fix script | ||||||||||||||||||||
| 190 | $ cat myfixes.fix | ||||||||||||||||||||
| 191 | #!/usr/local/bin/catmandu run | ||||||||||||||||||||
| 192 | do importer(OAI,url:"http://biblio.ugent.be/oai") | ||||||||||||||||||||
| 193 | retain(_id) | ||||||||||||||||||||
| 194 | end | ||||||||||||||||||||
| 195 | $ chmod 755 myfixes.fix | ||||||||||||||||||||
| 196 | $ ./myfixes.fix | ||||||||||||||||||||
| 197 | |||||||||||||||||||||
| 198 | # From Perl | ||||||||||||||||||||
| 199 | use Catmandu; | ||||||||||||||||||||
| 200 | |||||||||||||||||||||
| 201 | # If you have Catmandu::OAI and Catmandu::MongoDB installed | ||||||||||||||||||||
| 202 | my $importer = Catmandu->importer('OAI',url => 'https://biblio.ugent.be/oai') | ||||||||||||||||||||
| 203 | my $store = Catmandu->store('MongoDB',database_name => 'test'); | ||||||||||||||||||||
| 204 | |||||||||||||||||||||
| 205 | # Import all the OAI records into MongoDB | ||||||||||||||||||||
| 206 | $store->add_many($importer); | ||||||||||||||||||||
| 207 | |||||||||||||||||||||
| 208 | # Export all the MongoDB records to YAML and apply some fixes | ||||||||||||||||||||
| 209 | # myfixes.txt: | ||||||||||||||||||||
| 210 | # upcase(title.*) | ||||||||||||||||||||
| 211 | # remove_field(_metadata) | ||||||||||||||||||||
| 212 | # join_field(creator,'; ') | ||||||||||||||||||||
| 213 | # join_field(subject,'-- ') | ||||||||||||||||||||
| 214 | my $fixer = Catmandu->fixer('myfixes.txt'); | ||||||||||||||||||||
| 215 | my $exporter = Catmandu->exporter('YAML'); | ||||||||||||||||||||
| 216 | |||||||||||||||||||||
| 217 | $exporter->add_many( $fixer->fix($store) ); | ||||||||||||||||||||
| 218 | $exporter->commit; | ||||||||||||||||||||
| 219 | |||||||||||||||||||||
| 220 | =head1 DESCRIPTION | ||||||||||||||||||||
| 221 | |||||||||||||||||||||
| 222 | Catmandu provides a command line client and a Perl API to ease the export (E) | ||||||||||||||||||||
| 223 | transformation (T) and loading (L) of data into databases or data file, ETL in short. | ||||||||||||||||||||
| 224 | |||||||||||||||||||||
| 225 | Most of the daily work processing structured data can be done on the command line | ||||||||||||||||||||
| 226 | executing the C<catmandu> command. With our catmandu command ETL processing is available | ||||||||||||||||||||
| 227 | in a Perl context. Catmandu is different from other | ||||||||||||||||||||
| 228 | ETL tools by its focus on command line processing with much support for dataformats | ||||||||||||||||||||
| 229 | available in (academic) libraries: MARC, MODS, OAI and SRU. But, also generic formats such | ||||||||||||||||||||
| 230 | as JSON, YAML, CVS, Excel, XML, RDF, Atom are supported. | ||||||||||||||||||||
| 231 | |||||||||||||||||||||
| 232 | Read : | ||||||||||||||||||||
| 233 | |||||||||||||||||||||
| 234 | =over | ||||||||||||||||||||
| 235 | |||||||||||||||||||||
| 236 | =item * L<Catmandu::Introduction> for a primer on the command line capabilities of Catmandu. | ||||||||||||||||||||
| 237 | |||||||||||||||||||||
| 238 | =item * L<Catmandu::Importer> for the basics of importing | ||||||||||||||||||||
| 239 | |||||||||||||||||||||
| 240 | =item * L<Catmandu::Fix> for the basics of transformations | ||||||||||||||||||||
| 241 | |||||||||||||||||||||
| 242 | =item * L<Catmandu::Exporter> for the basics of exporting | ||||||||||||||||||||
| 243 | |||||||||||||||||||||
| 244 | =item * L<Catmandu::Store> for the basics of storing information | ||||||||||||||||||||
| 245 | |||||||||||||||||||||
| 246 | =item * Or, visit our website at L<http://librecat.org/> and our blog L<https://librecatproject.wordpress.com/> | ||||||||||||||||||||
| 247 | for many tutorials | ||||||||||||||||||||
| 248 | |||||||||||||||||||||
| 249 | =back | ||||||||||||||||||||
| 250 | |||||||||||||||||||||
| 251 | The documentation below describes the methods available when including Catmandu as | ||||||||||||||||||||
| 252 | part of a Perl script. For an overview of the command line tool itself read the | ||||||||||||||||||||
| 253 | documentation on L<catmandu>. | ||||||||||||||||||||
| 254 | |||||||||||||||||||||
| 255 | =head1 USE | ||||||||||||||||||||
| 256 | |||||||||||||||||||||
| 257 | To include Catmandu in a Perl script it should be loaded with a C<use> command: | ||||||||||||||||||||
| 258 | |||||||||||||||||||||
| 259 | use Catmandu; | ||||||||||||||||||||
| 260 | |||||||||||||||||||||
| 261 | By default no methods are imported into the Perl context. To import all or some Catmandu methods, | ||||||||||||||||||||
| 262 | provide them as a list to the C<use> command: | ||||||||||||||||||||
| 263 | |||||||||||||||||||||
| 264 | use Catmandu -all; | ||||||||||||||||||||
| 265 | use Catmandu qw(config store exporter); | ||||||||||||||||||||
| 266 | |||||||||||||||||||||
| 267 | Catmandu can load configuration options for exports, importers, fixers via configuration | ||||||||||||||||||||
| 268 | files (see the CONFIG section below). When adding the --load option (optionally with a path) to the | ||||||||||||||||||||
| 269 | C<use> command, these configuration files will be loaded at the start of your script. | ||||||||||||||||||||
| 270 | |||||||||||||||||||||
| 271 | use Catmandu -load; | ||||||||||||||||||||
| 272 | use Catmandu --load => ['/my/config/directory']; | ||||||||||||||||||||
| 273 | |||||||||||||||||||||
| 274 | # or use all the options | ||||||||||||||||||||
| 275 | use Catmandu -all -load => [qw(/config/path' '/another/config/path)]; | ||||||||||||||||||||
| 276 | |||||||||||||||||||||
| 277 | =head1 CLASS METHODS | ||||||||||||||||||||
| 278 | |||||||||||||||||||||
| 279 | =head2 log | ||||||||||||||||||||
| 280 | |||||||||||||||||||||
| 281 | Return the current L<Log::Any::Adapter> logger. | ||||||||||||||||||||
| 282 | |||||||||||||||||||||
| 283 | use Catmandu; | ||||||||||||||||||||
| 284 | use Log::Any::Adapter; | ||||||||||||||||||||
| 285 | use Log::Log4perl; | ||||||||||||||||||||
| 286 | |||||||||||||||||||||
| 287 | Log::Any::Adapter->set('Log4perl'); | ||||||||||||||||||||
| 288 | Log::Log4perl::init('./log4perl.conf'); | ||||||||||||||||||||
| 289 | |||||||||||||||||||||
| 290 | my $logger = Catmandu->log; | ||||||||||||||||||||
| 291 | $logger->info("Starting main program"); | ||||||||||||||||||||
| 292 | |||||||||||||||||||||
| 293 | with log4perl.conf like: | ||||||||||||||||||||
| 294 | |||||||||||||||||||||
| 295 | # Send a copy of all logging messages to STDERR | ||||||||||||||||||||
| 296 | log4perl.rootLogger=DEBUG,STDERR | ||||||||||||||||||||
| 297 | |||||||||||||||||||||
| 298 | # Logging specific for your main program | ||||||||||||||||||||
| 299 | log4perl.category.myprog=INFO,STDERR | ||||||||||||||||||||
| 300 | |||||||||||||||||||||
| 301 | # Logging specific for on part of Catmandu | ||||||||||||||||||||
| 302 | log4perl.category.Catmandu::Fix=DEBUG,STDERR | ||||||||||||||||||||
| 303 | |||||||||||||||||||||
| 304 | # Where to send the STDERR output | ||||||||||||||||||||
| 305 | log4perl.appender.STDERR=Log::Log4perl::Appender::Screen | ||||||||||||||||||||
| 306 | log4perl.appender.STDERR.stderr=1 | ||||||||||||||||||||
| 307 | log4perl.appender.STDERR.utf8=1 | ||||||||||||||||||||
| 308 | |||||||||||||||||||||
| 309 | log4perl.appender.STDERR.layout=PatternLayout | ||||||||||||||||||||
| 310 | log4perl.appender.STDERR.layout.ConversionPattern=%d [%P] - %p %l time=%r : %m%n | ||||||||||||||||||||
| 311 | |||||||||||||||||||||
| 312 | =head2 default_load_path(['/default/path']) | ||||||||||||||||||||
| 313 | |||||||||||||||||||||
| 314 | Returns the default location where L<Catmandu> looks for configuration and lib | ||||||||||||||||||||
| 315 | when called with no argument. Sets the default location if a path is given. | ||||||||||||||||||||
| 316 | The default load path is the script directory or it's parent if the script | ||||||||||||||||||||
| 317 | directory is C<bin>. | ||||||||||||||||||||
| 318 | |||||||||||||||||||||
| 319 | =head2 load | ||||||||||||||||||||
| 320 | |||||||||||||||||||||
| 321 | Load all the configuration options in the catmandu.yml configuration file. | ||||||||||||||||||||
| 322 | See CONFIG below for extended examples of configuration options. | ||||||||||||||||||||
| 323 | |||||||||||||||||||||
| 324 | =head2 load('/path', '/another/path') | ||||||||||||||||||||
| 325 | |||||||||||||||||||||
| 326 | Load all the configuration options stored at alternative paths. | ||||||||||||||||||||
| 327 | |||||||||||||||||||||
| 328 | A load path C<':up'> will search upwards from your program for configuration. | ||||||||||||||||||||
| 329 | |||||||||||||||||||||
| 330 | See CONFIG below for extended examples of configuration options. | ||||||||||||||||||||
| 331 | |||||||||||||||||||||
| 332 | =head2 roots | ||||||||||||||||||||
| 333 | |||||||||||||||||||||
| 334 | Returns an ARRAYREF of paths where configuration was found. Note that this list | ||||||||||||||||||||
| 335 | is empty before C<load>. | ||||||||||||||||||||
| 336 | |||||||||||||||||||||
| 337 | =head2 root | ||||||||||||||||||||
| 338 | |||||||||||||||||||||
| 339 | Returns the first path where configuration was found. Note that this is | ||||||||||||||||||||
| 340 | C<undef> before C<load>. | ||||||||||||||||||||
| 341 | |||||||||||||||||||||
| 342 | =head2 config | ||||||||||||||||||||
| 343 | |||||||||||||||||||||
| 344 | Returns the current configuration as a HASHREF. | ||||||||||||||||||||
| 345 | |||||||||||||||||||||
| 346 | =head2 default_store | ||||||||||||||||||||
| 347 | |||||||||||||||||||||
| 348 | Return the name of the default store. | ||||||||||||||||||||
| 349 | |||||||||||||||||||||
| 350 | =head2 store([NAME]) | ||||||||||||||||||||
| 351 | |||||||||||||||||||||
| 352 | Return an instance of L<Catmandu::Store>. The NAME is a name of a L<Catmandu::Store> or the | ||||||||||||||||||||
| 353 | name of a store configured in a catmandu.yml configuration file. When no NAME is given, the | ||||||||||||||||||||
| 354 | 'default' store in the configuration file will be used. | ||||||||||||||||||||
| 355 | |||||||||||||||||||||
| 356 | E.g. if the configuration file 'catmandu.yml' contains: | ||||||||||||||||||||
| 357 | |||||||||||||||||||||
| 358 | store: | ||||||||||||||||||||
| 359 | default: | ||||||||||||||||||||
| 360 | package: ElasticSearch | ||||||||||||||||||||
| 361 | options: | ||||||||||||||||||||
| 362 | index_name: blog | ||||||||||||||||||||
| 363 | test: | ||||||||||||||||||||
| 364 | package: Mock | ||||||||||||||||||||
| 365 | |||||||||||||||||||||
| 366 | then in your program: | ||||||||||||||||||||
| 367 | |||||||||||||||||||||
| 368 | # This will use ElasticSearch | ||||||||||||||||||||
| 369 | my $store = Catmandu->store('ElasticSearch', index_name => 'blog'); | ||||||||||||||||||||
| 370 | |||||||||||||||||||||
| 371 | # or because we have a 'default' set in the configuration file | ||||||||||||||||||||
| 372 | |||||||||||||||||||||
| 373 | my $store = Catmandu->store('default'); | ||||||||||||||||||||
| 374 | |||||||||||||||||||||
| 375 | # or because 'default' will be used when no name was provided | ||||||||||||||||||||
| 376 | |||||||||||||||||||||
| 377 | my $store = Catmandu->store; | ||||||||||||||||||||
| 378 | |||||||||||||||||||||
| 379 | # This will use Mock | ||||||||||||||||||||
| 380 | my $store = Catmandu->store('test'); | ||||||||||||||||||||
| 381 | |||||||||||||||||||||
| 382 | Configuration settings can be overwritten by the store command: | ||||||||||||||||||||
| 383 | |||||||||||||||||||||
| 384 | my $store2 = Catmandu->store('default', index_name => 'test2'); | ||||||||||||||||||||
| 385 | |||||||||||||||||||||
| 386 | =head2 default_fixer | ||||||||||||||||||||
| 387 | |||||||||||||||||||||
| 388 | Return the name of the default fixer. | ||||||||||||||||||||
| 389 | |||||||||||||||||||||
| 390 | =head2 fixer(NAME) | ||||||||||||||||||||
| 391 | |||||||||||||||||||||
| 392 | =head2 fixer(FIX,FIX) | ||||||||||||||||||||
| 393 | |||||||||||||||||||||
| 394 | =head2 fixer([FIX]) | ||||||||||||||||||||
| 395 | |||||||||||||||||||||
| 396 | Return an instance of L<Catmandu::Fix>. NAME can be the name of a fixer section | ||||||||||||||||||||
| 397 | in a catmandu.yml file. Or, one or more L<Catmandu::Fix>-es can be provided inline. | ||||||||||||||||||||
| 398 | |||||||||||||||||||||
| 399 | E.g. if the configuration file 'catmandu.yml' contains: | ||||||||||||||||||||
| 400 | |||||||||||||||||||||
| 401 | fixer: | ||||||||||||||||||||
| 402 | default: | ||||||||||||||||||||
| 403 | - do_this() | ||||||||||||||||||||
| 404 | - do_that() | ||||||||||||||||||||
| 405 | |||||||||||||||||||||
| 406 | then in your program al these lines below will create the same fixer: | ||||||||||||||||||||
| 407 | |||||||||||||||||||||
| 408 | my $fixer = Catmandu->fixer('do_this()', 'do_that()'); | ||||||||||||||||||||
| 409 | my $fixer = Catmandu->fixer(['do_this()', 'do_that()']); | ||||||||||||||||||||
| 410 | my $fixer = Catmandu->fixer('default'); | ||||||||||||||||||||
| 411 | my $fixer = Catmandu->fixer(); # The default name is 'default' | ||||||||||||||||||||
| 412 | |||||||||||||||||||||
| 413 | FIX-es can be also written to a Fix script. E.g. if myfixes.txt contains: | ||||||||||||||||||||
| 414 | |||||||||||||||||||||
| 415 | do_this() | ||||||||||||||||||||
| 416 | do_that() | ||||||||||||||||||||
| 417 | |||||||||||||||||||||
| 418 | then the above code will even be equivalent to: | ||||||||||||||||||||
| 419 | |||||||||||||||||||||
| 420 | my $fixer = Catmandu->fixer('myfixes.txt'); | ||||||||||||||||||||
| 421 | |||||||||||||||||||||
| 422 | =head2 default_importer | ||||||||||||||||||||
| 423 | |||||||||||||||||||||
| 424 | Return the name of the default importer. | ||||||||||||||||||||
| 425 | |||||||||||||||||||||
| 426 | =head2 default_importer_package | ||||||||||||||||||||
| 427 | |||||||||||||||||||||
| 428 | Return the name of the default importer package if no | ||||||||||||||||||||
| 429 | package name is given in the config or as a param. | ||||||||||||||||||||
| 430 | |||||||||||||||||||||
| 431 | =head2 importer(NAME) | ||||||||||||||||||||
| 432 | |||||||||||||||||||||
| 433 | Return an instance of L<Catmandu::Importer>. The NAME is a name of a L<Catmandu::Importer> or the | ||||||||||||||||||||
| 434 | name of a importer configured in a catmandu.yml configuration file. When no NAME is given, the | ||||||||||||||||||||
| 435 | 'default' importer in the configuration file will be used. | ||||||||||||||||||||
| 436 | |||||||||||||||||||||
| 437 | E.g. if the configuration file 'catmandu.yml' contains: | ||||||||||||||||||||
| 438 | |||||||||||||||||||||
| 439 | importer: | ||||||||||||||||||||
| 440 | default: | ||||||||||||||||||||
| 441 | package: OAI | ||||||||||||||||||||
| 442 | options: | ||||||||||||||||||||
| 443 | url: http://www.instute.org/oai/ | ||||||||||||||||||||
| 444 | |||||||||||||||||||||
| 445 | then in your program all these lines will be equivalent: | ||||||||||||||||||||
| 446 | |||||||||||||||||||||
| 447 | my $importer = Catmandu->importer('OAI', url => 'http://www.instute.org/oai/'); | ||||||||||||||||||||
| 448 | my $importer = Catmandu->importer('default'); | ||||||||||||||||||||
| 449 | my $importer = Catmandu->importer(); # The default name is 'default' | ||||||||||||||||||||
| 450 | |||||||||||||||||||||
| 451 | Configuration settings can be overwritten by the importer command: | ||||||||||||||||||||
| 452 | |||||||||||||||||||||
| 453 | my $importer2 = Catmandu->importer('default', url => 'http://other.institute.org'); | ||||||||||||||||||||
| 454 | |||||||||||||||||||||
| 455 | =head2 default_exporter | ||||||||||||||||||||
| 456 | |||||||||||||||||||||
| 457 | Return the name of the default exporter. | ||||||||||||||||||||
| 458 | |||||||||||||||||||||
| 459 | =head2 default_exporter_package | ||||||||||||||||||||
| 460 | |||||||||||||||||||||
| 461 | Return the name of the default exporter package if no | ||||||||||||||||||||
| 462 | package name is given in the config or as a param. | ||||||||||||||||||||
| 463 | |||||||||||||||||||||
| 464 | =head2 exporter([NAME]) | ||||||||||||||||||||
| 465 | |||||||||||||||||||||
| 466 | Return an instance of L<Catmandu::Exporter> with name NAME (or the default when | ||||||||||||||||||||
| 467 | no name is given). The NAME is set in the configuration file (see 'importer'). | ||||||||||||||||||||
| 468 | |||||||||||||||||||||
| 469 | =head2 export($data,[NAME]) | ||||||||||||||||||||
| 470 | |||||||||||||||||||||
| 471 | Export data using a default or named exporter or exporter instance. | ||||||||||||||||||||
| 472 | |||||||||||||||||||||
| 473 | Catmandu->export({ foo=>'bar'}); | ||||||||||||||||||||
| 474 | |||||||||||||||||||||
| 475 | my $importer = Catmandu::Importer::Mock->new; | ||||||||||||||||||||
| 476 | Catmandu->export($importer, 'YAML', file => '/my/file'); | ||||||||||||||||||||
| 477 | Catmandu->export($importer, 'my_exporter'); | ||||||||||||||||||||
| 478 | Catmandu->export($importer, 'my_exporter', exporter_option => '...' , ...); | ||||||||||||||||||||
| 479 | Catmantu->export($importer, Catmandu::Exporter::YAML->new); | ||||||||||||||||||||
| 480 | |||||||||||||||||||||
| 481 | =head2 export_to_string | ||||||||||||||||||||
| 482 | |||||||||||||||||||||
| 483 | Export data using a default or named exporter to a string. | ||||||||||||||||||||
| 484 | |||||||||||||||||||||
| 485 | my $importer = Catmandu::Importer::Mock->new; | ||||||||||||||||||||
| 486 | my $yaml = Catmandu->export_to_string($importer, 'YAML'); | ||||||||||||||||||||
| 487 | # is the same as | ||||||||||||||||||||
| 488 | my $yaml = ""; | ||||||||||||||||||||
| 489 | Catmandu->export($importer, 'YAML', file => \$yaml); | ||||||||||||||||||||
| 490 | |||||||||||||||||||||
| 491 | =head1 EXPORTS | ||||||||||||||||||||
| 492 | |||||||||||||||||||||
| 493 | =over | ||||||||||||||||||||
| 494 | |||||||||||||||||||||
| 495 | =item config | ||||||||||||||||||||
| 496 | |||||||||||||||||||||
| 497 | Same as C<< Catmandu->config >>. | ||||||||||||||||||||
| 498 | |||||||||||||||||||||
| 499 | =item store | ||||||||||||||||||||
| 500 | |||||||||||||||||||||
| 501 | Same as C<< Catmandu->store >>. | ||||||||||||||||||||
| 502 | |||||||||||||||||||||
| 503 | =item importer | ||||||||||||||||||||
| 504 | |||||||||||||||||||||
| 505 | Same as C<< Catmandu->importer >>. | ||||||||||||||||||||
| 506 | |||||||||||||||||||||
| 507 | =item exporter | ||||||||||||||||||||
| 508 | |||||||||||||||||||||
| 509 | Same as C<< Catmandu->exporter >>. | ||||||||||||||||||||
| 510 | |||||||||||||||||||||
| 511 | =item export | ||||||||||||||||||||
| 512 | |||||||||||||||||||||
| 513 | Same as C<< Catmandu->export >>. | ||||||||||||||||||||
| 514 | |||||||||||||||||||||
| 515 | =item export_to_string | ||||||||||||||||||||
| 516 | |||||||||||||||||||||
| 517 | Same as C<< Catmandu->export_to_string >>. | ||||||||||||||||||||
| 518 | |||||||||||||||||||||
| 519 | =item fixer | ||||||||||||||||||||
| 520 | |||||||||||||||||||||
| 521 | Same as C<< Catmandu->fixer >>. | ||||||||||||||||||||
| 522 | |||||||||||||||||||||
| 523 | =item log | ||||||||||||||||||||
| 524 | |||||||||||||||||||||
| 525 | Same as C<< Catmandu->log >>. | ||||||||||||||||||||
| 526 | |||||||||||||||||||||
| 527 | =item -all/:all | ||||||||||||||||||||
| 528 | |||||||||||||||||||||
| 529 | Import everything. | ||||||||||||||||||||
| 530 | |||||||||||||||||||||
| 531 | =item -load/:load | ||||||||||||||||||||
| 532 | |||||||||||||||||||||
| 533 | use Catmandu -load; | ||||||||||||||||||||
| 534 | use Catmandu -load => []; | ||||||||||||||||||||
| 535 | # is the same as | ||||||||||||||||||||
| 536 | Catmandu->load; | ||||||||||||||||||||
| 537 | |||||||||||||||||||||
| 538 | use Catmandu -load => ['/config/path']; | ||||||||||||||||||||
| 539 | # is the same as | ||||||||||||||||||||
| 540 | Catmandu->load('/config/path'); | ||||||||||||||||||||
| 541 | |||||||||||||||||||||
| 542 | =back | ||||||||||||||||||||
| 543 | |||||||||||||||||||||
| 544 | =head1 CONFIG | ||||||||||||||||||||
| 545 | |||||||||||||||||||||
| 546 | Catmandu configuration options can be stored in files in the root directory of | ||||||||||||||||||||
| 547 | your programming project. The file can be YAML, JSON or Perl and is called | ||||||||||||||||||||
| 548 | C<catmandu.yml>, C<catmandu.json> or C<catmandu.pl>. In this file you can set | ||||||||||||||||||||
| 549 | the default Catmandu stores and exporters to be used. Here is an example of a | ||||||||||||||||||||
| 550 | C<catmandu.yml> file: | ||||||||||||||||||||
| 551 | |||||||||||||||||||||
| 552 | store: | ||||||||||||||||||||
| 553 | default: | ||||||||||||||||||||
| 554 | package: ElasticSearch | ||||||||||||||||||||
| 555 | options: | ||||||||||||||||||||
| 556 | index_name: myrepository | ||||||||||||||||||||
| 557 | |||||||||||||||||||||
| 558 | exporter: | ||||||||||||||||||||
| 559 | default: | ||||||||||||||||||||
| 560 | package: YAML | ||||||||||||||||||||
| 561 | |||||||||||||||||||||
| 562 | =head2 Split config | ||||||||||||||||||||
| 563 | |||||||||||||||||||||
| 564 | For large configs it's more convenient to split the config into several files. | ||||||||||||||||||||
| 565 | You can do so by having multiple config files starting with catmandu*. | ||||||||||||||||||||
| 566 | |||||||||||||||||||||
| 567 | catmandu.general.yml | ||||||||||||||||||||
| 568 | catmandu.db.yml | ||||||||||||||||||||
| 569 | ... | ||||||||||||||||||||
| 570 | |||||||||||||||||||||
| 571 | Split config files are processed and merged by L<Config::Onion>. | ||||||||||||||||||||
| 572 | |||||||||||||||||||||
| 573 | =head2 Deeply nested config structures | ||||||||||||||||||||
| 574 | |||||||||||||||||||||
| 575 | Config files can indicate a path under which their keys will be nested. This | ||||||||||||||||||||
| 576 | makes your configuration more readable by keeping indentation to a minimum. | ||||||||||||||||||||
| 577 | |||||||||||||||||||||
| 578 | A config file containing | ||||||||||||||||||||
| 579 | |||||||||||||||||||||
| 580 | _prefix: | ||||||||||||||||||||
| 581 | foo: | ||||||||||||||||||||
| 582 | bar: | ||||||||||||||||||||
| 583 | baz: 1 | ||||||||||||||||||||
| 584 | |||||||||||||||||||||
| 585 | will be loaded as | ||||||||||||||||||||
| 586 | |||||||||||||||||||||
| 587 | foo: | ||||||||||||||||||||
| 588 | bar: | ||||||||||||||||||||
| 589 | baz: 1 | ||||||||||||||||||||
| 590 | |||||||||||||||||||||
| 591 | See L<Config::Onion> for more information on how this works. | ||||||||||||||||||||
| 592 | |||||||||||||||||||||
| 593 | =head1 SEE ALSO | ||||||||||||||||||||
| 594 | |||||||||||||||||||||
| 595 | =over 4 | ||||||||||||||||||||
| 596 | |||||||||||||||||||||
| 597 | =item documentation | ||||||||||||||||||||
| 598 | |||||||||||||||||||||
| 599 | L<http://librecat.org/Catmandu/> | ||||||||||||||||||||
| 600 | |||||||||||||||||||||
| 601 | =item command line client | ||||||||||||||||||||
| 602 | |||||||||||||||||||||
| 603 | L<catmandu> | ||||||||||||||||||||
| 604 | |||||||||||||||||||||
| 605 | =item core modules | ||||||||||||||||||||
| 606 | |||||||||||||||||||||
| 607 | L<Catmandu::Importer> | ||||||||||||||||||||
| 608 | L<Catmandu::Exporter>, | ||||||||||||||||||||
| 609 | L<Catmandu::Store>, | ||||||||||||||||||||
| 610 | L<Catmandu::Fix>, | ||||||||||||||||||||
| 611 | L<Catmandu::Iterable> | ||||||||||||||||||||
| 612 | |||||||||||||||||||||
| 613 | =item extended features | ||||||||||||||||||||
| 614 | |||||||||||||||||||||
| 615 | L<Catmandu::Validator> | ||||||||||||||||||||
| 616 | |||||||||||||||||||||
| 617 | =back | ||||||||||||||||||||
| 618 | |||||||||||||||||||||
| 619 | =head1 AUTHOR | ||||||||||||||||||||
| 620 | |||||||||||||||||||||
| 621 | Nicolas Steenlant, C<< <nicolas.steenlant at ugent.be> >> | ||||||||||||||||||||
| 622 | |||||||||||||||||||||
| 623 | =head1 CONTRIBUTORS | ||||||||||||||||||||
| 624 | |||||||||||||||||||||
| 625 | Magnus Enger, C<< magnus at enger.priv.no >> | ||||||||||||||||||||
| 626 | |||||||||||||||||||||
| 627 | Nicolas Franck, C<< nicolas.franck at ugent.be >> | ||||||||||||||||||||
| 628 | |||||||||||||||||||||
| 629 | Patrick Hochstenbach, C<< patrick.hochstenbach at ugent.be >> | ||||||||||||||||||||
| 630 | |||||||||||||||||||||
| 631 | Vitali Peil, C<< vitali.peil at uni-bielefeld.de >> | ||||||||||||||||||||
| 632 | |||||||||||||||||||||
| 633 | Christian Pietsch, C<< christian.pietsch at uni-bielefeld.de >> | ||||||||||||||||||||
| 634 | |||||||||||||||||||||
| 635 | Dave Sherohman, C<< dave.sherohman at ub.lu.se >> | ||||||||||||||||||||
| 636 | |||||||||||||||||||||
| 637 | Jakob Voss, C<< nichtich at cpan.org >> | ||||||||||||||||||||
| 638 | |||||||||||||||||||||
| 639 | =head1 QUESTIONS, ISSUES & BUG REPORTS | ||||||||||||||||||||
| 640 | |||||||||||||||||||||
| 641 | For any questions on the use of our modules please join our mailing list at: | ||||||||||||||||||||
| 642 | |||||||||||||||||||||
| 643 | librecat-dev@lists.uni-bielefeld.de | ||||||||||||||||||||
| 644 | |||||||||||||||||||||
| 645 | or send in your bug reports or feature requests to our issue tracker at: | ||||||||||||||||||||
| 646 | |||||||||||||||||||||
| 647 | https://github.com/LibreCat/Catmandu/issues | ||||||||||||||||||||
| 648 | |||||||||||||||||||||
| 649 | =head1 LICENSE AND COPYRIGHT | ||||||||||||||||||||
| 650 | |||||||||||||||||||||
| 651 | This program is free software; you can redistribute it and/or modify it | ||||||||||||||||||||
| 652 | under the terms of either: the GNU General Public License as published | ||||||||||||||||||||
| 653 | by the Free Software Foundation; or the Artistic License. | ||||||||||||||||||||
| 654 | |||||||||||||||||||||
| 655 | See L<http://dev.perl.org/licenses/> for more information. | ||||||||||||||||||||
| 656 | |||||||||||||||||||||
| 657 | =cut | ||||||||||||||||||||