\*(R". Dla uproszczenia, zakładamy, że dokument jest dobrze sformatowany, tj. występują tylko elementy \*(L"
\*(R" i są one umieszczone na samym początku każdego akapitu. .PP .Vb 2 \& sub parse { \& my $self = shift; \& \& PARAGRAPH: while (1) { \& my ($paragraph,$pararef)=("",""); \& my $first=1; \& my ($line,$lref)=$self\->shiftline(); \& while (defined($line)) { \& if ($line =~ m/
/ && !$first\-\-; ) { \& # Nie po raz pierwszy widzimy
. \& # Włóż z powrotem bieżącą linię do wejścia, \& # i dodaj zbudowany akapit do wyjścia \& $self\->unshiftline($line,$lref); \& \& # Teraz, gdy dokument jest sformatowany, przetłumaczmy go: \& # \- Usunięcie początkowych tagów \& $paragraph =~ s/^
//s; \& \& # \- push to output the leading tag (untranslated) and the \& # rest of the paragraph (translated) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # Dodanie do akapitu
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # Ponowna inicjacja pętli
\& ($line,$lref)=$self\->shiftline();
\& }
\& # Nie dostaliśmy zdefiniowanej linii? Koniec pliku wejściowego.
\& return;
\& }
\& }
.Ve
.PP
Po zaimplementowaniu funkcji parsującej, można użyć własnych klas dokumentu, używając publicznego interfejsu zaprezentowanego w następnym rozdziale.
.SH "INTERFEJS PUBLICZNY dla skryptów używających Twojego parsera"
.IX Header "INTERFEJS PUBLICZNY dla skryptów używających Twojego parsera"
.SS "Konstruktor"
.IX Subsection "Konstruktor"
.IP "process(%)" 4
.IX Item "process(%)"
Funkcja zrobi w jednym uruchomieniu wszystko, co tylko trzeba zrobić z dokumentem po4a. Jej argumenty muszą być umieszczone w hashu. \s-1AKCJE:\s0
.RS 4
.IP "a." 3
.IX Item "a."
Czyta wszystkie pliki określone w po_in_name
.IP "b." 3
.IX Item "b."
Czyta wszystkie oryginalne dokumenty określone w file_in_name
.IP "c." 3
.IX Item "c."
Przetwarza (parsuje) dokument
.IP "d." 3
.IX Item "d."
Dodaje i stosuje wszystkie podane załączniki
.IP "e." 3
.IX Item "e."
Zapisuje przetłumaczony dokument do file_out_name (jeśli podano)
.IP "f." 3
.IX Item "f."
Zapisuje wygenerowany plik \s-1PO\s0 do po_out_name (jeśli podano)
.RE
.RS 4
.Sp
\&\s-1ARGUMENTY,\s0 poza tymi akceptowanymi przez \fBnew()\fR (z oczekiwanym typem):
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
Lista nazw plików, z których powinniśmy odczytać plik wejściowy.
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Kodowanie znaków dokumentu wejściowego (jeśli nie podano, nastąpi próba określenia kodowania z dokumentu wejściowego).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
Nazwa pliku, do którego należy zapisać wynikowy dokument.
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Kodowanie znaków wyjściowego dokumentu (jeśli nie podano, będzie użyte kodowanie znaków pliku \s-1PO\s0).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
Lista nazw plików, z których powinniśmy odczytać wejściowe pliki \s-1PO\s0 zawierające tłumaczenia, które będą użyte podczas tłumaczenia dokumentu.
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
Nazwa pliku, do którego powinien być zapisany wynikowy plik \s-1PO,\s0 zawierający komunikaty wyciągnięte z dokumentu wejściowego.
.IP "addendum (@)" 4
.IX Item "addendum (@)"
Lista nazw plików, z których powinniśmy odczytać pliki załączników.
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
Kodowanie znaków załączników.
.RE
.RS 4
.RE
.IP "new(%)" 4
.IX Item "new(%)"
Create a new po4a document. Accepted options (in the hash passed as a parameter):
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
Ustawia gadatliwość.
.IP "debug ($)" 4
.IX Item "debug ($)"
Ustawia debugowanie.
.RE
.RS 4
.RE
.SS "Manipulowanie plikami z dokumentacją"
.IX Subsection "Manipulowanie plikami z dokumentacją"
.IP "read($$)" 4
.IX Item "read($$)"
Add another input document data at the end of the existing array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR. The argument is the filename to read. If a second argument is provided, it is the filename to use in the references.
.Sp
This array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR holds this input document data as an
array of strings with alternating meanings.
* The string \f(CW$textline\fR holding each line of the input text data.
* The string \f(CW\*(C`$filename:$linenum\*(C'\fR holding its location and called as
\*(L"reference\*(R" (\f(CW\*(C`linenum\*(C'\fR starts with 1).
.Sp
Proszę zauważyć, że to niczego nie przetwarza. Należy użyć funkcji \fBparse()\fR po zakończeniu pakowania plików wejściowych do dokumentu.
.IP "write($)" 4
.IX Item "write($)"
Zapisuje przetłumaczony dokument do pliku o podanej nazwie.
.Sp
This translated document data are provided by:
* \f(CW\*(C`$self\->docheader()\*(C'\fR holding the header text for the plugin, and
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR holding each line of the main translated text in the array.
.SS "Manipulowanie plikami \s-1PO\s0"
.IX Subsection "Manipulowanie plikami PO"
.IP "readpo($)" 4
.IX Item "readpo($)"
Dodaje zawartość pliku (którego nazwa jest podawana w argumencie) do istniejącego pliku wejściowego \s-1PO.\s0 Stara zawartość nie jest tracona.
.IP "writepo($)" 4
.IX Item "writepo($)"
Zapisuje wygenerowany plik \s-1PO\s0 do pliku o podanej nazwie.
.IP "\fBstats()\fR" 4
.IX Item "stats()"
Zwraca statystyki dotyczące tłumaczeń. Proszę zauważyć, że nie są to te same statystyki, które wypisuje msgfmt \-\-statistic. Tutaj są to statystyki o obecnym wykorzystaniu pliku \s-1PO,\s0 podczas gdy msgfmt wyświetla status tego pliku. Funkcja jest opakowaniem funkcji Locale::Po4a::Po::stats_get zastosowanej do wejściowego pliku \s-1PO.\s0 Przykład użycia:
.Sp
.Vb 1
\& [zwykłe użycie dokumentu po4a ...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "Znaleźliśmy tłumaczenia $percent\e% ($hit z $queries) komunikatów.\en";
.Ve
.SS "Manipulowanie załącznikami"
.IX Subsection "Manipulowanie załącznikami"
.IP "addendum($)" 4
.IX Item "addendum($)"
Więcej informacji o tym, czym są załączniki, i jak tłumacze powinni je pisać, można znaleźć w \fBpo4a\fR\|(7). Aby dodać załącznik do przetłumaczonego dokumentu, wystarczy po prostu tej funkcji przekazać nazwę pliku, w którym się znajduje, i gotowe ;)
.Sp
Funkcja zwraca liczbę nie będącą nullem lub błąd.
.SH "FUNKCJE WEWNĘTRZNE, używane do pisania parserów"
.IX Header "FUNKCJE WEWNĘTRZNE, używane do pisania parserów"
.SS "Pobieranie wejścia, dostarczanie wyjścia"
.IX Subsection "Pobieranie wejścia, dostarczanie wyjścia"
Dostarczone są cztery funkcje pobierania wejścia i zwracania wyjścia. Są one bardzo podobne do shift/unshift i push/pop w Perlu.
.PP
.Vb 4
\& * Perl shift returns the first array item and drop it from the array.
\& * Perl unshift prepends an item to the array as the first array item.
\& * Perl pop returns the last array item and drop it from the array.
\& * Perl push appends an item to the array as the last array item.
.Ve
.PP
Pierwsza para dotyczy wejścia, a druga \- wyjścia. Mnemonik: w wejściu interesuje Cię pierwsza linia, co daje shift, a w wyjściu chcesz dostać wynik na końcu, tak jak do robi push.
.IP "\fBshiftline()\fR" 4
.IX Item "shiftline()"
This function returns the first line to be parsed and its corresponding reference (packed as an array) from the array \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR and drop these first 2 array items. Here, the reference is provided by a string \f(CW\*(C`$filename:$linenum\*(C'\fR.
.IP "unshiftline($$)" 4
.IX Item "unshiftline($$)"
Unshifts the last shifted line of the input document and its corresponding reference back to the head of \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR.
.IP "pushline($)" 4
.IX Item "pushline($)"
Push a new line to the end of \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.IP "\fBpopline()\fR" 4
.IX Item "popline()"
Pop the last pushed line from the end of \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR.
.SS "Zaznaczanie łańcuchów znaków jako możliwych do przetłumaczenia"
.IX Subsection "Zaznaczanie łańcuchów znaków jako możliwych do przetłumaczenia"
Dostarczona jest jedna funkcja obsługująca tekst, który powinien być przetłumaczony.
.IP "translate($$$)" 4
.IX Item "translate($$$)"
Argumenty obowiązkowe:
.RS 4
.IP "\-" 2
Łańcuch znaków do przetłumaczenia
.IP "\-" 2
Odnośnik tego komunikatu (tj. pozycja w pliku wejściowym)
.IP "\-" 2
Typ tego komunikatu (tj. tekstowy opis jego roli w strukturze; używany w \fBLocale::Po4a::Po::gettextization()\fR; patrz także \fBpo4a\fR\|(7), sekcja \fBProces przekształcania do formatu gettext: jak to działa?\fR)
.RE
.RS 4
.Sp
Funkcja przyjmuje także kilka dodatkowych argumentów. Muszą być zorganizowane jako hash. Na przykład:
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP "\fBwrap\fR" 4
.IX Item "wrap"
flaga logiczna określająca, czy traktujemy białe znaki w komunikacie jako nieistotne. Jeśli tak, to funkcja przed wyszukaniem lub wyciągnięciem tłumaczenia kanonizuje komunikat, a następnie zawija tekst tłumaczenia.
.IP "\fBwrapcol\fR" 4
.IX Item "wrapcol"
kolumna, w której tekst powinien być zawijany (domyślnie: 76).
.IP "\fBcomment\fR" 4
.IX Item "comment"
dodatkowy komentarz do dodania do wpisu.
.RE
.RS 4
.Sp
Akcje:
.IP "\-" 2
Dodaje nowy komunikat, odnośnik i typ do po_out.
.IP "\-" 2
Zwraca tłumaczenie tekstu (znalezione w po_in), tak że parser może zbudować doc_out.
.IP "\-" 2
Obsługuje kodowania znaków, aby zmienić kodowanie komunikatów przed wysłaniem do po_out i przed zwróceniem tłumaczeń.
.RE
.RS 4
.RE
.SS "Różne funkcje"
.IX Subsection "Różne funkcje"
.IP "\fBverbose()\fR" 4
.IX Item "verbose()"
Zwraca informację, czy podczas uruchomienia TransTractora, podano opcję verbose.
.IP "\fBdebug()\fR" 4
.IX Item "debug()"
Zwraca informację, czy podczas uruchomienia TransTractora podano opcję debug.
.IP "detected_charset($)" 4
.IX Item "detected_charset($)"
Mówi TransTractorowi, że w dokumencie źródłowym wykryto nowe kodowanie znaków (podane jako pierwszy argument wywołania). Zwykle kodowanie może być odczytane z nagłówka dokumentu. Pozostawione będzie tylko pierwsze kodowanie znaków, pochodzące albo z argumentów funkcji \fBprocess()\fR, albo z dokumentu.
.IP "\fBget_out_charset()\fR" 4
.IX Item "get_out_charset()"
Funkcja zwraca kodowanie znaków, które powinno być użyte w dokumencie wyjściowym (zazwyczaj użyteczne do zamienienia wykrytego kodowania znaków dokumentu wejściowego, tam gdzie został znaleziony).
.Sp
Użyje wyjściowego kodowania znaków podanego w linii poleceń. Jeśli go nie podano, użyje kodowania znaków wejściowego pliku \s-1PO,\s0 a jeżeli jako to kodowanie w pliku był ustawiony domyślny tekst \*(L"\s-1CHARSET\*(R",\s0 to zwróci kodowanie znaków wejściowego dokumentu, tak że nie zostanie przeprowadzona żadna konwersja kodowań.
.IP "recode_skipped_text($)" 4
.IX Item "recode_skipped_text($)"
Funkcja zwraca tekst przekazany jako argument przekodowany z kodowania znaków dokumentu wejściowego na kodowanie znaków dokumentu wyjściowego. Nie jest to potrzebne podczas tłumaczenia komunikatu (\fBtranslate()\fR wszystko przekodowuje samodzielnie), ale wtedy, gdy pominięto komunikat z dokumentu wejściowego, a dokument wyjściowy powinien mieć spójne kodowanie znaków.
.SH "DALSZE WSKAZÓWKI"
.IX Header "DALSZE WSKAZÓWKI"
Mankamentem obecnego TransTractora jest brak obsługi dokumentów zawierających wszystkie języki naraz, jak na przykład szablony debconf lub pliki .desktop.
.PP
Aby rozwiązać ten problem, jedynymi potrzebnymi zmianami w interfejsie są:
.IP "\-" 2
pobieranie hasha jak po_in_name (lista dla języka)
.IP "\-" 2
dodawanie argumentu do przetłumaczenia, wskazując język docelowy
.IP "\-" 2
make a pushline_all function, which would make pushline of its content for all languages, using a map-like syntax:
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
Zobaczymy, czy to wystarczy ;)
.SH "AUTORZY"
.IX Header "AUTORZY"
.Vb 3
\& Denis Barbier