summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJesse Luehrs <doy@tozt.net>2010-02-19 17:13:54 -0600
committerJesse Luehrs <doy@tozt.net>2010-02-19 17:13:54 -0600
commitc0f3e6ac4d3b810dc2b6c92a80a74d8a6b04ce9b (patch)
tree751efb535ea108b1bff850886db107476ef792a4
parent5401bf1ae36ff2678d9eae85167ebafbf5ab007c (diff)
downloadlocale-pofilemanager-c0f3e6ac4d3b810dc2b6c92a80a74d8a6b04ce9b.tar.gz
locale-pofilemanager-c0f3e6ac4d3b810dc2b6c92a80a74d8a6b04ce9b.zip
add docs
-rw-r--r--lib/Locale/POFileManager.pm54
-rw-r--r--lib/Locale/POFileManager/File.pm42
2 files changed, 96 insertions, 0 deletions
diff --git a/lib/Locale/POFileManager.pm b/lib/Locale/POFileManager.pm
index 2ce4357..b32b076 100644
--- a/lib/Locale/POFileManager.pm
+++ b/lib/Locale/POFileManager.pm
@@ -33,10 +33,34 @@ the L<Locale::PO> parser library.
=head2 new
+Accepts a hash of arguments:
+
+=over 4
+
+=item base_dir
+
+The directory that contains the .po files. Required.
+
+=item canonical_language
+
+The language for the file that contains the canonical set of msgids. Required.
+
+=item stub_msgstr
+
+The msgstr to insert when adding stubs to language files. This can be either a
+literal string, or a coderef which accepts a hash containing the keys C<msgid>,
+C<lang>, and C<canonical_msgstr> (the msgstr value from the
+C<canonical_language>. Optional.
+
+=back
+
=cut
=head2 base_dir
+Returns a L<Path::Class::Dir> object corresponding to the C<base_dir> passed to
+the constructor.
+
=cut
has base_dir => (
@@ -48,6 +72,9 @@ has base_dir => (
=head2 files
+Returns a list of L<Locale::POFileManager::File> objects corresponding to the
+.po files that were found in the C<base_dir>.
+
=cut
has files => (
@@ -85,6 +112,8 @@ sub _build_files {
=head2 canonical_language
+Returns the canonical language id passed to the constructor.
+
=cut
has canonical_language => (
@@ -108,6 +137,10 @@ sub BUILD {
=head2 stub_msgstr
+Returns the string passed to the constructor as C<stub_msgstr> if it was a
+string, or a coderef wrapped to supply the C<canonical_msgstr> option if it was
+a coderef.
+
=cut
sub stub_msgstr {
@@ -133,6 +166,9 @@ sub stub_msgstr {
=head2 has_language
+Returns true if a language file exists for the given language in the
+C<base_dir>, false otherwise.
+
=cut
sub has_language {
@@ -148,6 +184,10 @@ sub has_language {
=head2 add_language
+Creates a new language file for the language passed in as an argument. Creates
+a header for that file copied over from the header in the C<canonical_language>
+language file, and saves the newly created file in the C<base_dir>.
+
=cut
sub add_language {
@@ -173,6 +213,9 @@ sub add_language {
=head2 language_file
+Returns the L<Locale::POFileManager> object corresponding to the given
+language.
+
=cut
sub language_file {
@@ -186,6 +229,9 @@ sub language_file {
=head2 canonical_language_file
+Returns the L<Locale::POFileManager> object corresponding to the
+C<canonical_language>.
+
=cut
sub canonical_language_file {
@@ -195,6 +241,10 @@ sub canonical_language_file {
=head2 find_missing
+Searches through all of the files in the C<base_dir>, and returns a hash
+mapping language names to an arrayref of msgids that were found in the
+C<canonical_language> file but not in the file for that language.
+
=cut
sub find_missing {
@@ -211,6 +261,10 @@ sub find_missing {
=head2 add_stubs
+Adds stub msgid (and possibly msgstr, if the C<stub_msgstr> option was given)
+entries to each language file for each msgid found in the C<canonical_language>
+file but not in the language file.
+
=cut
sub add_stubs {
diff --git a/lib/Locale/POFileManager/File.pm b/lib/Locale/POFileManager/File.pm
index e5e8267..7e7fc3d 100644
--- a/lib/Locale/POFileManager/File.pm
+++ b/lib/Locale/POFileManager/File.pm
@@ -40,10 +40,27 @@ manipulating the translation entries in it.
=head2 new
+Accepts a hash of arguments:
+
+=over 4
+
+=item file
+
+The name of the file this represents. Required.
+
+=item stub_msgstr
+
+The msgstr to insert when adding stubs to language files. This can be either a
+literal string, or a coderef which accepts a hash containing the keys C<msgid>
+and C<lang>. Optional.
+
=cut
=head2 file
+Returns a L<Path::Class::File> object corresponding to the C<file> passed to
+the constructor.
+
=cut
has file => (
@@ -55,6 +72,8 @@ has file => (
=head2 stub_msgstr
+Returns the C<stub_msgstr> passed to the constructor.
+
=cut
has stub_msgstr => (
@@ -64,14 +83,23 @@ has stub_msgstr => (
=head2 entries
+Returns a list of L<Locale::PO> objects corresponding to translation entries in
+the file.
+
=cut
=head2 add_entry
+Adds a new translation entry to the file. This can be provided either as a
+L<Locale::PO> object directly, or as a hash of options to pass to the
+L<Locale::PO> constructor (except without the leading dashes).
+
=cut
=head2 msgids
+Returns a list of msgids found in the file.
+
=cut
has entries => (
@@ -109,6 +137,8 @@ sub add_entry {
=head2 entry_for
+Returns the L<Locale::PO> object corresponding to the given msgid.
+
=cut
sub entry_for {
@@ -119,6 +149,8 @@ sub entry_for {
=head2 save
+Writes the current contents of the file back out to disk.
+
=cut
sub save {
@@ -129,6 +161,8 @@ sub save {
=head2 language
+Returns the language that this file corresponds to.
+
=cut
sub language {
@@ -140,6 +174,10 @@ sub language {
=head2 find_missing_from
+Takes another translation file (either as a filename or as a
+L<Locale::POFileManager::File> object), and returns a list of msgids that the
+given file contains that this file doesn't.
+
=cut
sub find_missing_from {
@@ -158,6 +196,10 @@ sub find_missing_from {
=head2 add_stubs_from
+Takes another translation file (either as a filename or as a
+L<Locale::POFileManager::File> object), and adds stubs for each msgid that the
+given file contains that this file doesn't.
+
=cut
sub add_stubs_from {