Crate rhai_fs 

About rhai-fs

This crate provides filesystem access for the Rhai scripting language.

Usage

Cargo.toml

[dependencies]
rhai-fs = "0.1.5"

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:

+

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

+(path1: PathBuf, path2: PathBuf) -> 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: PathBuf)

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

create_dir(path_raw: String)

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

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: 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_dir(path_raw: String) -> Array

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

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_raw: String, options: &str) -> SharedFile

Helper function for open_file(path, options) 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

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.

remove_dir

remove_dir(path_raw: String)

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

remove_dir(path: PathBuf)

Removes an empty directory.

Throws an exception when:

• 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.

set_file_len(file: SharedFile, len: i64) -> i64

Resizes the file to the specified length.

If len is less than the current file size, the file will be truncated. If len is greater than the current file size, the file will be extended and the new portion filled with zeros.

to_debug(path: PathBuf) -> String

to_string(path: PathBuf) -> String

truncate_file(file: SharedFile) -> i64

Truncates the file to zero size.

write(file: SharedFile, str: &str) -> i64

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

Throws an exception when:

• 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.