Skip to main content
Version: 2.2.5

File

file.contents​

Read the whole contents of a file.

Type:

(string) -> string

Arguments:

  • (unlabeled) (of type string)

file.copy​

Copy a file. Arguments and implementation follows the POSIX cp command line specifications.

Type:

(?recursive : bool, ?force : bool, ?preserve : bool, string, string) -> unit

Arguments:

  • recursive (of type bool, which defaults to false): Copy file hierarchies.
  • force (of type bool, which defaults to false): If a file descriptor for a destination file cannot be obtained attempt to unlink the destination file and proceed.
  • preserve (of type bool, which defaults to false): Duplicate source files attributes in the destination file.
  • (unlabeled) (of type string): Source
  • (unlabeled) (of type string): Destination

file.digest​

Return an MD5 digest for the given file.

Type:

(string) -> string

Arguments:

  • (unlabeled) (of type string)

file.download​

Download file using a regular http.get request. Returns true on success.

Type:

(filename : string, ?timeout : float, string) -> bool

Arguments:

  • filename (of type string): Downloaded filename.
  • timeout (of type float, which defaults to 5.): Timeout in seconds
  • (unlabeled) (of type string)

file.exists​

Returns true if the file or directory exists.

Type:

(string) -> bool

Arguments:

  • (unlabeled) (of type string)

file.extension​

Returns a file's extension.

Type:

(?dir_sep : string, ?leading_dot : bool, string) -> string

Arguments:

  • dir_sep (of type string, which defaults to "/"): Directory separator.
  • leading_dot (of type bool, which defaults to true): Return extension with a leading dot, e.g. .foo.
  • (unlabeled) (of type string)

file.getter​

Getter to the contents of a file.

Type:

(string) -> () -> string

Arguments:

  • (unlabeled) (of type string): Name of the file from which the contents should be taken.

file.getter.float​

Float getter from a file.

Type:

(?default : float, string) -> {float}

Arguments:

  • default (of type float, which defaults to 0.): Default value when the file contains invalid data.
  • (unlabeled) (of type string): Name of the file from which the contents should be taken.

file.is_directory​

Returns true if the file exists and is a directory.

Type:

(string) -> bool

Arguments:

  • (unlabeled) (of type string)

file.iterator​

Iterate over the contents of a file.

Type:

(string) -> () -> string?

Arguments:

  • (unlabeled) (of type string)

file.lines​

Get the list of lines of a file.

Type:

(string) -> [string]

Arguments:

  • (unlabeled) (of type string)

file.lines.iterator​

Iterate over the lines of a file.

Type:

(string) -> () -> string?

Arguments:

  • (unlabeled) (of type string)

file.ls​

List all the files in a directory.

Type:

(?absolute : bool, ?recursive : bool, ?pattern : string?, ?sorted : bool,
 string) -> [string]

Arguments:

  • absolute (of type bool, which defaults to false): Whether to return absolute paths.
  • recursive (of type bool, which defaults to false): Whether to look recursively in subdirectories.
  • pattern (of type string?, which defaults to null): Pattern that the filenames should match (e.g. "*.mp3").
  • sorted (of type bool, which defaults to false): Return results in a sorted order.
  • (unlabeled) (of type string): Directory to look in.

file.metadata​

Read metadata from a file.

Type:

(string, ?exclude : [string]) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.
  • exclude (of type [string], which defaults to []): Decoders to exclude

file.metadata.ffmpeg​

Read metadata from a file using the ffmpeg decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.flac​

Read metadata from a file using the flac decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.flac_native​

Read metadata from a file using the flac_native decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.id3​

Read metadata from a file using the id3 decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.id3v1​

Read metadata from a file using the id3v1 decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.id3v2​

Read metadata from a file using the id3v2 decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.image​

Read metadata from a file using the image decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.mp4​

Read metadata from a file using the mp4 decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.native​

Read metadata from a file using the native decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.ogg​

Read metadata from a file using the ogg decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.ogg_native​

Read metadata from a file using the ogg_native decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.taglib​

Read metadata from a file using the taglib decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.metadata.video-metadata​

Read metadata from a file using the video-metadata decoder.

Type:

(string) -> [string * string]

Arguments:

  • (unlabeled) (of type string): File from which the metadata should be read.

file.mime​

Get a file's mime type. Uses libmagic if enabled, otherwise try to get the value using the file binary. Returns null() if no value can be found.

Type:

(string) -> string?

Arguments:

  • (unlabeled) (of type string): The file to test

file.mime.cli​

Get a file's mime type by calling the file command line binary.

Type:

(string) -> string?

Arguments:

  • (unlabeled) (of type string)

file.mime.magic​

Get the MIME type of a file.

Type:

(string) -> string

Arguments:

  • (unlabeled) (of type string)

file.mkdir​

Create a directory.

Type:

(?perms : int, string) -> unit

Arguments:

  • perms (of type int, which defaults to 493): Default file rights if created (default is 0o755).
  • (unlabeled) (of type string)

file.move​

Move a file

Type:

(?force : bool, string, string) -> unit

Arguments:

  • force (of type bool, which defaults to false): Do not prompt for confirmation if the destination path exists.
  • (unlabeled) (of type string): Source
  • (unlabeled) (of type string): Destination

file.mtime​

Last modification time.

Type:

(string) -> float

Arguments:

  • (unlabeled) (of type string)

file.open​

Open a file.

Type:

(?write : bool, ?create : bool?, ?append : bool, ?non_blocking : bool,
 ?perms : int, string) -> socket

Arguments:

  • write (of type bool, which defaults to false): Open file for writing
  • create (of type bool?, which defaults to null): Create if nonexistent. Default: false in read-only mode, true when writing.
  • append (of type bool, which defaults to false): Append data if file exists.
  • non_blocking (of type bool, which defaults to false): Open in non-blocking mode.
  • perms (of type int, which defaults to 420): Default file rights if created. Default: 0o644
  • (unlabeled) (of type string)

Methods:

  • close (of type () -> unit): Close the socket.
  • non_blocking (of type (bool) -> unit): Set the non-blocking flag on the socket
  • read (of type ((?timeout : float?) -> string) .{wait : (?timeout : float?, (() -> unit)) -> unit}): Read data from a socket. Reading is done when the function returns an empty string "".
  • type (of type string): Socket type
  • write (of type ((?timeout : float?, string) -> unit) .{wait : (?timeout : float?, (() -> unit)) -> unit}): Write data to a socket

file.read​

Read the content of a file. Returns a function of type ()->string. File is done reading when function returns the empty string "".

Type:

(string) -> () -> string

Arguments:

  • (unlabeled) (of type string)

file.remove​

Remove a file.

Type:

(string) -> unit

Arguments:

  • (unlabeled) (of type string)

file.replaygain​

Compute the ReplayGain for a file (in dB).

Type:

(?id : string?, ?ratio : float, string) -> float?

Arguments:

  • id (of type string?, which defaults to null)
  • ratio (of type float, which defaults to 50.): Decoding ratio. A value of 50 means try to decode the file 50x faster than real time, if possible. Use this setting to lower CPU peaks when computing replaygain tags.
  • (unlabeled) (of type string): File name.

file.rmdir​

Remove a directory and its content.

Type:

(string) -> unit

Arguments:

  • (unlabeled) (of type string)

file.size​

File size in bytes.

Type:

(string) -> int

Arguments:

  • (unlabeled) (of type string)

file.temp​

Return a fresh temporary filename. The temporary file is created empty, with permissions 0o600 (readable and writable only by the file owner).

Type:

(?cleanup : bool, string, string) -> string

Arguments:

  • cleanup (of type bool, which defaults to false): Delete the file on shutdown
  • (unlabeled) (of type string): File suffix
  • (unlabeled) (of type string): File prefix

file.temp_dir​

Return a fresh temporary directory name. The temporary directory is created empty, in the default tmp directory, with permissions 0o700 (readable, writable and listable only by the file owner).

Type:

(?cleanup : bool, string, ?string) -> string

Arguments:

  • cleanup (of type bool, which defaults to false): Delete the file on shutdown
  • (unlabeled) (of type string): Directory name suffix.
  • (unlabeled) (of type string, which defaults to ""): Directory name prefix.

file.touch​

Ensure that a file exists, creating it empty if it does not.

Type:

(?perms : int, string) -> unit

Arguments:

  • perms (of type int, which defaults to 420)
  • (unlabeled) (of type string): Path of the file.

file.umask​

Get the process's file mode creation mask.

Type:

() -> int

file.umask.set​

Set process's file mode creation mask.

Type:

(int) -> unit

Arguments:

  • (unlabeled) (of type int)

file.watch​

Call a function when a file is modified. Returns unwatch function in unwatch method.

Type:

(string, (() -> unit)) -> unit

Arguments:

  • (unlabeled) (of type string): File to watch.
  • (unlabeled) (of type () -> unit): Handler function.

Methods:

  • unwatch (of type () -> unit): Function to remove the watch on the file.

file.which​

file.which("progname") looks for an executable named "progname" using directories from the PATH environment variable and returns "" if it could not find one.

Type:

(string) -> string?

Arguments:

  • (unlabeled) (of type string)

file.write​

Write data to a file.

Type:

(data : {string?}, ?perms : int, ?append : bool, string) -> unit

Arguments:

  • data (of type {string?}): Data to write. If passing a callback () -> string?, the callback must return null or "" when it has finished sending all its data.
  • perms (of type int, which defaults to 420): Default file rights if created. Default: 0o644.
  • append (of type bool, which defaults to false): Append data if file exists.
  • (unlabeled) (of type string): Path to write to

file.write.stream​

Stream data to a file. Returns a callback to write to the file. Execute with null or "" to signify the end of the writing operation.

Type:

(?perms : int, ?append : bool, string) -> (string?) -> unit

Arguments:

  • perms (of type int, which defaults to 420): Default file rights if created. Default: 0o644.
  • append (of type bool, which defaults to false): Append data if file exists.
  • (unlabeled) (of type string): Path to write to

medialib​

A library to store the metadata of files in given folders and query them. This is useful to generate playlists based on metadata.

Type:

(?id : string?, ?persistency : string?, ?refresh : float?,
 ?standardize : (([string * string]) -> [string * string]),
 ?initial_progress : bool, ?directories : [string], ?string?) -> unit

Arguments:

  • id (of type string?, which defaults to null)
  • persistency (of type string?, which defaults to null): Store the database in given file, which is reuse to populate the database on next run.
  • refresh (of type float?, which defaults to null): Scan directories for new files every given number of seconds (by default the database is never updated).
  • standardize (of type ([string * string]) -> [string * string], which defaults to <fun>): Function mapped on metadata when indexing. It can be used to change the field names to standard ones, pretreat data, etc.
  • initial_progress (of type bool, which defaults to true): Show progress of library being indexed at startup.
  • directories (of type [string], which defaults to []): Directories to look for files in.
  • (unlabeled) (of type string?, which defaults to null): Directory to look for files in.

Methods:

  • add_directory (of type (string) -> unit): Add a new directory which should be scanned.
  • clear (of type () -> unit): Remove all known metadata.
  • find (of type (?case_sensitive : bool, ?artist : string?, ?artist_contains : string?, ?artist_matches : string?, ?album : string?, ?genre : string?, ?title : string?, ?title_contains : string?, ?filename : string?, ?filename_contains : string?, ?filename_matches : string?, ?year : int?, ?year_ge : int?, ?year_lt : int?, ?bpm : int?, ?bpm_ge : int?, ?int?, ?predicate : (([string * string]) -> bool)) -> [string]): Find files according to conditions on metadata.
  • refresh (of type () -> unit): Update metadatas and look for new files.

path.basename​

Get the base name of a path, i.e. the name of the file without the full path. For instance file.basename("/tmp/folder/bla.mp3") returns "bla.mp3".

Type:

(string) -> string

Arguments:

  • (unlabeled) (of type string)

path.concat​

Concatenate two paths, using the appropriate directory separator.

Type:

(string, string) -> string

Arguments:

  • (unlabeled) (of type string)
  • (unlabeled) (of type string)

path.dirname​

Get the directory name of a path.

Type:

(string) -> string

Arguments:

  • (unlabeled) (of type string)

path.home.unrelate​

Expand path that start with '~' with the current home directory.

Type:

(string) -> string

Arguments:

  • (unlabeled) (of type string)

path.remove_extension​

Remove the file extension from a path.

Type:

(string) -> string

Arguments:

  • (unlabeled) (of type string)

playlist.files​

Retrieve the list of files contained in a playlist.

Type:

(?id : string?, ?mime_type : string?, ?timeout : float,
 ?cue_in_metadata : string?, ?cue_out_metadata : string?, string) -> 
[string]

Arguments:

  • id (of type string?, which defaults to null)
  • mime_type (of type string?, which defaults to null): Default MIME type for the playlist. null means automatic detection.
  • timeout (of type float, which defaults to 20.): Timeout for resolving the playlist
  • cue_in_metadata (of type string?, which defaults to "liq_cue_in"): Metadata for cue in points. Disabled if null.
  • cue_out_metadata (of type string?, which defaults to "liq_cue_out"): Metadata for cue out points. Disabled if null.
  • (unlabeled) (of type string): Path to the playlist

socket.unix.client​

Open a named UNIX socket and connect as a client.

Type:

(?non_blocking : bool, string) -> socket

Arguments:

  • non_blocking (of type bool, which defaults to false): Open in non-blocking mode.
  • (unlabeled) (of type string)

Methods:

  • close (of type () -> unit):
  • read (of type ((?timeout : float?) -> string) .{wait : (?timeout : float?, (() -> unit)) -> unit}):
  • type (of type string):
  • write (of type ((?timeout : float?, string) -> unit) .{wait : (?timeout : float?, (() -> unit)) -> unit}):

socket.unix.listen​

Open a named socket and wait for a client to connect

Type:

(?non_blocking : bool, string) -> socket

Arguments:

  • non_blocking (of type bool, which defaults to false): Open in non-blocking mode.
  • (unlabeled) (of type string)

Methods:

  • close (of type () -> unit):
  • read (of type ((?timeout : float?) -> string) .{wait : (?timeout : float?, (() -> unit)) -> unit}):
  • type (of type string):
  • write (of type ((?timeout : float?, string) -> unit) .{wait : (?timeout : float?, (() -> unit)) -> unit}):