Data::Buffer - phpMan

NAME
    Data::Buffer - Read/write buffer class

SYNOPSIS
        use Data::Buffer;
        my $buffer = Data::Buffer->new;

        ## Add a 32-bit integer.
        $buffer->put_int32(10932930);

        ## Get it back.
        my $int = $buffer->get_int32;

DESCRIPTION
    *Data::Buffer* implements a low-level binary buffer in which you can get
    and put integers, strings, and other data. Internally the implementation
    is based on "pack" and "unpack", such that *Data::Buffer* is really a
    layer on top of those built-in functions.

    All of the *get_** and *put_** methods respect the internal offset state
    in the buffer object. This means that you should read data out of the
    buffer in the same order that you put it in. For example:

        $buf->put_int16(24);
        $buf->put_int32(1233455);
        $buf->put_int16(99);

        $buf->get_int16;   # 24
        $buf->get_int32;   # 1233455
        $buf->get_int16;   # 99

    Of course, this assumes that you *know* the order of the data items in
    the buffer. If your setup is such that your sending and receiving
    processes won't necessarily know what's inside the buffers they receive,
    take a look at the *TEMPLATE USAGE* section.

USAGE
  Data::Buffer->new
    Creates a new buffer object and returns it. The buffer is initially
    empty.

    This method takes no arguments.

  Data::Buffer->new_with_init(@strs)
    Creates a new buffer object and appends to it each of the octet strings
    in *@strs*.

    Returns the new buffer object.

  $buffer->get_int8
    Returns the next 8-bit integer from the buffer (which is really just the
    ASCII code for the next character/byte in the buffer).

  $buffer->put_int8
    Appends an 8-bit integer to the buffer (which is really just the
    character corresponding to that integer, in ASCII).

  $buffer->get_int16
    Returns the next 16-bit integer from the buffer.

  $buffer->put_int16($integer)
    Appends a 16-bit integer to the buffer.

  $buffer->get_int32
    Returns the next 32-bit integer from the buffer.

  $buffer->put_int32($integer)
    Appends a 32-bit integer to the buffer.

  $buffer->get_char
    More appropriately called *get_byte*, perhaps, this returns the next
    byte from the buffer.

  $buffer->put_char($bytes)
    Appends a byte (or a sequence of bytes) to the buffer. There is no
    restriction on the length of the byte string *$bytes*; if it makes you
    uncomfortable to call *put_char* to put multiple bytes, you can instead
    call this method as *put_chars*. It's the same thing.

  $buffer->get_bytes($n)
    Grabs *$n* bytes from the buffer, where *$n* is a positive integer.
    Increments the internal offset state by *$n*.

  $buffer->put_bytes($bytes [, $n ])
    Appends a sequence of bytes to the buffer; if *$n* is unspecified,
    appends the entire length of *$bytes*. Otherwise appends only the first
    *$n* bytes of *$bytes*.

  $buffer->get_str
    Returns the next "string" from the buffer. A string here is represented
    as the length of the string (a 32-bit integer) followed by the string
    itself.

  $buffer->put_str($string)
    Appends a string (32-bit integer length and the string itself) to the
    buffer.

  $buffer->extract($n)
    Extracts the next *$n* bytes from the buffer *$buffer*, increments the
    offset state in *$buffer*, and returns a new buffer object containing
    the extracted bytes.

TEMPLATE USAGE
    Generally when you use *Data::Buffer* it's to communicate with another
    process (perhaps a C program) that bundles up its data into binary
    buffers. In those cases, it's very likely that the data will be in some
    well-known order in the buffer: in other words, it might be documented
    that a certain C program creates a buffer containing:

    *   an int8

    *   a string

    *   an int32

    In this case, you would presumably know about the order of the data in
    the buffer, and you could extract it accordingly:

        $buffer->get_int8;
        $buffer->get_str;
        $buffer->get_int32;

    In other cases, however, there may not be a well-defined order of data
    items in the buffer. This might be the case if you're inventing your own
    protocol, and you want your binary buffers to "know" about their
    contents. In this case, you'll want to use the templating features of
    *Data::Buffer*.

    When you use the *put_* methods to place data in a buffer,
    *Data::Buffer* keeps track of the types of data that you're inserting in
    a template description of the buffer. This template contains all of the
    information necessary for a process to receive a buffer and extract the
    data in the buffer without knowledge of the order of the items.

    To use this feature, simply use the *insert_template* method after
    you've filled your buffer to completion. For example:

        my $buffer = Data::Buffer->new;
        $buffer->put_str("foo");
        $buffer->put_int32(9999);
        $buffer->insert_template;

        ## Ship off the buffer to another process.

    The receiving process should then invoke the *get_all* method on the
    buffer to extract all of the data:

        my $buffer = Data::Buffer->new;
        $buffer->append( $received_buffer_data );
        my @data = $buffer->get_all;

    @data will now contain two elements: "foo" and 9999.

LOW-LEVEL METHODS
  $buffer->append($bytes)
    Appends raw data *$bytes* to the end of the in-memory buffer. Generally
    you don't need to use this method unless you're initializing an empty
    buffer, because when you need to add data to a buffer you should
    generally use one of the *put_** methods.

  $buffer->empty
    Empties out the buffer object.

  $buffer->bytes([ $offset [, $length [, $replacement ]]])
    Behaves exactly like the *substr* built-in function, except on the
    buffer *$buffer*. Given no arguments, *bytes* returns the entire buffer;
    given one argument *$offset*, returns everything from that position to
    the end of the string; given *$offset* and *$length*, returns the
    segment of the buffer starting at *$offset* and consisting of *$length*
    bytes; and given all three arguments, replaces that segment with
    *$replacement*.

    This is a very low-level method, and you generally won't need to use it.

    Also be warned that you should not intermix use of this method with use
    of the *get_** and *put_** methods; the latter classes of methods
    maintain internal state of the buffer offset where arguments will be
    gotten from and put, respectively. The *bytes* method gives no thought
    to this internal offset state.

  $buffer->length
    Returns the length of the buffer object.

  $buffer->offset
    Returns the internal offset state.

    If you insist on intermixing calls to *bytes* with calls to the *get_**
    and *put_** methods, you'll probably want to use this method to get some
    status on that internal offset.

  $buffer->set_offset($offset)
    Sets the internal offset state to *$offset*.

  $buffer->reset_offset
    Sets the internal offset state to 0.

  $buffer->dump(@args)
    Returns a hex dump of the buffer. The dump is of the *entire* buffer
    *$buffer*; in other words, *dump* doesn't respect the internal offset
    pointer.

    *@args* is passed directly through to the *bytes* method, which means
    that you can supply arguments to emulate support of the internal offset:

        my $dump = $buffer->dump($buffer->offset);

  $buffer->insert_padding
    A helper method: pads out the buffer so that the length of the
    transferred packet will be evenly divisible by 8, which is a requirement
    of the SSH protocol.

AUTHOR & COPYRIGHTS
    Benjamin Trott, ben AT rhumba.com

    Except where otherwise noted, Data::Buffer is Copyright 2001 Benjamin
    Trott. All rights reserved. Data::Buffer is free software; you may
    redistribute it and/or modify it under the same terms as Perl itself.