Xilize & BeanShell

source for Home/ByExample/BeanShell :: index.xil

Xilize & BeanShell

BeanShell code may go in any number of @*.bsh@ files and any functions defined
in them can be used in signature directives or macros in Xilize source files.

The new @signature@ directive allows users to create custom signatures which
have the same status during translation as the ones built into Xilize.

The new &{exmacro: ... } markup provides a couple of ways to use BeanShell in
inline markup, that is, within a block of text.

Xilize automatically finds and evaluates *.bsh files as it examines directories
for *.xil source files.  All *.bsh files in a directory are "sourced" -- to use
the BeanShell term for interpreting a file.  BeanShell functions and custom
signatures defined in a directory are available to Xilize source files in that
directory or in of its subdirectories.  (For BeanShell functions, the reality is
more flexible than this, but follow that rule as a "best practice.")

BeanShell is quite efficient.  Do not be shy about writing code.  It is also
very forgiving.  All the rules about type checking and catching exceptions in
Java do not apply.

>xil>{{{h2. custom signatures 
h2. custom signatures

Before a custom signature's code is called the following variables are defined
and are available to functions with the signature's scope.  (Similar to the way
jEdit provides "view" and "buffer" to its macros.)

| sig | the Signature object
| task | the current Task object
| block | the current Block object
| text | the String returned by @block.linesAsString()@. This is the text of the
signed block with Xilize comments removed, any tab chars replaced by space
chars, and trailing whitespace removed from each line.

Each of these objects provides a number of useful methods any of which can be
used in signature scope.  See the javadoc for more information.

While signatures can not take parameters, you can achieve that effect in other
ways. See the @exampleFile()@ function and its corresponding signature
@example@.
>xil>}}}

>xil>{{{h2. macros 
h2. macros

While signatures are applied to blocks of text, macros are used within blocks
and are marked with  &{exmacro:...} to distinguish them from @${ key }@
key/value-substitution markup (Note the @&@ instead of [@$@].)

There are two forms of macro use: unrestricted and as a text operator.

>xil>{{{h3. unrestricted 
h3. unrestricted

| syntax | &{exmacro: any BeanShell code goes here }
| example | &{exmacro:new Date()} produces &{new Date()}
| global variables | @task@, the current Task object
| constraint | the code may not contain '}' but may consist of multiple
statments terminated with ';'.
| best practice | define a function in an external bsh file and put just the
function call within the markup:   &{exmacro:myFunc(x,y,)}

Here is a rather contrived example:

bc. It was &{exmacro: c =
Calendar.getInstance(TimeZone.getTimeZone("US/Eastern")); c.get(Calendar.HOUR)
}
o'clock  on the east coast and &{exmacro: c = Calendar.getInstance();
c.get(Calendar.HOUR) }
o'clock here  on the west coast when this when this page was generated.

produces:

It was &{ c = Calendar.getInstance(TimeZone.getTimeZone("US/Eastern"));
c.get(Calendar.HOUR) } o'clock on the east coast and &{ c =
Calendar.getInstance(); c.get(Calendar.HOUR) } o'clock here on the west coast
when this when this page was generated.
>xil>}}}


>xil>{{{h3. text operator 
h3. text operator

| syntax | &{exmacro: functionName : any arbitrary string }
| example | &{exmacro:cap:macros rock!} produces &{cap:macros rock!}.  The
function @cap()@ is defined in an external *.bsh file.
| global variables | @task@, the current Task object, and<br /> @text@, the
string following the ':' and terminated by the closing '}' and can be used in
your function.
| constraint | The "functionName" function must be defined to take no arguments
and of course return a string or an object whose @toString()@ method makes
sense

This is a merely a convenient shorthand for &{exmacro: functionName("any
arbitrary string") }.
>xil>}}}

>xil>}}}

>xil>{{{h2. notes 
h2. notes

Several packages are imported into the BeanShell environment prior to any
BeanShell code being called.

Xilize imports these packages:

    * com.centeredwork.xilize
    * java.util.regex
    
BeanShell always imports these packages:

    * javax.swing.event
    * javax.swing
    * java.awt.event
    * java.awt
    * java.net
    * java.util
    * java.io
    * java.lang

You may import anything else as long as it is available on your classpath.  

*jEdit note:*  the jEdit jar has BeanShell built in, so if that is on your class
path, or you are running from the jEdit Console, you are done.  Otherwise, the
BeanShell jar used in this source distribution is /dist/lib/bsh-core-2.0b4.jar
(the a subset of the BeanShell code used in jEdit).  Currently I'm thinking
Xilize will be released as two different jars:  one for standalone use with the
BeanShell jar built in and one without it for jEdit.

*signature directory:*  I plan on to continue to support all of the above and,
additionally, have Xilize treat any subdirectory named "signatures" in a special
manner.  Files in a @signatures@ directory will be understood to contain
signatures -- similar to the way jEdit uses the @macros@ directory and the *.bsh
file it contains to name and implement jEdit macros.  Each *.bsh file in a
signatures subdirectory will be understood to contain a single signature
definition, with the name of the file (minus the @.bsh@ extention) used as the
name of the signature. Such signatures would not require an explicit @signature@
directive to in the Xilize source.

>xil>}}}

>xil> :indentSize=4:noTabs=true:mode=xilize:collapseFolds=1:

Long lines are wrapped in this listing.
Use your web browser's "View Page Source" feature to examine the HTML