bps::Dir Class Reference

The bps.Dir class provides access to directory structures and their contents in a platform-independent way. More...

Public Types
enum	FilterSpec {   Dirs = 0x0001 , Files = 0x0002 , Drives = 0x0004 , AllEntries = 0x0007 , NoSymLinks = 0x0008 , Readable = 0x0010 , Writable = 0x0020 , Executable = 0x0040 , Modified = 0x0080 , Hidden = 0x0100 ,   System = 0x0200 , AllDirs = 0x0400 , CaseSensitive = 0x0800 , NoDotAndDotDot = 0x1000 }
	This enum describes the filtering options available to bps.Dir, eg for entryList() and entryInfoList(). More...
enum	SortSpec { Name = 0x00 , Time = 0x01 , Size = 0x02 , Unsorted = 0x03 , DirsFirst = 0x04 , Reversed = 0x08 , IgnoreCase = 0x10 , DirsLast = 0x20 , LocaleAware = 0x40 , Type = 0x80 }
	This enum describes the sort options available to bps.Dir, eg for entryList() and entryInfoList(). More...

Public Member Functions
String	absFilePath (String aName)
	Returns the absolute path name of a file in the directory. More...
void	cd (String aDirName)
	Changes the Dir's directory to dirName if possible; otherwise throws an exception. More...
void	cdUp ()
	Changes directory by moving one directory up from the Dir's current directory if possible; otherwise throws an exception.
	Dir (String aPath="")
	Constructor for the Dir class. More...
Array	entryList (String aFilter, FilterSpec aFilterSpec, SortSpec aSortSpec)
	Get a list of the names of all the files and directories in the directory, ordered in accordance with sortSpec and filtered in accordance with filterSpec. More...
Boolean	fileExists (QString aFileName)
	Check file existence in this directory. More...
String	filePath (String aFileName)
	Get path of file in this directory. More...
void	mkdir (String aDirName=Null)
	Creates the directory if possible; otherwise throws an exception. More...
void	mkpath (String aDirName=Null)
	Creates the directory branch if possible; otherwise throws an exception. More...
void	remove (String aFileName)
	Removes (unlinks) the file from this directory. More...
void	rename (String aOldName, String aNewName)
	Rename a file or directory. More...
void	rmdir (String aDirName=Null)
	Deletes the directory aDirName if possible; otherwise throws an exception. More...
void	rmdirs (String aDirName=Null)
	Deletes the directory structure aDirName if possible; otherwise throws an exception. More...
void	setCurrent ()
	Sets the application's current working directory to this directory if possible; otherwise throws an exception.
String	toString () const

Static Public Member Functions
static String	cleanPath (String aPath)
	Removes all multiple directory separators "/" and resolves any "."s or ".."s found in the path. More...
static String	fromNativeSeparators (String aPath)
	Returns path using '/' as file separator. More...
static String	toNativeSeparators (String aPath)
	Returns path with the '/' separators converted to separators that are appropriate for the underlying operating system. More...

Public Attributes
const Array	drives
	An array of strings containing the drive names (c:, d:, etc); empty on Unix.
const String	home
	Returns the absolute path of the user's home directory. More...
const String	root
	The root directory.

Static Public Attributes
static String	current
	The current directory.

Properties
String	absolute
	True if the directory name is absolute; otherwise false. More...
String	absPath
	Contains the absolute path (a path that starts with "/" or with a drive specification). More...
String	canonicalPath
	Returns the canonical path, i.e. More...
String	exists
	True if the directory exists; otherwise false. More...
String	name
	Contains the name of the directory. More...
String	path
	Path of as set when construction the object. More...
String	readable
	True if the directory is readable; otherwise false. More...

Detailed Description

The bps.Dir class provides access to directory structures and their contents in a platform-independent way.

It provides a means of listing directory content, creating filenames with proper path separators, etc.

var dir = new bps.Dir;
var codeFiles = dir.entryList('*.cpp');
for (var i = 0; i < codeFiles.length; ++i) 
    bps.log(codeFiles[i]);

Member Enumeration Documentation

FilterSpec

enum bps::Dir::FilterSpec

This enum describes the filtering options available to bps.Dir, eg for entryList() and entryInfoList().

Enumerator
Dirs	List directories only.
Files	List files only.
Drives	List disk drives only.
AllEntries	List directories, files, drives and symlinks (this does not list broken symlinks unless you specify System).
NoSymLinks	Do not list symbolic links (ignored by operating systems that don't support symbolic links).
Readable	List files for which the application has read access.
Writable	List files for which the application has write access.
Executable	List files for which the application has execute access. Executables must be combined with Dirs or Files.
Modified	Only list files that have been modified (ignored under Unix).
Hidden	List hidden files (on Unix, files starting with a .).
System	List system files (on Unix, FIFOs, sockets, and device files).
AllDirs	List all directories; i.e. don't apply the filters to directory names.
CaseSensitive	The filter should be case sensitive if the file system is case sensitive.
NoDotAndDotDot	Do not list the special entries "." and "..".

SortSpec

enum bps::Dir::SortSpec

This enum describes the sort options available to bps.Dir, eg for entryList() and entryInfoList().

Enumerator
Name	Sort by name.
Time	Sort by time (modification time).
Size	Sort by file size.
Unsorted	Do not sort.
DirsFirst	Put the directories first, then the files.
Reversed	Reverse the sort order.
IgnoreCase	Sort case-insensitively.
DirsLast	Put the files first, then the directories.
LocaleAware	Sort items appropriately using the current locale setting.
Type	Sort by file type (extension).

Constructor & Destructor Documentation

Dir()

bps::Dir::Dir

(

String

aPath = ""

)

Constructor for the Dir class.

Note

BpScript uses "/" as a directory separator throughout (although it understands the conventions of the platform it is used on). If you are working with paths, use "/" within your code, and use toNativeSeparators() when you want to display a path to the user.

Parameters

aPath

If path is empty, the current directory is used.

Member Function Documentation

absFilePath()

String bps::Dir::absFilePath

(

String

aName

)

Returns the absolute path name of a file in the directory.

Does not check if the file actually exists in the directory; but see exists(). Redundant multiple separators or "." and ".." directories in fileName are not removed, see cleanPath().

Parameters

aName

The name of the file or directory.

Returns

The absolute path name of the file or directory.

cd()

void bps::Dir::cd

(

String

aDirName

)

Changes the Dir's directory to dirName if possible; otherwise throws an exception.

Parameters

aDirName

The name of the directory to change to.

cleanPath()

static String bps::Dir::cleanPath ( String  aPath )

static

Removes all multiple directory separators "/" and resolves any "."s or ".."s found in the path.

Symbolic links are kept. This function does not return the canonical path, but rather the simplest version of the input. For example, "./local" becomes "local", "local/../bin" becomes "bin" and "/local/usr/../bin" becomes "/local/bin".

Parameters

aPath

The path to clean up.

Returns

The cleaned up path.

entryList()

Array bps::Dir::entryList	(	String	aFilter,
		FilterSpec	aFilterSpec,
		SortSpec	aSortSpec
	)

Get a list of the names of all the files and directories in the directory, ordered in accordance with sortSpec and filtered in accordance with filterSpec.

Parameters

aFilter	File name filter with wildcards.
aFilterSpec	Filter specifier.
aSortSpec	Sorting specifier.

Returns

Array of String with the found file names.

fileExists()

Boolean bps::Dir::fileExists

(

QString

aFileName

)

Check file existence in this directory.

Parameters

aFileName

The name of the file.

Returns

True if the file fileName exists; otherwise returns false.

filePath()

String bps::Dir::filePath

(

String

aFileName

)

Get path of file in this directory.

Parameters

aFileName

The name of the file.

Returns

The path name of the file fileName in the directory.

fromNativeSeparators()

static String bps::Dir::fromNativeSeparators ( String  aPath )

static

Returns path using '/' as file separator.

On Windows, for instance, fromNativeSeparators("c:\winnt\system32") returns "c:/winnt/system32".
The returned string may be the same as the argument on some operating systems, for example on Unix.

Parameters

aPath

The path to convert.

Returns

The converted path.

mkdir()

void bps::Dir::mkdir

(

String

aDirName = Null

)

Creates the directory if possible; otherwise throws an exception.

Parameters

aDirName

The name of the directory to create. Create the currently addressed one when no directory name provided.

mkpath()

void bps::Dir::mkpath

(

String

aDirName = Null

)

Creates the directory branch if possible; otherwise throws an exception.

Parameters

aDirName

Name of the directory branch to create. Create the currently addressed one when no directory name provided .

remove()

void bps::Dir::remove

(

String

aFileName

)

Removes (unlinks) the file from this directory.

If this was the last link to the file, the file is deleted.

Parameters

aFileName

The name of the file to remove.

rename()

void bps::Dir::rename	(	String	aOldName,
		String	aNewName
	)

Rename a file or directory.

On most file systems, rename() fails only if old name does not exist, if new name and old name are not on the same partition or if a file with the new name already exists. However, there are also other reasons why rename() can fail. For example, on at least one file system rename() fails if new name points to an open file.

Parameters

aOldName	The old name of the file or directory.
aNewName	The new name of the file or directory.

rmdir()

void bps::Dir::rmdir

(

String

aDirName = Null

)

Deletes the directory aDirName if possible; otherwise throws an exception.

The directory must be empty for rmdir() to succeed.

Parameters

aDirName

The name of the directory to delete. Delete the currently addressed one when no directory name provided .

rmdirs()

void bps::Dir::rmdirs

(

String

aDirName = Null

)

Deletes the directory structure aDirName if possible; otherwise throws an exception.

Attention

Contained files and subdirectories are recursively deleted.

Parameters

aDirName

Name of the directory structure to delete. Delete the currently addressed one when no directory name provided .

toNativeSeparators()

static String bps::Dir::toNativeSeparators ( String  aPath )

static

Returns path with the '/' separators converted to separators that are appropriate for the underlying operating system.

On Windows, toNativeSeparators("c:/winnt/system32") returns "c:\winnt\system32". The returned string may be the same as the argument on some operating systems, for example on Unix.

Parameters

aPath

The path to convert.

Returns

The converted path.

toString()

String bps::Dir::toString

(

)

const

Returns

Returns "Dir(absolute path)"

Member Data Documentation

home

const String bps::Dir::home

Returns the absolute path of the user's home directory.

Under Windows this function will return the directory of the current user's profile. Typically, this is: C:/Documents and Settings/Username

Use the toNativeSeparators() function to convert the separators to the ones that are appropriate for the underlying operating system.

If the directory of the current user's profile does not exist or cannot be retrieved, the following alternatives will be checked (in the given order) until an existing and available path is found:

• The path specified by the USERPROFILE environment variable.
• The path formed by concatenating the HOMEDRIVE and HOMEPATH environment variables.
• The path specified by the HOME environment variable.
• The path returned by the rootPath() function (which uses the SystemDrive environment variable)
• The C:/ directory.

Under non-Windows operating systems the HOME environment variable is used if it exists, otherwise the path returned by the rootPath() function is used.

Property Documentation

absolute

String bps::Dir::absolute

read

True if the directory name is absolute; otherwise false.

 

absPath

String bps::Dir::absPath

read

Contains the absolute path (a path that starts with "/" or with a drive specification).

It may contain symbolic links, but never contains redundant ".", "..", or multiple separators.

canonicalPath

String bps::Dir::canonicalPath

read

Returns the canonical path, i.e.

a path without symbolic links or redundant "." or ".." elements. On systems that do not have symbolic links this function will always return the same string that absolutePath() returns. If the canonical path does not exist (normally due to dangling symbolic links) canonicalPath() returns an empty string.

var bin = "/local/bin";         // where /local/bin is a symlink to /usr/bin
var binDir = new bps.Dir(bin);
var canonicalBin = binDir.canonicalPath;
// canonicalBin now equals "/usr/bin"
 
var ls = "/local/bin/ls";       // where ls is the executable "ls"
var lsDir = new bps.Dir(ls);
var canonicalLs = lsDir.canonicalPath;
// canonicalLS now equals "/usr/bin/ls". 

exists

String bps::Dir::exists

read

True if the directory exists; otherwise false.

 

name

String bps::Dir::name

read

Contains the name of the directory.

This is not the same as the path, e.g. a directory with the name "mail", might have the path "/var/spool/mail".

path

String bps::Dir::path

readwrite

Path of as set when construction the object.

The path may contain symbolic links, but never contains redundant ".", "..", or multiple separators. The returned path can be either absolute or relative. No check is made to see whether a directory with this path actually exists.

readable

String bps::Dir::readable

read

True if the directory is readable; otherwise false.

 

---

The documentation for this class was generated from the following file:

• bps.Dir.js