NAME

    UI::Bowdlator::Filter - Helper for specifying input filters to
    Bowdlator

SYNOPSIS

        # maps all typed characters to uppercase
        use UI::Bowdlator::Filter;
    
        # connect to Bowdlator server
        my $bowdlator = UI::Bowdlator::Filter->new()
            or die "Bowdlator server not online\n";
    
        my $composed = '';
        while ($bowdlator->getKey(handle_backspace => \$composed)) {
    
            if (/^[^[:graph:]]/a) { # non graphical character ends composition
                $bowdlator->commit(\$composed);
                next;
            }
    
            $composed .= uc;
    
            $bowdlator->suggest($composed);
        }

DESCRIPTION

    Makes writing filters for Bowdlator (http://github.com/a3f/Bowdlator)
    easier.

METHODS AND ARGUMENTS

    new([$sock])

      Connects to a running Bowdlator AF_UNIX socket. Returns undef on
      connection failure. Default socket is
      /usr/local/var/run/bowdlator.sock. Optionally, an actual socket or a
      path to one can be specified.

    getKey([keep_nul => 0, buffer_size => 160, handle_backspace => undef])

      Blocks till the user types a Key while Bowdlator is selected. Accepts
      following optional arguments:

      handle_backspace

	User code can offload backspace handling to the module. On
	backspace receipt, the module will discard the composed string's
	last character, and chop and return the one before it, so it can be
	rehandled. If the buffer is empty, a backspace (\b) is returned.

      keep_nul

	Bowdlator sends NUL-terminated strings. The module strips them
	unless instructed otherwise.

      buffer_size

	The recv buffer size. This shouldn't need changing. Default is 160.

      undef is returned on socket error.

    suggest($display, @candidates)

      Sends off a suggestion to $display and a list of @candidates to
      choose from. (Candidates list support not immplemented yet).

    commit(\$commit)

      Sends off the final string to $commit. If $commit is a ref, it will
      be cleared.

GIT REPOSITORY

    http://github.com/athreef/UI-Bowdlator-Filter

AUTHOR

    Ahmad Fatoum <athreef@cpan.org>, http://a3f.at

COPYRIGHT AND LICENSE

    Copyright (C) 2016 Ahmad Fatoum

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.