NAME
    Lirc::Client - A client library for the Linux Infrared Remote Control

SYNOPSIS
      use Lirc::Client;
      ...
      my $lirc = Lirc::Client->new( 'progname' );
      my $code;
      do {                            # Loop while getting ir codes
        $code = $lirc->next_code;     # wait for a new ir code
        print "Lirc> $code\n";
        process( $code );             # do whatever you want with the code
      } while( defined $code );       # undef will be returned when lirc dev exists

DESCRIPTION
    This module provides a simple interface to the Linux Infrared Remote
    Control (Lirc). The module encasuplates parsing the Lirc config file
    (.lircrc), openning a connection to the Lirc device, and retrieving
    events from the device.

  Use Details
    new( program, [rcfile], [dev], [debug], [fake] )
    new( program, \%options )
          my $lirc = Lirc::Client->new( 'progname',    # required
                       "$ENV{HOME}/.lircrc",           # optional
                       '/dev/lircd', 0, 0 );           # optional

          my $lirc = Lirc::Client->new( 'progname', {     # required
                       rcfile    => "$ENV{HOME}/.lircrc", # optional
                       dev        => "/dev/lircd",        # optional
                       debug    => 0,                     # optional
                       fake    => 1,                      # optional
                } );

        The constructor accepts two calling forms: an ordered list (for
        backwards compatibility), and a hash ref of configuration options.
        The two forms can be combined as long as the hash ref is last.

        When called the constructor defines the program token used in the
        Lirc config file, opens and parses the Lirc config file (rcfile
        defaults to ~/.lircrc if none specified), connects to the Lirc
        device (dev defaults to /dev/lircd if none specified), and returns
        the Lirc::Client object. Pass a true value for debug to have various
        debug information printed (defaults to false). A true value for the
        fake flag will cause Lirc::Client to read STDIN rather than the
        lircd device (defaults to false), which is primarily useful for
        debuging.

    recognized_commands()
          my @list = $lirc->recongnized_commands();

        Returns a list of all the recongnized commands for this application
        (as defined in the call to new.

    next_code()
    nextcode()
          my $code = $lirc->next_code;

        Retrieves the next IR command associated with the progname as
        defined in new(), blocking if none is available. next_code uses the
        stdio read commands which are buffered. Use next_codes if you are
        also using select.

    next_codes()
    nextcodes()
          my @codes = $lirc->next_codes;

        Retrieves any IR commands associated with the progname as defined in
        the new() constructor, blocking if none are available. next_codes
        uses sysread so it is compatible with select driven event loops.
        This is the most efficient method to accomplish a non-blocking read.

        Due to the mechanics of sysread and select, this version may return
        multiple ir codes so the return value is an array.

        Here is an example using IO::Select:

            use IO::Select;
            ....
            my $select = IO::Select->new();
            $select->add( $lirc->sock );
            while(1){
                # do your own stuff, if you want
                if( my @ready = $select->can_read(0) ){ 
                    # an ir event has been received (if you are tracking other
                                # filehandles, you need to make sure it is lirc)
                    my @codes = $lirc->next_codes;    # should not block
                    for my $code (@codes){
                        process( $code );
                    }
                }
            }

        This is much more efficient than looping over next_code in
        non-blocking mode. See the select.t test for the complete example.
        Also, checkout the Event module on cpan for a nice way to handle
        your event loops.

    sock()
          my $sock = $lirc->sock();

        Returns (or sets if an arguement is passed) the socket from which to
        read lirc commands. This can be used to work Lirc::Client into you
        own event loop.

    parse_line()
          my $code = $lirc->parse_line( $line );

        Takes a full line as read from the lirc device and returns code on
        the config line of the lircrc file for that button. This can be used
        in combination with sock to take more of the event loop control out
        of Lirc::Cli

    clean_up()
          $lirc->clean_up();

        Closes the Lirc device pipe, etc. clean_up will be called when the
        lirc object goes out of scope, so this is not necessary.

    debug()
          $lirc->debug;

        Return the debug status for the lirc object.

SEE ALSO
    The Lirc Project - http://www.lirc.org

AUTHOR
    Mark V. Grimes <mgrimes@cpan.org>

COPYRIGHT AND LICENSE
    Copyright (C) 2006 by Mark V. Grimes

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.2 or, at
    your option, any later version of Perl 5 you may have available.

BUGS
    None of which I am aware. Please let me know if you find any.

