| 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 | 328 | ▶ | use App::FileSync::Platform; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 8 | |||
| 9 | 328 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | 328 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 11 | 328 | ▶ | use autodie qw(:all); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 12 | |||
| 13 | 328 | ▶ | use Sub::Protected; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 14 | |||
| 15 | 328 | ▶ | use App::FileSync::I18N (); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 16 | |||
| 17 | 328 | ▶ | use version; our $VERSION = version->declare('0.002.1'); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 18 | |||
| 19 | # Raising through _throw should report the subclass's caller, not this file. | ||
| 20 | 328 | $Carp::Internal{ (__PACKAGE__) }++; | |
| 21 | |||
| 22 | =encoding utf8 | ||
| 23 | |||
| 24 | =head1 NAME | ||
| 25 | |||
| 26 | App::FileSync::Base - shared i18n behaviour for App::FileSync objects | ||
| 27 | |||
| 28 | =head1 SYNOPSIS | ||
| 29 | |||
| 30 | package App::FileSync::Something; | ||
| 31 | use parent -norequire, 'App::FileSync::Base'; | ||
| 32 | |||
| 33 | sub check { | ||
| 34 | my ($self, $path) = @_; | ||
| 35 | $self->_throw('path.empty') unless length $path; | ||
| 36 | return $self->i18n('client.verbose_action', { verb => 'push', path => $path }); | ||
| 37 | } | ||
| 38 | |||
| 39 | =head1 DESCRIPTION | ||
| 40 | |||
| 41 | Objects carry an optional C<language> (a code such as C<de> or a locale name | ||
| 42 | such as C<de_DE.UTF-8>). Two objects with different languages render their | ||
| 43 | messages independently, so a server can answer in its own language while a | ||
| 44 | client in the same process uses another. | ||
| 45 | |||
| 46 | =head1 METHODS | ||
| 47 | |||
| 48 | =head2 i18n | ||
| 49 | |||
| 50 | Purpose: render a catalogued message in this object's language. | ||
| 51 | |||
| 52 | Args: C<$key>, optional C<\%args>. | ||
| 53 | |||
| 54 | Returns: the rendered string, without a trailing newline. | ||
| 55 | |||
| 56 | Side Effects: none. | ||
| 57 | |||
| 58 | Usage: | ||
| 59 | |||
| 60 | my $text = $self->i18n('cli.sync.summary', { repo => $name, dry => '', pulled => 3, pushed => 0, deleted => 0, conflicts => 0 }); | ||
| 61 | |||
| 62 | =head3 EXAMPLE | ||
| 63 | |||
| 64 | my $client = App::FileSync::Client->new(config => $c, name => 'docs', language => 'en'); | ||
| 65 | print $client->i18n('word.file', { count => 2 }), "\n"; # 2 files | ||
| 66 | |||
| 67 | =head3 API SPECIFICATION | ||
| 68 | |||
| 69 | =head4 INPUT | ||
| 70 | |||
| 71 | [ | ||
| 72 | { name => 'self', type => 'object', can => 'i18n' }, | ||
| 73 | { name => 'key', type => 'string', min => 1 }, | ||
| 74 | { name => 'args', type => 'hashref', optional => 1 }, | ||
| 75 | ] | ||
| 76 | |||
| 77 | =head4 OUTPUT | ||
| 78 | |||
| 79 | { type => 'string' } | ||
| 80 | |||
| 81 | =head3 MESSAGES | ||
| 82 | |||
| 83 | None; it renders them. | ||
| 84 | |||
| 85 | =head3 FORMAL SPECIFICATION | ||
| 86 | |||
| 87 | i18n(self, k, a) = message(k, a, self.language) | ||
| 88 | |||
| 89 | =cut | ||
| 90 | |||
| 91 | 443 | ▶ | sub i18n { |
|
Subroutine
i18n: called CC=1 SCAR=0.0
Pod
documented
| |||
| 92 | 443 | my ($self, $key, $args) = @_; | |
| 93 | |||
| 94 | 443 | return App::FileSync::I18N::message($key, $args, $self->{language}); | |
| 95 | } | ||
| 96 | |||
| 97 | =head2 language | ||
| 98 | |||
| 99 | Purpose: the language this object renders messages in. | ||
| 100 | |||
| 101 | Args: none. | ||
| 102 | |||
| 103 | Returns: the configured language or locale, or C<undef> for the process default. | ||
| 104 | |||
| 105 | Side Effects: none. | ||
| 106 | |||
| 107 | Usage: | ||
| 108 | |||
| 109 | my $language = $object->language; | ||
| 110 | |||
| 111 | =head3 EXAMPLE | ||
| 112 | |||
| 113 | print $admin->language // 'process default', "\n"; | ||
| 114 | |||
| 115 | =head3 API SPECIFICATION | ||
| 116 | |||
| 117 | =head4 INPUT | ||
| 118 | |||
| 119 | [ { name => 'self', type => 'object' } ] | ||
| 120 | |||
| 121 | =head4 OUTPUT | ||
| 122 | |||
| 123 | { type => 'string', optional => 1 } | ||
| 124 | |||
| 125 | =head3 MESSAGES | ||
| 126 | |||
| 127 | None. | ||
| 128 | |||
| 129 | =head3 FORMAL SPECIFICATION | ||
| 130 | |||
| 131 | language(self) = self.language | ||
| 132 | |||
| 133 | =cut | ||
| 134 | |||
| 135 | 1 | ▶ | sub language { |
|
Subroutine
language: called CC=1 SCAR=0.0
Pod
documented
| |||
| 136 | 1 | my ($self) = @_; | |
| 137 | |||
| 138 | 1 | 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 | 58 | ▶ | sub _throw :Protected { |
|
Subroutine
_throw: called CC=1 SCAR=0.0
| |||
| 148 | 58 | my ($self, $key, $args) = @_; | |
| 149 | |||
| 150 | 58 | App::FileSync::I18N::throw($key, $args, $self->{language}); | |
| 151 | 328 | ▶ | } |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 152 | |||
| 153 | 328 | 1; | |
| 154 | |||
| 155 | __END__ | ||