diff --git a/versioned_docs/version-latest/04-standard-library/10-fs/_category_.yml b/versioned_docs/version-latest/04-standard-library/10-fs/_category_.yml new file mode 100644 index 000000000..65ad7acb9 --- /dev/null +++ b/versioned_docs/version-latest/04-standard-library/10-fs/_category_.yml @@ -0,0 +1,3 @@ +label: File System +collapsible: true +collapsed: true diff --git a/versioned_docs/version-latest/04-standard-library/10-fs/api-reference.md b/versioned_docs/version-latest/04-standard-library/10-fs/api-reference.md new file mode 100644 index 000000000..94165bf99 --- /dev/null +++ b/versioned_docs/version-latest/04-standard-library/10-fs/api-reference.md @@ -0,0 +1,653 @@ +--- +title: API reference +id: api-reference +description: Wing standard library API reference for the fs module +keywords: [Wing sdk, sdk, Wing API Reference] +hide_title: true +sidebar_position: 100 +--- + + + +# API Reference + + +## Classes + +### Fs + +The fs class is used for interacting with the file system. + +All file paths must be POSIX file paths (/ instead of \), +and will be normalized to the target platform if running on Windows. + +#### Initializers + +```wing +bring fs; + +new fs.Util(); +``` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | + +--- + + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| basename | Retrieve the final segment of a given file path. | +| dirname | Retrieve the name of the directory from a given file path. | +| exists | Check if the path exists. | +| join | Join all arguments together and normalize the resulting path. | +| mkdir | Create a directory. | +| mkdtemp | Create a temporary directory. | +| readdir | Read the contents of the directory. | +| readFile | Read the entire contents of a file. | +| readJson | Read the contents of the file and convert it to JSON. | +| readYaml | Convert all YAML objects from a single file into JSON objects. | +| relative | Solve the relative path from {from} to {to} based on the current working directory. | +| remove | Remove files and directories (modeled on the standard POSIX `rm`utility). | +| resolve | The right-most parameter is considered {to}. Other parameters are considered an array of {from}. | +| tryReaddir | If the path exists, read the contents of the directory; | +| tryReadFile | If the file exists and can be read successfully, read the entire contents; | +| tryReadJson | Retrieve the contents of the file and convert it to JSON if the file exists and can be parsed successfully, otherwise, return `undefined`. | +| tryReadYaml | Convert all YAML objects from a single file into JSON objects if the file exists and can be parsed successfully, `undefined` otherwise. | +| writeFile | Writes data to a file, replacing the file if it already exists. | +| writeJson | Writes JSON to a file, replacing the file if it already exists. | +| writeYaml | Writes multiple YAML objects to a file, replacing the file if it already exists. | + +--- + +##### `basename` + +```wing +bring fs; + +fs.basename(p: str); +``` + +Retrieve the final segment of a given file path. + +###### `p`Required + +- *Type:* str + +The path to evaluate. + +--- + +##### `dirname` + +```wing +bring fs; + +fs.dirname(p: str); +``` + +Retrieve the name of the directory from a given file path. + +###### `p`Required + +- *Type:* str + +The path to evaluate. + +--- + +##### `exists` + +```wing +bring fs; + +fs.exists(p: str); +``` + +Check if the path exists. + +###### `p`Required + +- *Type:* str + +The path to evaluate. + +--- + +##### `join` + +```wing +bring fs; + +fs.join(...paths: Array); +``` + +Join all arguments together and normalize the resulting path. + +###### `paths`Required + +- *Type:* str + +The array of path need to join. + +--- + +##### `mkdir` + +```wing +bring fs; + +fs.mkdir(dirpath: str, opts?: MkdirOptions); +``` + +Create a directory. + +###### `dirpath`Required + +- *Type:* str + +The path to the directory you want to create. + +--- + +###### `opts`Optional + +- *Type:* MkdirOptions + +--- + +##### `mkdtemp` + +```wing +bring fs; + +fs.mkdtemp(prefix?: str); +``` + +Create a temporary directory. + +Generates six random characters to be appended behind a required prefix to create a unique temporary directory. + +###### `prefix`Optional + +- *Type:* str + +The prefix for the directory to be created, default `wingtemp`. + +--- + +##### `readdir` + +```wing +bring fs; + +fs.readdir(dirpath: str); +``` + +Read the contents of the directory. + +###### `dirpath`Required + +- *Type:* str + +The path to evaluate. + +--- + +##### `readFile` + +```wing +bring fs; + +fs.readFile(filepath: str, options?: ReadFileOptions); +``` + +Read the entire contents of a file. + +###### `filepath`Required + +- *Type:* str + +The path of the file to be read. + +--- + +###### `options`Optional + +- *Type:* ReadFileOptions + +The `encoding` can be set to specify the character encoding. + +And the `flag` can be set to specify the attributes. +If a flag is not provided, it defaults to `'r'`. + +--- + +##### `readJson` + +```wing +bring fs; + +fs.readJson(filepath: str); +``` + +Read the contents of the file and convert it to JSON. + +###### `filepath`Required + +- *Type:* str + +The file path of the JSON file. + +--- + +##### `readYaml` + +```wing +bring fs; + +fs.readYaml(filepath: str); +``` + +Convert all YAML objects from a single file into JSON objects. + +###### `filepath`Required + +- *Type:* str + +The file path of the YAML file. + +--- + +##### `relative` + +```wing +bring fs; + +fs.relative(from: str, to: str); +``` + +Solve the relative path from {from} to {to} based on the current working directory. + +At times we have two absolute paths, and we need to derive the relative path from one to the other. + +###### `from`Required + +- *Type:* str + +--- + +###### `to`Required + +- *Type:* str + +--- + +##### `remove` + +```wing +bring fs; + +fs.remove(p: str, opts?: RemoveOptions); +``` + +Remove files and directories (modeled on the standard POSIX `rm`utility). + +Returns `undefined`. + +###### `p`Required + +- *Type:* str + +The path to the file or directory you want to remove. + +--- + +###### `opts`Optional + +- *Type:* RemoveOptions + +--- + +##### `resolve` + +```wing +bring fs; + +fs.resolve(...paths: Array); +``` + +The right-most parameter is considered {to}. Other parameters are considered an array of {from}. + +Starting from leftmost {from} parameter, resolves {to} to an absolute path. + +If {to} isn't already absolute, {from} arguments are prepended in right to left order, +until an absolute path is found. If after using all {from} paths still no absolute path is found, +the current working directory is used as well. The resulting path is normalized, +and trailing slashes are removed unless the path gets resolved to the root directory. + +###### `paths`Required + +- *Type:* str + +A sequence of paths or path segments. + +--- + +##### `tryReaddir` + +```wing +bring fs; + +fs.tryReaddir(dirpath: str); +``` + +If the path exists, read the contents of the directory; + +otherwise, return `undefined`. + +###### `dirpath`Required + +- *Type:* str + +The path to evaluate. + +--- + +##### `tryReadFile` + +```wing +bring fs; + +fs.tryReadFile(filepath: str, options?: ReadFileOptions); +``` + +If the file exists and can be read successfully, read the entire contents; + +otherwise, return `undefined`. + +###### `filepath`Required + +- *Type:* str + +The path of the file to be read. + +--- + +###### `options`Optional + +- *Type:* ReadFileOptions + +The `encoding` can be set to specify the character encoding, or the `flag` can be set to specify the attributes. + +--- + +##### `tryReadJson` + +```wing +bring fs; + +fs.tryReadJson(filepath: str); +``` + +Retrieve the contents of the file and convert it to JSON if the file exists and can be parsed successfully, otherwise, return `undefined`. + +###### `filepath`Required + +- *Type:* str + +The file path of the JSON file. + +--- + +##### `tryReadYaml` + +```wing +bring fs; + +fs.tryReadYaml(filepath: str); +``` + +Convert all YAML objects from a single file into JSON objects if the file exists and can be parsed successfully, `undefined` otherwise. + +###### `filepath`Required + +- *Type:* str + +The file path of the YAML file. + +--- + +##### `writeFile` + +```wing +bring fs; + +fs.writeFile(filepath: str, data: str); +``` + +Writes data to a file, replacing the file if it already exists. + +###### `filepath`Required + +- *Type:* str + +The file path that needs to be written. + +--- + +###### `data`Required + +- *Type:* str + +The data to write. + +--- + +##### `writeJson` + +```wing +bring fs; + +fs.writeJson(filepath: str, obj: Json); +``` + +Writes JSON to a file, replacing the file if it already exists. + +###### `filepath`Required + +- *Type:* str + +The file path that needs to be written. + +--- + +###### `obj`Required + +- *Type:* Json + +The JSON object to be dumped. + +--- + +##### `writeYaml` + +```wing +bring fs; + +fs.writeYaml(filepath: str, ...objs: Array); +``` + +Writes multiple YAML objects to a file, replacing the file if it already exists. + +###### `filepath`Required + +- *Type:* str + +The file path that needs to be written. + +--- + +###### `objs`Required + +- *Type:* Json + +The YANL objects to be dumped. + +--- + + + +## Structs + +### MkdirOptions + +Custom settings for creating directory. + +#### Initializer + +```wing +bring fs; + +let MkdirOptions = fs.MkdirOptions{ ... }; +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| mode | str | A file mode. | +| recursive | bool | Indicates whether parent folders should be created. | + +--- + +##### `mode`Optional + +```wing +mode: str; +``` + +- *Type:* str +- *Default:* "0777" + +A file mode. + +The string will be parsed as an octal integer. + +--- + +##### `recursive`Optional + +```wing +recursive: bool; +``` + +- *Type:* bool +- *Default:* true + +Indicates whether parent folders should be created. + +If a folder was created, the path to the first created folder will be returned. + +--- + +### ReadFileOptions + +Custom settings for reading file. + +#### Initializer + +```wing +bring fs; + +let ReadFileOptions = fs.ReadFileOptions{ ... }; +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| encoding | str | The character encoding utilized for file reading. | +| flag | str | The `flag` can be set to specify the attributes. | + +--- + +##### `encoding`Optional + +```wing +encoding: str; +``` + +- *Type:* str +- *Default:* "utf-8" + +The character encoding utilized for file reading. + +--- + +##### `flag`Optional + +```wing +flag: str; +``` + +- *Type:* str +- *Default:* 'r'. + +The `flag` can be set to specify the attributes. + +--- + +### RemoveOptions + +Custom settings for removing files and directories. + +#### Initializer + +```wing +bring fs; + +let RemoveOptions = fs.RemoveOptions{ ... }; +``` + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| force | bool | When `true`, exceptions will be ignored if `path` does not exist. | +| recursive | bool | If `true`, perform a recursive directory removal. | + +--- + +##### `force`Optional + +```wing +force: bool; +``` + +- *Type:* bool +- *Default:* false + +When `true`, exceptions will be ignored if `path` does not exist. + +--- + +##### `recursive`Optional + +```wing +recursive: bool; +``` + +- *Type:* bool +- *Default:* false + +If `true`, perform a recursive directory removal. + +In +recursive mode, operations are retried on failure. + +--- + +