# World

The “world” represents all Lilv state, and is used to discover/load/cache LV2 data (plugins, UIs, and extensions). Normal hosts which just need to load plugins by URI should simply use `lilv_world_load_all()` to discover/load the system’s LV2 resources.

LilvWorld *lilv_world_new(void)

  Initialize a new, empty world.

  If initialization fails, NULL is returned.

void lilv_world_set_option(LilvWorld *world, const char *uri, const LilvNode *value)

  Set an option for `world`.

  Currently recognized options:

  - `LILV_OPTION_FILTER_LANG`

  - `LILV_OPTION_DYN_MANIFEST`

  - `LILV_OPTION_LV2_PATH`

void lilv_world_free(LilvWorld *world)

  Destroy the world.

  It is safe to call this function on NULL. Note that destroying `world` will destroy all the objects it contains. Do not destroy the world until you are finished with all objects that came from it.

void lilv_world_load_all(LilvWorld *world)

  Load all installed LV2 bundles on the system.

  This is the recommended way for hosts to load LV2 data. It implements the established/standard best practice for discovering all LV2 data on the system. The environment variable LV2_PATH may be used to control where this function will look for bundles.

  Hosts should use this function rather than explicitly load bundles, except in special circumstances such as development utilities, or hosts that ship with special plugin bundles which are installed to a known location.

void lilv_world_load_bundle(LilvWorld *world, const LilvNode *bundle_uri)

  Load a specific bundle.

  `bundle_uri` must be a fully qualified URI to the bundle directory, with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/

  Normal hosts should not need this function (use `lilv_world_load_all()`).

  Hosts MUST NOT attach any long-term significance to bundle paths (for example in save files), since there are no guarantees they will remain unchanged between (or even during) program invocations. Plugins (among other things) MUST be identified by URIs (not paths) in save files.

void lilv_world_load_specifications(LilvWorld *world)

  Load all specifications from currently loaded bundles.

  This is for hosts that explicitly load specific bundles, its use is not necessary when using `lilv_world_load_all()`. This function parses the specifications and adds them to the model.

void lilv_world_load_plugin_classes(LilvWorld *world)

  Load all plugin classes from currently loaded specifications.

  Must be called after `lilv_world_load_specifications()`. This is for hosts that explicitly load specific bundles, its use is not necessary when using `lilv_world_load_all()`.

int lilv_world_unload_bundle(LilvWorld *world, const LilvNode *bundle_uri)

  Unload a specific bundle.

  This unloads statements loaded by `lilv_world_load_bundle()`. Note that this is not necessarily all information loaded from the bundle. If any resources have been separately loaded with `lilv_world_load_resource()`, they must be separately unloaded with `lilv_world_unload_resource()`.

int lilv_world_load_resource(LilvWorld *world, const LilvNode *resource)

  Load all the data associated with the given `resource`.

  All accessible data files linked to `resource` with rdfs:seeAlso will be loaded into the world model.

  Parameters:

    - world – The world.

    - resource – Must be a subject (a URI or a blank node).

  Returns:

    The number of files parsed, or -1 on error

int lilv_world_unload_resource(LilvWorld *world, const LilvNode *resource)

  Unload all the data associated with the given `resource`.

  This unloads all data loaded by a previous call to `lilv_world_load_resource()` with the given `resource`.

  Parameters:

    - world – The world.

    - resource – Must be a subject (a URI or a blank node).

const LilvPluginClass *lilv_world_get_plugin_class(const LilvWorld *world)

  Get the parent of all other plugin classes, lv2:Plugin.

const LilvPluginClasses *lilv_world_get_plugin_classes(const LilvWorld *world)

  Return a list of all found plugin classes.

  Returned list is owned by world and must not be freed by the caller.

const LilvPlugins *lilv_world_get_all_plugins(const LilvWorld *world)

  Return a list of all found plugins.

  The returned list contains just enough references to query or instantiate plugins. The data for a particular plugin will not be loaded into memory until a call to an lilv_plugin_* function results in a query (at which time the data is cached with the LilvPlugin so future queries are very fast).

  The returned list and the plugins it contains are owned by `world` and must not be freed by caller.

LilvNodes *lilv_world_find_nodes(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)

  Find nodes matching a triple pattern.

  Either `subject` or `object` may be NULL (a wildcard), but not both.

  Returns:

    All matches for the wildcard field, or NULL.

LilvNode *lilv_world_get(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)

  Find a single node that matches a pattern.

  Exactly one of `subject`, `predicate`, `object` must be NULL. This function is equivalent to lilv_nodes_get_first(lilv_world_find_nodes(…)) but simplifies the common case of only wanting a single value.

  Returns:

    The first matching node, or NULL if no matches are found.

bool lilv_world_ask(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)

  Return true iff a statement matching a certain pattern exists.

  This is useful for checking if particular statement exists without having to bother with collections and memory management.

  Parameters:

    - world – The world.

    - subject – Subject of statement, or NULL for anything.

    - predicate – Predicate (key) of statement, or NULL for anything.

    - object – Object (value) of statement, or NULL for anything.

LilvNode *lilv_world_get_symbol(LilvWorld *world, const LilvNode *subject)

  Get an LV2 symbol for some subject.

  This will return the lv2:symbol property of the subject if it is given explicitly, and otherwise will attempt to derive a symbol from the URI.

  Returns:

    A string node that is a valid LV2 symbol, or NULL on error.

LILV_OPTION_FILTER_LANG

  Enable/disable language filtering.

  Language filtering applies to any functions that return (a) value(s). With filtering enabled, Lilv will automatically return the best value(s) for the current LANG. With filtering disabled, all matching values will be returned regardless of language tag. Filtering is enabled by default.

LILV_OPTION_DYN_MANIFEST

  Enable/disable dynamic manifest support.

  Dynamic manifest data will only be loaded if this option is true.

LILV_OPTION_LV2_PATH

  Set application-specific LV2_PATH.

  This overrides the LV2_PATH from the environment, so that lilv will only look inside the given path. This can be used to make self-contained applications.