/ 
Devel-Trepan-0.46
River stage one • 2 direct dependents • 2 total dependents
/ DB::LineCache

NAME DB::LineCache

DB::LineCache - package to read and cache lines of a Perl program.

SYNOPSIS

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';
$lines = DB::LineCache::getlines('myperl.pl');
shift @INC;

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.

SUBROUTINES

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()

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

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_script_cache()

Clear the script cache entirely.

cached_files

cached_files() => list of files

Return an array of cached file names

checkcache

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

cache_script($script [, $opts]) => script

Cache psuedo eval-string for a pseudo eval-string if it's not already cached.

cache

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

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.

is_cached

cache($file_or_script) => boolean

Return true if $file_or_script is cached.

getline

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

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

highlight_string($string) => marked-up-string

Add syntax-formatting characters via Syntax::Highlight::Pel::Improved to marked-up-string according to table given in Devel::Trepan::DB::Colors.

path

path($filename) => string

Return full filename path for $filename.

remap_file

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;
DB::LineCache::remap_file('another_name', __FILE__);
print DB::LineCache::getline('another_name', __LINE__), "\n";

gives:

print DB::LineCache::getline('another_name', __LINE__), "\n";

remap_dbline_to_file

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.

sha1

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

size($filename_or_script) => string

Return the number of lines in $filename_or_script.

Example:

In file /tmp/foo.pl:

use Devel::Trepan::DB::LineCache;
DB::LineCache::cache(__FILE__);
printf "%s has %d lines\n", __FILE__,  DB::LineCache::size(__FILE__);

gives:

/tmp/foo.pl has 3 lines

stat

stat($filename) => stat-info

Return file stat() info in the cache for $filename.

Example:

In file /tmp/foo.pl:

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__)});

gives:

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

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

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

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

map_script($script) => string

A previous invocation of remap_file() could have mapped $script (a pseudo-file name that eval() uses) into something else. If that is the case we return the name that $script was mapped into. Otherwise we return $script

filename_is_eval

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

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. #

load_file($filename) => list of strings

Somewhat simulates what Perl does in reading a file when debugging is turned on. We 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.

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

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

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.