2.2. Reader

[<<<] [>>>]

The module reader is implemented in the C source file `reader.c' This is a very simple module it just reads the lines from the source code files and stores the actual text in memory using linked lists. There is not too much possibility to configure this module except that the memory handling functions and the file opening, closing and reading functions are used via function pointers that can be altered by the caller.

These input modules configurable by the embedding application make it possible to read the BASIC source code from database, network or from some other stream not being conventional text file.

Like any other module in ScriptBasic the reader module uses a module object. This is like a class definition except that the interpreter is coded in C and thus there is nothing like VTABLE or inheritance. Otherwise the code is object oriented. Here we list the actual definition of the reader object. Note however that this is actually a copy of the actual definition from the file `reader.c' and it may have been changed since I wrote this manual. So the reader object by the time I wrote this manual (v2.0.0) was:

#define BUFFER_INITIAL_SIZE 1024 //bytes
#define BUFFER_INCREMENT 1024 // number of bytes to increase the buffer size, when it is too small
  char *Buffer;  // buffer to read a line
  long dwBuffer; // size of Buffer in bytes
  long cBuffer;  // the number of character actually in the buffer

pSourceLine Result; // the lines of the file(s) read

// iteration variables pSourceLine CurrentLine; // the current line in the iteration long NextCharacterPosition; // the position of the next character to be returned during iteration char fForceFinalNL; // if this is TRUE then an extra new line is // added to the last line if it was terminated by EOF

pReportFunction report; void *reportptr; // this pointer is passed to the report function. The caller should set it. int iErrorCounter; unsigned long fErrorFlags;

pImportedFileList pImportList;

char *FirstUNIXline; struct _PreprocObject *pPREP; } ReadObject, *pReadObject;

The pointers fpOpenFile, fpGetCharacter and fpCloseFile point to functions that are used to open the input file. The pointer pFileHandleClass set by the higher code using the module reader is passed to these functions without caring its meaning. This is not used by the standard file input/output functions that are used by the command line version of the program, but can be useful for program environment when the source file is stored in some other forms and not in a file. An example of such use can be seen in the function scriba_LoadProgramString implemented in the file `scriba.c'.

The linked list of source lines is stored in the structure named SourceLine The definition of this structure is

typedef struct _SourceLine {
  char *line;
  long lLineNumber;
  long LineLength;
  char *szFileName;
  struct _SourceLine *next;
  } SourceLine, *pSourceLine;

You can see that each source line is pointed by the field line and the length of the line is also stored. The reason for this extra field is that the line itself may contain zero character although this is rare for a program source file to contain zero character inside.

Before the file is read the function reader_InitStructure should be called. This is usual for the ScriptBasic modules. This function initializes the reader object to the usual values that actually ScriptBasic needs.

The reader provides function reader_ReadLines that actually reads the lines and also processes all lines that contain an include or import directive to include a line.

The reader has some extra functions that are specific to ScriptBasic or generally saying are specific to program source reading.

Source programs under UNIX usually start with a line

#! /usr/bin/scriba

that tells the operating system how to start the code.

((((Some very old and totally outdated version of some UNIX systems check the first four characters to look for #! /. There is a space between the ! and the /. So if you want to be look a real code geek put this extra space before the executable path. To be honest I have never encountered this issue since 1987 when I met my first UNIX at TU Delft, Hollandia. OK that's for the story, get back to the reader!))) Always close the parentheses you open!)

The reader recognizes this line if this is the very first line of the program and unlinks it from the list. Instead you can reach this line via the reader object variable FirstUNIXline. This is specific to program source reading and not general file reading. But the reader module is a program source reader or more specific: a BASIC, even ScriptBasic program source reader, though it was coded to be as general as possible.

Another specific issue is the new line at the end of the last line. Lines are usually terminated by new-line. This line terminating character is included in the string at the end of each element of the linked list the reader creates. However when the last line is terminated by the pure EOF some syntax analyzers may fail (ScriptBasic syntax analyzer is also an example, but the reader is kind to care about this). For the reason if the variable fForceFinalNL is set to be TRUE this line gets the extra new-line when read.

[<<<] [>>>]