DB::LineCache - package to read and cache lines of a Perl program.
The LineCache package allows one to get any line from any file, caching lines of the file on first access to the file. Although the file may be any file, the common use is when the file is a Perl script since parsing of the file is done to figure out where the statement boundaries are.
The routines here may be is useful when a small random sets of lines are read from a single file, in particular in a debugger to show source lines.
use DB::LineCache; $lines = DB::LineCache::getlines('/tmp/myperl.pl') # The following lines have same effect as the above. unshift @INC, '/tmp'; Dir.chdir('/tmp') {$lines = DB::LineCache::getlines('myperl.pl') $line = DB::LineCache::getline('/tmp/myperl.pl', 6) # Note lines[6] == line (if /tmp/myperl.pl has 6 lines) DB::LineCache::clear_file_cache DB::LineCache::update_cache # Check for modifications of all cached files.
Note: in what follows we use $file_or_script to refer to either a filename which generally should be a Perl file, or a psuedo-file name that is created in an eval() string. Often, the filename does not have to be fully qualified. In some cases @INC will be used to find the file.
clear_file_cache()
clear_file_cache($filename)
Clear the file cache of $filename. If $filename is not given, clear all files in the cache.
clear_file_format_cache()
Remove syntax-formatted lines in the cache. Use this when you change the Syntax::Highlight::Perl colors and want to redo how files may have previously been syntax marked.
clear_script_cache()
Clear the script cache entirely.
cached_files() => list of files
Return an array of cached file names
checkcache() => list-of-filenames
checkcache($filename [, $opts]) => list-of-filenames
Discard cache entries that are out of date. If $filenameis undef, all entries in the file cache are checked.
If we did not previously have stat() information about a file, it will be added. Return a list of invalidated filenames. undef is returned if a filename was given but not found cached.
cache_script($script [, $opts]) => script
Cache psuedo eval-string for a pseudo eval-string if it's not already cached.
cache($file_or_script [, $reload_on_change]) => filename
Cache file name or script object if it's not already cached.
Return the expanded filename for it in the cache if a filename, or the script, or undef if we can't find the file.
undef
cache($file_or_script [, $reload_on_change, $opts]) => filename
Cache $filename_or_script if it's not already cached.
Return the expanded filename for $file_or_script if it is in the cache or undef if we can't find it.
cache($file_or_script) => boolean
Return true if $file_or_script is cached.
getline($file_or_script, $line_number [, $opts]) => string
Get line $line_number from $file_script. Return undef if there was a problem. If a file named $file_or_script is not found, the function will look for it in the @INC array.
getlines($filename, [$opts]) => string
Read lines of $filename and cache the results. However if $filename was previously cached use the results from the cache. Return undef if we can't get lines.
Examples:
$lines = LineCache::getline('/tmp/myfile.pl') # Same as above push @INC, '/tmp'; $lines = LineCache.getlines('myfile.pl')
highlight_string($string) => marked-up-string
Add syntax-formatting characters via Syntax::Highlight::Pel::Improved to string according to table given in Devel::Trepan::DB::Colors.
path($filename) => string
Return full filename path for $filename.
remap_dbline_to_file()
When we run trepan.pl -e ... or perl -d:Trepan -e ... we have data in internal an "line" array @DB::dbline but no external file. Here, we will create a temporary file and store the data in that.
trepan.pl -e
perl -d:Trepan -e ...
sha1($filename) => string
Return SHA1 for $filename.
Example:
In file "/tmp/foo.pl":
use Devel::Trepan::DB::LineCache; DB::LineCache::cache(__FILE__); printf "SHA1 of %s is:\n%s\n", __FILE__, DB::LineCache::sha1(__FILE__);
gives:
SHA1 of /tmp/foo.pl is: 719b1aa8d559e64bd0de70b325beff79beac32f5
size($filename_or_script) => string
Return the number of lines in $filename_or_script.
use Devel::Trepan::DB::LineCache; DB::LineCache::cache(__FILE__); printf "%s has %d lines\n", __FILE__, DB::LineCache::size(__FILE__);
/tmp/foo.pl has 3 lines
stat($filename) => stat-info
Return file stat() info in the cache for $filename.
use Devel::Trepan::DB::LineCache; DB::LineCache::cache(__FILE__); printf("stat() info for %s is: dev ino mode nlink uid gid rdev size atime ctime ... %4d %8d %7o %3d %4d %4d %4d %4d %d %d", __FILE__, @{DB::LineCache::stat(__FILE__)});
stat() info for /tmp/foo.pl is: dev ino mode nlink uid gid rdev size atime ctime ... 2056 5242974 100664 1 1000 1000 0 266 1347890102 1347890101
trace_line_numbers($filename [, $reload_on_change]) => list-of-numbers
Return an array of breakpoints in $filename.
is_trace_line($filename, $line_num [,$reload_on_change]) => boolean
Return true if $line_num is a trace line number of $filename.
filename_is_eval($filename) => boolean
Return true if $filename matches one of the pseudo-filename strings that get created for by eval().
update_script_cache($script, $opts) => boolean
Update a cache entry for an pseudo eval-string file name. If something is wrong, return undef. Return true if the cache was updated and false if not.
readlines($filename) => list of strings
Return a a list of strings for $filename. If we can't read $filename retun undef. Each line will have a "\n" at the end.
update_cache($filename, [, $opts]
Update a cache entry. If something's wrong, return undef. Return true if the cache was updated and false if not. If $$opts->{use_perl_d_file} is true, use that as the source for the lines of the file.
To install Devel::Trepan, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Devel::Trepan
CPAN shell
perl -MCPAN -e shell install Devel::Trepan
For more information on module installation, please visit the detailed CPAN module installation guide.