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).