NAME

SYNOPSIS

  use Fuse::Simple qw(accessor main);
  my $var = "this is a variable you can modify. write to me!\n";
  my $filesystem = {
    foo => "this is the contents of a file called foo\n",
    subdir => {
      "foo"  => "this foo is in a subdir called subdir\n",
      "blah" => "this blah is in a subdir called subdir\n",
    },
    "blah" => \ "subdir/blah",        # scalar refs are symlinks
    "magic" => sub { return "42\n" }, # will be called to get value
    "var"  => accessor(\$var),        # read and write this variable
    "var2" => accessor(\$var),        # and the same variable
    "var.b" => accessor(\ my $tmp),   # and an anonymous var
  };
  main(
    "mountpoint" => "/mnt",      # actually optional
    "debug"      => 0,           # for debugging Fuse::Simple. optional
    "fuse_debug" => 0,           # for debugging FUSE itself. optional
    "threaded"   => 0,           # optional
    "/"          => $filesystem, # required :-)
  );

DESCRIPTION

IMPORT TAGS

:usual

Includes: main accessor fserr nocache

:debug

Includes: wrap quoted dump_open_flags

:tools

Includes: fetch runcode saferun easy_getattr

:filesys

Includes: fs_not_imp fs_flush fs_getattr fs_getdir fs_open fs_read fs_readlink fs_release fs_statfs fs_truncate fs_write

MAIN FUNCTION

main(arg => value, ...)

Mount your filesystem, and probably never return. Arguments are:

UTIL FUNCTIONS

fetch($path, @args) (not exported)

Given /a/path/within/my/fs/foo, return the foo dir or file or whatever. @args will be passed to the final coderef if supplied.

runcode($code, @args) (not exported)

IF WE'RE GIVEN A CODEREF, run it, or return our cached version return after all CODE refs have been followed. also returns first arg if it wasn't a coderef.

saferun($sub,@args)

Runs the supplied $sub coderef, safely (IE catches die() etc), returns something usable by the rest of Fuse::Simple.

fserr($error_number)

Used by called coderef files, to return an error indication, for example:

  return fserr(E2BIG());
    

nocache($stuff_to_return)

Used by called coderef files, to return something that should not be cached.

wrap($sub, @name_etc)

Wrap a function with something that'll dump args on the way in and return values on the way out. This is a debugging fuction, sorta like strace for perl really.

quoted(@list)

return a nice printable version of the args, a little like Data::Dumper would

dump_open_flags($flags)

Translate the flags to the open() call

accessor(\$var)

return a sub that can be used to read and write the (scalar) variable $var:

  my $var = "default value";
  my $fs = { "filename" => accessor(\$var) };
    

This accessor is a bit over-simple, doesn't handle multi-block writes, partial block writes, seeked reads, non-saclar values, or anything particularly clever.

easy_getattr($mode, $size)

Internal function, to make it easier to return getattr()s 13 arguments when there's probably only 2 you really care about.

Returns everything else that getattr() should.

FUSE FILESYSTEM FUNCTIONS

fs_not_imp()

return ENOSYS "Function not implemented" to the program that's accessing this function.

fs_flush($path)

fs_getattr($path)

fs_getdir($path)

fs_open($path, $flags)

fs_read($path, $size, $offset )

fs_readlink($path)

fs_release($path, $flags)

fs_statfs()

fs_truncate($path, $offset)

fs_write($path, $buffer, $offset)

CODEREF FILES / ACCESSORS

They will be called with new contents and an offset if there's something to be written to them, and can return almost anything, which will be ignored unless it's an fserr().

It's also called with an empty string and an offset if it's to be truncated, and can return almost anything, which will be ignored unless it's an fserr().

  sub mysub {
    my ($contents, $off) = @_;
    if (defined $contents) {
      # we are writing to this file
    } else {
      # we are to return the contents
    }
  }
  my $fs = {
    "magic" => \&mysub,
  };

Will be called like:

  cat /mnt/magic
    mysub();           # the file is being read
  echo "123" > /mnt/magic
    mysub("123\n", 0); # the file is being written
  : > /mnt/magic
    mysub("", 0);      # the file is being truncated

You can return a string, which is the contents of the file.

You can return an fserr() for an error.

You can return a hashref (your sub will look like a directory!)

You can return a scalar ref (your sub will look like a symlink), etc.

You can even return another coderef, which will be called with the same args.

If your program die()s, you'll return ESTALE "Stale file handle".

If you die(fserr(E2BIG)), you'll return that specified error.

If you die(nocache("An error message\n")) you'll actually not return an error, but return a file containing that error message.

It would be rather disgusting to suggest that you could also die { "README" => "Contents\n" } to return a directory, so I won't :-)

Now... This isn't actually the whole story. An "ls" command will also "read" your "file", because it needs to know the length. To avoid calling your routines TOO often, the result will be cached on the first "getdir()" type operation, and then returned when you REALLY read it. The cache will then be cleared so, for example:

  ls /mnt/             # mysub("");
  ls /mnt/magic        # return cached copy
  ls -Fal /mnt/magic   # return cached copy
  cat /mnt/magic       # return cached copy, but clear cache
  cat /mnt/magic       # mysub("");          and clear cache
  ls /mnt/magic        # mysub("");
  ls /mnt/magic        # return cached copy
  echo foo >/mnt/magic # mysub("foo",0);
  ls /mnt/magic        # mysub("");
  ls /mnt/magic        # return cached copy

EXAMPLES

  see L</SYNOPSIS>

NOTES

BUGS

Please report any bugs or feature requests to <bug-fuse-simple at rt.cpan.org>, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Fuse-Simple>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

    perldoc Fuse::Simple

You can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

  <http://annocpan.org/dist/Fuse-Simple>

• CPAN Ratings

  <http://cpanratings.perl.org/d/Fuse-Simple>

• RT: CPAN's request tracker

  <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Fuse-Simple>

• Search CPAN

  <http://search.cpan.org/dist/Fuse-Simple>

ACKNOWLEDGEMENTS

SEE ALSO

The FUSE documentation at <http://fuse.sourceforge.net/>

<http://noseynick.org/>

AUTHOR

COPYRIGHT AND LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.