From aed3c674af4943938fa9b4a6d4c72b5bdcb60795 Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Sun, 12 Feb 2006 17:16:35 +0200 Subject: [PATCH] save_file returns undef and remembers $! if print fails. POD changes: Revised the synopses of the methods, paying attention to levels of quoting. Repeat the synopsis above the description of each method. Never write C; it looks bad in pod2text. --- po/perl/Locale/PO.pm | 141 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 114 insertions(+), 27 deletions(-) diff --git a/po/perl/Locale/PO.pm b/po/perl/Locale/PO.pm index d565f0f1..9284cb7b 100644 --- a/po/perl/Locale/PO.pm +++ b/po/perl/Locale/PO.pm @@ -15,8 +15,8 @@ use Carp; use fields # Multiline strings including quotes and newlines, but excluding # the initial keywords and any "#~ " obsoletion marks. Can be - # either undef or "" if not present. These end with a newline - # if not empty. + # either undef or "" if not present. These normally do not end + # with a newline. qw(msgid msgid_plural msgstr), # A reference to a hash where keys are numbers (as strings) # and values are in the same format as $self->{msgstr}. @@ -253,18 +253,21 @@ sub save_file { my $file = shift; my $entries = shift; my $ashash = shift; + my $err = undef; open( OUT, ">$file" ) or return undef; if ($ashash) { foreach ( sort keys %$entries ) { - print OUT $entries->{$_}->dump; + print OUT $entries->{$_}->dump or $err=$!, last; } } else { foreach (@$entries) { - print OUT $_->dump; + print OUT $_->dump or $err=$!, last; } } - close OUT; + close OUT or $err=$!; + if ($err) { $!=$err; return undef } + else { return 1 } } sub load_file_asarray { @@ -468,26 +471,31 @@ Locale::PO - Perl module for manipulating .po entries from GNU gettext use Locale::PO; $po = new Locale::PO([-option=>value,...]) - [$string =] $po->msgid([new string]); - [$string =] $po->msgstr([new string]); - [$string =] $po->comment([new string]); - [$string =] $po->automatic([new string]); - [$string =] $po->reference([new string]); - [$value =] $po->fuzzy([value]); - [$value =] $po->obsolete([value]); - [$value =] $po->c_format([value]); - [$value =] $po->php_format([value]); + + # get fields # set fields + $fully_quoted = $po->msgid; $po->msgid($backslashed); + $fully_quoted = $po->msgid_plural; $po->msgid_plural($backslashed); + $fully_quoted = $po->msgstr; $po->msgstr($backslashed); + $fully_quoted_href = $po->msgstr_n; $po->msgstr_n($backslashed_href); + $string = $po->comment; $po->comment($string); + $string = $po->automatic; $po->automatic($string); + $string = $po->reference; $po->reference($string); + $flag = $po->fuzzy; $po->fuzzy($flag); + $flag = $po->obsolete; $po->obsolete($flag); + $tristate = $po->c_format; $po->c_format($tristate); + $tristate = $po->php_format; $po->php_format($tristate); + print $po->dump; - $quoted_string = $po->quote($string); - $string = $po->dequote($quoted_string); + $fully_quoted_string = $po->quote($backslashed_string); + $backslashed_string = $po->dequote($fully_quoted_string); - $aref = Locale::PO->load_file_asarray(); - $href = Locale::PO->load_file_ashash(); - $ref = Locale::PO->load_file(,$ashash); - Locale::PO->save_file_fromarray(,$aref); - Locale::PO->save_file_fromhash(,$href); - Locale::PO->save_file(,$ref,$fromhash); + $aref = Locale::PO->load_file_asarray($filename); + $href = Locale::PO->load_file_ashash($filename); + $ref = Locale::PO->load_file($filename, $ashash); + Locale::PO->save_file_fromarray($filename, $aref); + Locale::PO->save_file_fromhash($filename, $href); + Locale::PO->save_file($filename, $ref, $fromhash); =head1 DESCRIPTION @@ -546,6 +554,9 @@ operator.\nPlease enter all numbers in octal.)> =item new + my Locale::PO $po = new Locale::PO; + my Locale::PO $po = new Locale::PO(%options); + Create a new Locale::PO object to represent a po entry. You can optionally set the attributes of the entry by passing a list/hash of the form: @@ -572,6 +583,10 @@ Note that the C and C must be in BACKSLASHED form. =item msgid + $fully_quoted_string = $po->msgid; + # $backslashed_string = $po->dequote($fully_quoted_string); + $po->msgid($backslashed_string); + Set or get the untranslated string from the object. The value is C if there is no such string for this message, not @@ -584,6 +599,10 @@ but returns the current string in FULLY-QUOTED form. =item msgid_plural + $fully_quoted_string = $po->msgid_plural; + # $backslashed_string = $po->dequote($fully_quoted_string); + $po->msgid_plural($backslashed_string); + Set or get the untranslated plural string from the object. The value is C if there is no plural form for this message. @@ -592,6 +611,10 @@ but returns the current string in FULLY-QUOTED form. =item msgstr + $fully_quoted_string = $po->msgstr; + # $backslashed_string = $po->dequote($fully_quoted_string); + $po->msgstr($backslashed_string); + Set or get the translated string from the object. The value is C if there is no such string for this message, not @@ -605,6 +628,11 @@ but returns the current string in FULLY-QUOTED form. =item msgstr_n + $fully_quoted_hashref = $po->msgstr_n; + # $backslashed_hashref = { %$fully_quoted_hashref }; + # $_ = $po->dequote($_) foreach values(%$backslashed_hashref); + $po->msgstr_n($backslashed_hashref); + Get or set the translations if there are plurals involved. Takes and returns a hashref where the keys are the 'N' case and the values are the strings. eg: @@ -617,12 +645,18 @@ the strings. eg: ); The value C should be treated the same as an empty hash. +Callers should neither modify the hash to which the returned reference +points, nor assume it to remain valid if C is later called +to install a new set of translations. This method expects the new strings in BACKSLASHED form but returns the current strings in FULLY-QUOTED form. =item comment + $string = $po->comment; + $po->comment($string); + Set or get translator comments from the object. If there are no such comments, then the value is C. Otherwise, @@ -632,6 +666,9 @@ each comment line nor the newline at the end of the last comment line. =item automatic + $string = $po->automatic; + $po->automatic($string); + Set or get automatic comments from the object (inserted by emacs po-mode or xgettext). @@ -642,6 +679,9 @@ each comment line nor the newline at the end of the last comment line. =item reference + $string = $po->reference; + $po->reference($string); + Set or get reference marking comments from the object (inserted by emacs po-mode or gettext). @@ -652,32 +692,48 @@ each comment line nor the newline at the end of the last comment line. =item fuzzy + $flag = $po->fuzzy; + $po->fuzzy($flag); + Set or get the fuzzy flag on the object ("check this translation"). When setting, use 1 to turn on fuzzy, and 0 to turn it off. =item obsolete + $flag = $po->obsolete; + $po->obsolete($flag); + Set or get the obsolete flag on the object ("no longer used"). When setting, use 1 to turn on obsolete, and 0 to turn it off. =item c_format + $tristate = $po->obsolete; + $po->obsolete($tristate); + Set or get the c-format or no-c-format flag on the object. This can take 3 values: 1 implies c-format, 0 implies no-c-format, and blank or undefined implies neither. =item php_format + $tristate = $po->php_format; + $po->php_format($tristate); + Set or get the php-format or no-php-format flag on the object. This can take 3 values: 1 implies php-format, 0 implies no-php-format, and blank or undefined implies neither. =item dump + print $po->dump; + Returns the entry as a string, suitable for output to a po file. =item quote + $fully_quoted_string = $po->quote($backslashed_string); + Converts a string from BACKSLASHED to FULLY-QUOTED form. Specifically, the quoted string will have all existing double-quote characters escaped by backslashes, and each line will be enclosed in @@ -685,6 +741,8 @@ double quotes. Preexisting backslashes will not be doubled. =item dequote + $backslashed_string = $po->dequote($fully_quoted_string); + Converts a string from FULLY-QUOTED to BACKSLASHED form. Specifically, it first removes the double-quote characters that surround each line. After this, each remaining double-quote character @@ -693,6 +751,8 @@ backslashes. Backslashes in any other position will be left intact. =item load_file_asarray + $arrayref = Locale::PO->load_file_asarray($filename); + Given the filename of a po-file, reads the file and returns a reference to a list of Locale::PO objects corresponding to the contents of the file, in the same order. @@ -705,6 +765,8 @@ of course. =item load_file_ashash + $hashref = Locale::PO->load_file_ashash($filename); + Given the filename of a po-file, reads the file and returns a reference to a hash of Locale::PO objects corresponding to the contents of the file. The hash keys are the untranslated strings (in BACKSLASHED form), @@ -715,6 +777,8 @@ This handles errors in the same way as C does. =item load_file + $ref = Locale::PO->load_file($filename, $ashash); + This method behaves as C if the C<$ashash> parameter is 0, or as C if C<$ashash> is 1. Your code will probably be easier to understand if you call either @@ -722,17 +786,31 @@ of those methods instead of this one. =item save_file_fromarray + $ok = Locale::PO->save_file_fromarray($filename, \@objects) + Given a filename and a reference to a list of Locale::PO objects, saves those objects to the file, creating a po-file. +Returns true if successful. +Returns C and sets C<$!> if an I/O error occurs. +Dies if a serious error occurs. + =item save_file_fromhash + $ok = Locale::PO->save_file_fromhash($filename, \%objects); + Given a filename and a reference to a hash of Locale::PO objects, saves those objects to the file, creating a po-file. The entries are sorted alphabetically by untranslated string. +Returns true if successful. +Returns C and sets C<$!> if an I/O error occurs. +Dies if a serious error occurs. + =item save_file + $ok = Locale::PO->save_file($filename, $ref, $fromhash); + This method behaves as C if the C<$fromhash> parameter is 0, or as C if C<$fromhash> is 1. Your code will probably be easier to understand if you call either @@ -776,7 +854,7 @@ Reformatted this list of changes. =item Z<>2006-02-05 Kalle Olavi Niemitalo -Added comments about the fields of C objects. +Added comments about the fields of Locale::PO objects. The C function binds C<$/> and C<$_> dynamically. Renamed C to C<_normalize_str>, and C to C<_dump_multi_comment>. @@ -793,11 +871,20 @@ C dumps comments even if they are C. POD changes: Documented the bugs fixed with the changes above. -Documented levels of quoting, and the exact behaviour of C and C. +Documented levels of quoting, and the exact behaviour of C and C. Documented the C method. Documented error handling in C and C. Documented when C, C etc. can return C. +=item Z<>2006-02-12 Kalle Olavi Niemitalo + +C returns C and remembers C<$!> if C fails. + +POD changes: +Revised the synopses of the methods, paying attention to levels of quoting. +Repeat the synopsis above the description of each method. +Never write C<< CZ<> >>; it looks bad in B. + =back =head1 COPYRIGHT AND LICENSE @@ -808,7 +895,7 @@ redistribute it and/or modify it under the same terms as Perl itself. =head1 BUGS -If you load_file then save_file, the output file may have slight +If you C then C, the output file may have slight cosmetic differences from the input file (an extra blank line here or there). The C and C methods are documented: "1 implies @@ -839,8 +926,8 @@ end in the PO file. These would be useful in error messages. The C and C methods return FULLY-QUOTED strings, but they expect BACKSLASHED strings as input. It would be better to have -both quoted or both unquoted; or perhaps C<< $po->msgid(-level => -'BACKSLASHED') >>. +both FULLY-QUOTED or both BACKSLASHED; or perhaps C<< +$po->msgid(-level => 'BACKSLASHED') >>. Locale::PO discards all types of comments it does not recognize. The B program of GNU gettext-tools 0.14.3 does the same,