RubyGateway 6.1.1 docs
(100% documented)
Open on GitHub Open in Dash

RbFailableAccess

Swift
public struct RbFailableAccess

A way to call Ruby methods and so on with a different error-handling style to the try/catch approach of RbObjectAccess: the methods return nil in failure cases instead of throwing errors. Get hold of this failable interface using RbObject.failable or RbGateway.failable:

if let classObj = Ruby.failable.getClass("Mod::Service"),
   let instance = classObj.failable.call("new"),
   let result = instance.failable.get("summary") {
   print(result)
}

This interface makes it easier to ignore errors especially on setters where there is often no apparent need to check the result. This may be construed as a feature; I’m not really convinced it pulls its weight over try?.

If any methods in this interface do return nil then an RbError has been raised and suppressed. You can access the most recent RbErrors whether suppressed or not via RbError.history.

Topics

Method Call

Call a method of a Ruby object.

This is a non-throwing version of RbObjectAccess.call(_:args:kwArgs:). See RbError.history to retrieve error details.

Declaration
Swift
public func call(
    _ method: String,
    args: [(any RbObjectConvertible)?] = [],
    kwArgs: KeyValuePairs<String, (any RbObjectConvertible)?> = [:]
) -> RbObject?
Parameters
method

The name of the method to call.
args

The positional arguments to the method, none by default.
kwArgs

The keyword arguments to the method, none by default.
Return Value

An RbObject for the result of the method, or nil if an error occurred.

Call a method of a Ruby object passing Swift code as a block used immediately.

This is a non-throwing version of RbObjectAccess.call(_:args:kwArgs:blockCall:). See RbError.history to retrieve error details.

Declaration
Swift
public func call(
    _ method: String,
    args: [(any RbObjectConvertible)?] = [],
    kwArgs: KeyValuePairs<String, (any RbObjectConvertible)?> = [:],
    blockCall: RbBlockCallback
) -> RbObject?
Parameters
method

The name of the method to call.
args

The positional arguments to the method, none by default.
kwArgs

The keyword arguments to the method, none by default.
blockCall

Swift code to pass as a block to the method.
Return Value

An RbObject for the result of the method, or nil if an error occurred.

Call a method of a Ruby object passing Swift code as a block.

This is a non-throwing version of RbObjectAccess.call(_:args:kwArgs:blockRetention:blockCall:). See RbError.history to retrieve error details.

Declaration
Swift
public func call(
    _ method: String,
    args: [(any RbObjectConvertible)?] = [],
    kwArgs: KeyValuePairs<String, (any RbObjectConvertible)?> = [:],
    blockRetention: RbBlockRetention,
    blockCall: @escaping @Sendable RbBlockCallback
) -> RbObject?
Parameters
method

The name of the method to call.
args

The positional arguments to the method, none by default.
kwArgs

The keyword arguments to the method, none by default.
blockRetention

Should the blockCall closure be retained for longer than this call? See RbBlockRetention.
blockCall

Swift code to pass as a block to the method.
Return Value

An RbObject for the result of the method, or nil if an error occurred.

Call a method of a Ruby object passing a Ruby Proc as a block.

This is a non-throwing version of RbObjectAccess.call(_:args:kwArgs:block:). See RbError.history to retrieve error details.

Declaration
Swift
public func call(
    _ method: String,
    args: [(any RbObjectConvertible)?] = [],
    kwArgs: KeyValuePairs<String, (any RbObjectConvertible)?> = [:],
    block: any RbObjectConvertible
) -> RbObject?
Parameters
method

The name of the method to call.
args

The positional arguments to the method, none by default.
kwArgs

The keyword arguments to the method, none by default.
block

A Ruby proc to pass as a block to the method.
Return Value

An RbObject for the result of the method, or nil if an error occurred.

Call a method of a Ruby object using a symbol.

This is a non-throwing version of RbObjectAccess.call(symbol:args:kwArgs:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func call(
    symbol: any RbObjectConvertible,
    args: [(any RbObjectConvertible)?] = [],
    kwArgs: KeyValuePairs<String, (any RbObjectConvertible)?> = [:]
) -> RbObject?
Parameters
symbol

A symbol for the method to call.
args

The positional arguments to the method, none by default.
kwArgs

The keyword arguments to the method, none by default.
Return Value

An RbObject for the result of the method, or nil if an error occurred.

Call a method of a Ruby object using a symbol passing Swift code as a block used immediately.

This is a non-throwing version of RbObjectAccess.call(symbol:args:kwArgs:blockCall:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func call(
    symbol: any RbObjectConvertible,
    args: [(any RbObjectConvertible)?] = [],
    kwArgs: KeyValuePairs<String, (any RbObjectConvertible)?> = [:],
    blockCall: RbBlockCallback
) -> RbObject?
Parameters
symbol

A symbol for the method to call.
args

The positional arguments to the method, none by default.
kwArgs

The keyword arguments to the method, none by default.
blockCall

Swift code to pass as a block to the method.
Return Value

An RbObject for the result of the method, or nil if an error occurred.

Call a method of a Ruby object using a symbol passing Swift code as a block.

This is a non-throwing version of RbObjectAccess.call(symbol:args:kwArgs:blockRetention:blockCall:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func call(
    symbol: any RbObjectConvertible,
    args: [(any RbObjectConvertible)?] = [],
    kwArgs: KeyValuePairs<String, (any RbObjectConvertible)?> = [:],
    blockRetention: RbBlockRetention = .none,
    blockCall: @escaping @Sendable RbBlockCallback
) -> RbObject?
Parameters
symbol

A symbol for the method to call.
args

The positional arguments to the method, none by default.
kwArgs

The keyword arguments to the method, none by default.
blockRetention

Should the blockCall closure be retained for longer than this call? See RbBlockRetention.
blockCall

Swift code to pass as a block to the method.
Return Value

An RbObject for the result of the method, or nil if an error occurred.

Call a method of a Ruby object using a symbol passing a Ruby Proc as a block.

This is a non-throwing version of RbObjectAccess.call(symbol:args:kwArgs:block:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func call(
    symbol: any RbObjectConvertible,
    args: [(any RbObjectConvertible)?] = [],
    kwArgs: KeyValuePairs<String, (any RbObjectConvertible)?> = [:],
    block: any RbObjectConvertible
) -> RbObject?
Parameters
symbol

A symbol for the method to call.
args

The positional arguments to the method, none by default.
kwArgs

The keyword arguments to the method, none by default.
block

A Ruby proc to pass as a block to the method.
Return Value

An RbObject for the result of the method, or nil if an error occurred.

Attributes

Get an attribute of a Ruby object.

This is a non-throwing version of RbObjectAccess.getAttribute(_:). See RbError.history to retrieve error details.

Declaration
Swift
public func getAttribute(_ name: String) -> RbObject?
Parameters
name

The attribute to access.
Return Value

The value of the attribute, or nil if an error occurred.

Set an attribute of a Ruby object.

This is a non-throwing version of RbObjectAccess.setAttribute(_:newValue:). See RbError.history to retrieve error details.

Declaration
Swift
public func setAttribute(_ name: String, newValue: (any RbObjectConvertible)?)
    -> RbObject?
Parameters
name

The attribute to set.
newValue

The new value for the attribute.
Return Value

The value set to the attribute, or nil if an error occurred.

Constants

Get an RbObject that represents a Ruby constant.

This is a non-throwing version of RbObjectAccess.getConstant(_:). See RbError.history to retrieve error details.

Declaration
Swift
public func getConstant(_ name: String) -> RbObject?
Parameters
name

The name of the constant to look up.
Return Value

An RbObject for the constant or nil if an error occurred.

Get an RbObject that represents a Ruby class.

This is a non-throwing version of RbObjectAccess.getClass(_:). See RbError.history to retrieve error details.

Declaration
Swift
public func getClass(_ name: String) -> RbObject?
Parameters
name

The name of the class to look up.
Return Value

An RbObject for the class or nil if an error occurred.

Bind an object to a constant name.

This is a non-throwing version of RbObjectAccess.setConstant(_:newValue:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func setConstant(_ name: String, newValue: (any RbObjectConvertible)?)
    -> RbObject?
Parameters
name

The name of the constant to create or replace.
newValue

The value for the constant.
Return Value

The value set for the constant or nil if an error occurred.

Instance Variables

Get the value of a Ruby instance variable.

This is a non-throwing version of RbObjectAccess.getInstanceVar(_:). See RbError.history to retrieve error details.

Declaration
Swift
public func getInstanceVar(_ name: String) -> RbObject?
Parameters
name

Name of the IVar. Must begin with a single @.
Return Value

Value of the IVar, or nil if an error occurred.

Set a Ruby instance variable.

This is a non-throwing version of RbObjectAccess.setInstanceVar(_:newValue:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func setInstanceVar(_ name: String, newValue: (any RbObjectConvertible)?)
    -> RbObject?
Parameters
name

Name of the IVar. Must begin with a single @.
newValue

The new value for the IVar.
Return Value

The value that was set, or nil if an error occurred.

Class Variables

Get the value of a Ruby class variable.

Must be called on an RbObject for a class, or RbGateway.

This is a non-throwing version of RbObjectAccess.getClassVar(_:). See RbError.history to retrieve error details.

Declaration
Swift
public func getClassVar(_ name: String) -> RbObject?
Parameters
name

Name of the CVar. Must begin with @@.
Return Value

Value of the CVar, or nil if an error occurred.

Set or create a Ruby class variable.

Must be called on an RbObject for a class, or RbGateway.

This is a non-throwing version of RbObjectAccess.setClassVar(_:newValue:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func setClassVar(_ name: String, newValue: (any RbObjectConvertible)?)
    -> RbObject?
Parameters
name

Name of the CVar. Must begin with @@.
newValue

The new value for the CVar.
Return Value

The value that was set, or nil if an error occurred.

Global Variables

Get the value of a Ruby global variable.

This is a non-throwing version of RbObjectAccess.getGlobalVar(_:). See RbError.history to retrieve error details.

Declaration
Swift
public func getGlobalVar(_ name: String) -> RbObject?
Parameters
name

Name of the global variable. Must begin with $.
Return Value

Value of the variable, or nil if an error occurred.

Set a Ruby global variable.

This is a non-throwing version of RbObjectAccess.setGlobalVar(_:newValue:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func setGlobalVar(_ name: String, newValue: (any RbObjectConvertible)?)
    -> RbObject?
Parameters
name

Name of the global variable. Must begin with $.
newValue

The new value for the variable.
Return Value

The value that was set, or nil if an error occurred.

Polymorphic Getter

Get some kind of Ruby object based on the name parameter.

This is a non-throwing version of RbObjectAccess.get(_:). See RbError.history to retrieve error details.

Declaration
Swift
@discardableResult
public func get(_ name: String) -> RbObject?
Parameters
name

Name of method / IVar / attribute / CVar / GVar / constant to access.
Return Value

Retrieved object, or nil if an error occurred.