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.

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.

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

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

Module Install Instructions

To install DB::LineCache, simply copy and paste either of the commands in to your terminal