NAME
SIRTX::VM::Chunk - module for interacting with SIRTX VM chunks
VERSION
version v0.01
SYNOPSIS
use SIRTX::VM::Chunk;This package inherits from Data::Identifier::Interface::Userdata and Data::Identifier::Interface::Known.
METHODS
new
my SIRTX::VM::Chunk $chunk = SIRTX::VM::Chunk->new;(since v0.01)
Creates a new chunk object.
The following options are supported:
type-
The type of the chunk as per "type".
flags-
A hashref with flags that are to be set as per "set_flag".
write
$chunk->write($fh);(since v0.01)
Writes the chunk to the given file handle. No options are supported.
read
$chunk->read($fh);(since v0.01)
Reads the chunk from the given file handle. Resets all internal state of the chunk. No options are supported.
Note: The handle to read from needs to support "tell" in perlfunc and "perlfunc/seek".
Note: A reference to the handle is stored in the object as per "attach_data". See details on what operations are allowed on the handle after this call.
type
my Data::Identifier $type = $chunk->type;
# or:
$chunk->type($type);(since v0.01)
Gets or sets the type of the chunk.
If the type is set and $type is not a Data::Identifier it is converted as per "new" in Data::Identifier using from.
Note: In order to be useable a type must have a valid sid (small-identifier), sni (sirtx-numerical-identifier) assigned, or being mapped to a host defined identifier, or a private identifier.
chunk_identifier
my $chunk_identifier = $chunk->chunk_identifier;
# or:
$chunk->chunk_identifier($chunk_identifier);(experimental since v0.01)
Gets or sets the chunk identifier.
Note: The type and range of this value is not yet fully defined and may be changed in later versions of this module.
padding
my $padding = $chunk->padding;(experimental since v0.01)
Returns the padding status of the chunk.
Padding is automatically added by this module as needed.
Note: The return type and range is not yet defined. However it is defined that the returned value will be true-ish if any non-zero amount of padding is used and false-ish if no padding is used.
Note: This method is hardly useful for most code. It is provided only for debugging.
Note: The returned value might or might not reflect the value as read by "read". It might be a calculated value.
my $bool = $chunk->flag($flag);
# or:
$chunk->flag($flag => $value); # value is not undef!(since v0.01)
Gets or sets the boolean state of a flag.
Currently the only supported flag is standalone.
This method can be used to set the state of the flag. However "set_flag" is often the more secure method to do this as it is not tri-state.
set_flag
$chunk->set_flag($flag => $value); # any boolean, including undef(since v0.01)
Sets the value of a flag. See "flag" for details on flags.
attach_data
$chunk->attach_data($fh [, $offset [, $length]]);(since v0.01)
Attaches an open handle as data for a chunk.
The passed handle ($fh) will be stored as a reference inside the chunk object.
The passed handle must support "tell" in perlfunc, "seek" in perlfunc, and "read" in perlfunc.
Optionally a offset and a length can be given to only use a subrange of the data as body for the chunk. This is analogous to "substr" in perlfunc. If no offset is given the current offset (not the start/offset 0) is used as offset. This is specifically designed to allow stream like reading. If no length is given the length from the offset to the end of the file is used. If $fh refers to a freshly opened file this results in all of the file being used as body by default.
Note: The an internal reference to the handle is used to avoid loading the content in memory or into a temporary file. This specifically allowes for chunks with large bodies.
Note: While an internal reference is held by the chunk the handle may go out of scope by the caller. However it is not valid to call "close" in perlfunc on the handle.
Note: The handle must be in a 8 bit binary mode before passed to this function. See also "binmode" in perlfunc regarding binary mode.
Note: If the data the handle refers to is altered in the used range (see offset and length) after this method is called the behaviour is undefined.
read_data
my $data = $chunk->read_data($length [, $offset]);(experimental since v0.01)
Reads data from the body of the chunk.
This method reads at most $length bytes at the offset of $offset (defaults to 0). The result will be returned.
If a read starting beyond the end of the data is requested undef is returned. If less than $length bytes are available a the available bytes are returned.
If any invalid values are passed this method will die.
Note: This method does not store the current read position. Hence any read that is not to read from the very beginning must provide a $offset.
AUTHOR
Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2025 by Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)