Skip to main content

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​

FormMeaning
${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 key key, default a: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. SA keeps 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} delivers a,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's and don't are 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; class is excluded.
OperatorNotes
+ - * / %+ 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 : cTernary.
a ?: bElvis: fires only on null (absent). false, 0 and "" are kept; the same holds for :default.
matchesRegex; 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.

HTML-doc encoding

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:

Var - Superclass of all vars.SimpleVar - Superclass of all vars that return strings.DefaultingVar - Variables that define a default value if the resolve method returns null.MapVar - Variables that pull values from maps.MultipartVar - Variables that consist of 2 or more comma-delimited arguments.StreamedVar - Superclass of all vars that stream their value to writers.

The following is the list of default variables defined in all modules:

ModuleClassPattern
juneau-svlPropertyVar${P:key[:default]}
juneau-svlEnvVariablesVar${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-configConfigVar${C:key[:default]}
juneau-rest-serverFileVar${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.

See also​