SVL Variables
Grammar
SVL has two marker forms. ${Type:key[:default]} looks up a variable; #{expr} evaluates a typed expression whose result is stringified where it lands in the template text.
Marker forms
| Form | Meaning |
|---|---|
${Type:key} / ${Type:key:default} | Var lookup. Type is a registered var name ([A-Za-z]+), e.g. ${S:user.home}, ${C:Foo.bar:none}. |
${name} / ${name:default} | If the text before the first top-level : is not a registered var name, the whole body is a property (P) lookup. ${HOSTNAME:localhost} keeps working. A property named like a registered var (e.g. C) reads as that var. |
#{expr} | Expression. Typed inside, stringified in the surrounding text. |
How the body is split on : depends on the var class:
- Defaulting vars (
FV,I,F,EF,A,P,S,E,MF,DE,C): the first top-level:splits key from default; the rest of the default is verbatim (${S:key:a:b}is keykey, defaulta:b). - Multipart and multipart-resolving vars (
RH,RA,SS,OS,R,RS,RQ,RF,RP,L): every top-level:starts a new part (${L:key:a:b}). - Simple vars (
U,UE,W,SA,X): the body is passed whole.SAkeeps its comma form,${SA:contentType,key[,default]}.
${}, ${:} and ${S:} reach the real P/S vars, which reject empty names. ${S:x:} has the default "". An unknown name such as ${D:X} is a property/scope lookup of key D with default X.
Escaping and quoting
- Top level:
\\,\$and\#emit the trailing character.$$is not an escape. - Inside
${...}: a backslash before:,',",,or}is removed before the var sees the key, part or default.${X:\'}delivers',${X:a\,b}deliversa,b,${X:\}}delivers}, and\\delivers one backslash. A literal colon in a key is written\:. An unescaped top-level,in a key is an error in strict mode and literal text in lenient mode. A quote opens a quoted run only at the start of a part (it'sanddon'tare plain text); a fully quoted part is unquoted. - Inside
#{...}: strings are'...'or"...". The only escape is a doubled quote ('it''s'); backslash is not a string escape. A quoted string does not interpolate:'${S:x}'is literal text.
Expressions
- Literals: strings, numbers (
1.,.5),true,false,null; unary+and-. - Bare words are scope lookups, not strings: write
upper('hello'). - A
${...}inside#{}is one primary token and yields the typed value. - Paths:
a.b,a?.b,a['k'],a[0]over maps, records and non-java.*beans;classis excluded.
| Operator | Notes |
|---|---|
+ - * / % | + concatenates when either side is a string; numbers promote int, long, double, BigDecimal. / on two integers stays integral only when exact, otherwise double; integral division or modulo by zero is an error. A string can be indexed ('abc'[0] is 'a'). |
== != < <= > >= | == is numeric for numbers, else equals; ordering needs same-family Comparable. |
and or not / && || ! | Boolean. |
a ? b : c | Ternary. |
a ?: b | Elvis: fires only on null (absent). false, 0 and "" are kept; the same holds for :default. |
matches | Regex; patterns are cached. |
Public functions keep their own semantics: #{add(1,2)} is a double, while #{1+2} follows SpEL coercion.
An expression may contain at most 1000 operators; a longer chain fails to parse ("expression too complex" in strict mode, literal text in lenient mode).
Collections. Selection items.?[age > 18] and projection items.![name]; the body is a full expression with the element as the current scope. The result size is capped by maxCollectionSize (default 1000): strict mode throws, lenient mode truncates.
Functions. fn(a, b) with nesting, from the VarFunction registry (upper, join(sep, parts...), jsonPath, ...). ul, ol, block and table return a Structure value that is stringified through the value formatter. See Simple Variable Language for the catalog.
Strict vs. lenient
The default is lenient. VarResolver.Builder.strict(true) makes malformed markers, parse errors, unknown prefixes or functions, denied functions, legacy $X{...} markers and limit overruns throw a positioned ExprException. Lenient mode keeps the marker as literal text. Unknown functions are detected at compile time.
Limits
maxExprDepth (default 32) bounds the nesting depth of ${} bodies and expression evaluation. maxCollectionSize (default 1000) bounds selection and projection results. Both are set on the builder and must be positive. The 1000-operator cap per expression is fixed.
valueFormatter
Lists, maps, beans and Structure values are stringified as JSON with no spaces ([1,2,3]). VarResolver.Builder.valueFormatter(Function<Object,String>) replaces the formatter; VarResolverSession.valueFormatter(...) overrides it per session.
allowFunctions
Builder.allowFunctions("name", "prefix*", "$op.*") takes glob patterns where * matches any run of characters. If it is never called, everything is allowed; called with no patterns, everything is denied, operators included. Repeated calls are additive, including after copy() (a copy can widen, not narrow). Operators dispatch to $op.* functions ($op.add, $op.ternary, $op.select, ...), which can be denied like any other. A denied function behaves like an unknown one (strict mode reports "not permitted"). A restricted function family still needs defaultFunctions() registered for unary minus ($op.neg) to work.
Values produced by vars and functions are never re-parsed as template syntax.
Under resolveHtmlDoc, literals and computed results inside #{} are emitted raw (not XML-escaped). That is unsafe with untrusted input; keep untrusted data out of #{} literals in HTML templates. See SVL Security.
Defining variables
Variables are defined through the Var API. The API comes with several predefined variables and is easily extensible.
The following is an example of a variable that performs URL-Encoding on strings.
// First create our var.
public class UrlEncodeVar extends SimpleVar {
// Must have a no-arg constructor!
public UrlEncodeVar() {
super("UE");
}
// The method we must implement
@Override
public String resolve(VarResolverSession session, String key) {
return URLEncoder.encode(key, "UTF-8");
}
}
// Next create a var resolver that extends the existing DEFAULT resolver
// that supports resolving system properties.
VarResolver varResolver = VarResolver.DEFAULT
.copy()
.vars(UrlEncodeVar.class)
.build();
// Retrieve a system property and URL-encode it if necessary.
String myProperty = varResolver.resolve("${UE:${S:my.property}}");
The following shows the class hierarchy of the Var class:
The following is the list of default variables defined in all modules:
| Module | Class | Pattern |
|---|---|---|
| juneau-svl | PropertyVar | ${P:key[:default]} |
| juneau-svl | EnvVariablesVar | ${E:key[:default]} |
| SystemPropertiesVar | ${S:key[:default]} | |
| EnvFileVar | ${EF:key[:default]} | |
| DotenvVar | ${DE:key[:default]} | |
| ArgsVar | ${A:key[:default]} | |
| ManifestFileVar | ${MF:key[:default]} | |
| HtmlWidgetVar | ${W:name} | |
| juneau-config | ConfigVar | ${C:key[:default]} |
| juneau-rest-server | FileVar | ${F:path[:default]} |
| ServletInitParamVar | ${I:name[:default]} | |
| LocalizationVar | ${L:key[:args...]} | |
| RequestAttributeVar | ${RA:key1[:key2...]} | |
| RequestFormDataVar | ${RF:key1[:key2...]} | |
| RequestHeaderVar | ${RH:key1[:key2...]} | |
| RequestPathVar | ${RP:key1[:key2...]} | |
| RequestQueryVar | ${RQ:key1[:key2...]} | |
| RequestSwaggerVar | ${RS:key} | |
| RequestVar | ${R:key1[:key2...]} | |
| SerializedRequestAttrVar | ${SA:contentType,key[,default]} | |
| SwaggerVar | ${SS:key1[:key2...]} | |
| UrlVar | ${U:uri} | |
| UrlEncodeVar | ${UE:uriPart} |
${P:...} is the unified property-stack resolver. It walks the configured Settings property source precedence
(local overrides, global overrides, args, system properties, environment, .env, and any custom sources). Use
${S:...} / ${E:...} / ${EF:...} / ${DE:...} / ${A:...} / ${MF:...} / ${C:...} when you need a source-specific lookup.