Behavior Expression Language

Enter a topic name to show or a new topic name to create; then press Enter

.

Obsolete

This topic is obsolete. It contains my original brainstorming notes about what grew up to become WikiTalk. -- DavidOrnstein

Summary

BehaviorExpressions are a mini-language for Wiki content. They are particularly useful for producing dynamic content and content linked to the state of the wiki engine (or context).

Status

this is very rough and has no implementation yet -- DavidOrnstein

The Behavior Expression Language (BEL)

bvc

Language Definition

A BehaviorExpression (expr in the language grammar below) is a series of cascading references to properties or functions on objects. Here are some simple examples:

        CurrentTopic
        Now
        Federation
        RecentlyChangedTopics("bobdole")

Each of these symbolReferences (i.e., a reference to either a property or a function; see the grammar below) is evaluated relative to an object. The left-most symbolReference in an expression is evaluated against the home object. This special object defines the global properties and functions of the BEL language. As a result, the above examples are equivalent to:

        home.CurrentTopic
        home.Now
        home.Federation
        home.RecentlyChangedTopics("bobdole")

symbolReferences further to the right are evaluated as properties (or functions) of the object to the left. So, given the expression home.CurrentTopic, CurrentTopic is a property of the home object. If you add to this, for example with home.CurrentTopic.Namespace, you get the Namespace property of the current topic.

The evaluator works by first building a tree of objects by parsing out the expression. It then reduces the tree, working from the leaves back to the root by evaluating them and turning them into strings (see below for sample parse trees). So, if an expr object isn't a string, it will eventually be converted down to one. This string is the eventual output for the behavior expression and that result is inserted into the Wiki page.

To use a BehaviorExpression in a wiki page, surround the expression with the @@ delimiter. For example:

        The date is @@Now.Date@@

If you need to use the sequence @@ inside a behavior expression, it must be escaped as \@@.

Built-in Objects

The BEL language is based on a set of strongly-typed objects (called BELObjects) that let you access information about the Wiki. Each object is an instance of a class. Each object has a specific set of properties and functions as a result of being an instance of a particular class. Also, classes can inherit from other classes; all classes eventually inherit from a class called Object (which is the only class that doesn't inherit from something else).

While there may be a 1:1 relationship between some of these BEL classes and .NET classes in the implementation of the language, that's a coincidence of implementation. The BEL object system is much simpler than the .NET object system; don't get confused and think you have the full .NET object system available via BEL.

Below is information about all of the classes that are part of BEL:

Object

Property or Function	Returns	Notes
Type	string	The name of the class of object
StringValue	object	The object as a string (with all children fully evaluated)

Home : Object

Property or Function	Returns	Notes
Today	DateTime
CurrentTopic	Topic
StringValue	"Home"

Topic : Object

Property or Function	Returns	Notes
Name	string	Name of the topic (without namespace)
Namespace	Namespace	The namespace containing the topic
StringValue	string	The name of the topic

Namespace : Object

Property or Function	Returns	Notes
Name	string	Name of the namespace
Description	string	Description of the namespace (blank string if none)
Topics	Collection of Topic
TopicNamed(string TopicName)	Topic or null
StringValue	string	The name of the namespace

Federation : Object

Property or Function	Returns	Notes
Namespaces	Collection of Namespace
NamespaceNamed(string NamespaceName)	Namespace or null
StringValue	"Federation"

DateTime : Object

Property or Function	Returns	Notes
Date	string
Time	string
StringValue	formatted date time string

Collection : Object

Property or Function	Returns	Notes
Count	integer
Item(integer index)
StringValue	string with all values listed [a, b, c]
ForEach(string iteratorPropertyName, Object arg)

UndefinedObject : Object (a.k.a. null)

Property or Function	Returns	Notes
StringValue	"null"

String : Object

Property or Function	Returns	Notes
StringValue	string	the value of the string itself

Integer: Object

Property or Function	Returns	Notes
StringValue	string	the value of the number

Collections

BEL supports simple collections (see the Collection BELObject object). These are ordered collections and they can hold other BELObjects.

Collection Literals

You can specify a collection using brackets in a BehaviorExpression:

        ["hello", "goodbye"]

This creates a collection with two BELObjects in it, both of which are Strings (one for "hello" and one for "goodbye").

Iterator Functions

Collections support special functions (called iterator functions) that allow you to iterate over the objects in the collection. For example,

        Federation.Namespaces.ForEach("each", each.Name)

This uses the special ForEach iterator. This iterator function takes two arguments. First is the name of a temporary property to create that will hold, in turn, each of the objects in the collection. Second, is an expression that is evaluated in a context in which that temporary property is defined.

The above example will produce a list of all of the namespaces. To produce a table of all namespaces and their descriptions, use this:

        Federation.Namespaces.ForEach("each", Wiki("||@@each.Name@@||@@each.Description@@||"))

The special Wiki() function processes its argument as Wiki text.

Language Grammar

The language is defined roughly as follows:

 expr := 
        term
        term '.' expr
 term :=
        literal |
        builtin |
        symbolReference
 symbolReference :=
        propertyReference |
        functionReference
 propertyReference := propertyName
 functionReference := functionName '(' args ')'
 args :=  | arglist
 arglist :=
        arg |
        arg ',' args
 arg := expr
 builtin := 'null' | 'home'
 propertyName := identifier
 functionName := identifier
 identifier := 'A-Za-z' 'A-Za-z0-9'*
 literal := string | integer | collectionLiteral
 collectionLiteral := '[' exprs ']'
 exprs :=  | exprlist
 exprlist := 
        expr
        expr ',' expr
 string := " chars... "
 integer := '-'? [0-9]+

Implementation Notes

BELObjects

Each BEL-visible object is implemented in a .NET classes that supports IBELObject. Example include:

• BELHome - represents the home object
• BELNull - represents the null object
• BELString - represents a string literal
• etc.

The BEL parser builds a tree composed of these and some additional kinds of IBELObjects:

• BELPropertyReference - Holds a property name
• BELFunctionReference - Holds a function name and a list of args (IBELNodes objects)

Sample Trees

home.CurrentTopic

        BELPropertyReference (name: CurrentTopic)
        |
        |--------BELHome

CurrentTopic

        BELPropertyReference (name: CurrentTopic)
        |
        |--------BELHome

home.Federation.Namespaces

        BELPropertyReference (name: Namespaces)
        |
        |--------BELPropertyReference (name: Federation)
                |
                |--BELHome

null

        BELUndefinedObject

home

        BELHome

"Hello World"

        BELString ("Hello World")        

Execution

Execution proceeds very simply. The root object built by the parser is asked for its StringValue.

Open Issues

• When do expressions return wiki text and when HTML? - [ I've been looking at abstracting out the WikiOutput class completly from the Formatter. A significant problem would be behaviours that spit out HTML as they are output specific. I came to the conclusion that Behaviours should output wiki text as a minimum and then have optionally XML and has BehaviourWikiOutputs for each format that may be required. Alternativly the behaviour should have a string Execute(string Format, params object[] args) method where the format could be "Wiki", "HTML", "XML". On second thoughts I think that thoese 3 about cover it so maybe an enum and then the formatter can see if the what the current WikiOutput object can deal with, much like the windows clipboard. -- AdamStraughan ]
• What is the string in an iterator?