NAME

Wily::Message - Perl extension to handle Wily Messages

SYNOPSIS

  use Wily::Message;
  use Wily::Connect;

  # opens a file in wily and exits when the window is destroyed

  my $win_id;

  my $ws = Wily::Connect::connect();

  my $wm = Wily::Message->new(Wily::Message::WMnew, 0, 0, 0, 1,
      '/tmp/file_to_edit');
  $ws->syswrite($wm->flatten());

  my $buffer = '';
  until (Wily::Message::complete_message($buffer)) {
      $ws->sysread($buffer, 1024, length($buffer));
  }

  $buffer = $wm->from_string($buffer);

  if ($wm->{type} == Wily::Message::WRerror) {
      die "Error WMnew: $wm->{s}\n";
  } elsif ($wm->{type} == Wily::Message::WRnew) {
      $win_id = $wm->{window_id};
      $wm = Wily::Message->new(Wily::Message::WMattach, $win_id, 0, 0,
          Wily::Message::WEdestroy);
      $ws->syswrite($wm->flatten());
      until (Wily::Message::complete_message($buffer)) {
          $ws->sysread($buffer, 1024, length($buffer));
      }
      $buffer = $wm->from_string($buffer);
      if ($wm->{type} == Wily::Message::WRerror) {
           die "Error WMattach: $wm->{s}\n";
      } elsif ($wm->{type} == Wily::Message::WRattach) {
      } else {
          die "Expected a WRattach, but didn't get one";
      }
  } else {
      die "Expected a WRnew, but didn't get one";
  }

  while (1) {
      until (Wily::Message::complete_message($buffer)) {
           $ws->sysread($buffer, 1024, length($buffer));
      }
      $buffer = $wm->from_string($buffer);
      if ($wm->{type} == Wily::Message::WEdestroy and $wm->{window_id} == $win_id) {
          last;
      }
  }

DESCRIPTION

A simple object wrapper around Wily messages with a helper function to assist in extracting messages from the wily connection.

Creating Messages

        $msg = Wily::Message->new($type, $window_id, $p0, $p1, $flag, $s);

This returns a new Wily::Message object setup according to the parameters. All the parameters default to 0, except for $s which defaults to "". The meaning of $flag and $s depend on the message type. $window_id specified the id number of the wily window. $p0 and $p1 specify the range. Some of the fields are not used by some of the messages.

See the Wily documentation for details about what messages are valid and what they do.

Flattening a Message

        $bytes = $msg->flatten();

In order to send a message to Wily it must be flattened into a stream of bytes. The flatten() method does this. Those bytes would then typicaly be sent to Wily over the socket connection.

Size of a Message

        $size= $msg->size();

Returns the number of bytes that will be used by the flattened message.

Extracting a Message

        $msg = Wily::Message->new();
        $buffer = $msg->from_string($buffer);

The from_string() method extracts a message from the passed byte string, the message object is modified to represent the flattened message contained in the string. Any additional bytes in the string are returned. The passed byte string must contain at least an entire flattened message, or bad things will happen.

Testing for a Message

        if (Wily::Message::compete_message($buffer)) {
                $buffer = $msg->from_string($buffer);
        }

The complete_message function is passed a byte string and returns true if a complete message is contained at the beginning of the string. It returns false is there is no complete message.

EXPORT

None by default.

Optionally the Message and Event constants can be exported.

SEE ALSO

wily(1), Wily::Connect

http://sam.holden.id.au/software/plwily/

AUTHOR

Sam Holden, <sam@holden.id.au>

COPYRIGHT AND LICENSE

Copyright (C) 2004 by Sam Holden

This module is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version,

or

b) the "Artistic License" which comes with this module.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this module, in the file ARTISTIC. If not, I'll be glad to provide one.

You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA or visit their web page on the internet at http://www.gnu.org/copyleft/gpl.html.

cpanm Wily

perl -MCPAN -e shell
install Wily