Prev: Module encoding: Standard Encodings
Module files: File and Directory Access
This module provides access to files and directories of the underlying operating system, including a function to send a file via different messaging interfaces ("send as").
To read and write files, use module io.
If not absolute, pathes are always relative to the current directory. See also section * ().
Some functions of this module allow the use of file patterns: these may contain the wildcards * matching any number of characters, and '?' matching a single character. For instance, the pattern d:\documents\mShell\*Test.* matches any file in directory \documents\mShell on drive D: whose name ends with Test.
Many of the functions in this module can render a mobile phone completely unusable, e.g. by deleting system configuration data, or by overwriting sensitive files. Make sure you regularly back up your mobile phone, and inform yourself how to reset your phone to factory status. You have been warned!
files.attr
• function attr(path) → Number
Permissions: Read(path)
• function attr(path, newattr) → Number
Permissions: Read+Write(path)
Gets or sets the attribute bits of a file. With one argument, returns the attribute bits of the file or directory path. With two arguments, returns the old file attributes, and sets the new attributes of path.
The attribute bits define the characteristics of a file:
• const arch = 32
File or directory has the archive bit set.
• const dir = 16
Path references a directory.
• const hidden = 2
File or directory is hidden (invisible).
• const ro = 1
File or directory is read-only.
• const sys = 4
File or directory has the system bit set.
• const all = 55
All attribute bits set.
The status of the files.dir attribute cannot be changed.
Use the bitwise or operator | to combine single bits; use the bitwise and operator & to check for single bits.
// make the file "secret.dat" read-only and invisible
files.attr("secret.dat", files.ro | files.hidden);
// check whether a path is a directory
print
files.attr("c:\\documents\\mShell") & files.dir # 0
→ true
|
See also: files.scan
files.copy
• function copy(srcpattern, destdir, recursive=false) → Number
/r:recursive
Permissions: Read(srcpattern)+Write(destdir)
Copies a file or all files matching srcpattern to another directory destdir. If recursive=true, or /r is specified in interactive mode, also copies all files matching the file part of srcpattern in all subdirectories of the directory part of srcpattern, and creates the corresponding subdirectories in destdir.
Returns the number of files copied.
In interactive shells, this function is available as cp.
print files.copy("secret.dat", "d:\\")
→ 1
// copy all m scripts from drive C: to drive D:
files.copy("c:\\documents\\mShell\\*.m",
"d:\\documents\\mShell", true)
m>cp c:\documents\mShell\*.m d:\documents\mShell/r
|
The last two statements (the second in interactive mode) are equivalent.
files.delete
• function delete(pattern, recursive=false) → Number
/r:recursive
Permissions: Write(pattern)
Deletes a file or all files matching pattern. If recursive=true, or /r is specified in interactive mode, also deletes all files matching the file part of pattern in all subdirectories of the directory part of pattern.
Returns the number of files deleted.
In interactive shells, this function is available as del.
print files.delete("secret.dat");
→ 1
// delete all m scripts from drive C:
files.delete(""c:\\documents\\mShell\\*.m", true)
m>del c:\documents\mShell\*.m/r
|
The last two statements (the second in interactive mode) are equivalent.
See also: files.rmdir
files.edit
• function edit(path, cursor=0) → null
Permissions: Read+Write(path)
Loads the file path into the builtin editor, and shows the editor. Any previously loaded file (e.g. a script being edited) will be saved first. The cursor is moved to position cursor in the file. The character encoding applied is determined by the encoding property (see * (Reference)).
In interactive shells, this function is available as edit.
// edit an XML file
files.edit("\\documents\\MMS\\Sample.xml")
|
files.exists
• function exists(path) → Boolean
Permissions: Read(path)
Returns true if the file or directory denoted by path exists, false if there is no such file or directory.
print files.exists("c:\\documents\\mShell")
→ true
|
files.mkdir
• function mkdir(path, all=false) → null
/a:all
Permissions: Write(path)
Create a new directory path. path can be relative to the current directory, or absolute. See also section * ().
If all=false, mkdir creates just one directory. If all=true, or /a is specified in interactive mode, all directories down to the last in path are created, as necessary.
In interactive shells, this function is available as md.
mkdir("subdir");
mkdir("..\\otherdir");
mkdir("c:\\documents\\mShell", true)
m>md c:\documents\mShell/a
|
The last two statements (the second in interactive mode) are equivalent.
files.move
• function move(srcpattern, destpath, recursive=false) → Number
/r:recursive
Permissions: Read+Write(srcpattern)+Write(destdir)
Moves a file or all files matching srcpattern to another directory destdir. If recursive=true, or /r is specified in interactive mode, also moves all files matching the file part of srcpattern in all subdirectories of the directory part of srcpattern, removes and creates the corresponding subdirectories in destdir.
Returns the number of files moved.
In interactive shells, this function is available as mv.
print files.move("secret.dat", "d:\\")
→ 1
// move all m scripts from drive C: to drive D:
files.move("c:\\documents\\mShell\\*.m",
"d:\\documents\\mShell", true)
m>mv c:\documents\mShell\*.m d:\documents\mShell/r
|
The last two statements (the second in interactive mode) are equivalent.
files.parse
• function parse(path) → Array
Parses a path into its four components and returns them as an array:
| Key | Meaning | Type |
| drive | Drive (with trailing colon) | String |
| dir | Directory (with trailing backslash) | String |
| base | Base file name | String |
| ext | Extension (with leading dot) | String |
| |
path="c:\\documents\\mShell\\script.m";
print files.parse(path)
→ [c:,\documents\mShell\,script,.m]
// Concatenating the four components will
// always produce the original name:
n="";
for p in files.parse(path) do n = n + p end;
print n
→ c:\documents\mShell\script.m
|
files.rename
• function rename(oldfile, newfile) → null
Permissions: Write(oldfile)+Write(newfile)
Renames the file or directory oldfile to newfile. This function does not support wildcards.
files.rename("secret.dat", "topsecret.dat")
|
files.rmdir
• function rmdir(path, recursive=false) → Number
/r:recursive
Permissions: Write(path)
Removes the directory path. If recursive=false, the directory must be empty before it can removed. If recursive=true, or /r is specified in interactive mode, the directory with all its contents and subdirectories will be removed.
Returns the number of directories and files removed.
In interactive shells, this function is available as rd.
print rmdir("subdir")
→ 1
rmdir("..\\otherdir");
rmdir("c:\\myfiles\\images", true)
m>rd c:\myfiles\images/r
→ (number of items removed)
|
The last two statements (the second in interactive mode) are equivalent: they both remove the directory images with all its contents.
files.roots
• function roots() → Array
Returns an array with all accessible file system roots (drives).
print files.roots()
→ [A:,C:,D:,Z:]
|
files.scan
• function scan(pattern, attr=0, mask=files.dir | files.hidden | files.sys) → Array
Permissions: Read(pattern)
Returns an array with all directory entries whose name matches pattern and whose attribute bits defined by mask match attr: a file path matches if
files.attr(path) & mask = attr & mask.
Example values for attr and mask:
- The default values exclude directories, hidden and system files.
- attr=files.dir returns only directories.
- mask=0 ignores all attributes and thus returns all entries.
- attr=files.ro and mask=files.ro return only read only files and directories.
- attr=files.arch and mask=files.dir|files.arch return only files with the archive bit set.
The file names returned do not contain the directory part defined by
pattern, and are sorted by name.
// search the application directory for m help files
print files.scan(system.appdir+"*.mhp")
→ [agenda.mhp,app.mhp,array.mhp,audio.mhp,bigint.mhp,
bt.mhp,cam.mhp,comm.mhp,contacts.mhp,default.mhp,
files.mhp,graph.mhp,...<28>]
// search the document directory for hidden files only
print files.scan(system.docdir+"*",files.hidden)
→ [10204299.act]
|
files.send
• function send(path, subject=null) → null
Permissions: Read(path)
| | |
| Compatibility of function files.send |
| Nokia phones before Symbian 8 | Call is ignored |
|
Sends the file path over a messaging channel chosen by the user ("Send as"). Channels typically include Bluetooth, MMS, and e-mail. The recipient and other channel dependent message details will be specified interactively.
subject is the subject of the message (if applicable). If subject=null, it defaults to path without the directory component.
In interactive shells, this function is available as send.
// send a script file
files.send(system.docdir+"coolgame.m",
"The cool game I promised")
|
 | |  |
| Series 60 sample screen | | UIQ sample screen |
files.size
• function size(path) → Number
Permissions: Read(path)
Returns the size in bytes of the file denoted by path. Returns 0 if path denotes a directory.
print files.size(system.appdir+"Audio_mm.dll")
→ 2956
|
files.time
• function time(path) → Number
Permissions: Read(path)
• function time(path, newtime) → Number
Permissions: Read+Write(path)
Gets or sets the time when the file or directory denoted by path has been created or modified. The time is in seconds since midnight on January 1st of year 0. With one argument, returns the modification time of the file or directory path. With two arguments, returns the old modification time, and sets the new time.
print files.time("c:\\documents\\mShell")
→ 63276033444
|
See also module time.
files.wait
• function wait(path,withWrites=false,timeout=-1) → Boolean
Permissions: Read(path)
Waits for the contents of directory path being updated, i.e. a file in this directory being created, renamed, or deleted. If withWrites=true, also waits for a write to a file in this directory, i.e. each modification of a file's contents will also cause the function to return.
Returns true if (at least one) change occured, or false if the timeout has been reached.
This function can be used to wait for external applications creating data, e.g. the camera application creating an image. See also files.scan.
// wait up to 5 seconds for a file being created,
// renamed or deleted in system.docdir
files.wait(system.docdir, false, 5000)
→ false
|
Next: Module io: File and Stream Input/Output© 2004-2011 airbit AG, CH-8008 Zürich
Document AB-M-LIB-888
