NAME

Web::Dash::Lens - An experimental Unity Lens object

VERSION

0.02

SYNOPSIS

    use Web::Dash::Lens;
    use utf8;
    use Encode qw(encode);
    
    sub show_results {
        my (@results) = @_;
        foreach my $result (@results) {
            print "-----------\n";
            print encode('utf8', "$result->{name}\n");
            print encode('utf8', "$result->{description}\n");
            print encode('utf8', "$result->{uri}\n");
        }
        print "=============\n";
    }
    
    my $lens = Web::Dash::Lens->new(lens_file => '/usr/share/unity/lenses/applications/applications.lens');
    
    
    ## Synchronous query
    my @search_results = $lens->search_sync("terminal");
    show_results(@search_results);
    
        
    ## Asynchronous query
    use Future::Q;
    use Net::DBus::Reactor;
        
    $lens->search("terminal")->then(sub {
        my @search_results = @_;
        show_results(@search_results);
        Net::DBus::Reactor->main->shutdown;
    })->catch(sub {
        my $e = shift;
        warn "Error: $e";
        Net::DBus::Reactor->main->shutdown;
    });
    Net::DBus::Reactor->main->run();

DESCRIPTION

Web::Dash::Lens is an object that represents a Unity Lens. Note that this module is for using lenses, not for creating your own lenses.

CAVEAT

If you use AnyEvent::DBus, do not use *_sync() methods. Instead you have to use asynchronous methods and explicit condition variables.

    my $cv = AnyEvent->condvar;
    $lens->search_hint()->then(sub {
        $cv->send(@_);
    }, sub {
        $cv->croak(shift);
    });
    my $search_hint = $cv->recv;

This is because AnyEvent::DBus replaces the DBus reactor that is not completely compatible with the original Net::DBus::Reactor objects.

CLASS METHOD

$lens = Web::Dash::Lens->new(%args)

The constructor.

Fields in %args are:

lens_file => FILE_PATH (semi-optional)

The file path to .lens file. Usually you can find lens files installed under /usr/share/unity/lenses/.

You must either specify lens_file or combination of service_name and object_name.

service_name => DBUS_SERVICE_NAME (semi-optional)

DBus service name of the lens.

In a .lens file, the service name is specified by DBusName field.

object_name => DBUS_OBJECT_NAME (semi-optional)

DBus object name of the lens.

In a .lens file, the object name is specified by DBusPath field.

reactor => Net::DBus::Reactor object (optional, default: Net::DBus::Reactor->main)

The Net::DBus::Reactor object. This object is needed for *_sync() methods.

bus_address => DBUS_BUS_ADDRESS (optional, default: ":session")

The DBus bus address where this module searches for the lens service.

If bus_address is ":session", the session bus will be used. If bus_address is ":system", the system bus will be used. Otherwise, bus_address is passed to Net::DBus->new() method.

concurrency => CONCURRENCY_NUM (optional, default: 1)

The maximum number of asynchronous search queries that the lens handles simultaneously.

If you call searching methods more than this value before any of the requests is complete, the extra requests are queued in the lens and processed later.

Setting concurrency to 0 means there is no concurrency limit.

OBJECT METHODS

@results = $lens->search_sync($query_string)

Makes a search with the $query_string using the $lens. $query_string must be a text string, not a binary (octet) string.

In success, this method returns a list of search results (@results). Each element in @results is a hash-ref containing the following key-value pairs. All the string values are text strings, not binary (octet) strings.

uri => STR

A URI of the result entry. This URI is designed for Unity. Normal applications should refer to dnd_uri below.

icon_hint => STR

A string that specifies the icon of the result entry.

category_index => INT

The category index for the result entry. You can obtain category information by category() method.

mimetype => STR

MIME type of the result entry.

name => STR

The name of the result entry.

comment => STR

One line description of the result entry.

dnd_uri => STR

A URI of the result entry. This URI takes a form that most applications can comprehend. "dnd" stands for "Drag and Drop", I guess.

In failure, this method throws an exception.

See also: https://wiki.ubuntu.com/Unity/Lenses#Schema

$future = $lens->search($query_string)

The asynchronous version of search_sync() method.

Instead of returning the results, this method returns a Future::Q object that represents the search results obtained in future.

In success, $future will be fulfilled. You can obtain the list of search results by $future->get method.

In failure, $future will be rejected. You can obtain the exception by $future->failure method.

$search_hint = $lens->search_hint_sync()

Returns the search hint of the $lens. The search hint is a short description of the $lens. $search_hint is a text string, not a binary (or octet) string.

$future = $lens->search_hint()

The asynchronous version of search_hint_sync() method.

Instead of returning the results, this method returns a Future::Q object that represents the search hint obtained in future.

When done, $future will be fulfilled. You can obtain the search hint by $future->get method.

$category_hashref = $lens->category_sync($category_index)

Returns a hash-ref describing the category specified by $category_index.

$category_index is an integer greater than or equal to zero.

$category_hashref is an hash-ref containing information about the category. It has the following key-value pairs. All the string values are text strings, not binary (octet) strings.

name => STR

The name of the category.

icon_hint => STR

A string that specifies the icon of the category.

renderer => STR

A string that specifies how the results in this category should be rendered.

If $category_index is invalid, it throws an exception.

$future = $lens->category($category_index)

The asynchronous version of category_sync() method.

Instead of returning the category hash-ref, this method returns a Future::Q object.

In success, $future will be fulfilled. You can obtain the category hash-ref by $future->get method.

In failure, $future will be rejected. You can obtain the exception by $future->failure method.

$service_name = $lens->service_name

Returns the DBus service name of the $lens.

$object_name = $lens->object_name

Returns the DBus object name of the $lens.

$new_lens = $lens->clone

Returns the clone of the $lens.

IMPLEMENTATION

For how Web::Dash::Lens communicates with a Lens process via DBus, read the source code of Web::Dash::Lens and Web::Dash::DeeModel. I left some comments there.

AUTHOR

Toshio Ito <toshioito [at] cpan.org>

cpanm Web::Dash

perl -MCPAN -e shell
install Web::Dash