[Python-checkins] CVS: python/dist/src/Doc/lib libshlex.tex,1.9,1.10

[Eric S. Raymond]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv17271/Doc/lib

Modified Files:
	libshlex.tex 
Log Message:
push_source() and pop_source() entry points for shlex instances.
These basically just make available to the user what userhook()
does to the source stack.  Documentation included.



Index: libshlex.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libshlex.tex,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -r1.9 -r1.10
*** libshlex.tex	2000/07/16 19:01:10	1.9
--- libshlex.tex	2001/01/16 14:18:55	1.10
***************
*** 67,74 ****
  file immediately before it on the source inclusion stack is prepended
  (this behavior is like the way the C preprocessor handles
! \code{\#include "file.h"}).  The result of the manipulations is treated
! as a filename, and returned as the first component of the tuple, with
! \function{open()} called on it to yield the second component.
  
  This hook is exposed so that you can use it to implement directory
  search paths, addition of file extensions, and other namespace hacks.
--- 67,77 ----
  file immediately before it on the source inclusion stack is prepended
  (this behavior is like the way the C preprocessor handles
! \code{\#include "file.h"}).
  
+ The result of the manipulations is treated as a filename, and returned
+ as the first component of the tuple, with
+ \function{open()} called on it to yield the second component. (Note:
+ this is the reverse of the order of arguments in instance initialization!)
+ 
  This hook is exposed so that you can use it to implement directory
  search paths, addition of file extensions, and other namespace hacks.
***************
*** 76,79 ****
--- 79,98 ----
  the \method{close()} method of the sourced input stream when it
  returns \EOF.
+ 
+ For more explicit control of source stacking, use the next two
+ methods. 
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{push_source}{stream\optional{, filename}}
+ Push an input source stream onto the input stack.  If the filename
+ argument is specified it will later be available for use in error
+ messages.  This is the same method used internally by the
+ \method{sourcehook} method. (New in 2.1)
+ \end{methoddesc}
+ 
+ \begin{methoddesc}{pop_source}{}}
+ Pop the last-pushed input source from the input stack.
+ This is the same method used internally when the lexer reaches
+ \EOF on a stacked input stream. (New in 2.1)
  \end{methoddesc}