Writing-Perl-Modules-for-CPAN-Notes

第一章 CPAN

第二章 Perl Module Basics

使用 Exporter 模块主要是方便将模块内容导入当前名称空间, 这样就不需要加上模块名来访问.

第三章 模块设计和 Implementation

Plain Old Documentation

POD 格式的命令一般以 = 开头, 且必须出现在一行的行首.

所有位于 =pod 和 =cut 之间的文本都会被 Perl 视为 POD 文档, 如:

=pod

($low, $high) = estimate($design_time, $loc)

This function computes an estimate for the amount of time required for
a project. It takes two arguments - the amount of time spent on design in
hours and the expected number of lines of code. The return value is a list
of two values, the lower and upper bounds on the time required in hours.

=cut

POD 是一种以段落为主的格式, 段落的开头和结尾处都有一个空行.

写 POD 文档一般包含 5 个部分:

• NAME
• SYNPOSIS
• DESCRIPTION
• AUTHOR
• SEE ALSO

NAME section 的格式一般为 “模块名 + 短横线 + 简短描述”.

SYNPOSIS section 一般给出模块的简单用法.

DESCRIPTION section 包含对模块功能的文字描述.

AUTHOR section 给出 credit 和 contact info.

SEE ALSO 部分包含外部文档的 references.

示例如:

=pod

=head1 NAME

BOA::logger- provides logging for the Big 01' Application

=head1 SYNOPSIS

    my $logger = BOA::Logger->new("log_file"); # get new logger object
    $logger->level(10);                        # set log-levei to 10
    $logger->write(1, "Hello log!");           # write a line at log-level 1

=head1 DESCRIPTION

BOA::logger is an object-oriented class that provides access to a log file
with an associated log-level. Users of the module create a new BOA::logger
object with the new() method. The level() method is used to set the log-level
and the write() method is used to write lines to the log file.

=head1 AUTHOR

Sam Tregar <sam@tregar.com>

=head1 SEE ALSO

l<BOA>

=CUt

=head1 用于声明一级标题 (=head2 用于声明二级标题, 以此类推)

代码一般缩进两格即可.

几个格式化:

• B<bold>
• I<italic>
• C<code-style>
• F<filename>

=over 和 =back 可用于缩进, 默认为 4 个空格. 如:

=over

POD is so great that I need extra room to say it

=back

在 =over 和 =back 之间用 =item 来显示列表, 如:

=head1 My Favorite Things

=over

=item 1

An ancient train stopped in a forest.

=item 2

Victor Hugo

=item 3

Watermelon Sugar

=back

添加其他格式的内容, 用 =begin 和 =end, 如:

=begin html

<table>
  <tr><th>Name</th><th>Nickname</th></tr>
  <tr><td>Sam</td><td>Dave</td></tr>
</table>

=end html

可以将 html 换为其他格式如 man (manpage)

Functions or Objects?

面向对象容易通过继承来扩展. 但 OO modules 往往比 functional module 跟复杂.

函数式接口

常量和包变量用全大写, 子例程一般用全小写, 例程名一般不用缩写.

对于函数的描述文档如:

=over

=item @msgs = check_mail($imap_server, $username, $password)

=item @msgs = check_mail($imap_server, $username, $password, $mailbox)

This routine checks for new mail on a IMAP server. It takes three required arguments - the server address (name or IP), the user name and the password. The fourth, optional, argument is the mailbox name, which will default to "INBOX" if not set. If an error is encountered -1 is returned and an error message is printed to STDERR. If successful, a list of new message IDs is returned that can be used with retrieve_mail(). An empty list indicates no new messages.

=back