" 開頭的段落列表。為簡單起見，我們假定文件格式良好，即 "
" 標記是唯一存在的標記，並且該標記位於每個段落的最開始。 .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\-\-; ) { \& # 這不是我們第一次看到
。 \& # 將當前行重新放入輸入， \& # 並將構建的段落輸出 \& $self\->unshiftline($line,$lref); \& \& # 現在文件已形成，請翻譯它： \& # \- 刪除前導標記 \& $paragraph =~ s/^
//s; \& \& # \- 按鍵輸出前導標籤(未翻譯)和 \& # 段落的其餘部分(已翻譯) \& $self\->pushline( "
"
\& . $self\->translate($paragraph,$pararef)
\& );
\&
\& next PARAGRAPH;
\& } else {
\& # 追加到段落後面
\& $paragraph .= $line;
\& $pararef = $lref unless(length($pararef));
\& }
\&
\& # 重新初始化迴圈
\& ($line,$lref)=$self\->shiftline();
\& }
\& # 沒有得到定義的行嗎？輸入檔案的結尾。
\& return;
\& }
\& }
.Ve
.PP
一旦實現瞭解析函式，就可以使用下一節中介紹的公共介面來使用 document 類。
.SH 使用解析器的指令碼的公共介面
.IX Header "使用解析器的指令碼的公共介面"
.SS "構造 函式"
.IX Subsection "構造 函式"
.IP process(%) 4
.IX Item "process(%)"
此函式可以在一次呼叫中完成處理 po4a 文件所需的所有操作。它的引數必須打包為散列。操作：
.RS 4
.IP a. 3
.IX Item "a."
讀取 po_in_name 中指定的所有 PO 檔案
.IP b. 3
.IX Item "b."
讀取在 file_in_name 中指定的所有原始文件
.IP c. 3
.IX Item "c."
解析文件
.IP d. 3
.IX Item "d."
讀取並應用所有指定的附錄
.IP e. 3
.IX Item "e."
將翻譯的文件寫入 file_out_name (如果給定)
.IP f. 3
.IX Item "f."
將提取的 PO 檔案寫入 po_out_name (如果給定)
.RE
.RS 4
.Sp
引數，除了 \fBnew()\fR 接受的引數(具有預期型別)：
.IP "file_in_name (@)" 4
.IX Item "file_in_name (@)"
我們應該在其中讀取輸入文件的檔名列表。
.IP "file_in_charset ($)" 4
.IX Item "file_in_charset ($)"
Charset used in the input document (if it isn't specified, use UTF\-8).
.IP "file_out_name ($)" 4
.IX Item "file_out_name ($)"
我們應該在其中寫入輸出文件的檔名。
.IP "file_out_charset ($)" 4
.IX Item "file_out_charset ($)"
Charset used in the output document (if it isn't specified, use UTF\-8).
.IP "po_in_name (@)" 4
.IX Item "po_in_name (@)"
我們應該從中讀取輸入 PO 檔案的檔名列表，其中包含將用於翻譯文件的翻譯。
.IP "po_out_name ($)" 4
.IX Item "po_out_name ($)"
我們應該在其中寫入輸出 PO 檔案的檔名，其中包含從輸入文件提取的字串。
.IP "addendum (@)" 4
.IX Item "addendum (@)"
我們應該從中讀取附錄的檔名列表。
.IP "addendum_charset ($)" 4
.IX Item "addendum_charset ($)"
附錄的字符集。
.RE
.RS 4
.RE
.IP new(%) 4
.IX Item "new(%)"
建立新的 po4a 文件。接受的選項 (在作為引數傳遞的雜湊中)：
.RS 4
.IP "verbose ($)" 4
.IX Item "verbose ($)"
設定詳細程度。
.IP "debug ($)" 4
.IX Item "debug ($)"
設定除錯。
.IP "wrapcol ($)" 4
.IX Item "wrapcol ($)"
The column at which we should wrap text in output document (default: 76).
.Sp
The negative value means not to wrap lines at all.
.RE
.RS 4
.Sp
Also it accepts next options for underlying Po-files: \fBporefs\fR, \fBcopyright-holder\fR, \fBmsgid-bugs-address\fR, \fBpackage-name\fR, \fBpackage-version\fR, \fBwrap-po\fR.
.RE
.SS 操作文件檔案
.IX Subsection "操作文件檔案"
.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.
.Sp
This function takes two mandatory arguments and an optional one.
* The filename to read on disk;
* The name to use as filename when building the reference in the PO file;
* The charset to use to read that file (UTF\-8 by default)
.Sp
此陣列 \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR 將此輸入文件資料儲存為。
具有交替含義的字串陣列。
*字串 \f(CW$textline\fR 儲存輸入文字資料的每一行。
*字串 \f(CW\*(C`$filename:$linenum\*(C'\fR 儲存其位置並呼叫為。
"reference" (\f(CW\*(C`linenum\*(C'\fR 從 1 開始)。
.Sp
請注意，它不解析任何內容。當您完成將輸入檔案打包到文件中時，應該使用 \fBparse()\fR 函式。
.IP write($) 4
.IX Item "write($)"
將翻譯後的文件寫入給定的檔名。
.Sp
此翻譯文件資料由以下人員提供：
* \f(CW\*(C`$self\->docheader()\*(C'\fR 儲存外掛的標題文字，以及。
* \f(CW\*(C`@{$self\->{TT}{doc_out}}\*(C'\fR 儲存陣列中主翻譯文字的每一行。
.SS "操作 PO 檔案"
.IX Subsection "操作 PO 檔案"
.IP readpo($) 4
.IX Item "readpo($)"
將檔案的內容（該名稱作為引數傳遞）新增到現有輸入 PO。舊內容不會丟棄。
.IP writepo($) 4
.IX Item "writepo($)"
將提取的 PO 檔案寫入給定的檔名。
.IP \fBstats()\fR 4
.IX Item "stats()"
返回到目前為止完成的轉換的一些統計資訊。請注意，它與 msgfmt \-\-statistic 列印的統計資料不同。在這裡，它是關於 PO 檔案最近使用情況的統計資訊，而 msgfmt 則報告該檔案的狀態。它是應用於輸入 PO 檔案的 Locale::Po4a::Po::stats_get 函式的封裝。使用示例：
.Sp
.Vb 1
\& [正常使用 po4a 文件...]
\&
\& ($percent,$hit,$queries) = $document\->stats();
\& print "我們找到了 $percent\e% ($hit from $queries) 字串的翻譯\en";
.Ve
.SS 操作附錄
.IX Subsection "操作附錄"
.IP addendum($) 4
.IX Item "addendum($)"
請參閱 \fBpo4a\fR\|(7)，瞭解有關附錄的詳細資訊，以及翻譯人員應如何編寫附錄。要對翻譯後的文件應用附錄，只需將其檔名傳遞給此函式，即可完成 ;)
.Sp
此函式在出錯時返回非空整數。
.SH 用於編寫派生解析器的內部函式
.IX Header "用於編寫派生解析器的內部函式"
.SS 獲取輸入，提供輸出
.IX Subsection "獲取輸入，提供輸出"
提供了四個函式來獲取輸入和返回輸出。它們與 Perl 的 shift/unshift 和 push/pop 非常相似。
.PP
.Vb 4
\& * Perl shift 返回第一個陣列項並將其從陣列中刪除。
\& * Perl unshift 將項作為第一個陣列項新增到陣列中。
\& * Perl pop 返回最後一個數組項並將其從陣列中刪除。
\& * Perl push 將一項作為最後一個數組項追加到陣列中。
.Ve
.PP
第一對是關於輸入的，第二對是關於輸出的。助記符：在 input 中，您感興趣的是第一行，shift 提供什麼，而在 output 中，您希望將結果新增到末尾，就像 push 一樣。
.IP \fBshiftline()\fR 4
.IX Item "shiftline()"
此函式從陣列 \f(CW\*(C`@{$self\->{TT}{doc_in}}\*(C'\fR 返回要解析的第一行及其對應的引用 (打包為陣列)，並刪除前兩個陣列項。這裡，引用由字串 \f(CW\*(C`$filename:$linenum\*(C'\fR 提供。
.IP unshiftline($$) 4
.IX Item "unshiftline($$)"
取消將輸入文件的最後移位行及其對應的引用移回 \f(CW\*(C`{$self\->{TT}{doc_in}}\*(C'\fR 的頭部。
.IP pushline($) 4
.IX Item "pushline($)"
將新行推到 \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR 的末尾。
.IP \fBpopline()\fR 4
.IX Item "popline()"
從 \f(CW\*(C`{$self\->{TT}{doc_out}}\*(C'\fR 的末尾彈出最後推送的行。
.SS 將字串標記為可翻譯
.IX Subsection "將字串標記為可翻譯"
提供一個函式來處理應該翻譯的文字。
.IP translate($$$) 4
.IX Item "translate($$$)"
必選引數：
.RS 4
.IP \- 2
要翻譯的字串
.IP \- 2
此字串的引用 (即輸入檔案中的位置)
.IP \- 2
此字串的型別(即對其結構角色的文字描述；在 \fBLocale::Po4a::Po::gettextization()\fR 中使用；另請參閱 \fBpo4a\fR\|(7)，\fBGettextization: how does it work?\fR 部分)
.RE
.RS 4
.Sp
此函式還可以接受一些額外的引數。它們必須組織為雜湊。例如：
.Sp
.Vb 2
\& $self\->translate("string","ref","type",
\& \*(Aqwrap\*(Aq => 1);
.Ve
.IP \fBwrap\fR 4
.IX Item "wrap"
指示我們是否可以認為字串中的空格不重要的布林值。如果是，則該函式在查詢或提取翻譯之前對字串進行規範化，並對翻譯進行封裝。
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
the column at which we should wrap (default: the value of \fBwrapcol\fR specified during creation of the TransTractor or 76).
.Sp
The negative value will be substracted from the default.
.IP \fBcomment\fR 4
.IX Item "comment"
要新增到條目的額外註釋。
.RE
.RS 4
.Sp
操作：
.IP \- 2
將字串、引用和型別推送到 po_out。
.IP \- 2
返回字串的翻譯(如 po_in 中所示)，以便解析器可以構建 doc_out。
.IP \- 2
在將字串傳送到 po_out 和返回翻譯之前，處理字符集以重新編碼字串。
.RE
.RS 4
.RE
.SS 其他函式
.IX Subsection "其他函式"
.IP \fBverbose()\fR 4
.IX Item "verbose()"
返回是否在建立翻譯提取器期間傳遞了 verbose 選項。
.IP \fBdebug()\fR 4
.IX Item "debug()"
返回是否在建立翻譯提取器期間傳遞了除錯選項。
.IP \fBget_in_charset()\fR 4
.IX Item "get_in_charset()"
This function return the charset that was provided as master charset
.IP \fBget_out_charset()\fR 4
.IX Item "get_out_charset()"
此函式將返回應該在輸出文件中使用的字符集(通常用於替換已找到的輸入文件的檢測到的字符集)。
.Sp
它將使用命令列中指定的輸出字符集。如果未指定該命令，則將使用輸入 PO 的字元集，如果輸入 PO 具有預設的 "CHARSET"，則返回輸入文件的字符集，以便不會執行編碼。
.SH 未來方向
.IX Header "未來方向"
當前翻譯提取器的一個缺點是它不能處理包含所有語言的翻譯文件，如 debconf 模板或 .desktop 檔案。
.PP
要解決此問題，只需更改介面：
.IP \- 2
將雜湊作為 po_in_name (每種語言的列表)
.IP \- 2
新增要翻譯的引數以指示目標語言
.IP \- 2
使用類似對映的語法建立一個 pushline_all 函式，該函式將為所有語言建立其內容的 pushline：
.Sp
.Vb 3
\& $self\->pushline_all({ "Description[".$langcode."]=".
\& $self\->translate($line,$ref,$langcode)
\& });
.Ve
.PP
看看是否足夠 ;)
.SH 作者
.IX Header "作者"
.Vb 3
\& Denis Barbier