JSDoc: Module: files

The fwlib/files module includes utility functions for working with files. Where the methods accept a path parameter, you can pass in either a path string or an array of strings that make up the path. The array will be combined into a single string with a single / between each part of the path. This means you don't have to worry about whether the substrings end or begin with a / when building up a path. For example:

files.readJSON([fw.appJsCommandsDir, "settings.json"]);

This call works even though fw.appJsCommandsDir doesn't end in a /.

Source:

lib/fwlib/files.js, line 5

Requires

module:dojo/json

Methods

<static> append

Appends a string to the end of a text file.

Parameters:

Name	Type	Description
`inFilePath`	String \| Array	The path to the file to read.
`inText`	String	The string to append to the file.

Source:

lib/fwlib/files.js, line 204

Returns:

True if the text could be appended, false otherwise.

Type: Boolean

<static> convertURLToOSPath

Returns a path that's appropriate for the local OS. Most Fireworks path arguments are URLs that begin with file://, which can't be used in the OS X or Windows shells. For instance, "file:///C|/Program%20Files/Adobe" would be returned as "C:\Program Files\Adobe". Escaped characters in the URL are unescaped in the returned path. By default, the path is also wrapped in quotes, so that spaces in the path don't trip up the command line shell.

Parameters:

Name	Type	Argument	Default	Description
`inURL`	String \| Array			The file URL to convert.
`inDontQuote`	Boolean	<optional>	false	Pass true to prevent the returned path from being quoted.

Source:

lib/fwlib/files.js, line 595

Returns:

The OS appropriate version of the file URL.

Type: String

<static> copyDirectoryContents

Copies all the files from one directory to directory. The source directory will be copied recursively.

Parameters:

Name	Type	Description
`inFromPath`	String \| Array	The path to the source directory.
`inToPath`	String \| Array	The path to the destination directory. If this directory doesn't exist, it will be created, but only if the last directory in the path doesn't exist. If directories further up the path don't exist, then the call will fail. For example, if `file://path/to/a` exists, then passing `file://path/to/a/folder` will create the `folder` directory. But if only `file://path/to` exists, the call will fail.

Source:

lib/fwlib/files.js, line 407

<static> createTempDirectory

Returns the path to a newly created directory in the local system's temp folder.

Source:

lib/fwlib/files.js, line 521

Returns:

The path to the new temp directory or null if there was a problem creating the directory.

Type: String

<static> getCreatedDate

Returns a Date object containing the date and time the file was created.

Parameters:

Name	Type	Description
`inFilePath`	String \| Array	The path to the file.

Source:

lib/fwlib/files.js, line 315

Returns:

The creation date of the file, or null if the file doesn't exist.

Type: Date

<static> getCurrentScriptDirectory

Returns the path to the directory that contains the script that called the function.

Parameters:

Name	Type	Description
`inFunction`	Function	A function that is guaranteed to throw an exception. The simplest is `function(){0()}`.

Source:

lib/fwlib/files.js, line 489

See:

getCurrentScriptURL

Returns:

The path to the directory containing script that defined inFunction.

Type: String

<static> getCurrentScriptFilename

Returns the name of the script that called the function.

Parameters:

Name	Type	Description
`inFunction`	Function	A function that is guaranteed to throw an exception. The simplest is `function(){0()}`.

Source:

lib/fwlib/files.js, line 506

See:

getCurrentScriptURL

Returns:

The filename of the script that defined inFunction.

Type: String

<static> getCurrentScriptURL

Returns the file:// URL to the script file that called the function. In complicated scripts, it's often useful to load other scripts that are located in the same directory or nearby directories. Normally, you can access the current script's path via fw.currentScriptDir, but that value becomes null after one script calls another via fw.runScript().

The getCurrentScriptURL() function works around this by exploiting the fact that JS exceptions in Fireworks have a fileName property that points to the script that was executing when the exception occurred. So you can pass in a function that is guaranteed to throw an exception when it is called. getCurrentScriptURL() will call the function, catch the exception, and then return the path to your script. Hackery!

Parameters:

Name	Type	Description
`inFunction`	Function	A function that is guaranteed to throw an exception. The simplest is `function(){0()}`.

Source:

lib/fwlib/files.js, line 458

Returns:

The path to the script that defined inFunction.

Type: String

<static> getModifiedDate

Returns a Date object containing the date and time the file was last modified.

Parameters:

Name	Type	Description
`inFilePath`	String \| Array	The path to the file.

Source:

lib/fwlib/files.js, line 331

Returns:

The last modified date of the file, or null if the file doesn't exist.

Type: Date

<static> getSize

Returns the size of the file in bytes.

Parameters:

Name	Type	Argument	Default	Description
`inPath`	String \| Array			The path to the file.
`inUnit`	String	<optional>	""	An optional unit in which to report the file size. This parameter can be `"B"`, `"KB"`, `"GB"`, or `"TB"`. The size will be returned with the thousands separated by commas and the unit value added to the end, e.g. `"12,420 KB"`.

Source:

lib/fwlib/files.js, line 351

Returns:

The size of the file in bytes, or -1 if the file doesn't exist. If a value is passed in inUnit, the size is returned as a string.

Type: Number | String

<static> path

Returns a path that is made up of the arguments to the function. There is guaranteed to be only one slash between each argument, so so calling files.path("foo/bar", "My Command.jsf") will return "foo/bar/My Command.jsf". This avoids having to constantly check whether a directory path you have stored in a variable has a trailing / or not.

You can also pass in a single array of strings that will be combined in the same way. This is mostly used by the other functions in this module, which can take either a string or an array of strings for their path arguments.

Parameters:

Name	Type	Description
`arguments`	String \| Array	Two or more strings to combine into a path, or a single array of strings.

Source:

lib/fwlib/files.js, line 551

Returns:

A path created from the combination of the arguments.

Type: String

<static> read

Returns the contents of a text file. If the file does not exist, an empty string is returned.

Parameters:

Name	Type	Description
`inFilePath`	String \| Array	The path to the file to read.

Source:

lib/fwlib/files.js, line 79

Returns:

The text contents of the file.

Type: String | Array

<static> readChunks

Reads the contents of a text file one chunk at a time, passing each chunk to the inCallback parameter. If the file does not exist, the callback will never be called.

        The file reading is done synchronously, but breaking the reads up
        into chunks may sometimes be more efficient for very long files.
        You can also return `false` from the callback to stop reading the
        file part way through.

Parameters:

Name	Type	Description
`inFilePath`	String \| Array	The path to the file to read.
`inChunkSize`	Number=8192	The number of bytes to read per chunk.
`inCallback`	Function	A function that will be called after each chunk is read from the file. The function is called with two parameters: a string containing the most recent chunk and a number indicating the position of the beginning of the current chunk within the file. Return `false` from the callback to stop reading the file. Note that the last chunk in the file may be less than `inChunkSize` bytes long.

Source:

lib/fwlib/files.js, line 130

<static> readJSON

Returns the contents of a JSON file as a JS object. An object passed in via the inDefaultData param will have its properties overridden by the data from the JSON file. If the file does not exist, inDefaultData is returned unmodified.

Parameters:

Name	Type	Argument	Default	Description
`inFilePath`	String \| Array			The path to the file to read.
`inDefaultData`	Object	<optional>	null	An object holding default properties that will be overriden by the JSON data.

Source:

lib/fwlib/files.js, line 242

Returns:

The JSON object from the file.

Type: Object

<static> write

Writes a string to a text file. It will overwrite a file that already exists at the path. The text is always written out in UTF-8 format, rather than ISO-8859-1, so that accented characters are reproduced correctly.

Parameters:

Name	Type	Argument	Default	Description
`inFilePath`	String \| Array			The path to the file to write to. The full path to the new file must already exist, or the call will fail.
`inText`	String			The string to write to the file.
`inIncludeBOM`	Boolean	<optional>	false	Pass true to create the file with a UTF-8 byte order mark at the beginning of the file.

Source:

lib/fwlib/files.js, line 177

<static> writeJSON

Writes a JS object to a JSON text file. The JSON is pretty-printed by default.

Parameters:

Name	Type	Argument	Default	Description
`inFilePath`	String \| Array			The path to the file to write to.
`inData`	Object			The object to convert to JSON.
`inSpacer`	String	<optional>	"\t"	An optional string that is used to indent the JSON output. The default value is "\t". Because the Fireworks `file.readline()` method returns null if a line is longer than 2047 characters, you will generally want to use a spacer string to force the JSON output to include only one property per line. This makes the file slightly larger but it also makes it more likely that the JSON can be read back in by Fireworks successfully.

Source:

lib/fwlib/files.js, line 291