Libraries with Forge

Forge makes compatible Ruby libraries available to a Rubian session. Depending on the library, you can call functions, create objects and use their methods, or apply library-provided methods to ordinary values. The available interface is reported when the library is registered.

The environment must include Forge and the intended library. Registration requires the supplied administrator access. Library compatibility depends on the library version, Ruby environment and capabilities included in the package.

Inspect the available libraries#

catalog = forge_list

forge_list displays available libraries and their interfaces, and returns the registry information. Use its reported names when making calls. A failed lookup can return nil; retain the accompanying diagnostic.

In the full interactive environment, startup can prepare compatible installed libraries automatically. The startup report identifies available, skipped and unsuccessful registrations. KESTOWV_AUTO_FORGE=0, set in the launch environment before startup, disables that automatic preparation. On-demand registration remains available. Coordinate launch configuration with the administrator of a shared installation.

Register a library#

summary = forge_use('your-installed-library')

Replace the placeholder with the installed library name or an approved local library directory supplied for your evaluation. The command returns a registration summary when no function is requested. Read the reported functions, classes and value extensions before choosing how to use it. A library that supplies no callable interface is not made usable merely by appearing in a registration attempt.

forge_use(library, function, *arguments,
          name: nil, force: false, ruby: nil,
          entry_file: nil, mem_limit_bytes: nil)

fu is a shorter spelling of forge_use. Registration can take time and can fail without making the requested function available. A disconnected environment is an error, not an invitation to assume the library ran locally.

Call a function or use a value extension#

For a function shown in the catalog, use forge_call(library_name, function_name, *arguments). It returns the function's value. forge_use can also register a library and make that first call in one expression. A valid library function can return nil; inspect error output rather than interpreting every nil as failure.

Value extensions add operations to ordinary values. In a package that includes a compatible colorize library, for example:

forge_use('colorize')
puts 'Ready'.colorize(:green)

The expected visible result is colored text in a terminal that supports it. The explicit forms are forge_core_ext(library_name, value, method_name, *arguments) and forge_core_ext_use(library, value, method_name, *arguments, name: nil, force: false). Only extensions reported as available should be used.

Use classes and objects#

Registered classes can be used through their published Ruby names. A constructible class supports .new; the returned object exposes the reported instance methods. This allows compatible object-oriented libraries to participate in a Rubian workflow without reducing every interaction to a standalone function call.

A class without a public constructor must be obtained through a supported library factory or another supported operation. Undiscovered methods are unavailable. Passing one Forge-created object as an argument to another object's constructor or method is not supported in this edition. General block-taking APIs are also not implied by class support; only callbacks explicitly supported by the supplied library integration should be used.

Resolve a compatibility problem#

forge_stats supplies operating observations for the configured environment. It does not establish a performance advantage for every library. Keep the library name, version, registration result and smallest failing call when reporting a compatibility issue.