NAME
file - Fast IO operations using direct system calls
SYNOPSIS
use file;
# Slurp entire file
my $content = file::slurp('/path/to/file');
# Write to file
file::spew('/path/to/file', $content);
# Append to file
file::append('/path/to/file', "more data\n");
# Get all lines as array
my $lines = file::lines('/path/to/file');
# Process lines efficiently with callback
file::each_line('/path/to/file', sub {
my $line = shift;
print "Line: $line\n";
});
# Memory-mapped file access
my $mmap = file::mmap_open('/path/to/file');
my $data = $mmap->data; # Zero-copy access
$mmap->close;
# Line iterator (memory efficient)
my $iter = file::lines_iter('/path/to/file');
while (!$iter->eof) {
my $line = $iter->next;
# process line
}
$iter->close;
# File stat operations
my $size = file::size('/path/to/file');
my $mtime = file::mtime('/path/to/file');
my $exists = file::exists('/path/to/file');
# Type checks
file::is_file('/path/to/file');
file::is_dir('/path/to/dir');
file::is_readable('/path/to/file');
file::is_writable('/path/to/file');DESCRIPTION
Fast IO operations using direct system calls, bypassing PerlIO overhead. This module provides significantly faster file operations compared to Perl's built-in IO functions.
Performance
The module uses:
Direct read(2)/write(2) syscalls
Pre-allocated buffers based on file size
Memory-mapped file access for zero-copy reads
Efficient line iteration without loading entire file
FUNCTIONS
slurp
my $content = file::slurp($path);Read entire file into a scalar. Returns undef on error. Pre-allocates the buffer based on file size for optimal performance.
slurp_raw
my $content = file::slurp_raw($path);Same as slurp, explicit binary mode.
spew
my $ok = file::spew($path, $data);Write data to file (creates or truncates). Returns true on success.
append
my $ok = file::append($path, $data);Append data to file. Returns true on success.
lines
my $lines = file::lines($path);Returns arrayref of all lines (without newlines).
each_line
file::each_line($path, sub {
my $line = shift;
# process line
});Process each line with a callback. Memory efficient - doesn't load entire file into memory.
lines_iter
my $iter = file::lines_iter($path);
while (!$iter->eof) {
my $line = $iter->next;
}
$iter->close;Returns a line iterator object for memory-efficient line processing.
mmap_open
my $mmap = file::mmap_open($path);
my $mmap = file::mmap_open($path, 1); # writableMemory-map a file. Returns a file::mmap object.
file::mmap methods
- data() - Returns the mapped content as a scalar (zero-copy)
- sync() - Flush changes to disk (for writable maps)
- close() - Unmap the file
size
my $bytes = file::size($path);Returns file size in bytes, or -1 on error.
mtime
my $epoch = file::mtime($path);Returns modification time as epoch seconds, or -1 on error.
exists
if (file::exists($path)) { ... }Returns true if path exists.
is_file
if (file::is_file($path)) { ... }Returns true if path is a regular file.
is_dir
if (file::is_dir($path)) { ... }Returns true if path is a directory.
is_readable
if (file::is_readable($path)) { ... }Returns true if path is readable.
is_writable
if (file::is_writable($path)) { ... }Returns true if path is writable.
is_executable
if (file::is_executable($path)) { ... }Returns true if path is executable.
is_link
if (file::is_link($path)) { ... }Returns true if path is a symbolic link.
atime
my $epoch = file::atime($path);Returns access time as epoch seconds, or -1 on error.
ctime
my $epoch = file::ctime($path);Returns change time as epoch seconds, or -1 on error.
mode
my $mode = file::mode($path);Returns file permission mode (e.g., 0644), or -1 on error.
unlink
my $ok = file::unlink($path);Delete a file. Returns true on success.
copy
my $ok = file::copy($src, $dst);Copy a file. Returns true on success. Preserves file permissions.
move
my $ok = file::move($src, $dst);Move/rename a file. Returns true on success. Works across filesystems.
touch
my $ok = file::touch($path);Create file or update modification time. Returns true on success.
chmod
my $ok = file::chmod($path, $mode);Change file permissions. Returns true on success.
file::chmod('/path/to/file', 0755);mkdir
my $ok = file::mkdir($path);
my $ok = file::mkdir($path, $mode);Create a directory. Default mode is 0755. Returns true on success.
rmdir
my $ok = file::rmdir($path);Remove an empty directory. Returns true on success.
readdir
my $entries = file::readdir($path);Returns arrayref of directory entries (excluding . and ..).
atomic_spew
my $ok = file::atomic_spew($path, $data);Write data atomically using a temp file + rename. Returns true on success. This is safe against partial writes and power failures.
basename
my $name = file::basename($path);Returns the filename portion of a path.
file::basename('/path/to/file.txt') # returns 'file.txt'dirname
my $dir = file::dirname($path);Returns the directory portion of a path.
file::dirname('/path/to/file.txt') # returns '/path/to'extname
my $ext = file::extname($path);Returns the file extension including the dot.
file::extname('/path/to/file.txt') # returns '.txt'join
my $path = file::join(@parts);Join path components with the appropriate separator.
file::join('path', 'to', 'file') # returns 'path/to/file'head
my $lines = file::head($path);
my $lines = file::head($path, $n);Returns arrayref of first N lines (default 10).
tail
my $lines = file::tail($path);
my $lines = file::tail($path, $n);Returns arrayref of last N lines (default 10).
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.
LINE PROCESSING
Advanced line processing functions for filtering and transforming file content.
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 });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/ });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/ });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($_) });LINE CALLBACKS
Register custom predicates for use with grep_lines, count_lines, etc.
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');list_line_callbacks
my $names = file::list_line_callbacks();Returns arrayref of all registered callback names.
Built-in predicates: is_blank, is_not_blank, blank, not_blank, is_empty, is_not_empty, is_comment, is_not_comment.
AUTHOR
LNATION
LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.