NAME

Locale::Maketext -- framework for software localization

SYNOPSIS

[to be written]

DESCRIPTION

Locale::Maketext is a base class providing a framework for inheritance-based lexicons for software localization.

Further documentation is forthcoming.

Methods You May Override

These are all simple methods you should feel welcome to override as you like.

the method $LH->encoding

[to be written]

the method $LH->fallback_languages

[to be written]

the method $LH->sprintf(FORMAT, PARAMS)

Just a wrapper for the normal Perl builtin function sprintf -- it's here so you can use sprintf in bracketish notation.

the method $LH->quant

[to be written]

the method $LH->numerate

[to be written]

the method $LH->numf(NUMBER)

This returns NUMBER formatted appropriately for the conventions of $LH's language. The default behavior for this is just to get sprintf("%g", NUMBER), then to tr/,./.,/ it if $LH->{'numf_comma'} is true, and then to return it.

the method CLASS->new

This is used by CLASS->get_handle to actually perform the instantiation of each language-handle object into its class. Currently it just creates and blesses an empty hashref, and calls $LH->init on it.

the method $LH->init

This is used by CLASS->new to initialize newly instantiated language-handle objects. Currently this is a no-op.

STUFF

the method $LH->maketext(TEXT, PARAMS)

This looks up the entry for TEXT in the the lexicon for $LH's class and its superclasses (via $LH->lookup(TEXT)), and, assuming it's a coderef, returns the return value of &$coderef($LH, PARAMS), which is presumably a single scalar.

If $LH->lookup(TEXT) failed (i.e., returned undef), then maketext fails according to whatever mechanism is set in $LH's "fail" attribute -- if the 'fail' attribute is set to a coderef, maketext returns the output of &{$fail_coderef}($LH, TEXT, PARAMS). If $LH's "fail" attribute is set to a contentful string (i.e., not undef or ""), that's considered to be a method name, and maketext returns the output of $handle->methodname(TEXT, PARAMS). Otherwise, maketext returns undef.

(Actually, in all the cases above where maketext passes values to other subs, it passes copies of TEXT and/or PARAMS, so that the actual values passed to maketext can't be altered in-place. This is to parallel the way Perl copies @_ for method calls.)

the constructor CLASS->get_handle(LANGUAGES)

Constructs a language handle based on the list of locale IDs and/or language tags in the list LANGUAGES.

the method $LH->fail_with(FAILSPEC)

This sets the "fail" attribute of a given language handle. See the docs for $LH->maketext(TEXT, PARAMS).

the method $LH->fail_with

This returns the value of $LH's "fail" attribute.

the method 'failure_handler_auto'

[to be written]

the method $LH->lookup(TEXT)

This looks up the entry TEXT in the lexicons for the handle $LH. This is used by $LH->maketext(TEXT).

If $LH->lookup(TEXT) looks across the lexicons for $LH (which are gotten via $LH->lex_refs), this returns undef. Otherwise:

For the first lexicon containing an entry for TEXT, if that entry is a coderef (presumably thru being an anonymous sub, but it doesn't matter), it's returned.

If, however, the entry for TEXT is a string, that entry is replaced with the contents of $LH->compile($that_lexicon{TEXT}), and that value is returned.

Magic happens when lookup looks in a lexicon where you have set $Lexicon{'_AUTO'} = 1. This _AUTO flag means that a lookup in that lexicon can't really fail -- if there is no entry for TEXT, $LH->lookup(TEXT) will set $Lexicon{TEXT} = $LH->compile(TEXT), and return that value. This is generally useful only in base classes, as a way to mitigate lookup failures.

the method $LH->compile(TEXT) or CLASS->compile(TEXT)

This takes text in bracketish notation (presumably just retrieved via a lexicon returned from $LH->lex_refs), and returns an anonymous sub that is that text compiled into Perl.

Used by $LH->lookup(TEXT).

the method $LH->lex_refs

This returns a list of hashrefs which are the lexicons for the class that this handle belongs to. This is figured out by looking in the package for $LH's class, and the packages of the classes in its @ISA tree. The results of this are memoized for each class. This assumes that no class's @ISA will change after you've started calling maketext methods. I think this is a sane assumption, but in the very surprising case of you modifying @ISAs dynamically, you can call clear_isa_scan to clear all the memoization.

You should not override this method.

the routine Locale::Maketext::clear_isa_scan

also: the routine $LH->clear_isa_scan

also: the routine CLASS->clear_isa_scan

This clears all of lex_ref's memoization of all @ISA trees.

You should not override this method.

COPYRIGHT

Copyright 1999-2000, Sean M. Burke sburke@cpan.org, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Sean M. Burke, sburke@cpan.org