com.threecrickets.scripturian

Interface LanguageAdapter

All Known Implementing Classes:

ClojureAdapter, GroovyAdapter, JeppAdapter, JRubyAdapter, JythonAdapter, LanguageAdapterBase, LuajAdapter, NashornAdapter, PegdownAdapter, QuercusAdapter, RhinoAdapter, ScalaAdapter, SuccinctAdapter, VelocityAdapter, WikiTextAdapterBase, WikiTextConfluenceAdapter, WikiTextMarkdownAdapter, WikiTextMediaWikiAdapter, WikiTextTextileAdapter, WikiTextTracWikiAdapter, WikiTextTWikiAdapter

public interface LanguageAdapter

Allows execution of source code in a supported language.

Language adapters are usually accessed via a LanguageManager instance.

Author:

Tal Liron

See Also:

LanguageManager

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_EXTENSION Attribute for default source code filename extension.
static String	DEFAULT_TAG Default language tag used for scriptlets.
static String	EXTENSIONS Attribute for standard source code filename extensions.
static String	LANGUAGE_NAME Attribute for the name of the implemented language.
static String	LANGUAGE_VERSION Attribute for the version of the implemented language.
static String	NAME Attribute for the name of the language adapter implementation.
static String	TAGS Attribute for language tags supported for scriptlets.
static String	VERSION Attribute for the version of the language adapter implementation.

Method Summary

Modifier and Type	Method and Description
Program	createProgram(String sourceCode, boolean isScriptlet, int position, int startLineNumber, int startColumnNumber, Executable executable) Turns source code into a program.
Object	enter(String entryPointName, Executable executable, ExecutionContext executionContext, Object... arguments) Enters the executable at a stored, named location.
Map<String,Object>	getAttributes() Adapter attributes.
Lock	getLock() Used when isThreadSafe() returns false.
LanguageManager	getManager() The language manager.
String	getSourceCodeForExpressionInclude(String expression, Executable executable) Creates source code for including the output of a text-with-scriptlets document.
String	getSourceCodeForExpressionOutput(String expression, Executable executable) Creates source code for outputting a source code expression to standard output.
String	getSourceCodeForLiteralOutput(String literal, Executable executable) Creates source code for outputting literal text to standard output.
boolean	isEphemeral() Some languages are meant for use in one segment only.
boolean	isThreadSafe() Some languages or their script engines are inherently broken when called by multiple threads.
void	releaseContext(ExecutionContext executionContext) Cleans up any resources used for an execution context.
void	setManager(LanguageManager manager) The language manager.

Field Detail

NAME

static final String NAME

Attribute for the name of the language adapter implementation.

See Also:

Constant Field Values

VERSION

static final String VERSION

Attribute for the version of the language adapter implementation.

See Also:

Constant Field Values

LANGUAGE_NAME

static final String LANGUAGE_NAME

Attribute for the name of the implemented language.

See Also:

Constant Field Values

LANGUAGE_VERSION

static final String LANGUAGE_VERSION

Attribute for the version of the implemented language.

See Also:

Constant Field Values

EXTENSIONS

static final String EXTENSIONS

Attribute for standard source code filename extensions.

See Also:

Constant Field Values

DEFAULT_EXTENSION

static final String DEFAULT_EXTENSION

Attribute for default source code filename extension.

See Also:

Constant Field Values

TAGS

static final String TAGS

Attribute for language tags supported for scriptlets.

See Also:

Constant Field Values

DEFAULT_TAG

static final String DEFAULT_TAG

Default language tag used for scriptlets.

See Also:

Constant Field Values

Method Detail

getManager

LanguageManager getManager()

The language manager.

Returns:

The language manager

setManager

void setManager(LanguageManager manager)

The language manager.

Parameters:

manager - The manager

getAttributes

Map<String,Object> getAttributes()

Adapter attributes. Adapter must at least support the keys listed in this interface, but may support their own special keys.

Returns:

The attributes

isThreadSafe

boolean isThreadSafe()

Some languages or their script engines are inherently broken when called by multiple threads. Returning false here makes sure Scripturian respects this and blocks.

Returns:

True if we support being run by concurrent threads

isEphemeral

boolean isEphemeral()

Some languages are meant for use in one segment only. Return true here makes sure that Scripturian will not change the current language tag after each segment parsed by this adapter.

Returns:

True if the current language tag should not change

getLock

Lock getLock()

Used when isThreadSafe() returns false.

Returns:

The lock

getSourceCodeForLiteralOutput

String getSourceCodeForLiteralOutput(String literal,
                                     Executable executable)
                              throws ParsingException

Creates source code for outputting literal text to standard output.

Parameters:

literal - The literal text

executable - The executable

Returns:

Source code

Throws:

ParsingException - In case of a parsing error

getSourceCodeForExpressionOutput

String getSourceCodeForExpressionOutput(String expression,
                                        Executable executable)
                                 throws ParsingException

Creates source code for outputting a source code expression to standard output.

Parameters:

expression - The source code expression

executable - The executable

Returns:

Source code

Throws:

ParsingException - In case of a parsing error

getSourceCodeForExpressionInclude

String getSourceCodeForExpressionInclude(String expression,
                                         Executable executable)
                                  throws ParsingException

Creates source code for including the output of a text-with-scriptlets document.

For this to work, the executable must have been created with a container that supports an inclusion command named according to the language manager attribute LanguageManager.CONTAINER_INCLUDE_COMMAND_ATTRIBUTE.

Parameters:

expression - The source code expression

executable - The executable

Returns:

Source code

Throws:

ParsingException - In case of a parsing error

See Also:

LanguageManager.getAttributes()

createProgram

Program createProgram(String sourceCode,
                      boolean isScriptlet,
                      int position,
                      int startLineNumber,
                      int startColumnNumber,
                      Executable executable)
               throws ParsingException

Turns source code into a program. The intent is for the implementation to perform the bare minimum required for detecting errors in the source code. For better initialization, likely at the cost of extra processing up front, call Program.prepare() on the program.

Parameters:

sourceCode - The source code

isScriptlet - Whether the source code is a scriptlet

position - The program's position in the executable

startLineNumber - The line number in the document for where the program's source code begins

startColumnNumber - The column number in the document for where the program's source code begins

executable - The executable

Returns:

A program

Throws:

ParsingException - In case of a parsing error

enter

Object enter(String entryPointName,
             Executable executable,
             ExecutionContext executionContext,
             Object... arguments)
      throws NoSuchMethodException,
             ParsingException,
             ExecutionException

Enters the executable at a stored, named location. According to the language, the entry point can be a function, method, lambda, closure, etc.

Parameters:

entryPointName - The entry point name

executable - The executable

executionContext - The executable context

arguments - Optional state to pass to the entry point

Returns:

State returned from to the entry point or null

Throws:

NoSuchMethodException - In case the entry point does not exist

ParsingException - In case of a parsing error

ExecutionException - In case of an execution error

releaseContext

void releaseContext(ExecutionContext executionContext)

Cleans up any resources used for an execution context.

Parameters:

executionContext - The execution context

See Also:

ExecutionContext.getAttributes()