| Current Path : /proc/thread-self/root/usr/include/gap/ |
Linux ift1.ift-informatik.de 5.4.0-216-generic #236-Ubuntu SMP Fri Apr 11 19:53:21 UTC 2025 x86_64 |
| Current File : //proc/thread-self/root/usr/include/gap/io.h |
/****************************************************************************
**
*W io.h
**
**
** This file declares functions responsible for input and output processing.
**
** These provide the concept of a current input and output file. In the
** main module they are opened and closed with the 'OpenInput' and
** 'CloseInput' respectively 'OpenOutput' and 'CloseOutput' calls. All the
** other modules just read from the current input and write to the current
** output file.
**
** This module relies on the functions provided by the operating system
** dependent module 'system.c' for the low level input/output.
*/
#ifndef GAP_IO_H
#define GAP_IO_H
#include "system.h"
extern Char GET_NEXT_CHAR(void);
extern Char PEEK_NEXT_CHAR(void);
extern Char PEEK_CURR_CHAR(void);
// skip the rest of the current line, ignoring line continuations
// (used to handle comments)
extern void SKIP_TO_END_OF_LINE(void);
/****************************************************************************
**
*F * * * * * * * * * * * open input/output functions * * * * * * * * * * * *
*/
/****************************************************************************
**
*F OpenInput( <filename> ) . . . . . . . . . . open a file as current input
**
** 'OpenInput' opens the file with the name <filename> as current input.
** All subsequent input will be taken from that file, until it is closed
** again with 'CloseInput' or another file is opened with 'OpenInput'.
** 'OpenInput' will not close the current file, i.e., if <filename> is
** closed again, input will again be taken from the current input file.
**
** 'OpenInput' returns 1 if it could successfully open <filename> for
** reading and 0 to indicate failure. 'OpenInput' will fail if the file
** does not exist or if you do not have permissions to read it. 'OpenInput'
** may also fail if you have too many files open at once. It is system
** dependent how many are too many, but 16 files should work everywhere.
**
** Directely after the 'OpenInput' call the variable 'Symbol' has the value
** 'S_ILLEGAL' to indicate that no symbol has yet been read from this file.
** The first symbol is read by 'Read' in the first call to 'Match' call.
**
** You can open '*stdin*' to read from the standard input file, which is
** usually the terminal, or '*errin*' to read from the standard error file,
** which is the terminal even if '*stdin*' is redirected from a file.
** 'OpenInput' passes those file names to 'SyFopen' like any other name,
** they are just a convention between the main and the system package.
** 'SyFopen' and thus 'OpenInput' will fail to open '*errin*' if the file
** 'stderr' (Unix file descriptor 2) is not a terminal, because of a
** redirection say, to avoid that break loops take their input from a file.
**
** It is not neccessary to open the initial input file, 'InitScanner' opens
** '*stdin*' for that purpose. This file on the other hand cannot be
** closed by 'CloseInput'.
*/
extern UInt OpenInput (
const Char * filename );
/****************************************************************************
**
*F OpenInputStream( <stream>, <echo> ) . . . open a stream as current input
**
** The same as 'OpenInput' but for streams.
*/
extern UInt OpenInputStream(Obj stream, UInt echo);
/****************************************************************************
**
*F CloseInput() . . . . . . . . . . . . . . . . . close current input file
**
** 'CloseInput' will close the current input file. Subsequent input will
** again be taken from the previous input file. 'CloseInput' will return 1
** to indicate success.
**
** 'CloseInput' will not close the initial input file '*stdin*', and returns
** 0 if such an attempt is made. This is used in 'Error' which calls
** 'CloseInput' until it returns 0, therebye closing all open input files.
**
** Calling 'CloseInput' if the corresponding 'OpenInput' call failed will
** close the current output file, which will lead to very strange behaviour.
*/
extern UInt CloseInput ( void );
/****************************************************************************
**
*F OpenLog( <filename> ) . . . . . . . . . . . . . log interaction to a file
**
** 'OpenLog' instructs the scanner to echo all input from the files
** '*stdin*' and '*errin*' and all output to the files '*stdout*' and
** '*errout*' to the file with name <filename>. The file is truncated to
** size 0 if it existed, otherwise it is created.
**
** 'OpenLog' returns 1 if it could successfully open <filename> for writing
** and 0 to indicate failure. 'OpenLog' will fail if you do not have
** permissions to create the file or write to it. 'OpenOutput' may also
** fail if you have too many files open at once. It is system dependent how
** many are too many, but 16 files should work everywhere. Finally
** 'OpenLog' will fail if there is already a current logfile.
*/
extern UInt OpenLog (
const Char * filename );
/****************************************************************************
**
*F OpenLogStream( <stream> ) . . . . . . . . . . log interaction to a stream
**
** The same as 'OpenLog' but for streams.
*/
extern UInt OpenLogStream (
Obj stream );
/****************************************************************************
**
*F CloseLog() . . . . . . . . . . . . . . . . . . close the current logfile
**
** 'CloseLog' closes the current logfile again, so that input from '*stdin*'
** and '*errin*' and output to '*stdout*' and '*errout*' will no longer be
** echoed to a file. 'CloseLog' will return 1 to indicate success.
**
** 'CloseLog' will fail if there is no logfile active and will return 0 in
** this case.
*/
extern UInt CloseLog ( void );
/****************************************************************************
**
*F OpenInputLog( <filename> ) . . . . . . . . . . . . . log input to a file
**
** 'OpenInputLog' instructs the scanner to echo all input from the files
** '*stdin*' and '*errin*' to the file with name <filename>. The file is
** truncated to size 0 if it existed, otherwise it is created.
**
** 'OpenInputLog' returns 1 if it could successfully open <filename> for
** writing and 0 to indicate failure. 'OpenInputLog' will fail if you do
** not have permissions to create the file or write to it. 'OpenInputLog'
** may also fail if you have too many files open at once. It is system
** dependent how many are too many, but 16 files should work everywhere.
** Finally 'OpenInputLog' will fail if there is already a current logfile.
*/
extern UInt OpenInputLog (
const Char * filename );
/****************************************************************************
**
*F OpenInputLogStream( <stream> ) . . . . . . . . . . log input to a stream
**
** The same as 'OpenInputLog' but for streams.
*/
extern UInt OpenInputLogStream (
Obj stream );
/****************************************************************************
**
*F CloseInputLog() . . . . . . . . . . . . . . . . close the current logfile
**
** 'CloseInputLog' closes the current logfile again, so that input from
** '*stdin*' and '*errin*' will no longer be echoed to a file.
** 'CloseInputLog' will return 1 to indicate success.
**
** 'CloseInputLog' will fail if there is no logfile active and will return 0
** in this case.
*/
extern UInt CloseInputLog ( void );
/****************************************************************************
**
*V Prompt . . . . . . . . . . . . . . . . . . . . . . prompt to be printed
**
** 'Prompt' holds the string that is to be printed if a new line is read
** from the interactive files '*stdin*' or '*errin*'.
**
** It is set to 'gap> ' or 'brk> ' in the read-eval-print loops and changed
** to the partial prompt '> ' in 'Read' after the first symbol is read.
*/
/* TL: extern const Char * Prompt; */
/****************************************************************************
**
*V PrintPromptHook . . . . . . . . . . . . . . function for printing prompt
*V EndLineHook . . . . . . . . . . . function called at end of command line
**
** These functions can be set on GAP-level. If they are not bound the
** default is: Instead of 'PrintPromptHook' the 'Prompt' is printed and
** instead of 'EndLineHook' nothing is done.
*/
/* TL: extern Obj PrintPromptHook; */
extern Obj EndLineHook;
/****************************************************************************
**
*F OpenOutputLog( <filename> ) . . . . . . . . . . . log output to a file
**
** 'OpenInputLog' instructs the scanner to echo all output to the files
** '*stdout*' and '*errout*' to the file with name <filename>. The file is
** truncated to size 0 if it existed, otherwise it is created.
**
** 'OpenOutputLog' returns 1 if it could successfully open <filename> for
** writing and 0 to indicate failure. 'OpenOutputLog' will fail if you do
** not have permissions to create the file or write to it. 'OpenOutputLog'
** may also fail if you have too many files open at once. It is system
** dependent how many are too many, but 16 files should work everywhere.
** Finally 'OpenOutputLog' will fail if there is already a current logfile.
*/
extern UInt OpenOutputLog (
const Char * filename );
/****************************************************************************
**
*F OpenOutputLogStream( <stream> ) . . . . . . . . log output to a stream
**
** The same as 'OpenOutputLog' but for streams.
*/
extern UInt OpenOutputLogStream (
Obj stream );
/****************************************************************************
**
*F CloseOutputLog() . . . . . . . . . . . . . . . close the current logfile
**
** 'CloseInputLog' closes the current logfile again, so that output to
** '*stdout*' and '*errout*' will no longer be echoed to a file.
** 'CloseOutputLog' will return 1 to indicate success.
**
** 'CloseOutputLog' will fail if there is no logfile active and will return
** 0 in this case.
*/
extern UInt CloseOutputLog ( void );
/****************************************************************************
**
*F OpenOutput( <filename> ) . . . . . . . . . open a file as current output
**
** 'OpenOutput' opens the file with the name <filename> as current output.
** All subsequent output will go to that file, until either it is closed
** again with 'CloseOutput' or another file is opened with 'OpenOutput'.
** The file is truncated to size 0 if it existed, otherwise it is created.
** 'OpenOutput' does not close the current file, i.e., if <filename> is
** closed again, output will go again to the current output file.
**
** 'OpenOutput' returns 1 if it could successfully open <filename> for
** writing and 0 to indicate failure. 'OpenOutput' will fail if you do not
** have permissions to create the file or write to it. 'OpenOutput' may
** also fail if you have too many files open at once. It is system
** dependent how many are too many, but 16 files should work everywhere.
**
** You can open '*stdout*' to write to the standard output file, which is
** usually the terminal, or '*errout*' to write to the standard error file,
** which is the terminal even if '*stdout*' is redirected to a file.
** 'OpenOutput' passes those file names to 'SyFopen' like any other name,
** they are just a convention between the main and the system package.
**
** The function does nothing and returns success for '*stdout*' and
** '*errout*' when 'LockCurrentOutput(1)' is in effect (used for testing
** purposes).
**
** It is not neccessary to open the initial output file, 'InitScanner' opens
** '*stdout*' for that purpose. This file on the other hand can not be
** closed by 'CloseOutput'.
*/
extern UInt OpenOutput (
const Char * filename );
/****************************************************************************
**
*F OpenOutputStream( <stream> ) . . . . . . open a stream as current output
**
** The same as 'OpenOutput' (and also 'OpenAppend') but for streams.
*/
extern UInt OpenOutputStream (
Obj stream );
/****************************************************************************
**
*F CloseOutput() . . . . . . . . . . . . . . . . . close current output file
**
** 'CloseOutput' will first flush all pending output and then close the
** current output file. Subsequent output will again go to the previous
** output file. 'CloseOutput' returns 1 to indicate success.
**
** 'CloseOutput' will not close the initial output file '*stdout*', and
** returns 0 if such attempt is made. This is used in 'Error' which calls
** 'CloseOutput' until it returns 0, thereby closing all open output files.
**
** Calling 'CloseOutput' if the corresponding 'OpenOutput' call failed will
** close the current output file, which will lead to very strange behaviour.
** On the other hand if you forget to call 'CloseOutput' at the end of a
** 'PrintTo' call or an error will not yield much better results.
*/
extern UInt CloseOutput ( void );
/****************************************************************************
**
*F OpenAppend( <filename> ) . . open a file as current output for appending
**
** 'OpenAppend' opens the file with the name <filename> as current output.
** All subsequent output will go to that file, until either it is closed
** again with 'CloseOutput' or another file is opened with 'OpenOutput'.
** Unlike 'OpenOutput' 'OpenAppend' does not truncate the file to size 0 if
** it exists. Appart from that 'OpenAppend' is equal to 'OpenOutput' so its
** description applies to 'OpenAppend' too.
*/
extern UInt OpenAppend (
const Char * filename );
/****************************************************************************
**
*V In . . . . . . . . . . . . . . . . . pointer to current character, local
**
** 'In' is a pointer to the current input character, i.e., '*In' is the
** current input character. It points into the buffer 'Input->line'.
*/
/* TL: extern Char * In; */
// get the filename of the current input
extern const Char * GetInputFilename(void);
// get the number of the current line in the current thread's input
extern Int GetInputLineNumber(void);
//
extern const Char * GetInputLineBuffer(void);
//
extern Int GetInputLinePosition(void);
// get the filenameid (if any) of the current input
extern UInt GetInputFilenameID(void);
// get the filename (as GAP string object) with the given id
extern Obj GetCachedFilename(UInt id);
/* the widest allowed screen width */
#define MAXLENOUTPUTLINE 4096
// Reset the indentation level of the current output to zero. The indentation
// level can be modified via the '%>' and '%<' formats of 'Pr' resp. 'PrTo'.
extern void ResetOutputIndent(void);
// If 'lock' is non-zero, then "lock" the current output, i.e., prevent calls
// to 'OpenOutput' or 'CloseOutput' from changing it. If 'lock' is zero, then
// release this lock again.
//
// This is used to allow the 'Test' function of the GAP library to
// consistently capture all output during testing, see 'FuncREAD_STREAM_LOOP'.
extern void LockCurrentOutput(Int lock);
/****************************************************************************
**
*F Pr( <format>, <arg1>, <arg2> ) . . . . . . . . . print formatted output
**
** 'Pr' is the output function. The first argument is a 'printf' like format
** string containing up to 2 '%' format fields, specifing how the
** corresponding arguments are to be printed. The two arguments are passed
** as 'long' integers. This is possible since every C object ('int',
** 'char', pointers) except 'float' or 'double', which are not used in GAP,
** can be converted to a 'long' without loss of information.
**
** The function 'Pr' currently support the following '%' format fields:
** '%c' the corresponding argument represents a character, usually it is
** its ASCII or EBCDIC code, and this character is printed.
** '%s' the corresponding argument is the address of a null terminated
** character string which is printed.
** '%d' the corresponding argument is a signed integer, which is printed.
** Between the '%' and the 'd' an integer might be used to specify
** the width of a field in which the integer is right justified. If
** the first character is '0' 'Pr' pads with '0' instead of <space>.
** '%>' increment the indentation level.
** '%<' decrement the indentation level.
** '%%' can be used to print a single '%' character. No argument is used.
**
** You must always cast the arguments to '(long)' to avoid problems with
** those compilers with a default integer size of 16 instead of 32 bit. You
** must pass 0L if you don't make use of an argument to please lint.
*/
extern void Pr (
const Char * format,
Int arg1,
Int arg2 );
extern void SPrTo (
Char * buffer,
UInt maxlen,
const Char * format,
Int arg1,
Int arg2 );
/****************************************************************************
**
*F FlushRestOfInputLine() . . . . . . . . . . . . discard remainder of line
*/
extern void FlushRestOfInputLine( void );
StructInitInfo * InitInfoIO(void);
#endif // GAP_IO_H