=pod

=head1 NAME

Web::Dash - Unity Dash from Web browsers (experimental)

=head1 DESCRIPTION

L<Web::Dash> is a Web application version of Unity Dash.
Unity Dash is a powerful searching tool integrated in Unity desktop environment,
which is employed by Ubuntu Linux.

For detail of Unity, See L<https://wiki.ubuntu.com/Unity>

L<Web::Dash> acts like Unity Dash without the need of the whole Unity infrastructure.
All you need is some Lenses (searching agents) and your favorite Web browser,
and you can have the awesome searching power of Dash.

=head1 CAVEAT

=head2 This is an experimental application

L<Web::Dash> is quite an B<experimental> application.

It is not based on any official specification or documentation about Unity Dash or Unity Lens.
Instead, I analyzed the behavior of Unity Dash and Unity Lenses from outside,
and implemented what I guess was the correct usage of them.

I tested L<Web::Dash> in Ubuntu 12.04 and Xubuntu 12.04.
However it may not work as expected in other environments.
It is also possible for L<Web::Dash> to stop working in future versions of Unity or Ubuntu.

=head2 Privacy issues

Some Lenses are meant to search the local file system.
If you export those lenses to others, they are able to
see names of your files.

=head1 SCREENSHOTS

See L<https://github.com/debug-ito/Web-Dash/wiki/Screenshots>

=head1 TUTORIAL

=head2 Installation

To install L<Web::Dash>, first you need development tools and files for libexpat and libdbus.

    $ sudo apt-get install build-essential pkg-config libexpat1-dev libdbus-1-dev

Then, type

    $ sudo sh -c 'wget -O- http://cpanmin.us | perl - Web::Dash'

to install L<Web::Dash> from CPAN.

Of course, if you already have a CPAN client installed, you can type

    $ sudo cpanm Web::Dash


=head2 Installing some lenses

Most Unity Lenses are provided as .deb packages named C<unity-lens-*>.

In Ubuntu, some Lens packages are served by "extra" repository.
Make sure the repository is enabled in your system.

    $ grep extras /etc/apt/sources.list
    deb http://extras.ubuntu.com/ubuntu precise main
    deb-src http://extras.ubuntu.com/ubuntu precise main

Uncomment the deb lines if they are commented out.

To install Github lens, for example, type

    $ sudo apt-get update
    $ sudo apt-get install unity-lens-github


=head2 Start webdash

To start webdash, type

    $ webdash
    Twiggy: Accepting connections at http://127.0.0.1:5000/

Access the URL with a Web browser.


=head2 Run webdash in Ubuntu Server

In a non-GUI environment, first you need to execute the following.

    $ eval `dbus-launch --auto-syntax`

This will launch a DBus daemon for a session bus,
and set the environment variables necessary to access the bus.

After that, run C<webdash> as usual.

    $ webdash

If you run C<webdash> at startup (e.g., in /etc/rc.local),
B<< make sure to specify C<LANG> environment variable. >>
Lens processes need the C<LANG> environment variable to be set.


=head1 WEB API

L<Web::Dash> has a Web API for searching. See L<Web::Dash::WebAPI>.


=head1 AS A MODULE

As a Perl module, L<Web::Dash> provides a class object that can generate a L<PSGI> application.
You can use L<Web::Dash> in your .psgi file to customize which Lenses to export.

=head1 SYNOPSIS

In your app.psgi file.

    use Web::Dash;
    
    Web::Dash->new(lenses_dir => '/your/personal/lenses/directory')->to_app;

Or, if you want to select lenses...

    use Web::Dash;
    use Web::Dash::Lens;

    my @lenses;
    foreach my $lens_file (
        'extras-unity-lens-github', 'video'
    ) {
        push(@lenses, Web::Dash::Lens->new(
            lens_file => "/usr/share/unity/lenses/$lens_file/$lens_file.lens"
        ));
    }
    Web::Dash->new(lenses => \@lenses)->to_app;


=head1 CLASS METHODS

=head2 $dash = Web::Dash->new(%args)

The constructor.

Fields in C<%args> are:

=over

=item C<lenses_dir> => DIRECTORY_PATH (optional, default: '/usr/share/unity/lenses')

Specifies the root directory path under which it searches for lens files.

It loads *.lens files under this directory and creates L<Web::Dash::Lens> objects from them.

=item C<lenses> => ARRAYREF_OF_LENSES (optional)

Specifies an array-ref of L<Web::Dash::Lens> objects that you want to use with L<Web::Dash>.

If this option is specified, C<lenses_dir> option is ignored.

=back

=head1 OBJECT METHODS

=head2 $psgi_app = $dash->to_app()

Creates a L<PSGI> application from the C<$dash>.

Note that the PSGI application uses L<AnyEvent> for asynchronous responses.
Use L<AnyEvent>-compatible PSGI servers (like L<Twiggy>) to run the app.

=head1 SEE ALSO

=over

=item L<webdash>

Web::Dash daemon runner script.

=item L<Web::Dash::Lens>

An experimental Unity Lens object.

=back

=head1 AUTHOR

Toshio Ito C<< <toshioito [at] cpan.org> >>

=head1 LICENSE AND COPYRIGHT

Copyright 2013 Toshio Ito.

This program is free software; you can redistribute it and/or modify it
under the terms of the the Artistic License (2.0). You may obtain a
copy of the full license at:

L<http://www.perlfoundation.org/artistic_license_2_0>

Any use, modification, and distribution of the Standard or Modified
Versions is governed by this Artistic License. By using, modifying or
distributing the Package, you accept this license. Do not use, modify,
or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made
by someone other than you, you are nevertheless required to ensure that
your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service
mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge
patent license to make, have made, use, offer to sell, sell, import and
otherwise transfer the Package with respect to any patent claims
licensable by the Copyright Holder that are necessarily infringed by the
Package. If you institute patent litigation (including a cross-claim or
counterclaim) against any party alleging that the Package constitutes
direct or contributory patent infringement, then this Artistic License
to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER
AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY
YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR
CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.