/ 
File-Information-v0.05
River stage zero No dependents
/ File::Information::Base

NAME

File::Information::Base - generic module for extracting information from filesystems

VERSION

version v0.05

SYNOPSIS

use File::Information;

This is the base package for File::Information::Link, File::Information::Inode, and File::Information::Filesystem. Common methods are documented in this file. Details (such as supported keys) are documented in the respective modules.

METHODS

get

my $value = $obj->get($key [, %opts]);
# or:
my @value = $obj->get($key [, %opts], list => 1);

Get a value for a given key. The keys supported by this function depend on the module. Below you find a list with keys for aggregated values. Aggregated values are virtual and may be from different sources. If a key is not supported and no default option is given, the method will die.

The following optional options are supported:

as

The type to get the value in. This is the name of a perl package or special value (in all lower case). The packages supported depend on the type of data to be returned. Currently the following special values are supported: sid, uuid, oid, uri, ise (one of UUID, OID, or URI), mediatype, raw (a raw value). The following packages are supported (they need to be installed): Data::Identifier, DateTime, Data::URIID::Result, Data::TagDB::Tag, IO::Handle, File::Information::Link.

default

The value to be returned when no actual value could be read. This can also be undef which switches from die-ing when no value is available to returning undef.

lifecycle

The lifecycle to get the value for. The default is current. See also "lifecycles" in File::Information.

list

Note: This is experimental. Exact semantics of this mode may change or it may be removed completly in later versions.

Enables list support. In list mode this method returns an array of values. This can be used to access keys that hold multiple values.

To access keys that hold multiple values his mode must be used. Currently the list mode can also be used on keys that only hole one value. Then a list of on element is returned.

When this mode is used, default must be an array reference. Most commonly it will be [].

The following keys for aggregated values are supported:

comment

A comment on the document (if any).

contentise

An ISE of the document that refers to it's content (so all bit-perfect copies share this ISE).

description

A description of the document (if any).

displayname

A string that is suitable for display and likely meaningful to users.

fetchurl

An URL the file can be fetched from. This is very often a HTTPS URL. But it may be any valid URL.

finalmode

The final mode of the document. Normally this is unset, auto-final (meaning the document should become final once successfully verifies it's final state), or final (it reached it's final state).

hidden

Hidden files are generally not shown to the user (unless specifically requested). This is most common for system files or files that hold state information (like temporary files).

The exact meaning depend on the operating system, the filesystem, and the softwar interacting with them. On most UNIX like systems files with a filename starting with a dot are considered hidden (sometimes also called dot-files). On FAT lineage filesystems there is a special hidden attribute.

inodeise

An ISE for the inode. All hardlinks share this ISE but (bit-perfect) copies do not.

ise

The ISE of the document. That is it's UUID, OID, or URI.

mediatype

The media type of the document.

oid

The POD of the document.

readonly

If the file is ready only. This is different from immutable files in that they still can be deleted (or other file attributes be changed). Note: In the final lifecycle all files are read only.

system

If the file is a system file. The exact meaning system files depend on the operating system. Generally speaking a user should not write to or delete system files (directly).

Configuration files are generally not considered system files (as they may be edited by the user). Filesystems may contain special files that are considered system files. For example some filesystems might expose a list of bad blocks as a special file.

size

The file size (in bytes).

thumbnail

A file that can be used as a thumbnail for the document.

title

Title of the document (if any).

uri

The URI of the document. Note: This is not the URL one can use to fetch the document. This URI is the identifier of the document.

uuid

The UUID of the document.

writemode

The write mode for the document. Normally one of random access, append only, or none.

property_info

my $info = $obj->property_info($property);
# or:
my @info = $obj->property_info;
# or:
my @info = $obj->property_info($property [, ...] );

Returns information on one or more properties. If no property is given returns infos for all known ones.

Note: This object may not have values for all the listed properties. Likewise it is not guaranteed that two objects have the same list of properties.

The return value is a hashref or an array of hashrefs which contain the following keys:

name

The name of the digest in universal tag format (the format used in this module).

digest

my $digest = $obj->digest($algorithm [, %opts ]);

Returns a digest (hash). The supported algorithms and lifecycle values depend on object. If there is a any kind of problem this function dies.

Algorithm names are given in the universal tag form but aliases for names as by Digest are supported.

Common values include: md-5-128, sha-1-160, sha-2-256, and sha-3-512.

The following optional options are supported:

as

The type to get the value in. This is the name of a perl package or one of: hex (the default), binary, base64 (or b64), base64_padded, or utag. To get an object that is compatible with the Digest API use Digest. Do not try to use specific types such as Digest::MD5

default

The value to be returned when no actual value could be read. This can also be undef which switches from die-ing when no value is available to returning undef.

lifecycle

The lifecycle to get the value for. The default is current See also "lifecycles" in File::Information.

verify

my File::Information::VerifyBase $result = $obj->verify;
# same as:
my File::Information::VerifyBase $result = $obj->verify(lifecycle_from => 'current', lifecycle_to => 'final');

my $passed = $result->has_passed;

Performs a verify of the object using the given lifecycles. The verify operation checks if the given object in the state of lifecycle_from (by default 'current') is the same as in the state of lifecycle_to (by default 'final').

The resulting object contains information on the result of the verify. The most common operation is to call "has_passed" in File::Information::VerifyBase on the result.

Note: This operation may read the file and calculate digests. This may take significant time.

See also "digest", "lifecycles" in File::Information.

The following options (all optional) are supported:

lifecycle_from

The lifecycle to verify.

lifecycle_to

The lifecycle to verify against/to compare to.

base_from

The base object to compare (defaults to $obj).

Note: This is an experimental option.

base_to

The base object to compare (defaults to $obj) against.

Note: This is an experimental option.

uuid, oid, uri, ise, displayname, displaycolour, icontext, description

my $uuid          = $obj->uuid;
my $oid           = $obj->oid;
my $uri           = $obj->uri;
my $ise           = $obj->ise;
my $displayname   = $obj->displayname;
my $displaycolour = $obj->displaycolour;
my $icontext      = $obj->icontext;
my $description   = $obj->description;

These functions are for compatibility with Data::TagDB::Tag and Data::Identifier.

They perform the same as calling "get" with their name as key. For example:

my $displayname   = $obj->displayname;
# same as:
my $displayname   = $obj->get('displayname');

There availability depends on the type of object.

instance

my File::Information $instance = $obj->instance;

Returns the instance that was used to create this object.

extractor, db

my Data::URIID $extractor = $obj->extractor;
my Data::TagDB $db        = $obj->db;
my ...                    = $obj->digest_info;

These methods provide access to the same data as the methods of File::Information. Arguments will be passed to said functions. However the object my cache the result. Therefore it is only allowed to pass arguments that are compatible with caching (if any exist).

See "extractor" in File::Information, and "db" in File::Information for details.

AUTHOR

Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2024-2025 by Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)