@Immutable public interface Spec
A spec is a plain-text description of a Java object to be instantiated. This is a simple example of a spec:
com.rultor.base.Base64("AFEFEFSJKL789jojHKLW==")
Formally, a spec is defined as (simplified BNF):
spec := variable;
variable := composite
| name arguments | urn ':' name arguments
| array | dictionary | meta | arg
| text | bigtext
| integer | double | long | boolean;
arguments := '(' ( variable ( ',' variable )? )? ')';
name := [a-z0-9-]+;
urn := 'urn:[a-z]+:[0-9]+';
composite := type arguments;
type := [a-z0-9$-]+;
array := '[' ( variable ( ',' variable )? )? ']';
dictionary := '{' ( key ':' variable ( ',' key ':' variable )? )? '}';
key := text | alter;
meta := '$' '{' [a-z] '}';
arg := '$' '{' [0-9] ':' .* '}';
alter := '@' '(' text ')';
text := '"' ('\\"' | ~'"')* '"';
bigtext := '"""' .+ '"""';
integer := (+|-)? [0-9]+;
double := (+|-)? [0-9]+ '.' [0-9]+;
long := (+|-)? [0-9]+ 'L';
boolean := 'TRUE' | 'FALSE';
This description actually means that a spec is a variable, and there are a few possible kinds of variables. The most commonly used is a "composite", which represents a Java class to be instantiated. For example:
com.rultor.base.Empty()
Another one is a local reference to a rule, for example:
my-other-rule()
This spec actually tells its parser that the object should be
instantiated using the spec from another rule, named
my-other-rule. It's also possible to refer to the rule
of another user:
urn:github:526301:his-rule()
This spec tells its parser to go to the rule his-rule
that belongs to the user urn:github:526301.
Arrays and dictionaries are collections and maps in Java, for example:
[ "first line", "second line" ]
{
"name": "Jeff Lebowski",
"photo": java.net.URI("http://.."),
"age": 32
}
[ com.rultor.base.Empty(), 4, 67L, 14.989008 ]
As you see, both arrays and dictionaries are not strongly typed and may contains objects of different types.
Texts have two forms, a short/compact/usual one, and a long one,
called a "big text". Both of them create instances of Java
String class, but big text is more convenient for
multi-line blocks of text, for example:
"Hello, \"World!\"" """ <envelope> <message>Hello, "World!"</message> </envelope> """
So called "metas" may give you access to a few system properties
of a running rule, including, for example, ${work} and
${wallet}. Some classes need these types of arguments in order
to understand where they are running (what are the coordinates) or who
to charge for resource usage, for example:
com.rultor.base.Crontab(
${work}, "*5 * * * *",
com.rultor.base.Empty()
)
When you're writing a template, which will be used by other rules or even by other users, you will need to make it parametrized. For example, you want to define a spec template that will send emails, but an actual delivery address should be configurable by those who is using the template:
com.example.Send("Hello, it works!", ${0:email address})
In this example, the spec will instantiate class com.example.Send
with two parameters. The first one is a Java java.lang.String,
while the second one is not defined yet, but has to be provided by
those who is using this rule. If the name of the rule is, say, send,
than it can be used as:
send("me@example.com")
It's also possible to use so called "altered text", which contains Velocity commands, for example:
@("this is currently rule: ${work.rule()}")
Inside this velocity text you can use template arguments, for example:
@("URL is: #arg(0,'URL of the Github repository')")
Most of this magic is implemented in rultor-repo module.
| Modifier and Type | Interface and Description |
|---|---|
static class |
Spec.Simple
Simple.
|
static class |
Spec.Strict
Strict spec.
|
Copyright © 2009–2014 Rultor Inc.. All rights reserved.