=head1 标题

一级标题

=head2 子标题

二级标题

=head3 三级标题

=head4 四级标题

=head1 概述

这是第一段。段落之间用空行分隔。

这是第二段。

=over 4

=item 第一项

描述内容

=item 第二项

描述内容

=back

=cut

=head1 NAME

MyApp::Utils - 应用工具函数集合

=head1 VERSION

版本 1.00

=head1 SYNOPSIS

    use MyApp::Utils qw(trim slug);

    my $text = trim("  hello  ");      # "hello"
    my $slug = slug("Hello World!");   # "hello-world"

=head1 DESCRIPTION

本模块提供常用的工具函数，包括字符串处理、文件操作等。

所有函数默认不导出，需要显式导入：

    use MyApp::Utils qw(:all);

=head1 FUNCTIONS

=head2 trim($string)

去除字符串首尾空白字符。

    my $trimmed = trim("  hello  ");   # "hello"

=head2 slug($string)

将字符串转换为 URL 友好的格式。

    my $s = slug("Hello World!");   # "hello-world"

参数：

=over 4

=item $string - 输入字符串

=back

返回值：转换后的 slug 字符串。

=head1 SEE ALSO

L<Mojolicious>, L<Path::Tiny>

=head1 AUTHOR

Your Name E<lt>you@example.comE<gt>

=head1 LICENSE

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut

# 查看模块文档
perldoc Moose
perldoc DBI

# 查看模块源码
perldoc -m Moose

# 查看模块路径
perldoc -l Moose

# 查看内置函数文档
perldoc -f split
perldoc -f open
perldoc -f map

# 查看特殊变量
perldoc -v '$@'
perldoc -v '$_'

# 查看 Perl FAQ
perldoc -q "How do I read a file"
perldoc -q "regular expression"

# 查看 Perl 文档
perldoc perlintro
perldoc perlre
perldoc perlsyn

# 转换为 HTML
pod2html script.pl > script.html

# 转换为 man 手册
pod2man lib/My/Module.pm > Module.3pm

# 转换为纯文本
pod2text lib/My/Module.pm

# 转换为 Markdown
cpanm Pod::Markdown
pod2markdown lib/My/Module.pm > README.md

# 检查 POD 格式
podchecker lib/My/Module.pm

=head1 示例

=head2 基本使用

    #!/usr/bin/env perl
    use strict;
    use warnings;
    use MyApp::Utils qw(trim);

    my $input = "  Hello, World!  ";
    my $output = trim($input);
    print "结果: '$output'\n";
    # 输出: 结果: 'Hello, World!'

=head2 批量处理

    my @names = ("  Alice  ", " Bob ", "Charlie");
    my @clean = map { trim($_) } @names;
    print join(", ", @clean), "\n";
    # 输出: Alice, Bob, Charlie

=cut

#!/usr/bin/env perl
use strict;
use warnings;
use File::Find;
use Path::Tiny;

my $lib_dir = "lib";

my @modules;
find(sub {
    return unless /\.pm$/;
    my $file = $File::Find::name;

    open my $fh, '<', $file or return;
    my $content = do { local $/; <$fh> };
    close $fh;

    if ($content =~ /^=head1\s+NAME\s*\n(.+?)(?:\n\n|=)/ms) {
        my ($name, $desc) = split /\s*-\s*/, $1, 2;
        push @modules, {
            file => $file,
            name => $name,
            desc => $desc // "",
        };
    }
}, $lib_dir);

# 生成索引
print "# 模块索引\n\n";
printf "| %-30s | %-40s |\n", "模块", "描述";
printf "|%-30s-|%-40s-|\n", "-" x 30, "-" x 40;

for my $mod (sort { $a->{name} cmp $b->{name} } @modules) {
    printf "| %-30s | %-40s |\n", $mod->{name}, $mod->{desc};
}

#!/usr/bin/env perl
# POD 可以放在脚本中任意位置
use strict;
use warnings;

=head1 名称

myapp - 我的应用

=head1 用法

    ./myapp.pl [选项] [文件...]

=head1 描述

这是一个示例应用。

=cut

# 正常代码
sub main {
    print "Hello!\n";
}

=head1 函数

=head2 main()

主函数，程序入口。

=cut

main();

__END__

=head1 作者

Your Name

=head1 版权

Copyright 2026