NAME
Fuse::TM - Access a Topic Map as a Filesystem
SYNOPSIS
use Fuse::TM;
use TM;
my $map;
# map must be created/synced in somehow, see TM(1).
my $tmfs=Fuse::TM->new(tm=>$map,rw=>1,debug=>1);
# this blocks until the filesystem is unmounted,
# see fusermount.
$tmfs->mount("/tmp/somedir"); See also the tmfs(1) front-end.
DESCRIPTION
This package provides access to a Topic Map in form of a filesystem. Read-write access to the map is supported.
Filesystem Layout
The mountpoint will be populated with exactly two directories, topics and assocs.
Topics
The topics in the map are modelled as directories, one per topic, under the topics directory. Each topic directory contains a number of sub-directories and some files, all of which have fixed names. The following list details those elements:
- instance
-
is a subdir which contains symlinks to all topics that are instances of this topic. The topic ids are used as names for the symlinks. If no instances are present then the directory is empty.
- isa
-
is a subdir which contains symlinks to all topics this topic is an instance of (=classes). The topic ids are used as names for the symlinks. If no parent classes are present then the directory is empty.
- instances
-
is a read-only file that contains the topic ids of instances of this topic, one per line. The file is empty if no instances are present.
- isas
-
is a read-only file that contains the topic ids of all topics this one is an instance of (=classes), one per line. The file is empty if no classes are present.
- involved
-
is a read-only subdir which contains symlinks to all associations where this topic is involved (as a player, role or type). The names of the symlinks are of the format N:T, with N an arbitrary number and T either "role", "player" or "type" depending on the involvement of the topic. The dir is empty if no involvements are present.
- name
-
is a subdir that contains all basenames of this topic. The basenames are presented in separate files, with all filenames following the format N[@S][:T]. N is a running number, S is the scope topic id if the basename is (non-universally) scoped, and T is the type topic id if the basename is (non-trivially) typed. The content of the file is the basename text. The dir is empty if no basenames are present.
- oc
-
is a subdir that contains all occurrences attached to this topic. The occurrences are presented in separate files whose names follow the same scheme as basenames. The file content is the occurrence (text or URI). The dir is empty if no occurrences are present.
- ~
-
is a file that contains all subject indicator URIs for this topic, one URI per line. Present but empty if no subject indicators exist.
- =
-
is a symlink that points to a subject locator topic (=reified by this topic). If the topic reifies another topic or association in the same map, then the symlink points to that object. If the reified topic is given as URI, then the symlink will point to that URI (and thus likely dangle). The symlink is not present if this topic doesn't reify another.
Associations
Isa (class/instance) associations are presented as characteristics attached to the relevant topics (see isa/instance above).
All other, general, associations are modelled as directories under the assocs directory. For each association type there is a subdir under assocs with the type topic id as name. Within that, each thusly typed association instance is represented as a subdir with a running number as name.
This association instance directory contains one symlink named .type pointing back to the type topic for this association. For each role in the association there is a subdir named after the role topic id, which contains symlinks for all the player topics of this role.
METHODS
- new()
-
$tmfs=Fuse::TM->new(tm=>$tmobj,option=>value,...);
The constructor requires a TM map object and accepts the following other options, to be given as key/value pairs:
- debug
-
Debugging: if set to 1, Fuse::TM internal debugging is enabled (to STDERR). If set to 2, Fuse debugging is enabled additionally. Default: undef.
- rw
-
Read-write mode: if set to 1 the filesystem is mounted read-write and changes are written out the the map on unmounting. Defaults to undef: read-only mode.
- autocreate
-
Autocreate implied topics. If set to 1 and read-write mode is active, then non-existent topics are automatically created when a write action implies their existence. Default: undef.
For example writing to the file topics/x/oc/1:something will create the topic "something" if it didn't exist because the filename implies the occurrence to be of type "something".
- hide
-
Hide infrastructure items. If set to 1 infrastructure topics and associations are suppressed. See TM::PSI for details of what infrastructure elements are automatically created (and subject to the hide option). Default: undef.
- output
-
Output URI. If read-write mode is active and there were changes then the updated map is written on unmount. This option controls whether the original map is overwritten (default) or whether the new map is saved someplace else. The output parameter must follow the URI format described in TM::Serializable (i.e. io:stdout or file:something).
- outputdriver
-
TM Driver to use for the output. Defaults to the driver of the input map. Can be set to the name of a TM class that supports sync_out (i.e. TM::Materialized::*, TM::Serializable::* or TM::Synchronizable::*).
The constructor will croak() if problems are encountered.
- mount()
-
$tmfs->mount("/some/mount/dir");
Calls Fuse to mount the filesystem at the specified mount point, which must be an existing directory. This function blocks until the filesystem is unmounted. If read-write mode is enabled, then the updated map will be saved on unmount. mount will croak() if problems are encountered.
LIMITATIONS
Filesystem Attributes
File ownership is not modelled at all: all files and dirs belong to uid 0, root.
Permissions are not modelled fully: in read-only mode all files are mode 0444 and dirs 0555. In read-write mode all files are mode 0644 and dirs 0755.
Mode or ownership changes are not supported.
Write Support
Until the filesystem is unmounted any modifications are kept in memory only.
Overwriting files is only allowed for names, occurrences and subject indicators. Attempts to write to other files will result in EPERM errors.
Creating new files or renaming them is only allowed for names and occurrences. Attempting others will result in an EPERM. Renaming works for names or occurrences if they stay with the same topic, or for topics. Nothing else can be renamed and EFAULT errors will result if you try.
Renaming of topics is possible (and all involved others are updated accordingly). Neither fixed topic characteristic dirs (e.g. oc, name, isa) nor association instance dirs can be renamed.
(Re)Naming something with an unacceptable name will cause ENOENT errors.
Symbolic links cannot point outside the current map's filesystem, with the sole exception being a subject locator URI symlink.
Removing a topic is not possible if it is used as an association type or association role: EBUSY will be the result if you try. To remove an association type topic first all association instances must be removed.
Removing of a topic clears up all involvements: if used as a scope the scope will be changed to universal, if used as a type the type will be cleared, if used as role player then this player vanishes.
SEE ALSO
AUTHOR
Alexander Zangerl, <alphazulu@cpan.org>
COPYRIGHT AND LICENSE
Copyright 2009 Alexander Zangerl
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.