GS9 Programming Language

FILE LIBRARY
A Programming Language Manual

gs_fileopen

( lib: File, file: gslib_file.cpp )

ptr gs_fileopen( filename, mode )

IN
str	filename	path to the file to be opened
int	mode	open mode 0=read, 1=write, 2=both
OUT
ptr	file handler

Opens the file with the path and name specified by the filename parameter.
If mode is 0 then the file will be opened only for read. File must exist.
If mode is 1 then the file will be opened only for write. If not found, the file is created, otherwise it's content will cleared.
If mode is 2 then the file will be opened for both read and write. If not found, the file is created. Useful for appending new data.
If the open is successful, the file handler is returned. If not, it will return an invalid ptr (NULL).
The directories from the specified file path must always exist.
Remember that to specify the backslash in file paths, you must use a double backslash (like "c:\\myfile.txt")
The file cursor is the current position inside the file (in bytes), where the next read or write will take place.
When a file is opened, it's file cursor is set from the beginning of the file (0).
Always remeber to finaly close opened files, with gs_fileclose.

// will load and print the program file
func main()
{
	f = gs_fileopen("program.txt",0);        // open for read the program file
	if(f)                                    // if opened successfuly
	{
		gs_fileseek(f,0,2);                  // move read cursor to the end of the file to get the file size
		size = gs_filetell(f);               // the cursor position is now the file size
		gs_fileseek(f,0,0);                  // seek back at the begining
		buffer = str(size+1);                // create a string big enought to keep the whole file's content
		gs_filereaddata( &buffer, size, f ); // read file's content (size characters) in the buffer
		gs_fileclose(f);                     // close file
		buffer[[size]] = 0;                  // set the eos on the last position in the string
		println(buffer);                     // displaying the program may be limited by the println internal buffer
	}
}

C/C++ source code

gs_fileseek

( lib: File, file: gslib_file.cpp )

int gs_fileseek( f, pos, mode )

IN
ptr	f	file handler
int	pos	position to seek to
int	mode	seek mode 0=beginning, 1=current, 2=end
OUT
int	1=success, 0=fail

Moves file cursor to the specified position in file.
If mode is 0, pos position is considered from the beginning of the file and it must be positive or zero.
If mode is 1, pos position is considered as an offset from where the cursor is right now.
If mode is 2, pos position is considered from the end of the file and it must be negative or zero.
See gs_fileopen for examples.

C/C++ source code

gs_filetell

( lib: File, file: gslib_file.cpp )

int gs_filetell( f )

IN
ptr	f	file handler
OUT
int	current position or -1 if error

Returns the current position of the file cursor (in bytes).
Can be used with gs_fileseek(f,0,2) to find the size of the file.
See gs_fileopen for examples.

C/C++ source code

gs_filewriteint

( lib: File, file: gslib_file.cpp )

int gs_filewriteint( n, f )

IN
int	n	number to write
ptr	f	file handler
OUT
int	1=success, 0=fail

Writes the integer value of the parameter n in the file f at the current position of the file cursor.
Since integers in GS9 have 32bits, the file cursor will be incremented with 4 bytes;
The file must be opened for write.

C/C++ source code

gs_filewritefloat

( lib: File, file: gslib_file.cpp )

int gs_filewritefloat( n, f )

IN
flt	n	number to write
ptr	f	file handler
OUT
int	1=success, 0=fail

Writes the float value of the parameter n in the file f at the current position of the file cursor.
Floats in GS9 are stored on 32bits, so the file currsor will be incremented with 4 bytes;

C/C++ source code

gs_filewritetext

( lib: File, file: gslib_file.cpp )

int gs_filewritetext( s, f )

IN
str	s	string to write
ptr	f	file handler
OUT
int	1=success, 0=fail

Writes in f all characters from the s string, without eos (0).
Add another two characters 0xd, 0xa (\r\n) representing the end of line marker (eol).
This sequence is specific to text files in Windows.
Even if \n is enought to move on the next line, using only this might puzzle some primitive text editors.

func main()
{
	f = gs_fileopen("testfile.txt",1);
	gs_filewritetext("This is a line of text.",f);
	gs_filewritetext("This is another line of text.\r\nAnd yet, another one.",f);
	gs_fileclose(f);
}

C/C++ source code

gs_filewritedata

( lib: File, file: gslib_file.cpp )

int gs_filewritedata( buffer, size, f )

IN
refstr	buffer	refered buffer of characters to write
int	size	size to write (in bytes)
ptr	f	file handler
OUT
int	1=success, 0=fail

Writes a specified number of characters from a string refered by buffer.
Warning: buffer string's size must be at least size characters (including eos).

C/C++ source code

gs_filereadint

( lib: File, file: gslib_file.cpp )

int gs_filereadint( n, f )

IN
refint	n	refered integer variable to read in
ptr	f	file handler
OUT
int	1=success, 0=fail

Reads an integer value from file f into n and increment the file cursor with 4 bytes.

C/C++ source code

gs_filereadfloat

( lib: File, file: gslib_file.cpp )

int gs_filereadfloat( n, f )

IN
reffloat	n	refered float variable to read in
ptr	f	file handler
OUT
int	1=success, 0=fail

Reads a float value from file f into n and increment the file cursor with 4 bytes.

C/C++ source code

gs_filereadtext

( lib: File, file: gslib_file.cpp )

int gs_filereadtext( s, f )

IN
refstr	s	refered string variable to read in
ptr	f	file handler
OUT
int	1=success, 0=fail

Reads a line of text from a file (all characters until eol(\r\n) is reached).
Store it in a string, without the eol, but adding the eos.
So the string refered by s must be big enough to hold all the caracters from the line plus one for eos.

C/C++ source code

gs_filereaddata

( lib: File, file: gslib_file.cpp )

int gs_filereaddata( buffer, size, f )

IN
refstr	buffer	refered buffer of characters to read in
int	size	size to read (in bytes)
ptr	f	file handler
OUT
int	1=success, 0=fail

Reads a number of characters (bytes) from file f into a string buffer.
Warning: string buffer's size must be at leaset size (including eos) or the program may crash!

C/C++ source code

gs_fileclose

( lib: File, file: gslib_file.cpp )

int gs_fileclose( f )

IN
ptr	f	file handler
OUT
int	1=success, 0=fail

Closes the file handler f.
After closing the file, the handler f becomes invalid, and the file requires another opening if more read or write is needed.

C/C++ source code

gs_fileinfo

( lib: File, file: gslib_file.cpp )

str gs_fileinfo( filename )

IN
str	filename	path to a file
OUT
str	file info string in a fixed format

Returns file info in the following format: "Wed Jan 02 02:03:55 1980\nFILE_SIZE".
The FILE_SIZE substring have variable length, but the first part is fixed.
If file is not found, a VOID string is returned.

func main()
{
	fileinfo = gs_fileinfo("program.txt");
	println( fileinfo, " bytes");
}

C/C++ source code

gs_filedelete

( lib: File, file: gslib_file.cpp )

int gs_filedelete( filename )

IN
str	filename	path to file
OUT
int	1=success, 0=fail

Deletes the specified file from hard disk.

C/C++ source code

gs_filefind

( lib: File, file: gslib_file.cpp )

gs_filefind( path, callback, recursive )

IN
str	path	path to a directory or "" for current
str	callback	function name to be called for each found file
int	recursive	go deep into directories

Finds all files from the given directory name. The directory name must include the ending back slash.
For each found file a function with the given callback name is called.
The callback function must have two parameters: filepath (str), and isdir (int) that are received from the find cycle.
If recursive is 1, the files will be searched deep into any found directories.

func find_callback( filepath, isdir )
{
	println( filepath, isdir?"dir":"" );
}
func main()
{
	// list files and dirs from the current directory
	gs_filefind("MyName\\","find_callback",1);
}

C/C++ source code

gs_directoryget

( lib: File, file: gslib_file.cpp )

str gs_directoryget( )

OUT
str	path to the current directory

Returns a string containing the path of the current directory.

C/C++ source code

gs_directoryset

( lib: File, file: gslib_file.cpp )

int gs_directoryset( pathdir )

IN
str	pathdir	path to the directory to set as current
OUT
int	1=success, 0=fail

Changes current directory to pathdir.

C/C++ source code

gs_directorycreate

( lib: File, file: gslib_file.cpp )

gs_directorycreate( pathdir )

IN
str	pathdir	path to a directory

Creates a new folder.
The path up to the directory must exists.
No error is returned.

C/C++ source code

gs_directorydelete

( lib: File, file: gslib_file.cpp )

int gs_directorydelete( pathdir )

IN
str	pathdir	path to a directory
OUT
int	1=success, 0=fail

Delete anexisting folder.
The path up to the directory must exists.

C/C++ source code

gs_inigetint

( lib: File, file: gslib_file.cpp )

int gs_inigetint( filename, group, key, val )

IN
str	filename	path to ini file
str	group	group to search in
str	key	key name to search for
refint	val	receive key value
OUT
int	1=success, 0=fail

Reads an integer value from a standard INI file, with the specified group and key.
Warning: this function uses a common internal text buffer that is rewritten after each call.

C/C++ source code

gs_inigetstr

( lib: File, file: gslib_file.cpp )

int gs_inigetstr( filename, group, key, val )

IN
str	filename	path to ini file
str	group	group to search in
str	key	key name to search for
refstr	val	receive key value
OUT
int	1=success, 0=fail

Reads a string value from a standard INI file, with the specified group and key.
Warning: this function uses a common internal text buffer that is rewritten after each call.

C/C++ source code

gs_inisetint

( lib: File, file: gslib_file.cpp )

gs_inisetint( file_name, group, key, val )

IN
str	file_name	path to ini file
str	group	group to search in
str	key	key name to search for
int	val	key value to set

Writes an integer value into a standard INI file, with the specified group and key.
Warning: this function uses a common internal text buffer that is rewritten after each call.

C/C++ source code

gs_inisetstr

( lib: File, file: gslib_file.cpp )

gs_inisetstr( file_name, group, key, val )

IN
str	file_name	path to ini file
str	group	group to search in
str	key	key name to search for
str	val	key value to set

Writes a string value into a standard INI file, with the specified group and key.
Warning: this function uses a common internal text buffer that is rewritten after each call.

C/C++ source code