Doc/lib/liblinecache.tex

   1 \section{\module{linecache} ---
   2          Random access to text lines}
   3
   4 \declaremodule{standard}{linecache}
   5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   6 \modulesynopsis{This module provides random access to individual lines
   7                 from text files.}
   8
   9
  10 The \module{linecache} module allows one to get any line from any file,
  11 while attempting to optimize internally, using a cache, the common case
  12 where many lines are read from a single file.  This is used by the
  13 \refmodule{traceback} module to retrieve source lines for inclusion in
  14 the formatted traceback.
  15
  16 The \module{linecache} module defines the following functions:
  17
  18 \begin{funcdesc}{getline}{filename, lineno}
  19 Get line \var{lineno} from file named \var{filename}. This function
  20 will never throw an exception --- it will return \code{''} on errors
  21 (the terminating newline character will be included for lines that are
  22 found).
  23
  24 If a file named \var{filename} is not found, the function will look
  25 for it in the module\indexiii{module}{search}{path} search path,
  26 \code{sys.path}.
  27 \end{funcdesc}
  28
  29 \begin{funcdesc}{clearcache}{}
  30 Clear the cache.  Use this function if you no longer need lines from
  31 files previously read using \function{getline()}.
  32 \end{funcdesc}
  33
  34 \begin{funcdesc}{checkcache}{}
  35 Check the cache for validity.  Use this function if files in the cache
  36 may have changed on disk, and you require the updated version.
  37 \end{funcdesc}
  38
  39 Example:
  40
  41 \begin{verbatim}
  42 >>> import linecache
  43 >>> linecache.getline('/etc/passwd', 4)
  44 'sys:x:3:3:sys:/dev:/bin/sh\n'
  45 \end{verbatim}