+<!--}}}-->
+
+<sect>Expansion within variables <!--{{{-->
+
+ <p>Besides just assign static content to variables, there's plenty of
+ ways of adding external and more or less dynamic content.
+
+ <sect1>Commands' Output
+
+ <p>It is possible to substitute the output of a Unix command in an
+ initialization file. This is accomplished by enclosing the command
+ in backquotes (``) as in, for example:
+
+<tscreen><verb>
+my_hdr X-Operating-System: `uname -a`
+</verb></tscreen>
+
+ <p>The output of the Unix command ``uname -a'' will be substituted
+ before the line is parsed. Note that since initialization files are
+ line oriented, only the first line of output from the Unix command
+ will be substituted.
+
+ <sect1>Environment Variables
+
+ <p>UNIX environments can be accessed like the way it is done in
+ shells like sh and bash: Prepend the name of the environment by a
+ ``$'' sign. For example,
+
+<tscreen><verb>
+set record=+sent_on_$HOSTNAME
+</verb></tscreen>
+
+ <p>sets the <ref id="record" name="$record"> variable to the
+ string <em/+sent_on_/ and appends the value of the evironment
+ variable <tt>$HOSTNAME</tt>.
+
+ <p><bf/Note:/ There will be no warning if an environment variable
+ is not defined. The result will of the expansion will then be empty.
+
+ <sect1>Configuration Variables
+
+ <p>As for environment variables, the values of all configuration
+ variables as string can be used in the same way, too. For example,
+
+<tscreen><verb>
+set imap_home_namespace = $folder
+</verb></tscreen>
+
+ <p>would set the value of <ref id="imap_home_namespace"
+ name="$imap_home_namespace"> to the value to
+ which <ref id="folder" name="$folder"> is <em/currently/ set
+ to.
+
+ <p><bf/Note:/ There're no logical links established in such cases so
+ that the the value for <ref id="imap_home_namespace"
+ name="$imap_home_namespace"> won't change even
+ if <ref id="folder" name="$folder"> gets changed.
+
+ <p><bf/Note:/ There will be no warning if a configuration variable
+ is not defined or is empty. The result will of the expansion will
+ then be empty.
+
+ <sect1>Self-Defined Variables
+
+ <p>Mutt-ng flexibly allows users to define their own variables. To
+ avoid conflicts with the standard set and to prevent misleading
+ error messages, there's a reserved namespace for them: all
+ user-defined variables must be prefixed with <tt/user_/ and can be
+ used just like any ordinary configuration or environment
+ variable.
+
+ <p>For example, to view the manual, users can either define two
+ macros like the following
+
+<tscreen><verb>
+macro generic <F1> "!less -r /path/to/manual" "Show manual"
+macro pager <F1> "!less -r /path/to/manual" "Show manual"
+</verb></tscreen>
+
+ <p>for <tt/generic/, <tt/pager/ and <tt/index/. The alternative is to
+ define a custom variable like so:
+
+<tscreen><verb>
+set user_manualcmd = "!less -r /path/to_manual"
+macro generic <F1> "$user_manualcmd<enter>" "Show manual"
+macro pager <F1> "$user_manualcmd<enter>" "Show manual"
+macro index <F1> "$user_manualcmd<enter>" "Show manual"
+</verb></tscreen>
+
+ <p>to re-use the command sequence as in:
+
+<tscreen><verb>
+macro index <F2> "$user_manualcmd | grep '\^[ ]\\+~. '" "Show Patterns"
+</verb></tscreen>
+
+ <p>Using this feature, arbitrary sequences can be defined once and
+ recalled and reused where necessary. More advanced scenarios could
+ include to save a variable's value at the beginning of macro
+ sequence and restore it at end.
+
+ <p>When the variable is first defined, the first value it gets
+ assigned is also the initial value to which it can be reset using
+ the <tt/reset/ command.
+
+ <p>The complete removal is done via the <tt/unset/ keyword.
+
+ <p>After the following sequence:
+
+<tscreen><verb>
+set user_foo = 42
+set user_foo = 666
+</verb></tscreen>
+
+ <p>the variable <tt>$user_foo</tt> has a current value of 666 and an
+ initial of 42. The query
+
+<tscreen><verb>
+set ?user_foo
+</verb></tscreen>
+
+ <p>will show 666. After doing the reset via
+
+<tscreen><verb>
+reset user_foo
+</verb></tscreen>
+
+ <p>a following query will give 42 as the result. After unsetting it
+ via
+
+<tscreen><verb>
+unset user_foo
+</verb></tscreen>
+
+ <p>any query or operation (except the noted expansion within other
+ statements) will lead to an error message.
+
+ <sect1>Pre-Defined Variables
+
+ <p>In order to allow users to share one setup over a number of
+ different machines without having to change its contents, there's a
+ number of pre-defined variables. These are prefixed with
+ <tt/muttng_/ and are read-only, i.e. they cannot be set, unset or
+ reset. The reference chapter lists all available variables.
+
+ <p><em> Please consult the local copy of your manual for their
+ values as they may differ from different manual sources.</em> Where
+ the manual is installed in can be queried (already using such a
+ variable) by running:
+
+<tscreen><verb>
+muttng -Q muttng_docdir
+</verb></tscreen>
+
+ <p>To extend the example for viewing the manual via self-defined
+ variables, it can be made more readable and more portable by
+ changing the real path in:
+
+<tscreen><verb>
+set user_manualcmd = '!less -r /path/to_manual'
+</verb></tscreen>
+
+ <p>to:
+
+<tscreen><verb>
+set user_manualcmd = "!less -r $muttng_docdir/manual.txt"
+</verb></tscreen>
+
+ <p>which works everywhere if a manual is installed.
+
+ <p>Please note that by the type of quoting, muttng determines when
+ to expand these values: when it finds double quotes, the value will
+ be expanded during reading the setup files but when it finds single
+ quotes, it'll expand it at runtime as needed.
+
+ <p>For example, the statement
+
+<tscreen><verb>
+folder-hook . "set user_current_folder = $muttng_folder_name"
+</verb></tscreen>
+
+ <p>will be already be translated to the following when reading the
+ startup files:
+
+<tscreen><verb>
+folder-hook . "set user_current_folder = some_folder"
+</verb></tscreen>
+
+ <p>with <tt/some_folder/ being the name of the first folder muttng
+ opens. On the contrary,
+
+<tscreen><verb>
+folder-hook . 'set user_current_folder = $muttng_folder_name'
+</verb></tscreen>
+
+ <p>will be executed at runtime because of the single quotes so that
+ <tt/user_current_folder/ will always have the value of the currently
+ opened folder.
+
+ <p>A more practical example is:
+
+<tscreen><verb>
+folder-hook . 'source ~/.mutt/score-$muttng_folder_name'
+</verb></tscreen>
+
+ <p>which can be used to source files containing score commands
+ depending on the folder the user enters.
+
+ <sect1>Type Conversions
+
+ <p>A note about variable's types during conversion: internally
+ values are stored in internal types but for any dump/query or set
+ operation they're converted to and from string. That means that
+ there's no need to worry about types when referencing any variable.
+ As an example, the following can be used without harm (besides
+ makeing muttng very likely behave strange):
+
+<tscreen><verb>
+set read_inc = 100
+set folder = $read_inc
+set read_inc = $folder
+set user_magic_number = 42
+set folder = $user_magic_number
+</verb></tscreen>
+
+<!--}}}-->
+
+<sect>Defining/Using aliases<label id="alias"> <!--{{{-->