class Novika::CapabilityCollection

Overview

A collection of language capability implementations.

Capability implementations can indirectly (by id) interact with each other by sharing the capability collection they're members of.

# (!) Compile with -Dnovika_console

caps = CapabilityCollection.new

# Add capability classes:
caps << Capabilities::Impl::Essential
caps << Capabilities::Impl::System
caps << Capabilities::Impl::Console

# Enable capabilities. At this point you kinda don't know
# which implementation is used under the hood, so you
# need to refer to the capability by its id.
caps.enable("essential")
caps.enable("system")
caps.enable("console")

block = Block.new(caps.block)
block.slurp("console:on 1000 nap console:off")

Engine.exhaust(block, caps)

Defined in:

novika/capability.cr

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.new(parent : Block | Nil = nil) #

[View source]

Class Method Detail

def self.available : Array(ICapabilityClass) #

Lists all available (registered) capability classes.

For a capability class to be registered (available), it should be the last subclass of a Capability includer (subclass depth is irrelevant), or have no subclasses and directly include Capability.


[View source]
def self.with_available #

Creates a capability collection, and adds all available capabilities (see CapabilityCollection.available). Does not enable any of them.

Returns the resulting capability collection.


[View source]
def self.with_default #

Creates a capability collection, and adds capabilities that are on by default. Doesn't enable any. Returns the resulting capability collection.


[View source]

Instance Method Detail

def <<(cls : ICapabilityClass) #

Adds a capability class cls to this collection.


[View source]
def <<(library : Library) #

Adds a library to this collection. Overwrites any previous library with the same id.


[View source]
def []?(cls : T.class) : T | Nil forall T #

Returns the instance of the given capability class cls, if such instance can be found in this collection. Otherwise, returns nil.


[View source]
def block : Block #

Returns the capability block: a block managed by this collection, which includes the vocabulary injected by the enabled capabilities.


[View source]
def copy : CapabilityCollection #

Copies this capability collection.

  • This collection shares library load callbacks (themselves, not the list of them) with the returned collection.

  • This collection shares FFI Library instances with the returned one, by reference.

  • This collection shares capability block parent (see .new) with the returned one, by reference.

Everything else is copied or created anew.


[View source]
def enable(id : String) : Bool #

Enables a capability with the given id.

To enable a capability means to create an instance of the corresponding implementation class, and use that instance to inject the capability vocabulary into this collection's capabilities block, #block. You can then access #block and e.g. inherit from it to access the vocabulary of the enabled capabilities.

Does nothing if the capability is already enabled. Does nothing if there is no capability with the given id.

Returns whether there is a capability with the given id.


[View source]
def enable_all #

Enables all capabilities unconditionally.

Returns self.


[View source]
def enable_default #

Enables all capabilities that respond with true when sent ICapabilityClass#on_by_default?.

For capabilities that respond with false, you'll need to target them explicitly with #enable(id), or use #enable_all instead of #enable_default.

Returns self.


[View source]
def enabled #

Returns an array of capabilities that are enabled in this collection at the moment.


[View source]
def fetch(cls : T.class, & : T -> U) : U | Nil forall T, U #

Yields the capability instance of the given capability class cls to the block, if such instance can be found in this collection.

Returns the result of the block, or nil.


[View source]
def get_capability_class?(id : String) #

Returns the capability class with the given id. Returns nil if there is no such capability class in this collection.


[View source]
def get_library?(id : String) #

Returns the library with the given id. Returns nil if there is no such library in this collection.


[View source]
def has_capability?(id : String) #

Returns whether this collection includes a capability with the given id.


[View source]
def has_capability_enabled?(id : String) #

Returns whether this collection has the capability with the given id enabled.


[View source]
def has_library?(id : String) #

Returns whether this collection includes a library with the given id.


[View source]
def load_library?(id : String) : Library | Nil #

Tries to load a library (aka shared object) with the given id. Returns the resulting Library object, or nil.

The library object is cached: further calls to #load_library? and #get_library? will return that library object.


[View source]
def on_load_library?(callback : String -> Library | Nil) #

Subscribes callback to library load requests, so that whenever the runtime needs a library, callback gets a chance to be invoked and load it.

callback is only going to be invoked if all previously defined callbacks failed (returned nil).

callback should return a Library if it successfully loaded it; otherwise, it should return nil.


[View source]
def on_load_library?(&callback : String -> Library | Nil) #

Subscribes callback to library load requests, so that whenever the runtime needs a library, callback gets a chance to be invoked and load it.

callback is only going to be invoked if all previously defined callbacks failed (returned nil).

callback should return a Library if it successfully loaded it; otherwise, it should return nil.


[View source]