| Avidemux 2.6 Scripting Reference

- Main Page
- Modules
- Classes
- Examples

- Class List
- Class Index
- Class Hierarchy
- Class Members

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.