Crate rhai_fs

Expand description

About `rhai-fs`

This crate provides filesystem access for the Rhai scripting language.

Usage

`Cargo.toml`

[dependencies]
rhai-fs = "0.1.2"

Rhai script

// Create a file or open and truncate if file is already created
let file = open_file("example.txt");
let blob_buf = file.read_blob();
print("file contents: " + blob_buf);
blob_buf.write_utf8(0..=0x20, "foobar");
print("new file contents: " + blob_buf);
file.write(blob_buf);

Rust source

use rhai::{Engine, EvalAltResult};
use rhai::packages::Package;
use rhai_fs::FilesystemPackage;

fn main() -> Result<(), Box<EvalAltResult>> {
    // Create Rhai scripting engine
    let mut engine = Engine::new();

    // Create filesystem package and add the package into the engine
    let package = FilesystemPackage::new();
    package.register_into_engine(&mut engine);

    // Print the contents of the file `Cargo.toml`.
    let contents = engine.eval::<String>(r#"open_file("Cargo.toml", "r").read_string()"#)?;
    println!("{}", contents);

    Ok(())
}

Features

Feature	Default	Description
`no_index`	disabled	Enables support for `no_index` builds of Rhai
`sync`	disabled	Enables support for `sync` builds of Rhai
`metadata`	disabled	Enables support for generating package documentation

API

The following functions are defined in this package:

`+`

`+(path1: PathBuf, path2: PathBuf) -> PathBuf`

`+(path: PathBuf, str: &str) -> PathBuf`

`+=(path1: PathBuf, path2: PathBuf)`

`append(path1: PathBuf, path2: PathBuf)`

`bytes(file: SharedFile) -> i64`

Returns the size of the file, in bytes.

`canonicalize(path: PathBuf) -> PathBuf`

Returns the canonical, absolute form of the path with all intermediate components normalized and symbolic links resolved.

`create_dir`

`create_dir(path_raw: String)`

Helper function for create_dir that takes a string instead of PathBuf.

`create_dir(path: PathBuf)`

Recursively create a directory and all of its parent components if they are missing.

`cwd() -> PathBuf`

Returns path to current working directory.

Throws an exception when:

The current working directory does not exist.
The process lacks the permissions to access the current working directory.

property get `exists(path: PathBuf) -> bool`

Returns true if path points to something in the filesystem (a file or directory) so long as the current process can access it.

property get `is_absolute(path: PathBuf) -> bool`

Returns true if the Path is absolute, i.e., if it is independent of the current directory.

property get `is_dir(path: PathBuf) -> bool`

Returns true if the path exists on disk and is pointing at a directory.

property get `is_file(path: PathBuf) -> bool`

Returns true if the path exists on disk and is pointing at a regular file.

property get `is_relative(path: PathBuf) -> bool`

Returns true if the Path is relative, i.e., not absolute.

property get `is_symlink(path: PathBuf) -> bool`

Returns true if the Path is relative, i.e., not absolute.

`open_dir`

`open_dir(path_raw: String) -> Array`

Helper function for open_dir that takes a string instead of PathBuf.

`open_dir(path: PathBuf) -> Array`

Returns an array of paths in the directory.

Throws an exception when:

The provided path doesn’t exist.
The provided path isn’t a directory.
The process lacks permissions to view the contents.

`open_file`

`open_file(path: PathBuf) -> SharedFile`

Creates or opens a file for reading and writing.

`open_file(path_raw: String) -> SharedFile`

Helper function for open_file(path) that takes a string instead of PathBuf.

`open_file(path: PathBuf, options: &str) -> SharedFile`

Available options for opening a file.

Flag	Access	Creation
r	Read only	No
r+	Read & write	No
w	Write only	Yes
wx	Write only	Required
w+	Read & write	Yes
a	Append only	Yes
ax	Append only	Required
a+	Read & append	Yes
ax+	Read & append	Required

`open_file(path_raw: String, options: &str) -> SharedFile`

Helper function for open_file(path, options) that takes a string instead of PathBuf.

`path(path: &str) -> PathBuf`

Creates a path from the passed string.

`position(file: SharedFile) -> i64`

Returns the current stream position.

`push(path1: PathBuf, path2: PathBuf)`

`read_blob`

`read_blob(file: SharedFile) -> Blob`

Reads from the current stream position until EOF and returns it as a Blob, respects the engine’s max_array_size.

`read_blob(file: SharedFile, len: i64) -> Blob`

Reads from the current stream position up to the passed len and returns it as a Blob, respects the engine’s max_array_size.

`read_from_file(blob: Blob, mut file: SharedFile) -> i64`

Reads from the current stream position into the provided Blob with the read length being returned.

`read_string`

`read_string(file: SharedFile) -> String`

Reads from the current stream position until EOF and returns it as a string, respects the engine’s max_string_size.

Throws an exception when:

The read function encounters an I/O error.

`read_string(file: SharedFile, len: i64) -> String`

Reads from the current stream position up to the passed len and returns it as a string, respects the engine’s max_string_size.

Throws an exception when:

The read function encounters an I/O error.

The provided path doesn’t exist.
The provided path isn’t a directory.
The process lacks permissions to remove the directory.
The directory isn’t empty.

`remove_file(path: PathBuf)`

Remove a file at the given path.

Throws an exception when:

The path points to a directory.
The file doesn’t exist.
The user lacks permissions to remove the file.

`remove_file_str(path_raw: String)`

Helper function for remove_file that takes a string instead of PathBuf.

`seek(file: SharedFile, pos: i64) -> i64`

Sets the stream to the provided position, relative to the start of the file.

Throws an exception when:

Seeking to a negative position.

The write function encounters an I/O error.

`write_to_file(blob: Blob, mut file: SharedFile) -> i64`

Writes the blob into the file at the current stream position.

Structs

FilesystemPackage
Package for filesystem manipulation operations.