NAME
File::FStore::File - Module for interacting with file stores
VERSION
version v0.02
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;
$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
. die
s on any error.
See also: "link" in perlfunc.
symlink_out
$file->symlink_out($filename);
Creates an symlink to this file as $filename
. die
s 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.
stat
my @res = $file->stat;
This method performs the same task and returns the same values as "stat" in perlfunc. In contrast however it die
s 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 die
s.
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 die
s 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
.
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)