Moonshine Module File Format

Moonshine version 1.1.2

Summary of Features

hide any files and folders you want from view

define your own file types based on lists of file specs

builtin <directory> and <executable> file types are provided for your convenience.

define custom icons to correspond to your file types

define custom context sensitive 'right-click' menus for file types

nest menus to any level of depth

define actions (combinations of linux system level commands and moonshine builtins) for menu items and other events

capture the output of your actions to a captured commands window, which provides a history of all captured command

sapecify what syntax hightlighting rules to use for file types

define customized help for your environment

define customized drop-down menus to add to the moonshine menu bar

add customized menu items to any of moonshine's standard drop-down menus

variables containing run-time project-related information are provided for use in defining actions

Includes a builtin action block tag, <common&g, so you can define menu items common to all (non directory) files.

Summary of Changes

1.1.3

added support for $list, a builtin that compiles a list of visible items for the selcted folder and fills in the %list variable. Optionals are as follows:

(none)     lists both files and folders
files           lists files only
folders     lists folders only
recurse    recurse through subdirectories

for example '$list recurse files'

1.1.2

Backed out document changes relating to the separation of actions and menus. These changes have not been implemented; they (or something similar) may be made in a later revision of moonshine.

Commands now block until complete. In other words, in the action 'a;b;c' 'c' will not be run until 'b' exits). Put an '&' at the end of a command to tell moonshine -not- to block. In 'a;b&;c' 'c' will get run immediately after 'b' is launched without waiting for 'b' to finish. This is true for the $brew builtin also, but all other builtins ignore the '&' symbol. If a command is captured the '&' is ignored.

Actions defined for the <directory> file type operate IN the directory now instead of acting ON the directory. This is the oposite of the way things worked in versions 1.1.1 and earlier. To define an action that acts on a directory simply do a '$cd ..' as the first command in the action.

Added support for the %type & %newtype options. %type is the module-define file type corresponding to the file defined by %file. Likewise, %newtype corresponds to %newfile. Any command that sets %file also sets %type and any command that sets %newfile also sets %newtype.

Eliminated the $help builtin in favor of the %help variable. Their was really no difference between them. $help will be supported for backward compatibility for right now and is treated as a variable.

1.1.1

Documented separation of menus and actions into two distinct entities. Changes have not actually been made to moonshine yet.

Document support for %type and %newtype. Didn't actually get around to putting support in the code yet though- it'll be there next release.

Overhauled the set of known variables. Old variables are supported for backword compatability:
  common - <common>
  %s - %file
  separator - <separator>
  %newfolder - %newfile
  %importfile - %newfile
  %rename - %newfile
  %openwith - %command
  %print - %command

Changed module help url syntax to a $help built-in action. Also defined a %help variable to provide the module with the value.

1.1.0

Added a 'syntax' block to the list of 'Recognized Blocks'.

Removed discussion of syntax highlighting from this document

Updated example

General Module File Information

A Moonshine module file must end with a .module extension

The first line in a module file must be #Moonshine Module File

Unrecognized text within a module file gets ignored.

Object Types

A Moonshine module is defined using tagged data. In other words, segments of data within a module file are introduced using identifier tags. Moonshine uses these tags not only to locate the data within the module file but also to identify the format and content type of the data following the tag. Moonshine differentiates between the following types of data:

string	raw, unformatted text
list	a delimited (usually with commas or spaces) series of strings contained on one line
block	a sequence of lists on successive lines
named block	a string and block pair, the string giving the block a name (block names must be unique).

All tags have to start in column zero and must end with a colon. List and string data must follow a tag on the same line. Block data begins on the line following the tag. Named blocks have a string on the line with a tag (between the tag and the colon- 'drop down &Actions :') and a block beginning on the line below it. Blocks are terminated by a blank line. Because moonshine uses tags to locate the data it needs, the placement of tagged data with a module file is not important, and any text that is not part of a known tag or the data it introduces gets ignored.

Recognized Tags

The following table presents a list of the tags that moonshine recognizes, the type of data associated with the tag, and a short description of each. Some of these tags will be described in greater detail later in this document.

Tag	Data Type	Description
file type definitions	block	each line in the block provides a file type definition
file type name	named block	each line defines a system level command or refererences another action. one of thesxe should be defined for each file type defined in the file type definitions block.
drag and drop	string	an action to run on a file just after it is dropped in its new location
open project	string	an action to run just after a project opens
close project	string	an action to run just before a project closes
save project	string	an action to run just after a project is saved
hide directories	list	a space delimited list of file specs. Matching directories will be hidden from the user's view in the source tree browser
hide files	list	a space delimited list of file specs. Matching files will be hidden from the user's view in the source tree browser
read column pixmaps	list	yes pixmap,no pixmap Pixmaps for the read column in the source tree browser
write column pixmaps	list	yes pixmap,no pixmap Pixmaps for the write column in the source tree browser
exec column pixmaps	list	yes pixmap,no pixmap Pixmaps for the exec column in the source tree browser
drop down	named block	an action block that will become a drop-down on the source browser's menu bar between the preferences down-drop and the window drop-down
syntax	block	each line contains: file type name, syntax name A syntax name is the syntax file name without path or extension

File Type Definitions

Each line in the block following the file type definitions tag defines a file type. When determining the file type of a file Moonshine starts at the top of this list of definitions and tries to match the file. As soon as a matching entry is located, moonshine stops searching (in other words, the first one wins). The possible formats of a file type definition are shown on the table below.

<directory>	,	icon for folder closed	,	icon for folder opened
file type name	,	icon	,	space delimited list of file specs
<executable>	,	icon

These are described briefly on the table below

file type name	Will be display in the source browser type column. Use as the name of a menu block to define right-click menu for the file type.
icon	either <none> or a valid pixmap (.xpm) file name relative to the module directory
file spec	any valid linux file spec (i.e. .txt .text .doc Makefile Makefile.)
<directory>	A built in file type. All directories are of this type.
<executable>	A built in file type. It should be placed in the file types block after any other file types that may be executable.

Action Blocks

One of these should be provided for each file types (including the two builtin ones) in order to provide right-click menu in the source code browser for files of that type. For these, use the file type as the block name. A menu block must also be provided for any sub-menus defined for these or the drop-down action blocks. Lines must be formatted according to one of the formats given in the table below.

<separator>
name	,	icon
name	,	icon	,	action
name	,	icon	,	action block name

A short description of items in the above table requiring an explation is provided in the table below. Note the second entry in the table above does not provide an action or a action block name. This type of entry defines reference to a submenu with a name corresponding to the item name. This should be the rule rather than the exception. Define an explicit name only to avoid duplication.

name	The item name visible in the source tree browser.
icon	Either <none> or a valid pixmap (.xpm) file name relative to the module directory.
action	An action- this will be described in the next section
<separator>	the source tree browser menu will have a separator at this location
menu	Indicates the name of a menu block that will define a sub-menu.

Moonshine pre-defines four action block names. These are described on the table below.

<common>	items added to all right-click menus for all non-directory file types
<help>	items will be added to the bottom of the Help menu. Normally, actions using $help are placed here.
<project>	items will be added to the project menu between the close and exit options.
<preferences>	items will be added to the bottom of the preferences menu.

Actions

In Moonshine, actions are associated with either events (such as drag & drop) or with menu items in either drop down menus or right-lick menus. An action consists of a series of commands separated by a ; symbol. These commands may be either Moonshine builtin commands (preceded by a $ synbol) or unix system level commands (such as /usr/bin/g++ or /usr/bin/netscape). System level commands have their output 'capturted' by prefixing the command with a @ symbol (@make all). System level commands must be in your unix path, specified full path, or specified relative modules/bin.

Each command within an action will be run independently of the other commands (executed via a different invocation of '/bin/sh -c'). Becuse of this, changes in the working directory or environment varibles will not carry over from one command to another. A builtin commands $cd is provided to change the working directory. Store any variables you need to be kept across commands in temp files. Note that a command, as defined here, may be any number of linux system commands separated by pipes and so forth.Becuase these commands are run using '/bin/sh -c' they must adere to the rules of that shell (see the man page for sh for more information)

An actions is launched when a user selects a menu option in either a right- click menu or a drop-down menu and when certain other events take place (as defined in the list of recognized tags earlier in this document). These actions will either operate on the files selected in the browser or will ignore the selected files, depending on how the action is launched; actions launched from right-click menus or because of a drag and drop event took place will always operate on the selected files in the source browser. These actions will iterate over the files, with action being run through, in its entirety, on each file successively (unless the %glob variable is used, in which case the action will be run once only). If any of the commands in an action blocks (see the & symbol in the chart belowe) the entire action will block until the command completes. For example, consider the following actions

: $brew %file; ci -l %file
$brew %file &

In the first action, the call to $brew blocks until the brew editor exits This allows other commands to be run after editing is completed. Note that the for multiple files second and subsequent files are not be processed until the action is completed on the first file. In other words, the action sequence will be brew file one and block until brew closes, run the rest of the action on file one, brew file two and block until brew closes,....

The $openwith and $print builtins and run-once commands; in other words, they get executed once per action reguardless of whether the action is an iterating one or not. They will be invoked first regardless of where the builtin actually appears within an action, and will be then removed from the action and the %command variable filled in. Only then will the action actually be run.

The table below describes the symbols that have special meaning within an action

Symbol	Location	Description
;	between commands	An action may consist of multiple commands separated by semicolons. Each of these will be run indepardantly of one another. Each can be captured and may reference either a moonshine builtin command or a linux system level (shell) command.
@	first character of command, first character of word	Indicates that output should be captured. The entire action will pass through the captured commands window if any one of the commands have captured output (only the commands with the @ starting them will actually have their output captured. Builtin commands cannot be captured.
$	first character of command, first character of word	references a moonshine builtin. Builtins cannot be mixed with system (shell) commands within the same command, but may be mixed within an actions.
%	first character of a word	indicates that the word is a module variable (these will be described later).
&	last character of a command, separate word	indicates that moonshine should not wait until a command exists before continuing on to the next command in an action. This works with all system commands and the $brew builtin. Ignored if the output of the command is captured.

Moonshine also defines a number of variables for use in actions to provide module-writers information about what is going on in moonshine. A given set of variables is only valid within a particular action (not within actions it may reference or those actions that reference it). Many of these variables are only valid in particular circumstances, such as those that provide information on files highlighted in the source code browser.

It is important to understand that, as mentioned earlier, actions that operate on the files highlighted in the browser normally iterate over these files. In order to determine whether an action iterates, moonshine looks for variables that provide information on a group of files. If it finds any such variable, the action will be run once only; otherwise the command will be run iteratively on each highlighted file, from top to bottom (of the browser). Using any moonshine builtin that defines an iterating variable will causes an action to iterate regardless of the presence of these group style variables. Iterating variables are provided on the table below and a description is provided for each one. Builtins are discussed later on in this document.

Iterating Variables (available only if an action iterates over files selected in the browser)

%file	the name of a file highlighted in the source tree browser
%path	The full path to a file highlighted in the source tree browser
%type	The module-defined file type for a file highlighted in the source browser
%newfile	the file name of a newly created or renamed file as set by the $import, $rename, $newfile, and $newfolder built-in actions
%oldpath	the path to the previous location of a file that was just successfully moved by the user with drag and drop
%newtype	the new file type for a newly created or renamed file. Set by the $import, $rename, $newfile, and $newfolder built-in actions

Grouping Variables (use of any of these will cause an action not to iterate over files)

%glob

A glob of all the files highlighted in the source tree browser. Files will be specified relative to the project root folder (which will also be the working directory of the action).

Other non-iterating variables

%command	a user-specified command set by the $openwith or $print builtins
%root	The absolute path to the project root folder
%project	the name of the project
%help	The name of the user-defined help browser.

Builtin Commands

builtin	variables it sets	description
$newfolder	%newfile, %newtype	Create a new folder within the selected folder. Valid only with folders. Does a $cd into the folder before creating the new one.
$newfile	%newfile, %newtype	Create a new file within a selected folder. Valid only with folders. Does a $cd into the folder before creating the new file.
$importfile	%newfile, %newtype	Import a file from another location into the selected folder. Valid only with folders. Does a $cd into the folder before copying thew file in.
$rename	%newfile, %newtype	Opens the rename box in order to rename a file or folder
$delete	none	Deletes the selected file or folder
$brew	none	Launches the internal brew editor.
$print	%command	Opens the print dialog to retrieve a print command from the user and set the %command variable. All variables and builtins (except $print and $openwith) arte valid within this user-defined command. NOTE: this does not execute the command, it just sets the variable.
$openwith	%command	Opens the open with dialog to retrieve a user-defined command and set the %command variable. All variables and builtins (except $print and $openwith) arte valid within this user-defined command. NOTE: this does not execute the command, it just sets the variable.
$cd directory	none	Change the current directory. Requires a valid directory as an argument (src, %root, %file, ../).
$list [files] [folders] [recurse]	%list	Builds a list of all the files and/or folders in the selected folder, optionally recursing through subdirectories as it build the list

For file based actions the actions do their work in the parent of the selected file. Actions defined for folder do their work WITHIN the folder. To define an action that operates on a folder insteaqd of within it simply do a "$cd .." as the first command in the action.

The $openwith and $print builtins fill in the %command variable. They do NOT execute the user-specified command. It is up to module writer to do this. For example, define an action as '$print;%print'. This may seem strange, but these two builtins exist solely to launch their dialogs and set the %command variable, not to execute user-specified commands. This allows the user-specified command to be examined and/or manipulated by the action before the command itself is executed. if $print or $openwith does not find a reference to %file or %glob in either the user-defined command or the module-defined action continaing it, %file with be tacked on to the end of the user-defined command.

Syntax

This block maps file types to syntax definitions (defined in syntax files- see syntax.html). Each line maps a single file type to a signal syntax name. Two additional options are available corresponding to file types in this mapping and are described in the table below.

<default>	defines a default syntax to use for any file types that do not have an entry in this mapping and for any files that do not correspond to any of the defined file types
<capture>	defines what syntax to use for coloring the output of captured commands

A Simple Example of a Module

#Moonshine Module File

hide directories: CVS RCS
hide files: #*# *~ .*

file type definitions:
<directory>, mini-folder.xpm
File, mini-file.xpm, *.* *

syntax:
<default>, default
<captured>, captured-commands
Unknown, default

<directory> :
Rename, mini-rename.xpm, $rename
Delete, mini-delete.xpm, $delete
Import file, mini-import.xpm, $importfile
New, <none>, dir_new

dir_new :
Folder, verticle-folder.xpm, $newfolder
File, mini-new-file.xpm, $newfile

<common> :
Rename, mini-rename.xpm, $rename
Delete, mini-delete.xpm, $delete

File :
*brew, mini-edit.xpm, $brew
Open with..., mini-edit.xpm, $openwith
Print, printer.xpm, $print

More complex examples of modules can be found in the modules directory (usually /usr/share/moonshine/modules).