Ingy döt Net > Pointer-0.11 > Pointer

Download:
Pointer-0.11.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.11   Source  

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:

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

syntax highlighting: