/ 
File-FStore-v0.01
/ File::FStore::File

NAME

File::FStore::File - Module for interacting with file stores

VERSION

version v0.01

SYNOPSIS

use File::FStore;

my File::FStore $store = File::FStore->new(path => '...');

my File::FStore::File $file = $store->query(...);

This package provides access to file level values.

METHODS

dbname

my $dbname = $file->dbname;

This returns the name of the file relative to the store's data directory.

Note: This method is generally not very useful for most applications.

See also: "filename", "open".

filename

my $filename = $file->filename;

This returns the filename within the store. The filename is returned in a format that is suitable to be passed to operating system functions.

Note: When possible "open" should be preferred.

See also: "open".

contentise

my $ise = $file->contentise;
# or:
my $ise = $file->contentise(as => ...);

Returns the content based ISE (identifier) for the file. This can be used as a primary key for the given file in databases. It is globally unique (so can be transfered to unrelated systems without worry of of collisions).

Takes a single optional option as which is documented in "as" in Data::Identifier. Defaulting to uuid.

Note: Calculation of this identifier requires the values for size from the properties domain and the values for sha-1-160 and sha-3-512 from the digests domain.

ise

my $ise = $file->ise;
# or:
my $ise = $file->ise(%opts);

Returns an ISE (identifier) for this file.

Currently an alias for "contentise". Later versions may add more logic.

open

my $fh = $file->open;

Opens the file and returns a filehandle. The file is opened read-only (as all files in the store are read-only to begin with).

See also: "filename".

update

$file->update;
# or:
$file->update(%opts);

Updates the file in the database. Also performs a verify of the file as part of the update.

The following (all optional) options are supported:

no_digests

This will try to skip digest calculation.

stat

my @res = $file->stat;

This method performs the same task and returns the same values as "stat" in perlfunc. In contrast however it dies if the request cannot be performed. This however can only happen if the store is corruped.

The value is cached. Therefore some attributes (mostly atime) might be out of sync. However those attributes are unreliable to begin with, hence the cache doesn't really make this worse.

Note: If you plan to perform an "open" on this file call that first and then this method. This will improve performance and reduce the chance of race conditions.

get

my $value = $file->get($domain => $key);
# or:
my $hashref = $file->get($domain);
# or:
my $hashhashref = $file->get;

Returns information about the file. If a $domain and $key is given the value is returned as scalar. If only a $domain is given all values for that domain are returned as a hashref. If no parameters are given a hashref with the domains as keys and the hashrefs of the per-domain values is returned.

If a value is unknown this method dies.

The following domains are supported:

properties

This domain contains flat properties of the file sich as it's size.

See "PROPERTIES".

digests

This domain contains digests for the file as known. Those are the final digests. If the file does not match the those values at this point it is corruped.

The key is the digest name in universal tag (utag) format (e.g. sha-3-224).

set

$file->set($domain => $key => $value);
# or:
$file->set($domain => {$key => $value});
# or:
$file->set({$domain => {$key => $value}});

This sets a value on the file. The value is checked against already known values. If a value is set for a key that already holds a value this method dies if the values missmatch.

This method takes a domain-key-value triplet, or a domain and a hashref with multiple values, or a single hashref with the domain(s) as keys and hashrefs with key-value pairs as values.

See also: "get".

store

my File::FStore $store = $file->store;

Returns the store this file belongs to.

db

my Data::TagDB $db = $file->db;
# or:
my Data::TagDB $db = $file->db(default => $def);

Proxy for "db" in File::FStore.

extractor

my Data::URIID $extractor = $file->extractor;
# or:
my Data::URIID $extractor = $file->extractor(default => $def);

Proxy for "extractor" in File::FStore.

fii

my File::Information $fii = $file->fii;

Proxy for "fii" in File::FStore.

PROPERTIES

The following properties are known.

size

The file size in bytes.

inode

The inode number. The value is specific to the filesystem the file is on.

mediasubtype

The media subtype of the file.

Warning: This property is commonly very missunderstood. It is best to not set this manually and let the store maintain the value. Setting this value is acceptable when importing data from another store or from a File::Information::Base object.

Note: Only values listed at https://www.iana.org/assignments/media-types/media-types.xhtml are valid. Any value not listed by IANA is invalid.

contentise

The content ISE (identifier) value. This value is mainly maintained internally, however may be set early as a mean to verify the file integrity. For reading the value there is a special method "contentise".

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)