mvmf: mvmf-namespaces man page
mvmf: mvmf-namespaces man page
MVMF-NAMESPACES(5) File Formats Manual MVMF-NAMESPACES(5)
SYNOPSIS
mvmf-namespaces - Namespaces in mvmf and MFL
DESCRIPTION
When you write (or your MFL script writes) a mail message, you specify a
name to write to. That name itself is neither a folder nor a filename,
but a combination of namespace and element within it. The namespace is
selected by the first part of the name. Perhaps an example is best be-
fore going further. Let's say you have a sieve statement:
fileinto "FOLDERS/work";
In this example, we'll say that the namespace is called "FOLDERS/" and
that the statement puts the message into something called "work" within
that namespace. And that's the gist of it. The first part of the name
that you use will match a namespace name, and the rest of the name has
some meaning within that namespace. When you write a script to file a
message, you have to know what namespaces are available, and perhaps a
little bit about them. Punctuation, such as the slash in this example,
is like any other characters -- it is a part of the name but has no spe-
cial significance here (some punctuation may have meaning for specific
contexts, but not in interpretation of namespaces).
One idiosyncracy (er, niffty aspect) of mvmf namespaces is that the
longest namespace name wins. One can imagine mvmf namespaces being cre-
ated to match a common sieve and IMAP model: that a name "INBOX" refers
to your incoming mail folder, whereas a name "INBOX.something" refers to
a subfolder called "something". "INBOX" and "INBOX." can be two differ-
ent namespaces with very different characteristics. For example, "IN-
BOX" could refer to an mbox format mailbox at '/var/mail/user', whereas
"INBOX." could map to a Maildir++ hierarchy within the user's home di-
rectory. Or if you are a UNIX shell user, you might create two parallel
namespaces that refer to the same directory, but which have different
default storage types. (e.g. "MAILDIR/" and "MBOX/"). (Note that if a
folder already exists, mvmf will attempt to use it via whatever type it
is, regardless of the default type of the namespace.)
A namespace name can be empty (blank). If you define a namespace with
an empty name, it will be the namespace of last resort; i.e., it will
match anything not matched by a namespace with a longer prefix.
It's anticipated that in most environments an administrator has defined
the namespaces you can use and has made them known to you. If, on the
other hand, YOU are the administrator, or if you are running an mvmf
utility standalone, or if you simply want to create your own namespaces,
you need to know some details of creating and parameterizing namespaces.
To create (and fully understand) namespaces, you need to know how they
are parameterized. Don't be daunted by the length of this text, it's
really fairly straightforward.
In mvmf, a message folder has a specific storage type. Specific storage
types include "mbox" and "maildir".
Within the specific storage type is a general storage type. You will
never touch this directly, but it's important to know that some of the
specific storage types' attributes are really associated with the gen-
eral type. The specific types "mbox" and "maildir" are of the general
storage type "file" -- and files have certain things that you can say
about them.
When you create a namespace, you tell it the specific storage type for
any new folders created in that namespace. The namespace gets a copy of
all of the attributes that have been defined for that specific storage
type at that time. Namespaces themselves may have attributes that re-
late to namespaces only, and not to any particular storage type.
With that, when you are defining how you want your folders to work,
you'll do these general things:
-- assign attributes to specific storage types. e.g. you might want to
specify how locking of mbox types works, before deriving any name-
spaces from it.
-- create namespaces relating to specific storage types, and give them
additional attributes.
There are attributes associated with storage types and namespaces. Each
attribute has a name and a value. Values are either strings or integers.
Integer values may be presented as strings but are interpreted as inte-
gers.
General file type attributes
We mentioned that there are "specific" and "general" storage types.
There is no direct interface to the general storage type attributes,
they are set and accessed via the specific types. There may be general
attributes that apply to all specific types related to it (perhaps with
interpretations relevant to the specific type), and there may also be
individual attributes that apply only to certain specific types.
Here are attributes that can be associated with anything that is related
to the general storage type "file" . This includes the "mbox" and
"maildir" specific types, and any namespace associated with them.
layout (string)
how the names are laid out within the namespace's directory path.
A layout type of "fs" (or "filesystem") simply maps the folder
name's tail (the part after the namespace prefix) to a file
within the namespace's path. A layout type of "maildir++" is
similar, except that it adds a leading "." character to the
filename, and replaces all "/" characters with "." . See also
the namespace "tailhook" hack that provides a way for you to edit
the tail.
locking (string)
what sort of locking to apply. This is a comma-separated list of
locking specifications, which are applied in the order given.
Each specification is simply the name of the locking type to use:
choose from the set {dotlock, fcntl, flock, lockf}. Note that
your system might not support all of them; any type not supported
is ignored. If there are no recognized lock types in the at-
tribute you set, no locking is done!
mbox and maildir specific type attributes
At present there are no specific attributes defined only for mbox or
maildir that aren't also defined for general file storage type.
Namespace attributes
Attributes for namespaces:
path (string)
the filesystem path for that namespace.
Namespace tailhook
There is also a "tailhook" capability associated with namespaces. This
provides you a way to alter the tail part of the folder name before it's
used in generating the full folder name. The tailhook is an MFL func-
tion that you write that massages the tail string. Remember that the
folder name is viewed as a namespace prefix followed by a folder tail.
When you provide a tailhook, the tail portion is passed to that hook,
which must return a new string that represents the tail string you re-
ally want.
For example, let's say (as in the example below) you have a namespace
"MBOX/" that might refer to a directory "Mail/" in users' home direc-
tory. When writing to "MBOX/MINE" the default action would be to write
to "Mail/MINE". You could define a tailhook "mail_tail" to add a prefix
and to make the foldername lowercase:
string mail_tail( string tail ) {
return ( (string)"xx-" + $str_lower(tail) );
};
(Note well: this is a hack that is done this way because MFL does not
yet have lambda expressions. If lambda expressions come to pass, this
tailhook association might be phased out.)
(PS: 20 years later, in October 2025, this hasn't happend.)
MFL namespace functions
use the "$msst_" and "$msns_" families of built-in functions to assign
attributes and to define namespaces. Refer to the documentation con-
cerning built-in-functions in MFL (e.g. on the mvmf website) for
specifics.
Examples
This sequence will define an INBOX namespace that points to the incoming
mbox in /var/mail, an "INBOX." namespace that refers to a Maildir in the
users' home directory, and two namespaces MAILDIR/ and MBOX/ which refer
the user's "Mail" subdirectory (this is fairly unsophisticated; real
code might have more checks). For the MAILDIR and MBOX namespaces, a
"mail_tail" tailhook is associated-- note that the mail_tail function
must be defined before the namespace is used. Here, we'll assume that
it's defined as in the example above.
// Parameterize the way we want specific types to work by default
$msst_attr_set( "mbox", "locking", "dotlock, flock" );
$msst_attr_set( "mbox", "layout", "fs" );
$msst_attr_set( "maildir", "layout", "maildir++" );
// Create the INBOX
$msns_define( "INBOX", "mbox" );
$msns_attr_set( "INBOX", "path",
(string)"/var/mail/" + $env_variable( "USER" ) );
// Create the "INBOX." namespace for default folder storage
// inside ~/Maildir
$msns_define( "INBOX.", "maildir" );
$msns_attr_set( "INBOX.", "path", (*$env_homedir()) + "/Maildir" );
// Create the MAILDIR and MBOX namespaces which are different views
// into the same directory. Note the override of the layout for
// the maildir view.
$msns_define( "MAILDIR/", "maildir" );
$msns_attr_set( "MAILDIR/", "path", (*$env_homedir()) + "/Mail" );
$msns_attr_set( "MAILDIR/", "layout", "fs" );
$msns_tailhook( "MAILDIR/", "mail_tail" );
$msns_define( "MBOX/", "mbox" );
$msns_attr_set( "MBOX/", "path", (*$env_homedir()) + "/Mail" );
$msns_attr_set( "MBOX/", "layout", "fs" );
$msns_tailhook( "MBOX/", "mail_tail" );
Now one can reference the ~/Maildir subfolder xx as "INBOX.xx" .
When a script writes to "MBOX/foo" (that doesn't previously exist), the
file ~/Mail/xx-foo will be created as an mbox; writing to a new
"MAILDIR/foo" will create ~/Mail/xx-foo as a maildir. (The "xx-" is
added by the tailhook).
SEE ALSO
mvmda(1)
http://www.mvmf.org/ -- the official web site.
CREDITS TO
M. Mallett (mem@mvmf.org) 2003-2025
BUGS
You tell me..
MVMF-NAMESPACES(5)