BRL.FileSystem: Functions Modinfo Source  

File system

The BlitzMax filesystem module contains commands to perform operations on the computer's files and directories.

OpenFile, ReadFile and WriteFile return a Stream object for reading and or writing data to files.

Directories can be examined file by file using a combination of the ReadDir, NextFile and CloseDir commands or LoadDir can be used to read the file names of a directory into a string array.

File properties can be examined with the FileType, FileTime, FileSize and FileMode commands.

Files and directories (folders) can be created and deleted with the CreateFile, CreateDir, DeleteFile and DeleteDir commands.

Finally, the FileSystem module contains various utility functions for handling file paths in a system independent manner. These commands include RealPath, StripDir, StripExt, StripAll, StripSlash, ExtractDir and ExtractExt.

Functions

Function ChangeDir( path$ )
ReturnsTrue if successful.
DescriptionChange current directory.
Example
' changedir.bmx

print "CurrentDir()="+currentdir()

' change current folder to the parent folder

changedir ".."

' print new CurrentDir()

print "CurrentDir()="+currentdir()

Function CloseDir( dir )
DescriptionClose a directory.

Function CloseFile( stream:TStream )
DescriptionCloses a file stream.
InformationAfter performing file operations on an open file make sure to close the file stream with either CloseFile or the identical CloseStream command.

Function CopyDir( src$,dst$ )
ReturnsTrue if successful.
DescriptionCopy a directory.

Function CopyFile( src$,dst$ )
DescriptionCopy a file.

Function CreateDir( path$,recurse=False )
ReturnsTrue if successful.
DescriptionCreate a directory.
InformationIf recurse is true, any required subdirectories are also created.
Example
' createdir.bmx

success=createdir("myfolder")
if not success runtimeerror "error creating directory"

Function CreateFile( path$ )
ReturnsTrue if successful.
DescriptionCreate a file.
Example
' createfile.bmx

success=createfile("myfile")
if not success runtimeerror "error creating file"

Function CurrentDir$()
ReturnsThe current directory.
DescriptionGet Current Directory.
Example
' currentdir.bmx

cd$=currentdir()
print "CurrentDir()="+cd$

Function DeleteDir( path$,recurse=False )
ReturnsTrue if successful.
DescriptionDelete a directory.
InformationSet recurse to true to delete all subdirectories and files recursively - but be careful!
Example
' deletedir.bmx

success=deletedir("myfolder")
if not success runtimeerror "error deleting directory"

Function DeleteFile( path$ )
ReturnsTrue if successful.
DescriptionDelete a file.
Example
' deletefile.bmx

success=deletefile("myfile")
if not success runtimeerror "error deleting file"

Function ExtractDir$( path$ )
DescriptionExtract directory from a file path.
Example
' extractdir.bmx

print extractdir("mypath/myfile.bmx")	'prints mypath

Function ExtractExt$( path$ )
DescriptionExtract extension from a file path.
Example
' extractext.bmx

print extractext("mypath/myfile.bmx")	'prints bmx

Function FileMode( path$ )
Returnsfile mode flags.
DescriptionGet file mode.
Example
' filemode.bmx

' the following function converts the file mode to 
' the standard unix permission bits string

Function Permissions$(mode)
	local	testbit,pos
	local	p$="rwxrwxrwx"
	testbit=%100000000
	pos=1
	while (testbit)
		if mode & testbit res$:+mid$(p$,pos,1) else res$:+"-"
		testbit=testbit shr 1
		pos:+1	
	wend
	return res
End Function

print Permissions$(filemode("filemode.bmx"))

Function FileSize( path$ )
ReturnsSize, in bytes, of the file at path, or -1 if the file does not exist.
DescriptionGet file size.
Example
' filesize.bmx

' the following prints the size of this source file in bytes

print filesize("filesize.bmx")

Function FileTime( path$ )
ReturnsThe time the file at path was last modified.
DescriptionGet file time.
Example
' filetime.bmx

print filetime("filetime.bmx")

Function FileType( path$ )
Returns0 if file at path doesn't exist, FILETYPE_FILE (1) if the file is a plain file or FILETYPE_DIR (2) if the file is a directory.
DescriptionGet file type.
Example
' filetype.bmx

print filetype(".")		'prints 2 for directory type
print filetype("filetype.bmx")	'prints 1 for file type
print filetype("notfound.file")	'prints 0 for doesn't exist

Function LoadDir$[]( dir$,skip_dots=True )
ReturnsA string array containing contents of dir.
DescriptionLoad a directory.
InformationThe skip_dots parameter, if true, removes the '.' (current) and '..' (parent) directories from the returned array.
Example
' loaddir.bmx

' declare a string array

local files$[]

files=loaddir(currentdir())

for t$=eachin files
	print t	
next

Function NextFile$( dir )
ReturnsFile name of next file in directory opened using ReadDir, or an empty string.
DescriptionReturn next file in a directory.

Function OpenFile:TStream( url:Object,readable=True,writeable=True )
DescriptionOpen a file for input and/or output.
InformationThis command is similar to the OpenStream command but will attempt to cache the contents of the file to ensure serial streams such as http: based url's are seekable. Use the CloseStream command when finished reading and or writing to a Stream returned by OpenFile.
Example
' openfile.bmx

' the following prints the contents of this source file 

file=openfile("openfile.bmx")

if not file runtimeerror "could not open file openfile.bmx"

while not eof(file)
	print readline(file)
wend
closestream file

Function ReadDir( path$ )
ReturnsAn integer directory handle, or 0 if the directory does not exist.
DescriptionOpen a directory.
Example
' readdir.bmx

dir=ReadDir(CurrentDir())

If Not dir RuntimeError "failed to read current directory"

Repeat
	t$=NextFile( dir )
	If t="" Exit
	If t="." Or t=".." Continue
	Print t	
Forever

CloseDir dir

Function ReadFile:TStream( url:Object )
DescriptionOpen a file for input.
InformationThis command is similar to the ReadStream command but will attempt to cache the contents of the file to ensure serial streams such as http: based url's are seekable. Use the CloseStream command when finished reading and or writing to a Stream returned by OpenFile.
Example
' readfile.bmx

' the following prints the contents of this source file 

file=readfile("readfile.bmx")

if not file runtimeerror "could not open file openfile.bmx"

while not eof(file)
	print readline(file)
wend

closestream file

Function RealPath$( path$ )
DescriptionGet real, absolute path of a file path.
Example
' realpath.bmx

print realpath("realpath.bmx")	'prints full path of this source

print realpath("..") 'prints full path of parent directory

Function RenameFile( oldpath$,newpath$ )
ReturnsTrue if successful.
DescriptionRenames a file.

Function SetFileMode( path$,mode )
DescriptionSet file mode.
Example
' setfilemode.bmx

' the following makes this source file readonly

writebits=%010010010

' read the file mode

mode=filemode("setfilemode.bmx")

'mask out the write bits to make readonly

mode=mode & ~writebits

'set the new file mode

setfilemode("setfilemode.bmx",mode)

Function StripAll$( path$ )
DescriptionStrip directory and extension from a file path.
Example
' stripall.bmx

print stripall("mypath/myfile.bmx")	'prints myfile

Function StripDir$( path$ )
DescriptionStrip directory from a file path.
Example
' stripdir.bmx

print stripdir("mypath/myfile.bmx")	'prints myfile.bmx

Function StripExt$( path$ )
DescriptionStrip extension from a file path.
Example
' stripext.bmx

print stripext("mypath/myfile.bmx")	'prints mypath/myfile

Function StripSlash$( path$ )
DescriptionStrip trailing slash from a file path.
InformationStripSlash will not remove the trailing slash from a 'root' path. For example, "/" or (on Win32 only) "C:/".
Example
' stripslash.bmx

print stripslash("mypath/")	'prints mypath

Function WriteFile:TStream( url:Object )
DescriptionOpen a file for output.
InformationThis command is identical to the WriteStream command.
Example
' writefile.bmx

file=writefile("test.txt")

if not file runtimeerror "failed to open test.txt file" 

writeline file,"hello world"

closestream file

Module Information

Version1.08
AuthorMark Sibly
LicenseBlitz Shared Source Code
CopyrightBlitz Research Ltd
ModserverBRL
History1.08 Release
HistoryRebuild for StdC chmod_ linkage
History1.07 Release
HistoryFixed RealPath failing with 'hidden' dirs
History1.06 Release
History1.05 Release
HistoryFixed Win32 CreateDir
History1.04 Release
HistoryCleaned up FixPath and RealPath
HistoryAdded optional resurse parameter to CreateDir