.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" ======================================================================== .\" .IX Title "Locale::Maketext::Utils 3" .TH Locale::Maketext::Utils 3 "2014-11-17" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Locale::Maketext::Utils \- Adds some utility functionality and failure handling to Local::Maketext handles .SH "SYNOPSIS" .IX Header "SYNOPSIS" In MyApp/Localize.pm: .PP .Vb 3 \& package MyApp::Localize; \& use Locale::Maketext::Utils; \& use base \*(AqLocale::Maketext::Utils\*(Aq; \& \& our $Encoding = \*(Aqutf\-8\*(Aq; # see below \& \& # no _AUTO \& our %Lexicon = (... .Ve .PP Make all the language Lexicons you want. (no _AUTO) .PP Then in your script: .PP .Vb 1 \& my $lang = MyApp::Localize\->get_handle(\*(Aqfr\*(Aq); .Ve .PP Now \f(CW$lang\fR behaves like a normal Locale::Maketext handle object but there are some new features, methods, and failure handling which are described below. .ie n .SH "our $Encoding" .el .SH "our \f(CW$Encoding\fP" .IX Header "our $Encoding" If you set your class's \f(CW$Encoding\fR variable the object's encoding will be set to that. .PP .Vb 1 \& my $enc = $lh\->encoding(); .Ve .PP \&\f(CW$enc\fR is \f(CW$MyApp::Localize::fr::Encoding\fR || \f(CW$MyApp::Localize::Encoding\fR || \fIencoding()\fR's default .SH "Argument based singleton" .IX Header "Argument based singleton" The \fIget_handle()\fR method returns an argument based singleton. That means the overhead of initializing an object and compiling parts of the lexicon being used only happen once even if \fIget_handle()\fR is called several times with the same arguments. .ie n .SH "Lexicon hashes that are ""read only""" .el .SH "Lexicon hashes that are ``read only''" .IX Header "Lexicon hashes that are read only" Sometimes you want your lexicon to be a tied hash that is read only which would be fatal when storing a compiled key's value (e.g. GDBM_File). .PP To faciltate that (without needing other special \fItie()\fRs as per \*(L"Tie::Hash::ReadonlyStack compat Lexicon\*(R") you can simply \fIinit()\fR your handle with: .PP .Vb 1 \& $lh\->{\*(Aquse_external_lex_cache\*(Aq} = 1; .Ve .PP That will cause all compiled strings to be stored in the object instead of back in the lexicon. .SH "Aliasing" .IX Header "Aliasing" In your package you can create an alias with this: .PP .Vb 3 \& _\|_PACKAGE_\|_\->make_alias($langs, 1); \& or \& MyApp::Localize\->make_alias([qw(en en_us i_default)], 1); \& \& _\|_PACKAGE_\|_\->make_alias($langs); \& or \& MyApp::Localize::fr\->make_alias(\*(Aqfr_ca\*(Aq); .Ve .PP Where \f(CW$langs\fR is a string or a reference to an array of strings that are the aliased language tags. .PP You must set the second argument to true if _\|_PACKAGE_\|_ is the base class. .PP The reason is there is no way to tell if the pakage name is the base class or not. .PP This needs done before you call \fIget_handle()\fR or it will have no effect on your object really. .PP Ideally you'd put all calls to this in the main lexicon to ensure it will apply to any \fIget_handle()\fR calls. .PP Alternatively, and at times more ideally, you can keep each module's aliases in them and then when setting your obj require the module first. .SH "METHODS" .IX Header "METHODS" .SS "Deprecated for clarity:" .IX Subsection "Deprecated for clarity:" These are deprecated because they are ambiguous names (i.e. used in other places by other things) and thus problematic when harvesting phrases. .PP \fI\f(CI$lh\fI\->print($key, \f(CI@args\fI);\fR .IX Subsection "$lh->print($key, @args);" .PP Shortcut for .PP .Vb 1 \& print $lh\->maketext($key, @args); .Ve .PP \fI\f(CI$lh\fI\->fetch($key, \f(CI@args\fI);\fR .IX Subsection "$lh->fetch($key, @args);" .PP Alias for .PP .Vb 1 \& $lh\->maketext($key, @args); .Ve .PP \fI\f(CI$lh\fI\->say($key, \f(CI@args\fI);\fR .IX Subsection "$lh->say($key, @args);" .PP Like \f(CW$lh\fR\->print($key, \f(CW@args\fR); except appends $/ || \en .PP \fI\f(CI$lh\fI\->get($key, \f(CI@args\fI);\fR .IX Subsection "$lh->get($key, @args);" .PP Like \f(CW$lh\fR\->fetch($key, \f(CW@args\fR); except appends $/ || \en .ie n .SS "$lh\->\fIget_base_class()\fP" .el .SS "\f(CW$lh\fP\->\fIget_base_class()\fP" .IX Subsection "$lh->get_base_class()" Returns the base class of the object. So if \f(CW$lh\fR is a MyApp::Localize::fr object then it returns MyApp::Localize .ie n .SS "$lh\->\fIget_language_class()\fP" .el .SS "\f(CW$lh\fP\->\fIget_language_class()\fP" .IX Subsection "$lh->get_language_class()" Returns the language class of the object. So if \f(CW$lh\fR is a MyApp::Localize::fr object then it returns MyApp::Localize::fr .ie n .SS "$lh\->\fIget_language_tag()\fP" .el .SS "\f(CW$lh\fP\->\fIget_language_tag()\fP" .IX Subsection "$lh->get_language_tag()" Returns the real language name space being used, not \fIlanguage_tag()\fR's \*(L"cleaned up\*(R" one .ie n .SS "$lh\->langtag_is_loadable($lang_tag)" .el .SS "\f(CW$lh\fP\->langtag_is_loadable($lang_tag)" .IX Subsection "$lh->langtag_is_loadable($lang_tag)" Returns 0 if the argument is not a language that can be used to get a handle. .PP Returns the language handle if it is a language that can be used to get a handle. .ie n .SS "$lh\->\fIlang_names_hashref()\fP" .el .SS "\f(CW$lh\fP\->\fIlang_names_hashref()\fP" .IX Subsection "$lh->lang_names_hashref()" This returns a hashref whose keys are the language tags and the values are the name of language tag in \f(CW$lh\fR's native langauge. .PP It can be called several ways: .IP "\(bu" 4 Give it a list of tags to lookup .Sp .Vb 1 \& $lh\->lang_names_hashref(@lang_tags) .Ve .IP "\(bu" 4 Have it search \f(CW@INC\fR for Base/Class/*.pm's .Sp .Vb 1 \& $lh\->lang_names_hashref() # IE no args .Ve .IP "\(bu" 4 Have it search specific places for Base/Class/*.pm's .Sp .Vb 2 \& local $lh\->{\*(Aq_lang_pm_search_paths\*(Aq} = \e@lang_paths; # array ref of directories \& $lh\->lang_names_hashref() # IE no args .Ve .PP The module it uses for lookup (Locales::Language) is only required when this method is called. Make sure you have the latest verison of Locales as 0.04 (i.e. Locales::Base 0.03) is buggy! .PP The module it uses for lookup (Locales::Language) is currently limited to two character codes but we try to handle it gracefully here. .PP In array context it will build and return an additional hashref with the same keys whose values are the language name in the langueage itself. .PP Does not ensure that the tags are loadable, to do that see below. .ie n .SS "$lh\->\fIloadable_lang_names_hashref()\fP" .el .SS "\f(CW$lh\fP\->\fIloadable_lang_names_hashref()\fP" .IX Subsection "$lh->loadable_lang_names_hashref()" Exactly the same as \f(CW$lh\fR\->\fIlang_names_hashref()\fR (because it calls that method...) except it only contains tags that are loadable. .PP Has additional overhead of calling \f(CW$lh\fR\->\fIlangtag_is_loadable()\fR on each key. So most likely you'd use this on a single specific place (a page to choose their language setting for instance) instead of calling it on every instance your script is run. .ie n .SS "$lh\->append_to_lexicons( $lexicons_hashref );" .el .SS "\f(CW$lh\fP\->append_to_lexicons( \f(CW$lexicons_hashref\fP );" .IX Subsection "$lh->append_to_lexicons( $lexicons_hashref );" This method allows modules or script to append to the object's Lexicons. Consider using \*(L"Tie::Hash::ReadonlyStack compat Lexicon\*(R" instead. .PP Each key is the language tag whose Lexicon you will prepend its value, a hashref, to. .PP So assuming the key is 'fr', then this is the lexicon that gets appended to: .PP _\|_PACKAGE_\|_::fr::Lexicon .PP The only exception is if the key is '_'. In that case the main package's Lexicon is appended to: .PP _\|_PACKAGE_\|_::Lexicon .PP .Vb 8 \& $lh\->append_to_lexicons({ \& \*(Aq_\*(Aq => { \& \*(AqHello World\*(Aq => \*(AqHello World\*(Aq, \& }, \& \*(Aqfr\*(Aq => { \& \*(AqHello World\*(Aq => \*(AqBonjour Monde\*(Aq, \& }, \& }); .Ve .ie n .SS "$lh\->remove_key_from_lexicons($key)" .el .SS "\f(CW$lh\fP\->remove_key_from_lexicons($key)" .IX Subsection "$lh->remove_key_from_lexicons($key)" Removes \f(CW$key\fR from every lexicon. Consider using \*(L"Tie::Hash::ReadonlyStack compat Lexicon\*(R" instead. .PP What is removed is stored in \f(CW$lh\fR\->{'_removed_from_lexicons'} .PP If defined, \f(CW$lh\fR\->{'_removed_from_lexicons'} is a hashref whose keys are the index number of the \f(CW$lh\fR\->\fI_lex_refs()\fR arrayref. .PP The value is the key and the value that that lexicon had. .PP This is used internally to remove _AUTO keys so that the failure handler below will get used .ie n .SS "$lh\->\fIget_locales_obj()\fP" .el .SS "\f(CW$lh\fP\->\fIget_locales_obj()\fP" .IX Subsection "$lh->get_locales_obj()" Return a Locales object suitable for the object (or the optional locale tag argument). .PP If the locale tag can not be loaded it tries the super (if any) then \f(CW$lh\fR\->{'fallback_locale} (if set) and its super (if any) before defaulting to 'en'. .PP Locales is where all the \s-1CLDR\s0 data and logic comes from. .ie n .SS "$lh\->\fIget_language_tag_name()\fP;" .el .SS "\f(CW$lh\fP\->\fIget_language_tag_name()\fP;" .IX Subsection "$lh->get_language_tag_name();" Takes 2 optional arguments: .IP "1. A locale tag whose name you want (defaults to the object's locale)." 4 .IX Item "1. A locale tag whose name you want (defaults to the object's locale)." .PD 0 .IP "2. A locale tag whose language you want the name to be in (defaults to the object's locale)." 4 .IX Item "2. A locale tag whose language you want the name to be in (defaults to the object's locale)." .PD .PP These names are defined by the \s-1CLDR\s0. .ie n .SS "$lh\->\fIget_html_dir_attr()\fP" .el .SS "\f(CW$lh\fP\->\fIget_html_dir_attr()\fP" .IX Subsection "$lh->get_html_dir_attr()" With no argument, returns the object locale’s character orientation as a string suitable for HTML’s dir attribute. .PP Given a \s-1CLDR\s0 character orientation string it will return a string suitable for HTML’s dir attribute. .PP Given a locale tag and second argument of true (specifying that the first argument is a tag not a \s-1CLDR\s0 character orientation string ) it returns that locale’s character orientation as a string suitable for HTML’s dir attribute. .PP The character orientation comes from \s-1CLDR\s0. .ie n .SS "$lh\->\fIget_locale_display_pattern()\fP" .el .SS "\f(CW$lh\fP\->\fIget_locale_display_pattern()\fP" .IX Subsection "$lh->get_locale_display_pattern()" Returns the locale display pattern for the object or the tag given as the ofrst optional argument. .PP The pattern comes from the \s-1CLDR\s0. .ie n .SS "$lh\->\fIget_language_tag_character_orientation()\fP" .el .SS "\f(CW$lh\fP\->\fIget_language_tag_character_orientation()\fP" .IX Subsection "$lh->get_language_tag_character_orientation()" Returns the character orientation string for the object or the tag given as the first optional argument. .PP The string comes from the \s-1CLDR\s0. .ie n .SS "$lh\->lextext('Your key here.')" .el .SS "\f(CW$lh\fP\->lextext('Your key here.')" .IX Subsection "$lh->lextext('Your key here.')" Get the lexicon’s text of 'Your key here.' without compiling it (in other words all bracket notation is still in tact). .PP The results are suitable for the first arg to \fImakethis()\fR. .PP \fI\f(CI$lh\fI\->text('Your key here.')–deprecated for clarity\fR .IX Subsection "$lh->text('Your key here.')–deprecated for clarity" .PP Deprecated name of \f(CW$lh\fR\->\fIlextext()\fR. .PP It is deprecated because it is an ambiguous name (i.e. used in other places by other things) and thus problematic when harvesting phrases. .ie n .SS "$lh\->\fImakethis()\fP" .el .SS "\f(CW$lh\fP\->\fImakethis()\fP" .IX Subsection "$lh->makethis()" Like \fImaketext()\fR but does not lookup the phrase in the lexicon and compiles the phrase exactly as given. .ie n .SS "$lh\->\fImakethis_base()\fP" .el .SS "\f(CW$lh\fP\->\fImakethis_base()\fP" .IX Subsection "$lh->makethis_base()" Like \fImakethis()\fR but uses the base class as the phrase compiler instead of the object. .PP This is usful in testing when you want consistent semantics on arbitrary objects. .ie n .SS "$lh\->\fImakevar()\fP" .el .SS "\f(CW$lh\fP\->\fImakevar()\fP" .IX Subsection "$lh->makevar()" This is an alias to \fImaketext()\fR. Its sole purpose is to be used to semantically indicate that the source code does not contain a translatable string in the call to \fImaketext()\fR. .PP For example: .PP .Vb 1 \& $lh\->maketext(\*(AqHello World\*(Aq) .Ve .PP It is easy to tell that we need to provide translations for 'Hello World'. But given: .PP .Vb 1 \& $lh\->maketext($api_rv\->{\*(Aqstring\*(Aq}) .Ve .PP It is not easy to determine what \f(CW$api_rv\fR\->{'string'} is in order to pass it on to the translation team. .PP However if we do that like this: .PP .Vb 3 \& my $string = translatable(\*(AqHello World\*(Aq); # See Locale::Maketext::Utils::MarkPhrase \& … \& $lh\->makevar($api_rv\->{\*(Aqstring\*(Aq}) .Ve .PP Then the parser can simply ignore the call to \fImakevar()\fR and find the value it is interested in via \fItranslatable()\fR .PP Additionally, since \fImakevar()\fR is meant to work with variables it also has the distinction of taking an array ref, as its only arg, that contains the arguments you’d normally pass to make*(). .PP This makes it easier/possible to do something like this: .PP .Vb 1 \& $locale\->makevar(@mystuff) .Ve .PP in, say, Template Toolkit syntax. .PP For example, if 'api_mt_result' is [ 'You have [quant,_1,user,users].', 42 ] you could do: .PP .Vb 1 \& [% locale.makevar(api_mt_result) %] .Ve .PP instead of something hacky and convoluted like: .PP .Vb 3 \& [%\- SET item_list = [] \-%] \& [%\- FOREACH i IN api_mt_result; item_list.push(i.json); END \-%] \& [% \*(Aq\e[% locale.makevar(\*(Aq _ item_list.join(", ") _ \*(Aq) %\e]\*(Aq | evaltt %] .Ve .ie n .SS "$lh\->\fIget_asset()\fP" .el .SS "\f(CW$lh\fP\->\fIget_asset()\fP" .IX Subsection "$lh->get_asset()" Helps you find an asset for a locale based on the locale's fallback. .PP Takes a code ref and an optional locale tag (default to the object's locale). .PP The code ref is passed a locale tag (from the list of the locale's fallbacks). .PP The first tag that returns a defined value halts the loop and that value is returned. .PP .Vb 5 \& my $foo = $lh\->get_asset(sub { \& my ($tag) = @_; \& return "foo+$tag" if Foo\->has_locale($tag); \& return; \& }); .Ve .ie n .SS "$lh\->\fIget_asset_file()\fP" .el .SS "\f(CW$lh\fP\->\fIget_asset_file()\fP" .IX Subsection "$lh->get_asset_file()" Takes a path to look for with \f(CW%s\fR where the locale tag should be. The first locale (in the object's locale's fallback list) whose path passes \-f gets the path returned. Does a return; if none are found. .PP .Vb 1 \& my $template = $lh\->get_asset_file(\*(Aq…/.locale/%s.tt\*(Aq); # …/.locale/fr.tt .Ve .PP The optional second argument is a string to return when the path passes \-f. .PP .Vb 1 \& my $js = $lh\->get_asset_file(\*(Aq…/.locale/%s.css\*(Aq,\*(Aqhttp://example.com/locale_css/%s.css\*(Aq); # http://example.com/locale_css/fr.css .Ve .ie n .SS "$lh\->\fIget_asset_dir()\fP" .el .SS "\f(CW$lh\fP\->\fIget_asset_dir()\fP" .IX Subsection "$lh->get_asset_dir()" Same as \fIget_asset_file()\fR but the path must pass \-d. .ie n .SS "$lh\->\fIdelete_cache()\fP" .el .SS "\f(CW$lh\fP\->\fIdelete_cache()\fP" .IX Subsection "$lh->delete_cache()" Delete the internal cache. Returns the hashref that was removed. .PP You can pass it a key and only that is removed (i.e. instead of the entire cache). .PP .Vb 1 \& my $get_asset_file_cache = $lh\->delete_cache(\*(Aqget_asset_file\*(Aq); # only delete the cached data for get_asset_file() \& \& my $entire_cache = $lh\->delete_cache();# delete the entire cache .Ve .PP Currently this applies to 'get_asset_file', 'get_asset_dir', 'makethis', and 'makethis_base'. .SH "Automatically _AUTO'd Failure Handling with hooks" .IX Header "Automatically _AUTO'd Failure Handling with hooks" This module sets \fIfail_with()\fR so that failure is handled for every Lexicon you define as if _AUTO was set and in addition you can use the hooks below. .PP This functionality is turned off if: .IP "\(bu" 4 _AUTO is set on the Lexicon (and it was not removed internally for some strange reason) .IP "\(bu" 4 you've changed the failure function with \f(CW$lh\fR\->\fIfail_with()\fR (If you do change it be sure to restore your _AUTO's inside \f(CW$lh\fR\->{'_removed_from_lexicons'}) .PP The result is that a key is looked for in the handle's Lexicon, then the default Lexicon, then the handlers below, and finally the key itself (Again, as if _AUTO had been set on the Lexicon). I find this extremely useful and hope you do as well :) .ie n .SS "$lh\->{'_get_key_from_lookup'}" .el .SS "\f(CW$lh\fP\->{'_get_key_from_lookup'}" .IX Subsection "$lh->{'_get_key_from_lookup'}" If lookup fails this code reference will be called with the arguments ($lh, \f(CW$key\fR, \f(CW@args\fR) .PP It can do whatever you want to try and find the \f(CW$key\fR and return the desired string. .PP .Vb 1 \& return $string_from_db; .Ve .PP If it fails it should simply: .PP .Vb 1 \& return; .Ve .PP That way it will continue on to the part below: .ie n .SS "$lh\->{'_log_phantom_key'}" .el .SS "\f(CW$lh\fP\->{'_log_phantom_key'}" .IX Subsection "$lh->{'_log_phantom_key'}" If \f(CW$lh\fR\->{'_get_key_from_lookup'} is not a code ref, or \f(CW$lh\fR\->{'_get_key_from_lookup'} returned undef then this method is called with the arguments ($lh, \f(CW$key\fR, \f(CW@args\fR) right before the failure handler does its _AUTO wonderfulness. .SH "Improved Bracket Notation" .IX Header "Improved Bracket Notation" .SS "\fInumf()\fP" .IX Subsection "numf()" This uses the decimal format defined in \s-1CLDR\s0 to format the number. That means there is no need to subclass or define special data per class. .PP It takes an additional argument to specify the maximum number of decimal places you want. .SS "\fInumerate()\fP" .IX Subsection "numerate()" \&\s-1CLDR\s0 plural rule aware version of the Locale::Maketext \fInumerate()\fR. That means there is no need to subclass. .PP See Locales::DB::Docs::PluralForms for locale specific arguments. .SS "\fIquant()\fP" .IX Subsection "quant()" \&\s-1CLDR\s0 plural rule aware version of the Locale::Maketext \fIquant()\fR. .PP That means there is no need to subclass, you need to specify all arguments (except the always optional “Special Zero” argument that some locales have) .PP See Locales::DB::Docs::PluralForms for locale specific arguments. .PP e.g. Key is 'en', value is 'ru': .PP .Vb 1 \& \*(Aq… [quant,_1,one category text,other category text,special_zero text] …\*(Aq => \*(Aq… [quant,_1,one category text,few category text,many category text,other category text] …\*(Aq .Ve .PP You can use '%s' to specify the position of the number. Other wise it is prepended with a space (except “Special Zero” which won't contain the number.) .PP The number is formatted via \fInumf()\fR with a max decimal place of 3. .PP You can pass in an array ref instead of the number in order to pass in a max decimal places value. The first item is the number, the second item is the max decimal places. .PP .Vb 2 \& maketext(\*(AqThe average monthly rainfall is [quant,_1,inch,inches].\*(Aq, $n); # … is 42.869 inches. \& maketext(\*(AqThe average monthly rainfall is [quant,_1,inch,inches].\*(Aq, [$n,2]); # … is 42.87 inches. .Ve .SH "Additional bracket notation methods" .IX Header "Additional bracket notation methods" .SS "\fIjoin()\fP" .IX Subsection "join()" Joins the given arguments with the first argument: .PP .Vb 4 \& [join,\-,_*], @numbers becomes 1\-2\-3\-4\-5 \& [join,,_*], @numbers becomes 12345 \& [join,~,,_*], @numbers becomes 1,2,3,4,5 \& [join,~, ,_*], @numbers becomes 1, 2, 3, 4, 5 .Ve .PP Array ref arguments are expanded: .PP .Vb 1 \& $lh\->maketext(\*(Aq… [join,\-,_1,2] …\*(Aq, [1,2,3],4); # … 1\-2\-3\-4 … .Ve .SS "\fIlist_and()\fP" .IX Subsection "list_and()" Take a list of arguments (like join–array ref arguments are expanded) and format it per the locale's \s-1CLDR\s0 list pattern for and. .PP .Vb 1 \& You chose [list_and,_1]., \e@pals \& \& You chose Rhiannon. \& You chose Rhiannon and Parker. \& You chose Rhiannon, Parker, and Char. \& You chose Rhiannon, Parker, Char, and Bean. .Ve .PP See \*(L"\fIget_list_and()\fR\*(R" in Locales for more information. .SS "\fIlist_or()\fP" .IX Subsection "list_or()" Same as list_and but with or-lists. See \*(L"\fIget_list_or()\fR\*(R" in Locales for more information and an important caveat. .SS "\fIlist_and_quoted()\fP" .IX Subsection "list_and_quoted()" Like \fIlist_and()\fR but all values are quoted via the \s-1CLDR\s0 to disambiguate them. .SS "\fIlist_or_quoted()\fP" .IX Subsection "list_or_quoted()" Like \fIlist_or()\fR but all values are quoted via the \s-1CLDR\s0 to disambiguate them. .PP \fI\fIlist()\fI–deprecated\fR .IX Subsection "list()–deprecated" .PP Creates a phrased list \*(L"and/or\*(R" style: .PP .Vb 1 \& You chose [list,and,_*]., @pals \& \& You chose Rhiannon. \& You chose Rhiannon and Parker. \& You chose Rhiannon, Parker, and Char. \& You chose Rhiannon, Parker, Char, and Bean. .Ve .PP The 'and' above is by default an '&': .PP .Vb 1 \& You chose [list,,_*] \& \& You chose Rhiannon, Parker, & Char .Ve .PP A locale can set that but I recommend being explicit in your lexicons so the translators will know what you're trying to say: .PP .Vb 2 \& [list,and,_*] \& [list,or,_*] .Ve .PP A locale can also control the seperator and \*(L"oxford\*(R" comma character (\s-1IE\s0 empty string for no oxford comma) .PP The locale can do this by setting some variables in the same manner you'd set 'numf_comma' to change how \fInumf()\fR behaves for a class without having to write an almost identical method. .PP The variables are (w/ defaults shown): .PP .Vb 3 \& $lh\->{\*(Aqlist_seperator\*(Aq} = \*(Aq, \*(Aq; \& $lh\->{\*(Aqoxford_seperator\*(Aq} = \*(Aq,\*(Aq; \& $lh\->{\*(Aqlist_default_and\*(Aq} = \*(Aq&\*(Aq; .Ve .PP Array ref arguments are expanded. .SS "\fIdatetime()\fP" .IX Subsection "datetime()" Allows you to get datetime output formatted for the current locale. .PP .Vb 1 \& \*(AqRight now it is [datetime]\*(Aq .Ve .PP It can take 2 arguments which default to DateTime\->now and 'date_format_long' respectively. .PP The first argument tells the function what point in time you want. The values can be: .IP "\(bu" 4 A DateTime object .IP "\(bu" 4 A hashref of arguments suitable for DateTime\->\fInew()\fR .IP "\(bu" 4 An epoch suitable for DateTime\->\fIfrom_epoch()\fR's 'epoch' field. .Sp Uses \s-1UTC\s0 as the time zone .IP "\(bu" 4 A time zone suitable for DateTime constructors' 'time_zone' field .Sp The current time is used. .Sp Passing it an empty string will result in \s-1UTC\s0 being used. .IP "\(bu" 4 An epoch and time zone as above joined together by a colon .Sp A colon followed by nothing will result in \s-1UTC\s0 .PP The second tells it what format you'd like that point in time stringified. The values can be: .IP "\(bu" 4 A coderef that returns a string suitable for DateTime\->\fIformat_cldr()\fR .IP "\(bu" 4 A string that is the name of a DateTime::Locale *_format_* method .IP "\(bu" 4 A string suitable for DateTime\->\fIformat_cldr()\fR .SS "\fIcurrent_year()\fP" .IX Subsection "current_year()" \&\s-1CLDR\s0 version of current year. i.e. Shortcut to [datetime,,YYYY]. .SS "\fIformat_bytes()\fP" .IX Subsection "format_bytes()" Convert byte count to human readable format. Does not require external modules. .PP .Vb 1 \& \*(AqYou have used [format_bytes,_1] of your alloted space.\*(Aq, $bytes .Ve .PP Accepts an optional argument for max number of decimal places, default is 2. .SS "\fIconvert()\fP" .IX Subsection "convert()" Shortcut to Math::Units \fIconvert()\fR .PP .Vb 1 \& \*(AqThe fish was [convert,_1,_2,_3]" long\*(Aq, $feet,\*(Aqft\*(Aq,\*(Aqin\*(Aq .Ve .SS "\fIboolean()\fP" .IX Subsection "boolean()" This method allows you to choose a word or phrase to use based on a boolean. .PP The first argument is the boolean value which should be true, false, or undefined. The next arguments are the string to use for a true value, the string to use for a false value and an optional value for an undefined value (if none is given undefined uses the false value). .PP .Vb 1 \& \*(AqYou [boolean,_1,have won,didn\*(Aqt win] a new car.\*(Aq \& \& \*(AqYou [boolean,_1,have won,didn\*(Aqt win,have not entered our contest to win] a new car.\*(Aq \& \& $lh\->maketext(q{Congratulations! It\*(Aqs a [boolean,_1,girl,boy]!}, $is_a_girl); .Ve .PP It can have “embedded args”: .PP .Vb 1 \& \*(AqYou must specify a value[boolean,_1, for the “_1” field]. .Ve .SS "\fIis_defined()\fP" .IX Subsection "is_defined()" This method allows you to choose a word or phrase to use based on definedness. .PP The first argument is the value which should be defined or undefined. .PP The next arguments are: the string to use for a defined value, the string to use for a undefined value and an optional string for a defined value that is false (if none is given undefined uses the undefined value). .PP It can have “embedded args”. .PP .Vb 3 \& \*(AqSorry, [is_defined,_2,“_2” is an invalid,you must specify a valid] value for “[_1]”.\*(Aq \*(Aqdomain\*(Aq, $domain \& # Sorry, “localhost” is an invalid value for “domain”. \& # Sorry, you must specify a valid value for “domain”. .Ve .SS "\fIis_future()\fP" .IX Subsection "is_future()" The first argument is the same as the first argument to \fIdatetime()\fR. Then comes the string for future and the string for false. .PP .Vb 1 \& Your session [is_future,_1,will expire,expired] on [datetime,_1,date_format_medium]. .Ve .SS "\fIcomment()\fP" .IX Subsection "comment()" Embed comments in your phrases. .PP .Vb 2 \& \*(AqThe transmogrifier has been constipulated to level “[_1]”[comment,The argument is the variable name containing the superposition of the golden ratio’s decimal place in relation to π as mildegredaded by the authoritative falloosifier.].\*(Aq \& # The transmogrifier has been constipulated to level “☺”. .Ve .SS "\fIasis()\fP" .IX Subsection "asis()" Include non-translatable text in your phrase, e.g. a proper name. .PP .Vb 1 \& \*(AqThanks you for contacting [asis,Feel Good Inc.].\*(Aq .Ve .PP This is a short-name alias to 'output,asis' so it can have embedded methods like any \fIoutput()\fR method. .PP .Vb 1 \& \*(AqThanks you for contacting [asis,Foo chr(38) Barsup(®)].\*(Aq .Ve .PP Does not support embedded args. .SS "\fIoutput()\fP" .IX Subsection "output()" When you output a phrase you might mark it up by wrapping the string in, say,
tags. You wouldn't inlcude \s-1HTML\s0 *in* the key itself for a number of obvious reasons (\s-1HTML\s0 is not human, \s-1HTML\s0 is not the only possible output you may ever want, etc): .PP .Vb 1 \& print $lh\->maketext(\*(Aq
Good news everyone!
\*(Aq); # WRONG DO NOT DO THIS !! \& \& print q{} . $lh\->maketext(\*(AqGood news everyone!\*(Aq) . "
"; # good .Ve .PP What about when you want to format something inside the string? For example, you want to be sure certain words stand out. Or the argument is a \s-1URL\s0 that you want to be a link? .PP Again, you don't want to add formatting inside the string so what do you do? You use the \fIoutput()\fR method. .PP This method allows you to specify various output types. Those types allows a key to specify how a word or phrase should be output without having to understand or anticipate every possible context it might be used in. .PP .Vb 1 \& \*(AqWhat ever you do, do [output,strong,NOT] cut the blue wire!\*(Aq \& \& \*(AqYour addon domain [output,underline,_1] has been setup.\*(Aq .Ve .PP \fIDefault output methods.\fR .IX Subsection "Default output methods." .PP Each output method name is the second argument to output. e.g. if the output method is 'xyz' you'd use it like this [output,xyz,…] and define a new one like this 'sub output_xyz { … }'. .PP All \fIoutput()\fR methods support embedded methods: \fIsub()\fR, \fIsup()\fR, \fIchr()\fR, \fIamp()\fR, and \fInumf()\fR. Note: \fIsub()\fR, \fIsup()\fR, and \fInumf()\fR are simplified in that they only work with one argument. .PP These default bare bones methods support 3 contexts: \s-1HTML\s0, \s-1ANSI\s0, and plain text. See \*(L"\fIoutput()\fR context\*(R" below. .PP Feel free to over ride them if they do not suit your needs. .PP The terminal control codes were ripped from Term::ANSIColor but the module itself is not used. .IP "\(bu" 4 \&\fIunderline()\fR .Sp Underline the string: .Sp .Vb 1 \& \*(AqYou [output,underline,must] be on time from now on.\*(Aq .Ve .Sp For \s-1HTML\s0 it uses a span tag w/ \s-1CSS\s0, for text it uses the standard terminal control code 4. .Sp Allows embedded arguments in the string. .Sp Supports \*(L"Arbitrary name/value attribute list\*(R". .IP "\(bu" 4 \&\fIstrong()\fR .Sp Make the string strong: .Sp .Vb 1 \& \*(AqYou [output,strong,do not] want to feed the velociraptors.\*(Aq .Ve .Sp For \s-1HTML\s0 it uses a , for text it uses the standard terminal control code 1. .Sp Allows embedded arguments in the string. .Sp Supports \*(L"Arbitrary name/value attribute list\*(R". .IP "\(bu" 4 \&\fIem()\fR .Sp Add emphasis to the string: .Sp .Vb 1 \& \*(AqWe [output,em,want] you to succeed.\*(Aq .Ve .Sp For \s-1HTML\s0 it uses a , for text it uses the standard terminal control code 3. (This may change in the future. See the blurb about \*(L"not all displays are \s-1ISO\s0 6429\-compliant\*(R" at \*(L"\s-1NOTES\s0\*(R" in Term::ANSIColor.) .Sp Allows embedded arguments in the string. .Sp Supports \*(L"Arbitrary name/value attribute list\*(R". .IP "\(bu" 4 \&\fIurl()\fR .Sp Handle URLs appropriately: .Sp In its simplest form you pass it a \s-1URL\s0 and the text: .Sp .Vb 1 \& \*(AqVisit [output,url,_1,CPAN] today.\*(Aq, \*(Aqhttp://search.cpan.org\*(Aq .Ve .Sp in \s-1HTML\s0 context you get: Visit CPAN today. .Sp in non-HTML context you get: Visit \s-1CPAN\s0 (http://search.cpan.org) today. .Sp It is more flexible by using a special hash. .Sp .Vb 1 \& \*(AqYou must [output,url,_1,html,click here,plain,go to] to complete your registration.\*(Aq .Ve .Sp The arguments after the method name ('output') and the output type ('url') are: the \s-1URL\s0, a hash of values to use in determining the string that the \s-1URL\s0 is turned into. .Sp The main keys are 'html' and 'plain' (the latter is used for both 'plain' and 'ansi' contexts). Their values are the string to use in conjuction with the context's rendering of the value. Embedded arguments are supported in those values: .Sp .Vb 1 \& \*(AqYou must [output,url,_1,html,click on the _2 icon,plain,go to] to complete your registration.\*(Aq, $URL, \*(Aq