# World

The world is the top-level object which represents an instance of Lilv. It is used to discover and load LV2 data, and stores an internal cache of loaded data for fast searching.

An application typically has a single world, which is constructed once on startup and used throughout the application’s lifetime.

## Construction

A world must be created before anything else. A world is created with `lilv_world_new()`, for example:

    LilvWorld* world = lilv_world_new();

## Setting Options

Various options to control Lilv’s behavior can be set with `lilv_world_set_option()`. The currently supported options are `LILV_OPTION_FILTER_LANG`, `LILV_OPTION_DYN_MANIFEST`, and `LILV_OPTION_LV2_PATH`.

For example, to set the LV2 path to only load plugins bundled in the application:

    LilvNode* lv2_path = lilv_new_file_uri(world, NULL, "/myapp/lv2");

    lilv_world_set_option(world, LILV_OPTION_LV2_PATH, lv2_path);

## Loading Data

Before using anything, data must be loaded from disk. All LV2 data (plugins, UIs, specifications, presets, and so on) is installed in bundles, a standard directory format

### Discovering and Loading Bundles

Typical hosts will simply load all bundles in the standard LV2 locations on the system:

    lilv_world_load_all(world);

This will discover all bundles on the system, as well as load the required data defined in any discovered specifications.

It is also possible to load a specific bundle:

    LilvNode* bundle_uri = lilv_new_file_uri(world, NULL, "/some/plugin.lv2");

    lilv_world_load_bundle(world, bundle_uri);

The LV2 specification itself is also installed in bundles, so if you are not using `lilv_world_load_all()`, it is necessary to manually load the discovered specification data:

    lilv_world_load_specifications(world);
    lilv_world_load_plugin_classes(world);

## Querying Data

The world contains a model of all the loaded data in memory which can be queried.

### Data Model

LV2 data is a set of “statements”, where a statement is a bit like a simple machine-readable sentence. The “subject” and “object” are as in natural language, and the “predicate” is like the verb, but more general.

For example, we could make a statement about a plugin in english:

> MyOsc has the name “Super Oscillator”

We can break this statement into 3 pieces like so:

Subject | Predicate | Object
--- | --- | ---
MyOsc | has the name | “My Super Oscillator”

Statements use URIs to identify things. In this case, we assume that this plugin has the URI `http://example.org/Osc`. The LV2 specification defines that `http://usefulinc.com/ns/doap#name` is the property used to describe a plugin’s name. So, this statement is:

Subject | Predicate | Object
--- | --- | ---
`http://example.org/Osc` | `http://usefulinc.com/ns/doap#name` | “My Oscillator”

### Finding Values

Based on this model, you can find all values that match a certain pattern. Patterns are just statements, but with `NULL` used as a wildcard that matches anything. So, for example, you can get the name of a plugin using `lilv_world_find_nodes()`:

    LilvNode* plugin_uri = lilv_new_uri(world, "http://example.org/Osc");
    LilvNode* doap_name  = lilv_new_uri(world, "http://usefulinc.com/ns/doap#name");

    LilvNodes* values = lilv_world_find_nodes(world, plugin_uri, doap_name, NULL);

Note that a set of values is returned, because some properties may have several values. When you are only interested in one value, you can use the simpler `lilv_world_get()` instead:

    LilvNode* value = lilv_world_get(world, plugin_uri, doap_name, NULL);

If you are only interested if a value exists at all, use `lilv_world_ask()`:

    bool has_name = lilv_world_ask(world, plugin_uri, doap_name, NULL);