Module Syntax

Summary of Features

A Moonshine module is how you customize moonshine for a particular development environment. A module file provides you with the following:

allows you to specify which files and folders will be hidden from view

allows you to define file types based on a set of file specs

includes a built in <directory> file type for your convenience.

includes a built in <executable> file type for your convenience.

allows you to define a custom icon to display for your file types

allows you to define action blocks for your file types. these will become context sensitive menus

allows you to nest your action blocks to any level of depth

includes several different types of actions making the definition of action blocks easy and flexible

provides a set of built in commands for use in action blocks

allows the output of commands you define in action blocks to be captured in a graphical window

allows you to define the language syntax for files types you have defined

allows you to define customized help for your environment using a <help>action block

allows you to define drop-down menus that will be added to the moonshine menu bar

allows you to add custom options to the project and preferences menus

provides variables containing run-time project-related information

General Information

A module file must end in a .module extension .

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

A module is defined using three types of objects: tag, list, and block.

Any unrecognized text contained within a module file will be ignored.

Object Types

Object Type Name	Object Type Description
tag	A tag is used to identify the placement and content of a list, action, or block.
action	A string representing a system-level command
list	A list is a comma separated or space delimited series of strings ended by a new line
block	A block is a series one or more lists ended by a double-newline

Tags

Tags must start in column zero and end with a colon.

A tag must be followed by a list or an action on the same line or by a block on the next line.

Tags are not case sensitive

Actions

Placement of actions within the module file is not important.

Recognized Actions

Tag	Description or Notes
drag and drop:	Action to run on a file just after it is dropped
open project:	Action to run just after a project opens
close project:	Action to run just before a project closes.
save project:	Action to run just after a project is saved.

Lists

Placement of lists within the module file is not important.

Recognized Lists

Tag	List Format	Description or Notes
hide directories	space delimited list of file specs	matching directories are hidden from view in the source tree browser
hide files	space delimited list of file specs	matching files will be hidden from view in the source tree browser
drop down menus	comma separate list of menu names	use the tag "drop down name" for the action blocks. Built-in commands are not supported in drop-down menus, with the exception of $cd.
read column pixmaps	comma separated list of pixmaps	On then off pixmap for the read list view column
write column pixmaps	comma separated list of pixmaps	On, off, then locked pixmap for the write list view column
exec column pixmaps	comma separated list of pixmaps	On then off pixmap for the read list view column

Blocks

Placement of blocks within the module file is not important.

Recognized Blocks

Block Type	Tag	Block Format
File Types Block	file type definitions	newline separated list of file type definitions
Action Block	comma separated list of file type names	newline separated list of actions

The File Types Block

When trying to determine the file type of a given file Moonshine will the file types that have been define in the order that they were encountered in the file. In other words, moonshine stops searching as soon as it finds a file type that includes a matching file spec.

File Types Block format

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

Notes

file type name	an action block, if one is desired, will use this as its tag. This can be any string without commas
icon	either <none> or a valid pixmap (.xpm) file name relative to the module directory
file spec	any valid unix 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

An action block may be provided for any or all of the file type that have been identified in the File Types Block, including <directory> and <executable>.

Action Block format

separator
name	,	icon	,	commands
name	,	icon	,	<tag>
name	,	icon

Predefined Action Blocks

Action Block Name	Description
<directory>	Actions defined for the <directory> file type.
<common>	Actions to be used with all file types except <directory>
<executable>	Actions defined for the <executable> file type.
<help>	Actions to add to the bottom of the Help menu.
<project>	Actions to add to the project menu between the close and exit options.
<preferences>	Actions to add to the bottom of the preferences menu.

Notes

name	The item name visible in the source tree browser.
*	Place in front of the action name to indicate the default action. The last one wins..
icon	Either <none> or a valid pixmap (.xpm) file name relative to the module directory.
commands	One or more system or built-in commands separated by semicolons. Executables must be in the path or specified relative to modules/bin. Do not use pipes or redirects with built-ins. Each of the commands is run independently. Because of this, changing directories with system commands does not work. Use the $cd built-in to change directories.
separator	the source tree browser menu will have a separator at this location
<tag>	Indicates the name of the action block that will define a sub-menu. Leave this out altogether to use name as the tag

The following table describes the symbols that may be used within commands. A symbol must immediately precede the first character of a word (e.g. @make). Only one symbol may be used with a word.

Symbols

Symbol	Description	Example
@	Indicates a command for which the output should be captured.	@make
$	Indicates a moonshine built-in command.	$rename
%	Indicates a variable.	%s
()	Indicates a file name or url to open in the user-defined help browser.	(http://www.rednecksoft.com)

The following table describes place-holders may be used in captured and system commands.

Variables

%s	the name of the file highlighted in the source tree browser
%newfolder	the new folder name
%newfile	the new file name
%importfile	the imported file name
%rename	the new file name
%openwith	the selected command
%print	the user-specified print command
%path	The full path to the file highlighted in the source tree browser
%oldpath	The full path to the directory that formerly contained the file. Valid only with $import and with the drag and drop action.
%root	Full path project root folder
%project	The name of the project

Valid Built-in Commands

$newfolder	Create a new folder within the selected folder. Does a $cd into the folder.
$newfile	create a new file within the selected folder. Does a $cd into the folder
$importfile	Import a file into the selected folder. Does a $cd into the folder
$rename	Opens the rename box and renames the file or folder to the selected name, unless canceled.
$delete	Deletes the selected file or folder
$brew	Launches the internal brew editor. There is no corresponding variable.
$print	Open the print dialog. Sets the %print variable but does NOT run the user-specified command.
$openwith	Opens the open with dialog. Sets the %print variable but does NOT run the user-specified command.
$cd	Change the current directory. Requires a valid directory as an argument, such as %s.

NOTES

With the exceptions noted in the built-in commands above, actions do their work in the parent folder of the item. To define an action for a folder that operates within the folder rather its parent, simply do a "$cd %s" as the first command of the action.

the $openwith and $print built-in commands fill in their corresponding variables. They do NOT execute the user-specified command . It is up to module writer to do this. For example, '$print; %print' . This may seem strange, but it allows the string to be examined or manipulated by the module before the command is executed.

Brew Editor Syntax Highlighting

A syntax highlighting block is introduced using the following tag:

(comma separated list of file type names) syntax:

This list introducing tag is used to specify syntax highlighting and default colors in the brew (built-in) editor. This section contains a list of lines that each specify a syntax to match on or a default foreground or background color.

There are four types of syntax.

1. keyword - Match on a specified keyword.

   Examples:
   keyword hello red normal
   keyword void black bold

2. regex - Match on a regular expression

   Examples:
   regex #.* blue normal
   regex [0-9]+\.?[0-9]* orange bold

Note: Regex patterns are limited to matching on a single line

3. block - Match on text between a start keyword and an end keyword. This type of match includes the keywords.

Examples:
block /* */ yellow italics

Note: Block syntax that have the same start and end keyword (i.e. " ") will only match on a single line.

4. line - Match on text between a keyword and the end of the line. This type of match includes the keyword.

   Examples:
   line // yellow italics
   line #include blue normal

Note: The line tag is considered obsolete as of version 0.9.6 of Moonshine. Use the regex tag to match to the end of a line instead.
Ex. 'line #define blue normal' would become 'regex #define.* blue normal'

Keyword and line syntax have the following format:
keyword | regex | line [keyword] [color] normal | bold | italics {id=[name]} {parent=[name]}

Block syntax have the following format:
block [start] [end] [color] normal | bold | italics {id=[name]} {parent=[name]}

The optional parameters at the end of this format, 'id=' and 'parent=', are used if you want to define a syntax (the child) to only match if it is within another syntax (the parent). To do this use the 'id=' parameter to assign a name to the parent and then reference that name in the child with the 'parent=' parameter. Note: Child syntaxes MUST come after there parent in the syntax list or they will be ignored.

Ex. block /* */ yellow italics id=c_comment
keyword Description orange italics parent=c_comment

In addition to syntax highlighting this block also allows you to specify the foreground and background colors for
the editor. This is done as follows:

fgcolor {color}
bgcolor {color}

As with syntax highlighting, if you specify more than one foreground or background color the last one wins. If no foreground or background colors are specified, then brew use fgcolor = black and bgcolor = white as its defaults.

All spacing can be any form of white space (spaces, tabs). The section is ended with a double-newline (this double new line must be present even if this block is at the end of the file).

Captured Command Syntax Highlighting

Captured command dialog syntax highlighting allow you to specify syntax highlighting rules for the output of captured commands. This section of the module file is identical to brew editor syntax highlighting blocks except that it is introduced by the tag -

captured command syntax:

At this time only one captured command syntax highlighting block is allow per module file. If more than one is present then only the first one is used.

A Complete Example of a Module

---------------------------------------------------------------------------------
#Moonshine Project Overlay

File Type Definitions:
<directory>, pix/verticle-folder-closed.xpm
text file, pix/mini-text.xpm, *.text *.txt
unknown file, pix/mini-file.xpm, *.* *

Drop Down Menus: Applications

<directory>:
separator
new, none, menu
separator
import, pix/mini-import.xpm, builtin, importfile

Drop Down Applications:
Star Office, <none>, system, soffice

<help>:
contents, pix/about.xpm, url, file:help/index.html

new:
folder, pix/mini-new-folder.xpm, builtin, newfolder
file, pix/mini-new-file.xpm, builtin, newfile

<common>:
rename, pix/mini-rename.xpm, builtin, rename
delete, pix/mini-delete.xpm, builtin, delete

text file:
separator
*brew, pix/mini-edit.xpm, builtin, brew
nedit, pix/nedit.xpm, system, nedit %s

unknown file:
separator
*brew, pix/mini-edit.xpm, builtin, brew

text file syntax:
fgcolor black
bgcolor white
keyword help red normal
line // yellow italics
block <START> <END> #00FF00 bold

unknown file syntax:
fgcolor black
bgcolor white

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