Devel::Trepan::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 Devel::Trepan::DB::LineCache; $lines = getlines('/tmp/myperl.pl') # The following lines have same effect as the above. unshift @INC, '/tmp'; $lines = getlines('myperl.pl'); shift @INC; chdir '/tmp'; $lines = getlines('myperl.pl') $line = getline('/tmp/myperl.pl', 6) # Note lines[6] == line (if /tmp/myperl.pl has 6 lines) clear_file_cache 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.
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 = getline('/tmp/myfile.pl') # Same as above push @INC, '/tmp'; $lines = getlines('myfile.pl')
highlight_string($string) => marked-up-string
Add syntax-formatting characters via Syntax::Highlight::Perl::Improved to marked-up-string according to table given in Devel::Trepan::DB::Colors.
path($filename) => string
Return full filename path for $filename.
remap_file($from_file, $to_file) => $to_file
Set to make any lookups retriving lines from of $from_file refer to $to_file.
Example:
Running:
use Devel::Trepan::DB::LineCache; remap_file('another_name', __FILE__); print getline('another_name', __LINE__), "\n";
gives:
print getline('another_name', __LINE__), "\n";
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.
In file /tmp/foo.pl:
/tmp/foo.pl
use Devel::Trepan::DB::LineCache; cache_file(__FILE__); printf "SHA1 of %s is:\n%s\n", __FILE__, Devel::Trepan::DB::LineCache::sha1(__FILE__);
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; cache_file(__FILE__); printf "%s has %d lines\n", __FILE__, Devel::Trepan::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; cache_file(__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__, @{Devel::Trepan::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 line numbers in (control opcodes) COP in $filename. These line numbers are the places where a breakpoint might be set in a debugger.
We get this information from the Perl run-time, so that should have been set up for this to take effect. See B::CodeLines for a way to get this information, basically by running an Perl invocation that has this set up.
is_trace_line($filename, $line_num [,$reload_on_change]) => boolean
Return true if $line_num is a trace line number of $filename.
See the comment in trace_line_numbers regarding run-time setup that needs to take place for this to work.
map_file($filename) => string
A previous invocation of remap_file() could have mapped $filename into something else. If that is the case we return the name that $filename was mapped into. Otherwise we return $filename
map_script($script, $string) => string
Note that a previous invocation of remap_file() could have mapped $script (a pseudo-file name that eval() uses) into something else.
Return the temporary file name that $script was mapped to.
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.
dualvar_lines($file_or_string, $is_file, $mark_trace) => # list of dual-var strings
# Routine to create dual numeric/string values for # $file_or_string. A list reference is returned. In string context # it is the line with a trailing "\n". In a numeric context it is 0 or # 1 if $mark_trace is set and B::CodeLines determines it is a trace # line. # # Note: Perl implementations seem to put a COP address inside # @DB::db_line when there are trace lines. I am not sure if this is # specified as part of the API. We don't do that here but (and might # even if it is not officially defined in the API.) Instead put value # 1. #
$file_or_string
load_file($filename) => list of strings
Somewhat simulates what Perl does in reading a file when debugging is turned on. We return the file contents as a list of strings in _>$filename. But also entry is a dual variable. In numeric context, each entry of the list is true if that line is traceable or break-pointable (is the address of a COP instruction). In a non-numeric context, each entry is a string of the line contents including the trailing \n.
\n
Note: something similar exists in Enbugger and it is useful when a debugger is called via Enbugger which turn on debugging late so source files might not have been read in.
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 the expanded file name 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.