view release on metacpan or  search on metacpan

lib/file.pm  view on Meta::CPAN

    file::extname('/path/to/file.txt')  # returns '.txt'

=head2 join

    my $path = file::join(@parts);

Join path components with the appropriate separator.

    file::join('path', 'to', 'file')  # returns 'path/to/file'

=head2 head

    my $lines = file::head($path);
    my $lines = file::head($path, $n);

Returns arrayref of first N lines (default 10).

=head2 tail

    my $lines = file::tail($path);
    my $lines = file::tail($path, $n);

Returns arrayref of last N lines (default 10).

=head1 CUSTOM OP IMPORT

For maximum performance, you can import function-style accessors that
use custom ops instead of method calls:

    use file qw(import);

    my $content = file_slurp($path);     # custom op, fastest
    file_spew($path, $data);
    my $exists = file_exists($path);
    my $size = file_size($path);
    my $is_file = file_is_file($path);
    my $is_dir = file_is_dir($path);
    my $lines = file_lines($path);
    file_unlink($path);
    file_mkdir($path);
    file_rmdir($path);
    file_touch($path);
    my $base = file_basename($path);
    my $dir = file_dirname($path);
    my $ext = file_extname($path);

Custom ops provide 2-6% additional speed over method calls.

=head1 LINE PROCESSING

Advanced line processing functions for filtering and transforming file content.

=head2 count_lines

    my $count = file::count_lines($path);
    my $count = file::count_lines($path, $predicate);

Count lines in a file. With a predicate, counts only matching lines.

    my $total = file::count_lines($path);
    my $non_blank = file::count_lines($path, 'is_not_blank');
    my $long = file::count_lines($path, sub { length(shift) > 80 });

=head2 find_line

    my $line = file::find_line($path, $predicate);

Find and return the first line matching a predicate. Returns undef if
no match found.

    my $comment = file::find_line($path, 'is_comment');
    my $error = file::find_line($path, sub { /ERROR/ });

=head2 grep_lines

    my $lines = file::grep_lines($path, $predicate);

Filter lines matching a predicate. Returns arrayref.

    my $comments = file::grep_lines($path, 'is_comment');
    my $non_blank = file::grep_lines($path, 'is_not_blank');
    my $errors = file::grep_lines($path, sub { /ERROR|WARN/ });

=head2 map_lines

    my $result = file::map_lines($path, $transform);

Transform each line. Returns arrayref of transformed values.

    my $upper = file::map_lines($path, sub { uc(shift) });
    my $lengths = file::map_lines($path, sub { length($_) });

=head1 LINE CALLBACKS

Register custom predicates for use with grep_lines, count_lines, etc.

=head2 register_line_callback

    file::register_line_callback($name, $coderef);

Register a named predicate for line filtering.

    file::register_line_callback('is_todo', sub { /TODO|FIXME/ });

    # Now use it:
    my $todos = file::grep_lines($path, 'is_todo');

=head2 list_line_callbacks

    my $names = file::list_line_callbacks();

Returns arrayref of all registered callback names.

Built-in predicates: C<is_blank>, C<is_not_blank>, C<blank>, C<not_blank>,
C<is_empty>, C<is_not_empty>, C<is_comment>, C<is_not_comment>.

=head1 AUTHOR

LNATION

=head1 LICENSE

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

=cut