Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

File API

The subset of the Ruby File methods that allows access to the Rhodes file structure. Refer to File System access in Device Capabilities for examples and for information on file access on different device platforms.

Using JavaScript API

You can call the Ruby File methods from JavaScript. To use the JavaScript API, add the public/js/rho_javascript_api.js file – created at build time as part of the application package – to the .html, .erb, or .js file calling the JavaScript method.

The JavaScript API methods with a return value can pass it as a parameter in jQuery-compatible continuation (deferred object, a kind of callback). Possible continuations to handle are done, fail, and complete.

Rho.Class.method(params).done(function(handler) { /* handler... */ })

You must enable JavaScript by putting rho-javascript into extensions in your build.yml.

extensions: ["rho-javascript"]

You must have a RhoElements license to use the JavaScript API.

Rhodes File structure

<rhodes root>  # system-dependent path
  apps         # Rho::RhoApplication::get_base_app_path
    app        # Rho::RhoApplication::get_app_path('app') - contain models
      model1   # Rho::RhoApplication::get_model_path('app','model1')
    public     # contains files from application public folder
    db         # contains schema and data files
      db-files # contains files stored in database(blobs)
               # for file paths from camera callback etc: Rho::RhoApplication::get_blob_path(relative_file_path); 
               # to create file path for blob: Rho::RhoApplication::get_blob_folder()
    lib        # contains rho framework library files. Blackberry does not 
               # have this folder, library files are stored in jar
    RhoLog.txt #application log

Click here to see the RhoApplication methods.

absolute_path

Returns the absolute pathname for the given fileName. Ruby File method.

Ruby syntax:

File.absolute_path(fileName, dirString)

JavaScript syntax:

Rho.File.absolute_path(fileName, dirString)
fileName String. The file name .
dirString String. Optional. If given, the relative path starts from this path rather than from the current working directory.

atime

Returns a Date object of the last time access for the given fileName. Ruby File method.

Ruby syntax:

File.atime(fileName)

JavaScript syntax:

Rho.File.atime(fileName)
fileName String. The file name.

basename

Returns the last component of the filename given in fileName, which must be formed using forward slashes (“/”). For example, returns “ruby.rb” when fileName is “/home/gumby/work/ruby.rb”. Ruby File method.

Ruby syntax:

File.basename(fileName, suffix)

JavaScript syntax:

Rho.File.basename(fileName, suffix)
fileName String. The file name.
suffix String. Optional. When this is set to the suffix at the end of fileName, basename returns the last component of fileName without the suffix.

blockdev?, is_blockdev

Returns true if the given fileName is a block device. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.blockdev?(fileName)

JavaScript syntax:

Rho.File.is_blockdev(fileName)
fileName String. The file name.

chardev?, is_chardev

Returns true if the given fileName is a character device. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.chardev?(fileName)

JavaScript syntax:

Rho.File.is_chardev(fileName)
fileName String. The file name.

chmod

Changes permission bits on the named file(s) to the bit pattern represented by mode. Returns the number of files processed. Ruby File method.

For information about the permission bits, refer to the Ruby File method and to the UNIX manual for chmod(2).

Ruby syntax:

File.chmod(mode, fileName, fileName2, ...)

JavaScript syntax:

Rho.File.chmod(mode, fileName, fileName2, ...)
mode Bit pattern for the permission bits.
fileName, fileName2, ... String. The file name(s) to be processed. fileName2 ... are optional.

chown

Changes the owner and group of the named file(s) to the given numeric owner and group id’s. Only a process with superuser privileges may change the owner of a file. The current owner of a file may change the file’s group to any group to which the owner belongs. A nil or -1 owner or group id is ignored. Returns the number of files processed. Ruby File method.

Ruby syntax:

File.chown(owner, group, fileName, fileName2, ...)

JavaScript syntax:

Rho.File.chown(owner, group, fileName, fileName2, ...)
owner Integer. The owner id.
group Integer. The group id.
fileName, fileName2, ... String. The file name(s) to be processed. fileName2 ... are optional.

ctime

Returns the change time for the named file (the time at which directory information about the file was changed, not the file itself). On Windows (NTFS), returns creation time (birth time). Ruby File method.

Ruby syntax:

File.ctime(fileName)

JavaScript syntax:

Rho.File.ctime(fileName)
fileName String. The file name.

delete, do_delete

Deletes the named files, returning the number of names passed as arguments. With JavaScript, use the fail continuation to catch error exemptions. Ruby File method.

Ruby syntax:

File.delete(fileName, fileName2, ...)

JavaScript syntax:

Rho.File.do_delete(fileName, fileName2, ...)
fileName, fileName2, ... String. The names of the file(s) to be deleted. fileName2 ... are optional.

directory?, is_directory

Returns true if the named file is a directory, or a symlink that points at a directory, and false otherwise. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.directory?(fileName)

JavaScript syntax:

Rho.File.is_directory(fileName)
fileName String. The name of the file (or directory).

dirname

Returns a String of all components of the filename given in fileName except the last one (“/home/gumby/work/ruby.rb” => “/home/gumby/work”). The filename must be formed using forward slashes (“/”) regardless of the separator used on the local file system. Ruby File method.

Ruby syntax:

File.dirname(fileName)

JavaScript syntax:

Rho.File.dirname(fileName)
fileName String. The name of the file.

executable?, is_executable

Returns true if the named file is executable by the effective user id of this process. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.executable?(fileName)

JavaScript syntax:

Rho.File.is_executable(fileName)
fileName String. The name of the file.

executable_real?, is_executable_real

Returns true if the named file is executable by the real user id of this process. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.executable_real?(fileName)

JavaScript syntax:

Rho.File.is_executable_real(fileName)
fileName String. The name of the file.

exist?, is_exist

Returns true if the named file exists. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.exist?(fileName)

JavaScript syntax:

Rho.File.is_exist(fileName)
fileName String. The name of the file.

expand_path

Converts a pathname to an absolute pathname, which is returned as a String. Relative paths are referenced from the current working directory of the process unless dirString is given, in which case it will be used as the starting point. The given pathname may start with a “~”, which expands to the process owner’s home directory (the environment variable HOME must be set correctly). “~user” expands to the named user’s home directory. Ruby File method.

Ruby syntax:

File.expand_path(fileName, dirString)

JavaScript syntax:

Rho.File.expand_path(fileName, dirString)
fileName String. The name of the file.
dirName String. Optional. The name of the file.

extname

Returns the extension (the portion of file name in path after the period), such as “.rb” from “a/b/d/test.rb”. Ruby File method.

Ruby syntax:

File.extname(fileName)

JavaScript syntax:

Rho.File.extname(fileName)
fileName String. The name of the file.

file?, is_file

Returns true if the named file exists and is a regular file. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.file?(fileName)

JavaScript syntax:

Rho.File.is_file(fileName)
fileName String. The name of the file.

fnmatch, is_fnmatch

Returns true if path matches against pattern. Returns null if this feature is not supported on the device platform. The pattern is not a regular expression; instead, it follows rules similar to shell filename globbing. Ruby File method.

Ruby syntax:

File.fnmatch?(pattern, path)

JavaScript syntax:

Rho.File.is_fnmatch(pattern, path)
pattern String. The path to match against the pattern.
path String. The pattern.

The pattern may contain the following metacharacters:

* Matches any file. Can be restricted by other values in the glob. * will match all files; c* will match all files beginning with c; *c will match all files ending with c; and *c* will match all files that have c in them (including at the beginning or end). Equivalent to / .* /x in regexp.
** Matches directories recursively or files expansively.
? Matches any one character. Equivalent to /.{1}/ in regexp.
[set] Matches any one character in set. Behaves exactly like character sets in Regexp, including set negation ([^a-z]).
<code></code> Escapes the next metacharacter.

ftype

Identifies the type of the named file; the return string is one of “file”, “directory”, “characterSpecial”, “blockSpecial”, “fifo”, “link”, “socket”, or “unknown”. Ruby File method.

Ruby syntax:

File.ftype(fileName)

JavaScript syntax:

Rho.File.ftype(fileName)
fileName String. The name of the file.

grpowned?, is_grpowned

Returns true if the named file exists and the effective group id of the calling process is the owner of the file. Returns false on Windows. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.grpowned?(fileName)

JavaScript syntax:

Rho.File.is_grpowned(fileName)
fileName String. The name of the file.

identical?, is_identical

Returns true if the named files are identical. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.identical?(fileName, fileName2)

JavaScript syntax:

Rho.File.is_identical(fileName, fileName2)
fileName String. The name of the first file.
fileName String. The name of the second file.

join

Returns a new string formed by joining the given strings. Ruby File method.

Ruby syntax:

File.join(part1, part2, ...)

JavaScript syntax:

Rho.File.join(part1, part2, ...)
part1, part2, ... Strings. The parts of the string to form.

lchmod

Equivalent to File.chmod, but does not follow symbolic links (so it will change the permissions associated with the link, not the file referenced by the link). Often not available. Returns the number of files processed. Ruby File method.

Ruby syntax:

File.lchmod(mode, fileName, fileName2, ...)

JavaScript syntax:

Rho.File.lchmod(mode, fileName, fileName2, ...)
mode Bit pattern for the permission bits.
fileName, fileName2, ... String. The file name(s) to be processed. fileName2 ... are optional.

lchown

Equivalent to File.chown, but does not follow symbolic links (so it will change the owner associated with the link, not the file referenced by the link). Often not available. Returns number of files in the argument list. Ruby File method.

Ruby syntax:

File.lchown(user, group, fileName, fileName2, ...)

JavaScript syntax:

Rho.File.lchown(user, group, fileName, fileName2, ...)
owner Integer. The user id.
group Integer. The group id.
fileName, fileName2, ... String. The file name(s) to be processed. fileName2 ... are optional.

link

Creates a new name for an existing file using a hard link. Will not overwrite newName if it already exists (raising a subclass of SystemCallError). Not available on all platforms. Ruby File method.

Use the fail continuation to catch error exemptions.

Ruby syntax:

File.link(oldName, newName)

JavaScript syntax:

Rho.File.link(oldName, newName)
oldName String. The old file name.
newName Integer. The new file name.

lstat

Same as File.stat, but does not follow the last symbolic link. Instead, reports on the link itself. Returns a hash object of Strings: the path and the file.extension. Ruby File method.

Ruby syntax:

File.lstat(fileName)

JavaScript syntax:

Rho.File.lstat(fileName)
fileName String. The file name.

mtime

Returns the modification time for the named file as a Date object. Ruby File method.

Ruby syntax:

File.mtime(fileName)

JavaScript syntax:

Rho.File.mtime(fileName)
fileName String. The file name.

open

Opens the file named by fileName according to mode (default is “r”) and returns a new File object. Ruby File method.

For information about the permission bits, refer to the Ruby File method and to the UNIX manual for open(2).

Ruby syntax:

File.open(fileName, mode, permission)

JavaScript syntax:

Rho.File.open(fileName, mode, permission)
fileName String. The file name.
mode Optional. The mode in which to open the file. Platform dependent.
permission Optional. Permission bits. Platform dependent.

mode values:

r Read-only, starts at beginning of file (default mode).
r+ Read-write, starts at beginning of file
w Write-only, truncates existing file to zero length or creates a new file for writing.
w+ Read-Write, truncates existing file to zero length or creates a new file for reading and writing.
a Write-only, starts at end of file if file exists, otherwise creates a new file for writing.
a+ Read-write, starts at end of file if file exists, otherwise creates a new file for writing.
t Text file mode (may appear with any of the key letters listed above). Forced.

owned?, is_owned

Returns true if the named file exists and the effective used id of the calling process is the owner of the file. Returns null if this feature is not supported on the device platform. Ruby File method.

JavaScript syntax:

File.owned?(fileName)

JavaScript syntax:

Rho.File.is_owned(fileName)
fileName String. The file name.

path

Returns the string representation of the path to the named file. Ruby File method.

JavaScript syntax:

File.path(fileName)

JavaScript syntax:

Rho.File.path(fileName)
fileName String. The file name.

pipe?, is_pipe

Returns true if the named file is a pipe. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.pipe?(fileName)

JavaScript syntax:

Rho.File.is_pipe(fileName)
fileName String. The file name.

readable?, is_readable

Returns true if the named file is readable by the effective user id of this process. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.readable?(fileName)

JavaScript syntax:

Rho.File.is_readable(fileName)
fileName String. The file name.

readable_real?, is_readable_real

Returns true if the named file is readable by the real user id of this process. Returns null if this feature is not supported on the device platform. Ruby File method.

JavaScript syntax:

File.readable_real?(fileName)

JavaScript syntax:

Rho.File.is_readable_real(fileName)
fileName String. The file name.

readlink

Returns a String: the name of the file referenced by the given link. Not available on all platforms. Ruby File method.

Ruby syntax:

File.readlink(link)

JavaScript syntax:

Rho.File.readlink(link)
link String. The link.

realdirpath

Returns a String: the real (absolute) pathname of pathName in the actual filesystem. The real pathname doesn’t contain symlinks or useless dots. Ruby File method.

Ruby syntax:

File.realdirpath(pathName, dirString)

JavaScript syntax:

Rho.File.realdirpath(pathName, dirString)
link String. The path name. The last component of the path name can be nonexistent.
link String. Optional. Used as a base directory for interpreting relative pathname instead of the current directory.

realpath

Returns a String: the real (absolute) pathname of pathname in the actual filesystem not containing symlinks or useless dots. Ruby File method.

JavaScript syntax:

File.realpath(pathName, dirString)

JavaScript syntax:

Rho.File.realpath(pathName, dirString)
link String. The path name. All components of the path name must exist when this method is called.
link String. Optional. Used as a base directory for interpreting relative pathname instead of the current directory.

rename

Renames the given file to the new name. Returns a SystemCallError if the file cannot be renamed. Ruby File method.

Ruby syntax:

File.rename(oldName, newName)

JavaScript syntax:

Rho.File.rename(oldName, newName)
oldName String. The file name.
link String. The new file name.

setgid?, is_setgid

Returns true if the named file has the setgid bit set. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.setgid?(fileName)

JavaScript syntax:

Rho.File.is_setgid(fileName)
fileName String. The file name.

setuid?, is_setuid

Returns true if the named file has the setuid bit set. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.setuid?(fileName)

JavaScript syntax:

Rho.File.is_setuid(fileName)
fileName String. The file name.

size

Returns the size of the named file. Ruby File method.

Ruby syntax:

File.size(fileName)

JavaScript syntax:

Rho.File.size(fileName)
fileName String. The file name.

size?, is_size

Returns nil if the named file doesn’t exist or has zero size, the size of the file otherwise. Returns null if this feature is not supported on the device platform. Ruby File method.

JavaScript syntax:

File.size?(fileName)

JavaScript syntax:

Rho.File.is_size(fileName)
fileName String. The file name.

socket?, is_socket

Returns true if the named file is a socket. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.socket?(fileName)

JavaScript syntax:

Rho.File.is_socket(fileName)
fileName String. The file name.

split

Splits the given string into a directory and a file component and returns them in a two-element array. See also File.dirname and File.basename. Ruby File method.

Ruby syntax:

File.split(fileName)

JavaScript syntax:

Rho.File.split(fileName)
fileName String. The file name.

stat

Returns a hash object. For information about the structure of the hash object, refer to the Ruby File::Stat method and to the UNIX manual for stat(2).

Ruby File method.

Ruby syntax:

File.stat(fileName)

JavaScript syntax:

Rho.File.stat(fileName)
fileName String. The file name.

sticky?, is_sticky

Returns true if the named file has the sticky bit set. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.sticky?(fileName)

JavaScript syntax:

Rho.File.is_sticky(fileName)
fileName String. The file name.

symlink

Creates a symbolic link called newName for the existing file oldName. Returns a NotImplemented exception on platforms that do not support symbolic links. Ruby File method.

Use the fail continuation to catch error exemptions.

Ruby syntax:

File.symlink(oldName, newName)

JavaScript syntax:

Rho.File.symlink(oldName, newName)
oldName String. The file name.
newName String. The symbolic link to create.

symlink?, is_symlink

Returns true if the named file is a symbolic link. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.symlink?(fileName)

JavaScript syntax:

Rho.File.is_symlink(fileName)
fileName String. The file name.

truncate

Truncates the file fileName to be at most integer bytes long. Not available on all platforms. Ruby File method.

Ruby syntax:

Rho.File.truncate(fileName, length)

JavaScript syntax:

Rho.File.truncate(fileName, length)
fileName String. The file name.
length Number. The number of bytes in the truncated file.

unmask

Returns the current umask value for this process. Umask values are subtracted from the default permissions, so a umask of 0222 would make a file read-only for everyone. Ruby File method.

Ruby syntax:

File.umask(mask)

JavaScript syntax:

Rho.File.umask(mask)
mask Number. Optional. If the optional mask argument is given, set the umask to that value and return the previous value.

unlink

An alias method to do_delete: deletes the named files, returning the number of names passed as arguments. A JavaScript implementation of the Ruby File method.

Ruby syntax:

File.unlink(fileName, fileName2, ...)

JavaScript syntax:

Rho.File.unlink(fileName, fileName2, ...)
fileName, fileName2, ... String. The names of the file(s) to be deleted. fileName2 ... are optional.

utime

Sets the access and modification times of the named file to the first two arguments. Returns the number of file names in the argument list. Ruby File method.

Ruby syntax:

File.utime(atime, mtime, fileName, fileName2, ...)
atime Date. The access time.
mtime Date. The modification time.
fileName, fileName2, ... String. The names of the file(s). fileName2 ... are optional.

world_readable?, is_world_readable

If fileName is readable by others, returns an integer representing the file permission bits of fileName. Returns nil otherwise. Ruby File method.

For information about the permission bits, refer to the Ruby File method and to the UNIX manual for stat(2).

Ruby syntax:

File.world_readable?(fileName)

JavaScript syntax:

Rho.File.is_world_readable(fileName)
fileName String. The file name.

world_writable?, is_world_writable

If fileName is writable by others, returns an integer representing the file permission bits of fileName. Returns nil otherwise. Ruby File method.

For information about the permission bits, refer to the Ruby File method and to the UNIX manual for stat(2).

Ruby syntax:

File.world_writable(fileName)

JavaScript syntax:

Rho.File.is_world_writable(fileName)
fileName String. The file name.

writable?, is_writable

Returns true if the named file is writable by the effective user id of this process. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.writable?(fileName)

JavaScript syntax:

Rho.File.is_writable(fileName)
fileName String. The file name.

writable_real?, is_writable_real

Returns true if the named file is writable by the effective user id of this process. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.writable_real?(fileName)

JavaScript syntax:

Rho.File.is_writable_real(fileName)
fileName String. The file name.

zero?, is_zero

Returns true if the named file exists and has a zero size. Returns null if this feature is not supported on the device platform. Ruby File method.

Ruby syntax:

File.zero?(fileName)

JavaScript syntax:

Rho.File.is_zero(fileName)
fileName String. The file name.

File Object Instance Methods

You can use the following File object Instance methods, taken from the {Ruby IO class](http://www.ruby-doc.org/core-1.9.3/IO.html).

getId

Returns the

Returns a Number: the id of this file object.

JavaScript syntax:

Rho.fileObject.getId()

getc

Returns a one character string, or null if at the end of a file. Click for the Ruby method.

Ruby syntax:

fileObject.getc()

JavaScript syntax:

Rho.fileObject.getc()

ungetc

Pushes back one character (passed as a parameter) onto ios, such that a subsequent buffered character read will return it. Click for the Ruby method.

Ruby syntax:

fileObject.ungetc(character)

JavaScript syntax:

Rho.fileObject.ungetc(character)
character String. A one character string.

gets

Reads the next “line” from the I/O stream. Click for the Ruby method.

Ruby syntax:

fileObject.gets(separatorOrLimit, limit)

JavaScript syntax:

Rho.fileObject.gets(separatorOrLimit, limit)
separatorOrLimit String, Number, or null. A separator.
limit Number. Optional. A limit.

putc

Returns a Number or a one character String. If obj is Numeric, write the character whose code is the least-significant byte of obj, otherwise write the first byte of the string representation of obj to ios. Click for the Ruby method.

Ruby syntax:

fileObject.putc(character)

JavaScript syntax:

Rho.fileObject.putc(charcter)
character one character String or Number.

puts

Writes the given objects to ios as with IO#print. Writes a record separator (typically a newline) after any that do not already end with a newline sequence. Click for the Ruby method.

Ruby syntax:

fileObject.puts(string1, string2, ...)

JavaScript syntax:

Rho.fileObject.puts(string1, string2, ...)
string1, string2, ... Objects to wriite. string2, ... is optional..

flush

Flushes any buffered data within ios to the underlying operating system. Click for the Ruby method.

Ruby syntax:

fileObject.flush

JavaScript syntax:

Rho.fileObject.flush()

close

Closes ios and flushes any pending writes to the operating system. Click for the Ruby method.

Ruby syntax:

fileObject.close

JavaScript syntax:

Rho.fileObject.close()
Back to Top