For security and compatibility, it would be a good idea to provide a read-to-go example on how to show how to sandbox rhai-fs.

This can be done quite seamlessly with overloading the function path(string), as every operation must go through this singular function to create a PathBuf, unless of course you push a rust defined PathBuf to the scope.

• for blobs there is max_array_size similar to strings
• Is it a good idea to read the file and then truncate to max? The file might be deliberately made huge si you crash the engine. Maybe use a read call with length is better ...
• necessary to introduce the PathBuf type? Or just use string paths... With helpers to manipulate segments
• max_string_len etc. may be zero to indicate unlimited; you'd need to use >=0
• The limits are probably not available under unchecked so you may need an additional feature gate... Or maybe I'll make the get calls available all the time but return zero under unchecked EDIT: I've made the max_... calls available even under unchecked so you don't have to include yet another feature flag.

Unfortunately, while testing I omitted support for static namespace package registration.

let package = FilesystemPackage::new();
package.register_into_engine_as(&mut engine, "fs");

then in a rhai script:

let file = fs::open_file(fs::path("hello.txt")); 
print(file.read_string());

You will receive the following error: ErrorFunctionNotFound("read_string (SharedFile)", 3:16). This error is due to the method not being added globally, this is a really simple fix.

Currently the Blob API for reading and writing clones on each read and write, this is unneeded and should be fixable by instead of taking a mutable reference to SharedFile, take a mutable reference to a Blob, SharedFile is already behind a reference so cloning that is fine.

The new API could look like so: file.read_blob() (Kept for convenience) blob.read_from_file(file) blob.read_from_file(file, len) blob.write_to_file(file)

I suggest we standardize on doc-comment sections similar to Rust's to make it easier for other tools to parse the docs in the future.

/// Main paragraph of comments.
///
/// Secondary info...  multiple lines and/or paragraphs.
///
/// # Parameters
///
/// ... docs on parameters, if needed
/// ... for simple parameters, the separate section may be omitted
///
/// # Returns
///
/// ... docs on value returned, if any
/// ... for simple values, the separate section may be omitted
///
/// # Errors
///
/// ... potential errors (if any)
/// ... always a good idea to make error info explicit
///
/// # Exceptions
///
/// ...  potential exceptions (if any)
/// ... always a good idea to make error info explicit
///
/// # Example
///
/// ... example code
///
/// # See Also
///
/// ... Rust std links etc. if any

It would be nice to have links to every rust std api used directly within the docs for the api.

For example: https://github.com/rhaiscript/rhai-fs/blob/896ea06cd3480ddc420b7b833dd3b2eb57841300/src/path.rs#L14-L22

Becomes:

/// 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. 
///
/// See [std::env::current_dir](https://doc.rust-lang.org/std/env/fn.current_dir.html) for more information.
#[rhai_fn(return_raw)] 
pub fn cwd() -> Result<std::path::PathBuf, Box<EvalAltResult>> { 
   std::env::current_dir().map_err(|e| e.to_string().into()) 
}