Avidemux 2.6 Scripting Reference
 All Classes Functions Enumerations Enumerator Properties Groups Pages
Public Types | Public Member Functions | Properties | List of all members
File Class Reference

The File class provides an interface for reading from and writing to files. More...

Public Types

enum  FileError {
  NoError = 0, ReadError = 1, WriteError = 2, FatalError = 3,
  ResourceError = 4, OpenError = 5, AbortError = 6, TimeOutError = 7,
  UnspecifiedError = 8, RemoveError = 9, RenameError = 10, PositionError = 11,
  ResizeError = 12, PermissionsError = 13, CopyError = 14
}
 Describes the errors that may be returned by the File.error property. More...
enum  OpenMode {
  NotOpen = 0x0000, ReadOnly = 0x0001, WriteOnly = 0x0002, ReadWrite = ReadOnly | WriteOnly,
  Append = 0x0004, Truncate = 0x0008, Text = 0x0010, Unbuffered = 0x0020
}
 Used with open() to describe the mode in which a file is opened. It is also returned by the File.openMode property. More...
enum  Permission {
  ReadOwner = 0x4000, WriteOwner = 0x2000, ExeOwner = 0x1000, ReadUser = 0x0400,
  WriteUser = 0x0200, ExeUser = 0x0100, ReadGroup = 0x0040, WriteGroup = 0x0020,
  ExeGroup = 0x0010, ReadOther = 0x0004, WriteOther = 0x0002, ExeOther = 0x0001
}
 Used by the File.permission property to report the permissions and ownership of a file. More...

Public Member Functions

Boolean canReadLine ()
 Returns true if a complete line of data can be read from the device; otherwise returns false.
void close ()
 Closes the file and sets its File.openMode to File::NotOpen. The error string is also reset.
Boolean copy (String newName)
 Copies the file currently specified by File.fileName to a file called newName.
Boolean exists ()
 Returns true if the file specified by File.fileName exists; otherwise false.
 File (String name)
 Constructs a new file object to represent the file with the given name.
Boolean flush ()
 Flushes any buffered data to the file.
Boolean link (String linkName)
 Creates a link named linkName that points to the file currently specified by File.fileName.
Boolean open (OpenMode mode)
 Opens the file and sets its File.openMode to mode.
String peek (Number maxSize)
 Peeks at most maxSize bytes from the file, returning the data peeked.
String read (Number maxSize)
 Reads and returns at most maxSize bytes from the file.
String readAll ()
 Reads and returns all available data from the file.
String readLine (Number maxSize=0)
 Reads and returns a line from the file but no more than maxSize characters.
Boolean remove ()
 Removes the file specified by File.fileName.
Boolean rename (String newName)
 Renames the file currently specified by File.fileName to newName.
Boolean reset ()
 Seeks to the start of the file.
Boolean resize (Number size)
 Sets the file size (in bytes).
Boolean seek (Number pos)
 Sets the current position to pos.
Boolean setPermissions (Permission permissions)
 Sets the permissions for the file to the permissions specified.
void setTextModeEnabled (Boolean enabled)
 If enabled, this function sets the Text flag on the file; otherwise the Text flag is removed.
String symLinkTarget ()
 Returns the absolute path of the file or directory that a symlink (or shortcut on Windows) points to. An empty string is returned if the object isn't a symbolic link.
void unsetError ()
 Sets the file's error to File::NoError.
Number write (String data)
 Writes the passed content to the file.

Properties

Boolean atEnd
 Returns true if the current read and write position is at the end of the file (i.e. there is no more data available for reading); otherwise returns false.
Number bytesAvailable
 Returns the number of bytes that are available for reading.
Number bytesToWrite
 For buffered devices, this function returns the number of bytes waiting to be written. For devices with no buffer, this function returns 0.
FileError error
 Returns the file error status.
String errorString
 Returns a human-readable description of the last file error that occurred.
String fileName
 Returns the name set by the File constructor.
Boolean isOpen
 Returns true if the file is open; otherwise false.
Boolean isReadable
 Returns true if data can be read from the file; otherwise false.
Boolean isSequential
 Returns true if this file is sequential; otherwise false.
Boolean isTextModeEnabled
 Returns true if the File.Text flag is enabled; otherwise false.
Boolean isWritable
 Returns true if data can be written to the file; otherwise false.
OpenMode openMode
 Returns the mode in which the file has been opened; i.e. File::ReadOnly or File::WriteOnly.
Permission permissions
 Returns the OR-ed combination of File::Permission for the file.
Number position
 Returns the position that data is written to or read from.
Number size
 Returns the size of the file.

Detailed Description

The File class provides an interface for reading from and writing to files.

Member Enumeration Documentation

enum FileError

Describes the errors that may be returned by the File.error property.

Enumerator:
NoError 

No error occurred.

ReadError 

An error occurred when reading from the file.

WriteError 

An error occurred when writing to the file.

FatalError 

A fatal error occurred.

ResourceError 

A resource error occurred.

OpenError 

The file could not be opened.

AbortError 

The operation was aborted.

TimeOutError 

A timeout occurred.

UnspecifiedError 

An unspecified error occurred.

RemoveError 

The file could not be removed.

RenameError 

The file could not be renamed.

PositionError 

The position in the file could not be changed.

ResizeError 

The file could not be resized.

PermissionsError 

The file could not be accessed.

CopyError 

The file could not be copied.

enum OpenMode

Used with open() to describe the mode in which a file is opened. It is also returned by the File.openMode property.

Enumerator:
NotOpen 

The file is not open.

ReadOnly 

The file is open for reading.

WriteOnly 

The file is open for writing.

ReadWrite 

The file is open for reading and writing.

Append 

The file is opened in append mode, so that all data is written to the end of the file.

Truncate 

If possible, the file is truncated before it is opened. All earlier contents of the file are lost.

Text 

When reading, the end-of-line terminators are translated to '\n'. When writing, the end-of-line terminators are translated to the local encoding, for example '\r\n' for Microsoft Windows.

Unbuffered 

Any buffer in the device is bypassed.

enum Permission

Used by the File.permission property to report the permissions and ownership of a file.

The values may be OR-ed together to test multiple permissions and ownership values.

Enumerator:
ReadOwner 

The file is readable by the owner of the file.

WriteOwner 

The file is writable by the owner of the file.

ExeOwner 

The file is executable by the owner of the file.

ReadUser 

The file is readable by the user.

WriteUser 

The file is writable by the user.

ExeUser 

The file is executable by the user.

ReadGroup 

The file is readable by the group.

WriteGroup 

The file is writable by the group.

ExeGroup 

The file is executable by the group.

ReadOther 

The file is readable by anyone.

WriteOther 

The file is writable by anyone.

ExeOther 

The file is executable by anyone.

Member Function Documentation

Boolean canReadLine ( )

Returns true if a complete line of data can be read from the device; otherwise returns false.

Note that unbuffered devices, which have no way of determining what can be read, always return false.

Boolean copy ( String  newName)

Copies the file currently specified by File.fileName to a file called newName.

The source file is closed before it is copied.

Returns
Returns true if successful; otherwise false. Note that if a file with the name newName already exists, copy() returns false (i.e. File will not overwrite it).
Boolean flush ( )

Flushes any buffered data to the file.

Returns
Returns true if successful; otherwise false.
Boolean link ( String  linkName)

Creates a link named linkName that points to the file currently specified by File.fileName.

What a link is depends on the underlying filesystem (be it a shortcut on Windows or a symbolic link on Unix). Note: To create a valid link on Windows, linkName must have a .lnk file extension.

Returns
Returns true if successful; otherwise false. This function will not overwrite an already existing entity in the file system; in this case, link() will return false and set the File.error property to return File::RenameError.
Boolean open ( OpenMode  mode)

Opens the file and sets its File.openMode to mode.

Returns
Returns true if successful; otherwise false.
String peek ( Number  maxSize)

Peeks at most maxSize bytes from the file, returning the data peeked.

This function has no way of reporting errors; returning an empty String can mean either that no data was currently available for peeking, or that an error occurred.

Boolean remove ( )

Removes the file specified by File.fileName.

The file is closed before it is removed.

Returns
Returns true if successful; otherwise false.
Boolean rename ( String  newName)

Renames the file currently specified by File.fileName to newName.

The file is closed before it is renamed.

Returns
Returns true if successful; otherwise false. If a file with the name newName already exists, rename() returns false (i.e., File will not overwrite it).
Boolean reset ( )

Seeks to the start of the file.

Returns
Returns true on success; otherwise false (for example, if the file is closed).
Boolean resize ( Number  size)

Sets the file size (in bytes).

Note: if the specified size is larger than the file's current size then the file is truncated to 0 bytes.

Returns
Returns true if the resize succeeds; otherwise false.
Boolean seek ( Number  pos)

Sets the current position to pos.

Returns
Returns true on success, or false if an error occurred.
Boolean setPermissions ( Permission  permissions)

Sets the permissions for the file to the permissions specified.

Returns
Returns true if successful; otherwise false if the permissions cannot be modified.
String symLinkTarget ( )

Returns the absolute path of the file or directory that a symlink (or shortcut on Windows) points to. An empty string is returned if the object isn't a symbolic link.

This name may not represent an existing file; it is only a string. File::exists() returns true if the symlink points to an existing file.

Number write ( String  data)

Writes the passed content to the file.

Returns
Returns the number of bytes that were actually written or -1 if an error occurred.

Property Documentation

FileError error
read

Returns the file error status.

The I/O device status returns an error code. For example, if open() returns false, or a read/write operation returns -1, this function can be called to find out the reason why the operation failed.

Boolean isOpen
read

Returns true if the file is open; otherwise false.

A file is open if it can be read from and/or written to. This property returns false if File.openMode returns File::NotOpen.

Boolean isReadable
read

Returns true if data can be read from the file; otherwise false.

Use bytesAvailable() to determine how many bytes can be read. This is a convenience function which checks if the File.openMode of the file contains the File::ReadOnly flag.

Boolean isWritable
read

Returns true if data can be written to the file; otherwise false.

This is a convenience function which checks if the File.openMode of the file contains the File::WriteOnly flag.