Expand description
⚠️ Master branch is unstable, use at your own risk
About rhai-fs
This crate provides filesystem access for the Rhai scripting language.
Usage
Cargo.toml
[dependencies]
rhai-fs = "0.1"Rhai script
// Create a file or open and truncate it already created
let file = open_file(path("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(path("Cargo.toml"), "r").read_string()"#)?;
println!("{}", contents);
Ok(())
}Features
| Feature | Default | Description |
|---|---|---|
no_index | disabled | Enables support for no_index builds of Rhai |
+
+(path: PathBuf, str: ImmutableString) -> PathBuf
+(path1: PathBuf, path2: PathBuf) -> PathBuf
+=(path1: PathBuf, path2: PathBuf)
append(path1: PathBuf, path2: PathBuf)
bytes(file: SharedFile) -> rhai::INT
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(path: PathBuf) -> ()
Recursively create a directory and all of its parent components if they are missing.
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.
is_absolute(path: PathBuf) -> bool
Returns true if the Path is absolute, i.e., if it is independent of the current directory.
is_dir(path: PathBuf) -> bool
Returns true if the path exists on disk and is pointing at a directory.
is_file(path: PathBuf) -> bool
Returns true if the path exists on disk and is pointing at a regular file.
is_relative(path: PathBuf) -> bool
Returns true if the Path is relative, i.e., not absolute.
is_symlink(path: PathBuf) -> bool
Returns true if the Path is relative, i.e., not absolute.
open_dir(path: PathBuf) -> rhai::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_raw: ImmutableString) -> SharedFile
Creates or opens a file for reading and writing.
open_file(path: PathBuf) -> SharedFile
Creates or opens a file for reading and writing.
open_file(path_raw: ImmutableString, 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: 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) -> rhai::INT
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_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(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: ImmutableString) -> ()
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.
seek(file: SharedFile, pos: i64) -> rhai::INT
Sets the stream to the provided position, relative to the start of the file.
Throws an exception when:
- Seeking to a negative position.
to_debug(path: PathBuf) -> String
to_string(path: PathBuf) -> String
write
write(file: SharedFile, blob: Blob) -> rhai::INT
Writes the blob into the file at the current stream position.
write(file: SharedFile, str: &str) -> rhai::INT
Writes the string into the file at the current stream position.
Throws an exception when:
- The write function encounters an I/O error.