Struct Rubylib

pub struct Rubylib { /* private fields */ }

Available on crate feature rubylib-native-file-system-loader only.

A Ruby source code loader that searches in paths given by the RUBYLIB environment variable.

MRI Ruby allows manipulating the require search path by setting the RUBYLIB environment variable before launching the Ruby CLI. The RUBYLIB variable is read on start-up and is expected to contain a platform-native path separator-delimited list of file system paths.

This loader will attempt to resolve relative paths in any of the paths given in RUBYLIB. Absolute paths are rejected by this loader.

This loader tracks the files it has loaded, which MRI refers to as “loaded features”. This loader deduplicates loaded features be detecting whether the given path resolves to the same file as a previously loaded path.

The RUBYLIB environment variable or other sequence of paths is parsed when this loader is created and is immutable.

This loader resolves files in the search paths in the order the directories appear in the RUBYLIB environment variable. Paths earlier in the sequence have higher priority.

// Grab the load paths from the `RUBYLIB` environment variable. If the
// variable is empty or unset, `None` is returned.
//
// Relative paths in `RUBYLIB` are resolved relative to the current process's
// current working directory.
let env_loader = Rubylib::new()?;

// Search `/home/artichoke/src` first, only attempting to search
// `/usr/share/artichoke` if no file is found in `/home/artichoke/src`.
//
// The relative path `./_lib` is resolved relative to the given working
// directory.
let fixed_loader = Rubylib::with_rubylib_and_cwd(
    OsStr::new("/home/artichoke/src:/usr/share/artichoke:./_lib"),
    Path::new("/home/artichoke"),
)?;

Implementations

impl Rubylib

pub fn new() -> Option<Self>

Create a new native file system loader that searches the file system for Ruby sources at the paths specified by the RUBYLIB environment variable.

The RUBYLIB environment variable is resolved once at the time this method is called and the resolved load path is immutable.

If any of the paths in the RUBYLIB environment variable are not absolute paths, they are absolutized relative to the current process’s current working directory at the time this method is called.

This source loader grants access to the host file system. The Rubylib loader does not support native extensions.

This method returns None if there are errors resolving the RUBYLIB environment variable, if the RUBYLIB environment variable is not set, if the current working directory cannot be retrieved, or if the RUBYLIB environment variable does not contain any paths.

pub fn with_rubylib(rubylib: &OsStr) -> Option<Self>

Create a new native file system loader that searches the file system for Ruby sources at the paths specified by the given rubylib platform string. rubylib is expected to be a set of file system paths that are delimited by the platform path separator.

The resolved load path is immutable.

If any of the paths in the given rubylib are not absolute paths, they are absolutized relative to the current process’s current working directory at the time this method is called.

This source loader grants access to the host file system. The Rubylib loader does not support native extensions.

This method returns None if the current working directory cannot be retrieved or if the given rubylib does not contain any paths.

pub fn with_rubylib_and_cwd(rubylib: &OsStr, cwd: &Path) -> Option<Self>

Create a new native file system loader that searches the file system for Ruby sources at the paths specified by the given rubylib platform string. rubylib is expected to be a set of file system paths that are delimited by the platform path separator.

The resolved load path is immutable.

If any of the paths in the given rubylib are not absolute paths, they are absolutized relative to the given current working directory at the time this method is called.

This source loader grants access to the host file system. The Rubylib loader does not support native extensions.

This method returns None if the given rubylib does not contain any paths.

pub fn resolve_file(&self, path: &Path) -> Option<PathBuf>

Check whether path points to a file in the virtual file system and return the absolute path if it exists.

Returns Some if the file system object pointed to by path exists. If path is relative, it is joined to each path in the RUBYLIB environment variable at the time this loader was initialized.

This method is infallible and will return None for non-existent paths.

pub fn is_file(&self, path: &Path) -> bool

Check whether path points to a file in the virtual file system.

Returns true if the file system object pointed to by path exists and is a readable file. If path is relative, it is absolutized relative to each path in the RUBYLIB environment variable at the time this loader was initialized.

This method is infallible and will return false for non-existent paths.

pub fn read_file(&self, path: &Path) -> Result<Vec<u8>>

Read file contents for the file at path.

Returns a byte vec of complete file contents. If path is relative, it is absolutized relative to each path in the RUBYLIB environment variable at the time this loader was initialized.

Errors

If path does not exist, an io::Error with error kind io::ErrorKind::NotFound is returned.

pub fn is_required(&self, path: &Path) -> Option<bool>

Check whether a file at path has been required already.

Returns true if the path is a loaded feature, false otherwise. If path is relative, it is absolutized relative to each path in the RUBYLIB environment variable at the time this loader was initialized.

This method is infallible and will return false for non-existent paths.

pub fn mark_required(&mut self, path: &Path) -> Result<()>

Mark a source at path as required on the interpreter.

This metadata is used by Kernel#require and friends to enforce that Ruby sources are only loaded into the interpreter once to limit side effects.

If path is relative, it is absolutized relative to each path in the RUBYLIB environment variable at the time this loader was initialized.

This method is infallible and will return false for non-existent paths.

Errors

If path does not exist, an io::Error with error kind io::ErrorKind::NotFound is returned.

Trait Implementations

impl Debug for Rubylib

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Rubylib

fn eq(&self, other: &Rubylib) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Rubylib

impl StructuralPartialEq for Rubylib