Bishop language reference

The Bishop language is a XML language, for good and for worse. Should there prove to be any public interest we will add support for other languages.

There is no loop construct in the language, and though recursion is possible it is strongly discouraged. It is not the intent that very complex code is to be written in Bishop.

It has been a general design goal to make the syntax and semantics similar to that of Java.

Bishop Elements & Attributes

The Bishop Element

<!ELEMENT bishop 
       (object 
        | invoke 
	| try 
	| if 
	| delete 
	| view 
	| import) + >

The bishop element is the root element. All Bishop scripts contain this element.

Example

<bishop> ... </bishop>

The Object Element

	
<!ELEMENT object ( in * )>
<!ATTLIST object
  name          CDATA           #REQUIRED
  type          CDATA           #REQUIRED
  static        (true | false)  "false"
  export        (true | false)  "false"
>

The object element is the construct for creating a new object of a specific Class. The construct is also used to change the attributes of existing objects.

Attributes

name=CDATA This attribute is assigned the name of the object to be created. If there exist an object with the same name in the current or a parent Scope no new object is created.

type=CDATA This attribute contains the full name of the class to be created.

static=(true | false) A flag indicating if the object is to remain active for the entire session (true), or for this request only (false).

export=(true | false) A flag indicating if the object is to be exported to the template engine (true) where it can be used to render views, or if the object is used for processing only (false)

Example

<bishop> <object name="foo" type="java.lang.String"/> </bishop>

The Delete Element

<!ELEMENT delete EMPTY>
<!ATTLIST delete
  name          CDATA           #REQUIRED
>

The Delete element is used to obliterate every trace of a given object.

Attributes

name=CDATA This attribute is assigned the name of the object to be obliterated.

Example

<bishop> <delete name="foo"/> </bishop>

The Invoke Element

<!ELEMENT invoke (in*, out?)>
<!ATTLIST invoke
  object        CDATA           #REQUIRED
  method        CDATA           #REQUIRED
>

The invoke element is used to invoke methods on objects. The objects are part of the model. Parameters can be passed to the method, and return values can be received. The Bishop runtime environment is responsible for locating the proper methods in the proper classes.

Attributes

object=CDATA Name of the object to be invoked.

method=CDATA Name of the method to be invoked.

Example

The following short example invokes the login method on the auth object (of the Authentication class). And passes username and password (which are two variables sent with the http post request sent by the http client). The result of the invocation is stored in the logged_in variable.

<bishop> <invoke object="auth" method="login"> <in name="username"> <in name="password"> <out name="logged_in"> </invoke> </bishop>

The In Element

<!ELEMENT in EMPTY>
<!ATTLIST in
  name          CDATA           #REQUIRED
  type          CDATA           #IMPLIED
  default-value CDATA           #IMPLIED
>

The in element is used to pass objects as arguments to the invoke element.

Attributes

name=CDATA Name of the object (for example name of a form variable sent with http post from the client)

type=CDATA Cast the object named name to this class. Assumes that the class cased to has a constructor accepting a java.lang.String object. This is useful for converting form variables to integers or booleans for example.

default-value=CDATA If there is no object named name then use this string to form a java.lang.String object (the object is subject to casting by the type attrib.) This is very useful when you cant assert that the client sends values of form variables that are empty.

Example

<bishop> <in name="age" type="java.lang.Integer" default-value="-1"> </bishop>

The Out Element

<!ELEMENT out EMPTY>
<!ATTLIST out
  name          CDATA           #REQUIRED
  export        (true | false)  "true"
  static        (true | false)  "false"
>

The out element is used to store the result of method invocations.

Attributes

name=CDATA Name of the object to be associated with the result.

export=(true | false) Should the resulting object be exported to the template engine (WebMacro).

static=(true | false) Should the object be kept for the rest of the session.

Example

<bishop> <out name="foo" export="true" static="false"> </bishop>

The Try Element

<!ELEMENT try ( ( 
                   invoke | 
		   try | 
		   if | 
		   view | 
		   import | 
		   object | 
		   delete)*, 
		 catch+)>

The try element is used to encapsulate exception controlled code.

Example

In the following example is the invoke element contained in a try block. Should the implementation of method bar in object foo, throw any exception of java.lang.Exception, then will the content of the catch block be executed. Multiple catch blocks can be declared after each other in much the same way that Java handles exceptions.

<bishop> <try> <invoke name="foo" method="bar"/> <catch type="java.lang.Exception" name="e"> ... exception handler goes here .. </catch> </try> </bishop>

The Catch Element

<!ELEMENT catch (invoke | view | import | object | if | try | delete)+>
<!ATTLIST catch
  type          CDATA           #REQUIRED
  name          CDATA           #REQUIRED
>

The object element are contained within try blocks to define exception handlers..

Attributes

type=CDATA The type of exception to be caught.

name=CDATA The name of the exception object.

The If Element

<!ELEMENT if ((object | invoke | try | if | view | import)+, else?)>
<!ATTLIST if
  name          CDATA           #REQUIRED
  value         CDATA           #IMPLIED
>

The if element is the core of conditional execution, and should be handled with care. Too many if statements may indicate that the model is too thin. The actual comparison is performed using the equals method. The object name is looked up, if not existing then the condition is false. The value of value is converted into the same type of object as name (using the java.lang.String constructor). If the condition is true then the content of the if block is executed (except else's), should it be false then any containing else block is executed.

Attributes

name=CDATA The name of the object to be used to comparison.

value=CDATA String to be used to construct an object of the same type as name

Example

The following example demonstrates the if construct.

<bishop>

	<if name="foo" value="true">

	  ... block to execute if true
	<else>
	  ... block to execute if false
	</else>
	</if>
	 </bishop>

The Else Element

<!ELEMENT else (invoke | try | if | view | import | delete | object)+>

The else element is a member of the if element, the content of an else block is to be executed should the if statement evaluate to false.

The Import Element

<!ELEMENT import EMPTY>
<!ATTLIST import
  name          CDATA           #REQUIRED
>

The import element is used to recursively invoke sub bishops.

Attributes

name=CDATA Name of the file that contain the Bishop script. This file must be available in the CLASSPATH.

Example

<bishop> <import name="login"/> </bishop>

The View Element

<!ELEMENT view EMPTY>
<!ATTLIST view
  name         CDATA            #IMPLIED
  template     CDATA		#REQUIRED
>

The view element.

Attributes

object=CDATA

method=CDATA

Example

<bishop> ... </bishop>

The Trace Element

<!ELEMENT trace (in *)>
<!ATTLIST trace
  msg         CDATA            #REQUIRED
  type	      (debug | info | warn | error)  "debug"
>

The trace element is used for trace output, such as debug and error information. The loging engine log4j is used (as it is throughout the rest of the Bishop).

Attributes

msg=CDATA Text to be printed. If this evaluates to the name of an existing object then that object's toString is printed. Otherwise is the text passed along to MessageFormat for processing. The objects inserted with in are passed as parameters to the format call.

type=(debug | info | warn | error) What type of trace info.

Example

<bishop>

	<trace msg="Current loop value is: {0}">

	<in name="foo">

	</trace>

	<trace msg="foo"/>

	</bishop>