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/')

 # The following lines have same effect as the above.
 unshift @INC, '/tmp';
 $lines = getlines('');
 shift @INC;

 chdir '/tmp';
 $lines = getlines('')

 $line = getline('/tmp/', 6)
 # Note lines[6] == line (if /tmp/ has 6 lines)

 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 the file cache of $filename. If $filename is not given, clear all files in the 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 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.


 $lines = getline('/tmp/')
 # Same as above
 push @INC, '/tmp';
 $lines = getlines('')


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.



  use Devel::Trepan::DB::LineCache;
  remap_file('another_name', __FILE__);
  print getline('another_name', __LINE__), "\n";


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



When we run -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($filename) => string

Return SHA1 for $filename.


In file /tmp/

  use Devel::Trepan::DB::LineCache;
  printf "SHA1 of %s is:\n%s\n", __FILE__, Devel::Trepan::DB::LineCache::sha1(__FILE__);


  SHA1 of /tmp/ is:


size($filename_or_script) => string

Return the number of lines in $filename_or_script.


In file /tmp/

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


  /tmp/ has 3 lines


stat($filename) => stat-info

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


In file /tmp/

  use Devel::Trepan::DB::LineCache;
  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",


  stat() info for /tmp/ 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. #

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.

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.