• NAME
• VERSION
• DESCRIPTION
• METHODS
  • new
  • _cas
  • _data
  • READ
  • GETC
  • getc
  • READLINE
  • getlines
  • WRITE
  • PRINT
  • PRINTF
  • print
  • printf
  • FILENO
  • fileno
• BUGS
• AUTHOR
• COPYRIGHT AND LICENSE

NAME

DataStore::CAS::VirtualHandle - Handy base class for virtual filehandles

VERSION

version 0.020001

DESCRIPTION

This class implements an API compatible with both IO::Handle and original-style GLOBREF handles. It acts as a proxy, passing all operations to the CAS instance which created it.

This object is a blessed globref, but it has a handy _data attribute which gives you access to the hash portion of the glob, so the CAS implementation can store per-handle details.

See DataStore::CAS::Virtual for an example of how this is used, in the methods new_write_handle, _handle_write, _handle_seek, _handle_tell, and commit_write_handle.

METHODS

All methods normally pass through to the CAS that created it:

  $handle->METHODNAME(@ARGS);
  # proxies to...
  $handle->_cas->_handle_METHODNAME($handle, @args)

thanks to AUTOLOAD. There are a few methods that have been given specific implementations though:

new

  $handle= $class->new( $cas_instance, \%data )
  # cas_instance is now found in $handle->_cas
  # a copy of \%data is now found in $handle->_data

Creates a new VirtualHandle object. Blesses the globref and all that ugly stuff. Stores a reference to a CAS and some arbitrary fields for you.

_cas

The CAS instance this handle belongs to.

_data

A hashref of arbitrary data the CAS owner wants to keep in this handle.

READ

GETC

getc

These methods all proxy to, or are implemented using read ($cas->_handle_read).

READLINE

getlines

These methods all proxy to, or are implemented using getline ($cas->_handle_getline).

WRITE

PRINT

PRINTF

print

printf

These methods all proxy to, or are implemented using write ($cas->_handle_write).

FILENO

fileno

These methods return undef. (If you actually have a file descriptor, why would you need a virtual handle object?)

BUGS

The Perl I/O abstraction.

But more specifically, you cannot yet use "Perl IO Layers" on these objects, because it appears I would have to re-implement the layers from scratch.

You also cannot use sysread/syswrite on them. (there doesn't appear to be any way to capture those calls with the TIE interface.)

These objects to not actually inherit from IO::Handle, because loading IO::Handle in a program that doesn't intend to use it is wasteful, and because it would make these objects appear to have methods which they don't support.

AUTHOR

Michael Conrad <mconrad@intellitree.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Michael Conrad, and IntelliTree Solutions llc.

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