NAME

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

VERSION

version v0.04

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.

This package inherits from File::FStore::Base.

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".

open

my $fh = $file->open;

$fh->binmode; # allow binary data.

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).

Note: This module doesn't set the handle to binary mode similar to "open" in perlfunc. See "binmode" in perlfunc for details.

See also: "filename".

link_out

$file->link_out($filename);

Creates an hardlink to this file as $filename. dies on any error.

See also: "link" in perlfunc.

symlink_out

$file->symlink_out($filename);

Creates an symlink to this file as $filename. dies on any error.

See also: "symlink" in perlfunc.

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.

on_pre_set

A callback that is called before any data is set (see "set") on this file. $file is passed as first argument.

on_post_set

A callback that is called after all data is set (see "set") on this file. $file is passed as first argument.

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".

delete

$file->delete;

Removes the given file from the store. This also unlinks all links within the store.

If there is no hardlink outside the store to the given file it is fully removed from the filesystem.

Note: After this call no future calls are allowed on this handle or any other handle referencing the same file.

sync_with_db

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

Syncs the file with the database. It may read data from, and write data to the database related to this file.

Note: This method calls "in_transaction" in Data::TagDB with type rw.

It mainly operates on three tags:

content

The content tag is the tag that represents the state of this file (size, digests, ...) (but not the filesystem object or other objects).

See also "contentise".

inode

The inode tag represents the actual file on the filesystem. This is the tag file system browsing software will use.

The inode tag has the content tag as it's final state.

See also "inodeise" in File::Information::Base.

proto

The proto tag represents the work independent on the filesystem. This is often used by software that implement some kind of catalogue.

The proto tag has the content tag as a state, maybe as it's final state.

The following (all optional) options are supported:

autocreate

Whether tags should be automatically created if not yet part of the database.

Defaults to false.

See also "as" in Data::Identifier.

db

The database object to use.

Defaults to the value returned by "db".

final_of_proto

Whether this file is the final state of the proto tag (true value) or just one of it's states (false value).

Defaults to false.

proto

The tag to be used as proto tag (if any). This may be anything that "as" in Data::Identifier will accept.

Defaults to undef.

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".

inodeise

The inode ISE (identifier) value. This value represents the inode on the file system. It is mainly maintained internally, but used by and imported from external sources such as tagpool. The value is stable for the inode's lifetime. It may be different or the same if the inode number is reused. It is stable since when the inode was created and also doesn't change when the inode is written to (in contrast to "contenise".

See also: "get" in File::Information::Base.

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)

cpanm File::FStore

perl -MCPAN -e shell
install File::FStore