NAME
    Pointer - Object Oriented Memory Pointers in Pure Perl

SYNOPSIS
     use Pointer;
     use Pointer::int;
     use Pointer::sv;

     # Hello, world the hard way
     print pointer->of_scalar("Hello, world")->get_pointer->get_pointer->get_string;

     # Test to see if a scalar is a string
     print "It's a string!"
       if pointer('sv')->of_scalar('12345')->sv_flags & SVf_POK;

     # Hex dump of the first 3 words of the SV for $/
     print "> $_\n" for pointer('int')->of_scalar($/)->get_hex(3);

     # Print 5 integers 10 integers away from the address of $$
     print((pointer('int')->of_scalar($$) + 10)->get(5));

DESCRIPTION
    This module allows you to create Perl objects that emulate C pointers.
    You can use them to read and explore the memory of your Perl process.

    Pointer.pm (and every subclass) exports a function called "pointer" that
    returns a new pointer object. Each object has a type like (void, int,
    long, sv). Support for each pointer type is written as a subclass of
    Pointer.pm. Pointer.pm itself is for type "void". To create a pointer to
    a long integer, do:

        use Pointer::long;
        my $p = pointer('long');

    Your new pointer is not pointing to anything yet. One way to put an
    address into the pointer is directly, like this:

        $p->to(0x123456);

    Another way is to point it at an existing scalar like this:

        $p->of_scalar($foo);

    Both of these methods return the pointer so that you can chain other
    methods onto them:

        my $int = $p->of_scalar($foo)->get;

    The "get" method returns whatever the pointer points to. Since $p is an
    integer pointer, this call returns an integer. The "get" method takes an
    optional number as an argument, which indicates the number of values to
    get.

    Pointer pointers honor pointer arithmetic. If you add or subtract a
    number to a pointer, the result is another pointer. As in C pointer
    arithmetic, the number of bytes added to the address depends on the size
    of the type represented by the pointer.

        my $p1 = pointer('long')->of_scalar($foo);
        my $p2 = $p1 - 5;

    is the same as:

        my $p1 = pointer('long')->of_scalar($foo);
        my $p2 = pointer('long')->address($p1->address - 5 * $p1->sizeof);

METHODS
    The following methods are available for all pointers:

    * to()
        Sets the address of a pointer to a specific integer. Returns the
        pointer object for chaining calls.

    * of_scalar()
        Sets the address of a pointer to the address a Perl scalar or SV.
        Returns the pointer object for chaining calls.

    * address()
        Returns the memory address of the pointer as an integer.

    * hex_address()
        Returns the address as a hexadecimal string.

    * type()
        Returns the type of the pointer.

    * sizeof()
        Returns the size (in bytes) of whatever type of data is pointed to.

    * get()
        Get the item(s) pointed to by the pointer. This function takes a
        numeric argument indicating how many items you want to retrieve. The
        function returns a list of the items requested.

    * get_hex()
        Similar to "get", but returns the items in hexadeciaml.

    * get_string()
        Returns the null terminated string pointed to by the pointer.

    * get_pointer()
        If your pointer points to a pointer address, this call will take the
        pointer address, and return a new pointer object that contains it.
        You can pass in the type of the new pointer. The default type is a
        void pointer.

    * get_raw()
        Returns the raw byte content pointed to by the pointer. You will
        need to unpack the raw data yourself. Takes an argument indicating
        how many bytes to return.

SUBCLASSING
    Pointer.pm was made to be subclassed. Every type of pointer is a
    subclass. See the modules: Pointer::int, Pointer::long and Pointer::sv
    for examples.

BUGS & DEFICIENCIES
    Pointers are tricky beasts, and there are myriad platform issues. At
    this point, Pointer.pm is but a naive attempt at a novel idea. Hopefully
    it can be fleshed out into a robust and serious module.

    Support for pointers to structs is minimal, but is a primary design
    goal. Pointer ships with a subclass for the sv struct as an example.
    Expect better struct support in a future release.

    If you have a good feel for C pointers, and grok where I am trying to go
    with this module, please send me an email with your good ideas.

AUTHOR
    Brian Ingerson <INGY@cpan.org>

COPYRIGHT
    Copyright (c) 2004. Brian Ingerson. All rights reserved.

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

    See <http://www.perl.com/perl/misc/Artistic.html>

