Package com.randomnoun.common.jessop

Interface JessopScriptBuilder

All Known Implementing Classes:
AbstractJessopScriptBuilder, JavaJessopScriptBuilder, JavascriptJessopScriptBuilder, LispJessopScriptBuilder, LuaJessopScriptBuilder, Python2JessopScriptBuilder, RubyJessopScriptBuilder
public interface JessopScriptBuilder
Each target language we intend to support within jessop must have an implementation of this interface. Developers wishing to implement this interface should use the AbstractJessopScriptBuilder abstract class.

Implementations of this class should return the language it supports (and the default script engine name) via the getLanguage() and getDefaultScriptEngineName() methods.

These values will be used to select the correct JessopScriptBuilder identified in the <%@ jessop language="xxx"%> declaration in the jessop source file.

When this class is instantiated, the caller will invoke setPrintWriter(PrintWriter) and setTokeniserAndDeclarations(Tokeniser, JessopDeclarations).

As the Tokeniser parses the jessop source file, it will invoke emit() methods on this class. As these methods are called, this class should generate code in the target language via the printWriter.

Care should be taken to ensure that code in the target language script is on the same line number as the corresponding code on the input script, to make error messages more developer-friendly.

Author:
knoxg

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    emitDeclaration(int line, String s)
    Called by the tokeniser and requests that this JessopScriptBuilder process a <%@ ...
    void
    emitExpression(int line, String s)
    Called by the tokeniser and requests that this JessopScriptBuilder generate code to generate some evaluated output.
    void
    emitScriptlet(int line, String s)
    Called by the tokeniser and requests that this JessopScriptBuilder copy the included code into the generated script.
    void
    emitText(int line, String s)
    Called by the tokeniser and requests that this JessopScriptBuilder generate code to generate some text output.
    JessopDeclarations
    getDeclarations()
    Returns the value of any jessop declarations that are in effect.
    String
    getDefaultBindingsConverterClassName()
    Returns the name of the default bindingsConverter class that should be used for the default script engine, or null if no converter is required.
    String
    getDefaultExceptionConverterClassName()
    Returns the name of the default exceptionConverter class that should be used for the default script engine, or null if no converter is required.
    String
    getDefaultScriptEngineName()
    Returns the name of the script engine that is used to evaluate this script; e.g.
    String
    getLanguage()
    Returns the name of the language that this scriptBuilder can parse; e.g.
    void
    setPrintWriter(PrintWriter pw)
    Sets the printWriter that this class will write to during emit() methods
    void
    setTokeniserAndDeclarations(Tokeniser t, JessopDeclarations declarations)
    Sets the tokeniser and declaration that are in effect at the start of parsing.

  • Method Details

    • getLanguage

      String getLanguage()
      Returns the name of the language that this scriptBuilder can parse; e.g. "javascript" or "python2".

      This is used to register this JessopScriptBuilder in the registry and is used to lookup the JessopScriptBuilder from the language defined in the jessop script declaration.

      Returns:
      the name of the language that this scriptBuilder can parse; e.g. "javascript" or "python2".

    • getDefaultScriptEngineName

      String getDefaultScriptEngineName()
      Returns the name of the script engine that is used to evaluate this script; e.g. "rhino" or "jython"
      Returns:
      the name of the script engine that is used to evaluate this script; e.g. "rhino" or "jython"

    • getDefaultExceptionConverterClassName

      String getDefaultExceptionConverterClassName()
      Returns the name of the default exceptionConverter class that should be used for the default script engine, or null if no converter is required.

      Changing the engine in the jessop declaration will reset the the converter to null.

      Returns:
      the name of the default exceptionConverter class that should be used for the default script engine

    • getDefaultBindingsConverterClassName

      String getDefaultBindingsConverterClassName()
      Returns the name of the default bindingsConverter class that should be used for the default script engine, or null if no converter is required.

      Changing the engine in the jessop declaration will reset the the converter to null.

      Returns:
      the name of the default bindingsConverter class that should be used for the default script engine

    • setPrintWriter

      void setPrintWriter(PrintWriter pw)
      Sets the printWriter that this class will write to during emit() methods
      Parameters:
      pw - the printWriter that this class will write to during emit() methods

    • setTokeniserAndDeclarations

      void setTokeniserAndDeclarations(Tokeniser t, JessopDeclarations declarations)
      Sets the tokeniser and declaration that are in effect at the start of parsing. This allows this ScriptBuilder to switch ScriptBuilders.
      Parameters:
      t - tokeniser that is processing the jessop source
      declarations - jessop declarations that are in effect

    • emitText

      void emitText(int line, String s)
      Called by the tokeniser and requests that this JessopScriptBuilder generate code to generate some text output.

      This method should escape the output and generate code that outputs this text in the implementation language.

      Parameters:
      line - jessop source line number that begins this text output
      s - the text to output; may include newlines.

    • emitExpression

      void emitExpression(int line, String s)
      Called by the tokeniser and requests that this JessopScriptBuilder generate code to generate some evaluated output. i.e. process a <%= ... %> expression.

      This method should generate the code to evaluate and output the contents of the <%= ... %> expression.

      This method should attempt to preserve line numbers between the jessop source file and the generated code file.

      Parameters:
      line - jessop source line number that begins this text output.
      s - the contents of the <%= ... %> expression.

    • emitScriptlet

      void emitScriptlet(int line, String s)
      Called by the tokeniser and requests that this JessopScriptBuilder copy the included code into the generated script. i.e. process a <% ... %> scriptlet. (The 'scriptlet' term is the term used in the JSP specification)

      This method should generate the same code that is contained within the <% ... %> scriptlet.

      This method should attempt to preserve line numbers between the jessop source file and the generated code file.

      This scriptlet may not be syntactically correct by itself and may require further scriptlets to function, e.g. 

       <% if (a > b) { %>
 something
 <% } %>
      Parameters:
      line - jessop source line number that begins this scriptlet.
      s - the contents of the <%= ... %> expression.

    • emitDeclaration

      void emitDeclaration(int line, String s) throws ScriptException
      Called by the tokeniser and requests that this JessopScriptBuilder process a <%@ ... %> directive.

      The exact semantics of these declarations can be defined per-language, but 'jessop' declarations should be processed by the AbstractJessopScriptBuilder, i.e. declarations that are in the form <%@ jessop language="xxx" %>

      Ideally, there's only one declaration, at the top of the source script.

      Parameters:
      line - jessop source line number that begins this directive
      s - the contents of the <%@ ... %> directive
      Throws:
      ScriptException

    • getDeclarations

      JessopDeclarations getDeclarations()
      Returns the value of any jessop declarations that are in effect.

      Used to maintain declarations when switching JessopScriptBuilders, and to retrieve declarations after the script is built.