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 &{ ... } 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.

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.

macros

While signatures are applied to blocks of text, macros are used within blocks and are marked with &{...} 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.

unrestricted

syntax &{ any BeanShell code goes here }
example &{new Date()} produces Sat Jul 14 14:03:22 PDT 2007
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: &{myFunc(x,y,)}

Here is a rather contrived example:

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.

produces:

It was 5 o'clock on the east coast and 2 o'clock here on the west coast when this when this page was generated.

text operator

syntax &{ functionName : any arbitrary string }
example &{cap:macros rock!} produces Macros Rock!. The function cap() is defined in an external *.bsh file.
global variables task, the current Task object, and
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 &{ functionName("any arbitrary string") }.

notes

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

Xilize imports these packages:

BeanShell always imports these packages:

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.

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