NAME

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

VERSION

version 0.08

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 shallow 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 do 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) 2023 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.

cpanm DataStore::CAS

perl -MCPAN -e shell
install DataStore::CAS