File 'fmail.tcl' (part of 'Fmail')

::fmail::Action (ip name arguments body)
Wrapper around ::fmail::action to allow its usage from within a rule interpreter executing a rule script. Speciality: The new action is automatically added to the calling interpreter. Aliased into the rule interpreter, thus executed in the trusted environment.
Argument: ip	Handle of the interpreter calling the command. Used to link the new action into the calling interpreter.
Argument: name	The name of the new action.
Argument: arguments	A list containing the names of the arguments to the new action.
Argument: body	The code to execute when calling the action.
Returns: is name.

::fmail::CfgGet (ip key)
Wrapper around ::fmail::cfgGet to allow its usage from within a rule interpreter executing a rule script. Aliased into the safe interpreter.
Argument: ip	Handle of the interpreter calling the command. Ignored.
Argument: key	The name of the configuration variable to retrieve.
Returns: as of ::fmail::cfgGet

::fmail::CfgRead ()

The main procedure reading the configuration of fmail. Its operation is explained in the user manual, see <xref user-cfg>.

::fmail::CfgSet (ip key value)
Wrapper around ::fmail::cfgSet to allow its usage from within a rule interpreter executing a rule script. Aliased into the safe interpreter.
Argument: ip	Handle of the interpreter calling the command. Ignored.
Argument: key	The name of the configuration variable to set.
Argument: value	The new value of the variable.
Returns: None. As of ::fmail::cfgSet

::fmail::CfgWritePersistentConfiguration ()

This procedure is called upon exit if a persistent variable was changed (See ::fmail::cfgSet and ::fmail::cfgLappend) and writes the contents of all persistent variables into the file read later upon the next startup.

::fmail::Clone (cmd)
Takes the name of a tcl procedure and then uses introspection to generate tcl code whose evaluation will create the procedure. Namespace references in the name of the procedure are ignored, i.e. the generated code will contain only the plain unqualified name.
Argument: cmd	Name of the procedure to clone.

::fmail::ExecuteAction (ip action arglist)
Procedure handling the execution of actions in rule interpreters. The main speciality is catching the special abort error code and propagating it upward instead of generating an error for it.
Argument: ip	Handle of the rule interpreter to execute the action in..
Argument: action	Name of the action to execute.
Argument: arglist	Additional arguments given to the action.

::fmail::Input (ip method args)
This procedure wraps around the input object. Calls to the object methods are delegated to it, but predicates are executed here. Assumes that predicates are simple functions not yielding control back to the interpreter via "vwait" or "update". This is required to enable us to store the calling rule interpreter in a global state variable without fear of getting it overwritten. This is required to allow the use of predicates in the body of a predicate as that is the only way of making the rule interpreter known to these nested invocations. Feather and its curried objects should make this fragile construction obsolete. I hope that it comes in #source soon.
Argument: ip	The handle of the calling rule interpreter.
Argument: method	Name of the called method.
Argument: args	The argument to give to the method.
Returns: as of the called method or predicate.

::fmail::InsertAction (ip cmd)
Copies the specified action into the named interpreter.
Argument: ip	Handle of the interpreter to copy the command into.
Argument: cmd	Name of the command / procedure to copy into the interpreter.

::fmail::Log (ip text)
Logging command. Available to rule scripts for generation of debugging output. Beware, the log is currently not protected against parallel access from multiple processes.
Argument: ip	The handle of the rule interpreter calling the command.
Argument: text	The text to write into the log.

::fmail::Pipeto (ip cmd args)
Standard action, but not defined as such to avoid the transfer of channel handles between interpreters. Executes the cmd with its arguments (args). A serialized representation of the input object is fed into the standard input of the command (via an anonymous pipe). This representation is obtained and sent by a call to the method 'copy2channel' of the 'input' object. The channel to sent the data to is provided as the single argument of this call. Remark: This command is in the grey area between the pure intent-independent language elements and the mail specific code. It imposes a restriction on the interface of the 'input' object, but does not declare the object to be a mail. To avoid this was the main reason behind the wording of a 'serialized representation'.
Argument: ip	Handle of the rule interpreter calling this action.
Argument: cmd	The external command to pipe the input object to.
Argument: args	Additional arguments to the cmd.

::fmail::PredExpr (input e)
Internal procedure used by 'allof' and 'anyof' to interpret one of its arguments, by either calling the specified predicate or evaluating it as an expression.
Argument: input	Contains the name of the command under which the input object can be reached.
Argument: e	The list element to interpret.
Returns: Either the result from the expression, or the value returned by the predicate.

::fmail::Process (ip ruleset args)
Wrapper around ::fmail::process, allows the execution of nested rule scripts. The nested script is executed in the same interpreter as the calling script. Aliased into the rule interpreter.
Argument: ip	Handle of the rule interpreter calling it.
Argument: ruleset	The name of the ruleset to execute.
Argument: args	Empty, or a list containing 2 arguments. The first is ignored, the second specifies the name of the object command to use in the nested rules.

::fmail::RcRead ()

Locates and executes the main re#source file. Afterward the system is ready to read the configuration. See <xref user-cfg> too.

::fmail::__Setup ()

Noop, just here to provide the other parts of the package an entrypoint for autoloading this file.

::fmail::action (name arguments body)
The command to define a new action.
Argument: name	The name of the new action.
Argument: arguments	A list containing the names of the arguments to the new action.
Argument: body	The code to execute when calling the action.
Returns: is name.

::fmail::actionName (name)
Encapsulates the conversion from action names to the name of the procedures implementing them. Well, not really implementing them, it is more like serving as storage before copying them to the rule interpreter executing a rule script.
Argument: name	The name of the action we want to store.
Returns: The name of the procedure to use as store for the action code.

::fmail::always (ip action args)
Implements the always rule.
Argument: ip	Handle of the rule interpreter calling the command.
Argument: action	Name of the action executed by the rule.
Argument: args	Additional arguments given to the action.

::fmail::cfgDefine (key persistent initialvalue)
Defines a configuration variable, possibly with an initial (default) value. In case of multiple definitions with the same key the last definition counts. Because of this the persistence mechanism loads the last values at last, to avoid having them overwritten here.
Argument: key	The name of the variable defined here
Argument: persistent	Flag, specifies wether the last value of this variable shall persist to the next invocation of the package.
Argument: initialvalue (= {})	The value to set upon definition.
Returns: None.

::fmail::cfgGet (key)
Retrieve the value of the specified configuration variable.
Argument: key	The name of the configuration variable to retrieve.
Returns: The contents of the named configuration variable.

::fmail::cfgLappend (key value)
Convenience procedure. Appends the specified value to the contents of the named configuration variable, treating it as a list. Schedules a write on exit if the changed variable was as persistent.
Argument: key	The name of the configuration variable to set.
Argument: value	The new value of the variable.
Returns: None

::fmail::cfgSet (key value)
Sets the value of the specified configuration variable. Schedules a write on exit if the changed variable was as persistent.
Argument: key	The name of the configuration variable to set.
Argument: value	The new value of the variable.
Returns: None

::fmail::def (name rulescript)
Defines a new rule set via its name and script to execute. An existing set with the same name will be destroyed.
Argument: name	Name of the rule set.
Argument: rulescript	The script to execute upon invocation of the rule set.
Returns: The name.

::fmail::default (ip action args)
Like ::fmail::always, but with a twist. It aborts the execution of rules after the execution of the specified action.
Argument: ip	Handle of the rule interpreter calling the command.
Argument: action	Name of the action executed by the rule.
Argument: args	Additional arguments given to the action.

::fmail::input (method args)
The second wrapper around the input object. This one is used by the trusted part of the system to enable recursive calls to predicates from within a predicate. See ::fmail::Input too.
Argument: method	Name of the called method.
Argument: args	The argument to give to the method.
Returns: As of the called method or predicate.

::fmail::never (ip action args)
Implements the never rule.
Argument: ip	Handle of the rule interpreter calling the command. Ignored
Argument: action	Name of the action which is ignored by the rule.
Argument: args	Additional arguments to the action, these are ignored too.

::fmail::on (ip condition action args)
Implements the main rule element, conditional execution of actions. Aliased into the rule interpreter. This is necessary to allow the trusted evaluation of the condition and any predicate inside.
Argument: ip	Handle of the rule interpreter calling the command.
Argument: condition	The condition guarding the action. The action is executed if and only if the condition evaluates to true. The condition is interpreted as an expression.
Argument: action	The name of the action to execute if the condition gave approval.
Argument: args	Additional arguments given to the action

::fmail::predicate (name arguments body)
The command to define a new predicate.
Argument: name	The name of the new predicate.
Argument: arguments	A list containing the names of the arguments to the new predicate.
Argument: body	The code to execute when calling the predicate.
Returns: is name.

::fmail::process (datacmd via rules)
Evaluates a rule set (i.e. its script) for a specific object. The object is given through its main command. This object is called the "input object", or short "input". Uses a separate interpreter for the evaluation to minimize possible damage by erroneous rule scripts.
Argument: datacmd	Name of the main command for the input object.
Argument: via	Dummy argument, ignored. Allows syntactic sugar when calling the procedure.
Argument: rules	The name of the rule set to evaluate.