| File: | blib/lib/App/FileSync/Base.pm |
| Coverage: | 100.0% |
| line | stmt | bran | cond | sub | time | code |
|---|---|---|---|---|---|---|
| 1 | package App::FileSync::Base; | |||||
| 2 | ||||||
| 3 | # The few behaviours every App::FileSync object shares: rendering catalogued | |||||
| 4 | # messages in the object's own language, and raising them. Kept tiny on | |||||
| 5 | # purpose; it is a mixin for i18n, not a framework. | |||||
| 6 | ||||||
| 7 | 314 314 314 | 48102 255 4160 | use App::FileSync::Platform; | |||
| 8 | ||||||
| 9 | 314 314 314 | 491 226 2437 | use strict; | |||
| 10 | 314 314 314 | 595 265 5832 | use warnings; | |||
| 11 | 314 314 314 | 485 204 629 | use autodie qw(:all); | |||
| 12 | ||||||
| 13 | 314 314 314 | 730967 353915 807 | use Sub::Protected; | |||
| 14 | ||||||
| 15 | 314 314 314 | 31372 247 2504 | use App::FileSync::I18N (); | |||
| 16 | ||||||
| 17 | 314 314 314 | 458 232 611 | use version; our $VERSION = version->declare('0.001.1'); | |||
| 18 | ||||||
| 19 | # Raising through _throw should report the subclass's caller, not this file. | |||||
| 20 | $Carp::Internal{ (__PACKAGE__) }++; | |||||
| 21 | ||||||
| 22 | =encoding utf8 | |||||
| 23 | ||||||
| 24 - 89 | =head1 NAME
App::FileSync::Base - shared i18n behaviour for App::FileSync objects
=head1 SYNOPSIS
package App::FileSync::Something;
use parent -norequire, 'App::FileSync::Base';
sub check {
my ($self, $path) = @_;
$self->_throw('path.empty') unless length $path;
return $self->i18n('client.verbose_action', { verb => 'push', path => $path });
}
=head1 DESCRIPTION
Objects carry an optional C<language> (a code such as C<de> or a locale name
such as C<de_DE.UTF-8>). Two objects with different languages render their
messages independently, so a server can answer in its own language while a
client in the same process uses another.
=head1 METHODS
=head2 i18n
Purpose: render a catalogued message in this object's language.
Args: C<$key>, optional C<\%args>.
Returns: the rendered string, without a trailing newline.
Side Effects: none.
Usage:
my $text = $self->i18n('cli.sync.summary', { repo => $name, dry => '', pulled => 3, pushed => 0, deleted => 0, conflicts => 0 });
=head3 EXAMPLE
my $client = App::FileSync::Client->new(config => $c, name => 'docs', language => 'en');
print $client->i18n('word.file', { count => 2 }), "\n"; # 2 files
=head3 API SPECIFICATION
=head4 INPUT
[
{ name => 'self', type => 'object', can => 'i18n' },
{ name => 'key', type => 'string', min => 1 },
{ name => 'args', type => 'hashref', optional => 1 },
]
=head4 OUTPUT
{ type => 'string' }
=head3 MESSAGES
None; it renders them.
=head3 FORMAL SPECIFICATION
i18n(self, k, a) = message(k, a, self.language)
=cut | |||||
| 90 | ||||||
| 91 | sub i18n { | |||||
| 92 | 440 | 530 | my ($self, $key, $args) = @_; | |||
| 93 | ||||||
| 94 | 440 | 873 | return App::FileSync::I18N::message($key, $args, $self->{language}); | |||
| 95 | } | |||||
| 96 | ||||||
| 97 - 133 | =head2 language
Purpose: the language this object renders messages in.
Args: none.
Returns: the configured language or locale, or C<undef> for the process default.
Side Effects: none.
Usage:
my $language = $object->language;
=head3 EXAMPLE
print $admin->language // 'process default', "\n";
=head3 API SPECIFICATION
=head4 INPUT
[ { name => 'self', type => 'object' } ]
=head4 OUTPUT
{ type => 'string', optional => 1 }
=head3 MESSAGES
None.
=head3 FORMAL SPECIFICATION
language(self) = self.language
=cut | |||||
| 134 | ||||||
| 135 | sub language { | |||||
| 136 | 1 | 1 | my ($self) = @_; | |||
| 137 | ||||||
| 138 | 1 | 3 | return $self->{language}; | |||
| 139 | } | |||||
| 140 | ||||||
| 141 | # _throw | |||||
| 142 | # Purpose: raise a catalogued error in this object's language. | |||||
| 143 | # Entry: $key names a catalogue entry; $args fills its placeholders. | |||||
| 144 | # Exit: never returns. | |||||
| 145 | # Side effects: croaks (see App::FileSync::I18N::throw). Protected: only | |||||
| 146 | # this class and its subclasses may call it. | |||||
| 147 | sub _throw :Protected { | |||||
| 148 | my ($self, $key, $args) = @_; | |||||
| 149 | ||||||
| 150 | App::FileSync::I18N::throw($key, $args, $self->{language}); | |||||
| 151 | 314 314 314 | 31052 244 3440 | } | |||
| 152 | ||||||
| 153 | 1; | |||||
| 154 | ||||||