com.github.misberner.duzzt.annotations

Annotation Type GenerateEmbeddedDSL

@Target(value=TYPE)
@Retention(value=SOURCE)
public @interface GenerateEmbeddedDSL

Generate an embedded DSL from the target class or interface.

Automatic Variable Arguments Overloads

Regular Expression Syntax

The regular expression syntax used by Duzzt follows common rules. Concatenation of regular expressions is declared implicitly by absence of any other operators, while a pipe character (|) is used to separate alternatives (union). Modifiers *, + or ? are used to specify that the preceding regular expression must occur an arbitrary number of times (including zero) (*), an arbitrary number of times, but at least once (+), or zero or one times (?).

Named Subexpressions

To avoid having to repeat common subexpressions that occur multiple times, named subexpressions can be introduced. A named subexpression serves as a placeholder for a regular expression. Named subexpressions are declared in the where() field. They can be referenced by enclosing their name in angle brackets (<>). Named subexpressions can be referenced by other named subexpressions, but their must not be any cyclic dependencies between named subexpressions.

Precedence rules

The precedence rules are as follows: a modifier operator has precedence over any other operators, concatenation has precedence over union. Parentheses (()) can be used to explicitly override these precedence rules.

Syntax Definition

The following BNF describes the syntax of Duzzt Regular Expressions.

regex	::=	union-regex
union-regex	::=	concat-regex (| concat-regex)*
concat-regex	::=	mod-regex mod-regex*
mod-regex	::=	mod-regex (?|*|+) | atomic-regex
atomic-regex	::=	( regex ) | identifier | < identifier >

An identifier is a string consisting of alphanumeric characters and _ only, and beginning with an alphabetic character or _.

Author:

Malte Isberner

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	name The simple (i.e., unqualified) name of the EDSL class to generate.
String	syntax The syntax of the embedded DSL, specified as a regular expression.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	autoVarArgs Automatically generate variable argument overloads for all suitable methods.
boolean	classPublic Specifies whether the generated DSL class should be declared as public.
com.github.misberner.apcommons.util.Visibility	delegateConstructorVisibility Controls the visibility of the delegate constructor, i.e., the constructor which takes an instance of the DSL implementation as argument.
boolean	enableAllMethods Automatically treat all methods (excluding those defined by the Object class) as actions of the embedded DSL.
boolean	forwardAllConstructors Controls whether to automatically generate forwards for all visible constructors.
com.github.misberner.apcommons.util.Visibility	forwardConstructorVisibility
boolean	includeInherited Consider inherited methods as potential DSL actions.
com.github.misberner.apcommons.util.AFModifier	modifier Specifies whether the generated DSL class should be declared as final.
boolean	nonVoidTerminators The default setting is false.
String	packageName The package in which the generated EDSL class will be placed.
SubExpr[]	where Named subexpressions that can be used in the embedded DSL syntax definition.

Element Detail

name

public abstract String name

The simple (i.e., unqualified) name of the EDSL class to generate. This is a mandatory option.

syntax

public abstract String syntax

The syntax of the embedded DSL, specified as a regular expression. This is a mandatory option.

See above for a syntax definition for regular expressions.

packageName

public abstract String packageName

The package in which the generated EDSL class will be placed.

The value is interpreted as a package reference relative to the implementation class annotated with this annotation:

• if the value is ".", the resulting package name is the same as that of the implementation class. This is the default.
• if the value starts with a dot, followed by a legal Java package name, that package name is appended to the package name of the implementation class, forming the result package name.
• otherwise, the value is taken as the package name as-is.

The default value is ".".

Default:

"."

classPublic

public abstract boolean classPublic

Specifies whether the generated DSL class should be declared as public. If set to false, it will have package-private visibility.

The default setting is true.

Default:

true

modifier

public abstract com.github.misberner.apcommons.util.AFModifier modifier

Specifies whether the generated DSL class should be declared as final. If set to false, it will be non-final.

The default setting is false.

Default:

com.github.misberner.apcommons.util.AFModifier.DEFAULT

where

public abstract SubExpr[] where

Named subexpressions that can be used in the embedded DSL syntax definition.

Named subexpressions are referenced by their name, enclosed in angle brackets (< and >). Subexpressions may reference other subexpressions, but there must not be any cyclic dependencies between subexpressions.

Subexpressions are specified as regular expressions. See above for a syntax definition for regular expressions.

The default value is {}, meaning that no subexpressions are declared.

Default:

{}

autoVarArgs

public abstract boolean autoVarArgs

Automatically generate variable argument overloads for all suitable methods.

The global behavior can be overridden on a per-method basis by setting DSLAction.autoVarArgs().

The default setting is true.

Default:

true

nonVoidTerminators

public abstract boolean nonVoidTerminators

The default setting is false.

Default:

false

enableAllMethods

public abstract boolean enableAllMethods

Automatically treat all methods (excluding those defined by the Object class) as actions of the embedded DSL. If set to false, only those methods annotated with a DSLAction annotation and have DSLAction#disable() set to false will be available as DSL actions.

The default setting is true.

Default:

true

includeInherited

public abstract boolean includeInherited

Consider inherited methods as potential DSL actions. If set to false, only those methods directly declared in this class will be regarded as potential DSL actions.

The default setting is true.

Default:

true

forwardAllConstructors

public abstract boolean forwardAllConstructors

Controls whether to automatically generate forwards for all visible constructors. If set to false, only those constructors annotated with DSLConstructor will be forwarded. If set to true, forwarding of a single constructor can be effectively prevented by annotating it with DSLConstructor and setting DSLConstructor.value() to Visibility.PRIVATE.

The default setting is true.

Default:

true

delegateConstructorVisibility

public abstract com.github.misberner.apcommons.util.Visibility delegateConstructorVisibility

Controls the visibility of the delegate constructor, i.e., the constructor which takes an instance of the DSL implementation as argument. If no such constructor should be visible, set this to Visibility.PRIVATE. Note that the visibility of the generated delegate constructor will never be higher than that of the DSL implementation.

The default setting is Visibility.PUBLIC.

Default:

com.github.misberner.apcommons.util.Visibility.PUBLIC

forwardConstructorVisibility

public abstract com.github.misberner.apcommons.util.Visibility forwardConstructorVisibility

Default:

com.github.misberner.apcommons.util.Visibility.PUBLIC