Antlr4.StringTemplate A compiler for a single template.

Throw out \n and leading whitespace tokens inside BIGSTRING_NO_NL.

Name subtemplates _sub1, _sub2, ... Compile full template with unknown formal args. Compile full template with respect to a list of formal args.

Used for assembly/disassembly; describes instruction set

temp data used during construction and functions that fill it / use it. Result is impl CompiledTemplate object. The compiled code implementation to fill in. Track unique strings; copy into CompiledTemplate's String[] after compilation Track instruction location within code.instrs array; this is next address to Write to. Byte-addressable memory. Write value at index into a byte array highest to lowest byte, left to right. The result of compiling an Template. Contains all the bytecode instructions, string table, bytecode address to source code map, and other bookkeeping info. It's the implementation of an Template you might say. All instances of the same template share a single implementation (impl field). Every template knows where it is relative to the group that loaded it. The prefix is the relative path from the root. "/prefix/name" is the fully qualified name of this template. All ST.getInstanceOf() calls must use fully qualified names. A "/" is added to the front if you don't specify one. Template references within template code, however, uses relative names, unless of course the name starts with "/". This has nothing to do with the outer filesystem path to the group dir or group file. We set this as we load/compile the template. Always ends with "/". The original, immutable pattern (not really used again after initial "compilation"). Useful for debugging. Even for subtemplates, this is entire overall template. The token that begins template definition; could be <@r> of region. Overall token stream for template (debug only) How do we interpret syntax of template? (debug only) A list of all regions and subtemplates The group that physically defines this Template definition. We use it to initiate interpretation via Template.ToString(). From there, it becomes field 'group' in interpreter and is fixed until rendering completes. Does this template come from a <@region>...<@end> embedded in another template? If someone refs <@r()> in template t, an implicit @t.r() ::= "" is defined, but you can overwrite this def by defining your own. We need to prevent more than one manual def though. Between this var and isEmbeddedRegion we can determine these cases.

Cloning the for a instance allows to be called safely during interpretation for templates that do not contain formal arguments.

A copy of the current instance. The copy is a shallow copy, with the exception of the field which is also cloned. Used by Template.Add() to Add args one by one w/o turning on full formal args definition signal Represents the name of a formal argument defined in a template: test(a,b,x=defaultvalue) ::= "<a> <n> <x>" Each template has a set of these formal arguments or uses a placeholder object: UNKNOWN (indicating that no arguments were specified such as when we create a template with "new Template(...)"). Note: originally, I tracked cardinality as well as the name of an attribute. I'm leaving the code here as I suspect something may come of it later. Currently, though, cardinality is not used. If they specified default value x=y, store the token here This class represents the tokenizer for templates. It operates in two modes: inside and outside of expressions. It behaves like an ANTLR TokenSource, implementing nextToken(). Outside of expressions, we can return these token types: TEXT, INDENT, LDELIM (start of expr), RCURLY (end of subtemplate), and NEWLINE. Inside of an expression, this lexer returns all of the tokens needed by the STParser. From the parser's point of view, it can treat a template as a simple stream of elements. This class defines the token types and communicates these values to STParser.g via TemplateLexer.tokens file (which must remain consistent). What char starts an expression? This keep track of the mode of the lexer. Are we inside or outside an Template expression? To be able to properly track the inside/outside mode, we need to track how deeply nested we are in some templates. Otherwise, we know whether a '}' and the outermost subtemplate to send this back to outside mode. When we started token, track initial coordinates so we can properly build token objects. Our lexer routines might have to emit more than a single token. We buffer everything through this list. Ensure x is next character on the input stream ID : ('a'..'z'|'A'..'Z'|'_'|'/') ('a'..'z'|'A'..'Z'|'0'..'9'|'_'|'/')* ; STRING : '"' ( '\\' '"' | '\\' ~'"' | ~('\\'|'"') )* '"' ; We build STToken tokens instead of relying on CommonToken so we can override ToString(). It just converts token types to token names like 23 to LDELIM. A unique set of strings where we can get a string's index. We can also get them back out in original order.

Name of overall template

Overall template token

Overall template text

Build an AST from a single StringTemplate template A dir of templates w/o headers like ST v3 had. Still allows group files in dir though like TemplateGroupDirectory parent. Track all events that happen while evaluating this template All templates evaluated and embedded in this ST. Used for tree view in STViz. An event that happens when building Template trees, adding attributes etc... This interface describes an object that knows how to Format or otherwise Render an object appropriately. There is one renderer registered per group for a given Java type. If the Format string passed to the renderer is not recognized then simply call ToString(). formatString can be null but locale will at least be Locale.getDefault() Essentially a char filter that knows how to auto-indent output by maintaining a stack of indent levels. The indent stack is a stack of strings so we can repeat original indent not just the same number of columns (don't have to worry about tabs vs spaces then). Anchors are char positions (tabs won't work) that indicate where all future wraps should justify to. The wrap position is actually the larger of either the last anchor or the indentation level. This is a filter on a Writer. \n is the proper way to say newline for options and templates. Templates can mix \r\n and \n them but use \n for sure in options like wrap="\n". Template will generate the right thing. Override the default (locale) newline by passing in a string to the constructor.

Stack of indents

Stack of integer anchors (char positions in line)

The newline character used for this writer

The underlying output stream

Track char position in the line (later we can think about tabs). Indexed from 0. We want to keep charPosition <= lineWidth. This is the position we are *about* to Write not the position last written to.

The absolute char index into the output of the next char to be written.

Write out a string literal or attribute expression or expression element. Write out a string literal or attribute expression or expression element. If doing line wrap, then check wrap before emitting this str. If at or beyond desired line width then emit a \n and any indentation before spitting out this str. An automatically created aggregate of properties. I often have lists of things that need to be formatted, but the list items are actually pieces of data that are not already in an object. I need ST to do something like: Ter=3432 Tom=32234 .... using template: $items:{it.name$=$it.type$}$ This example will call getName() on the objects in items attribute, but what if they aren't objects? I have perhaps two parallel arrays instead of a single array of objects containing two fields. One solution is allow Maps to be handled like properties so that it.name would fail getName() but then see that it's a Map and do it.get("name") instead. This very clean approach is espoused by some, but the problem is that it's a hole in my separation rules. People can put the logic in the view because you could say: "go get bob's data" in the view: Bob's Phone: $db.bob.phone$ A view should not be part of the program and hence should never be able to go ask for a specific person's data. After much thought, I finally decided on a simple solution. I've added setAttribute variants that pass in multiple property values, with the property names specified as part of the name using a special attribute name syntax: "name.{propName1,propName2,...}". This object is a special kind of HashMap that hopefully prevents people from passing a subclass or other variant that they have created as it would be a loophole. Anyway, the ASTExpr.getObjectProperty() method looks for Aggregate as a special case and does a get() instead of getPropertyName. Allow StringTemplate to add values, but prevent the end user from doing so. Deal with structs created via ST.add("structname.{prop1, prop2}", ...); A line number and char position within a line. Used by the source mapping stuff to map address to range within a template. Used during tests to track all errors All the errors that can happen and how to generate a message

Represents a range.

This structure represents an immutable integer interval that describes a range of values, from Start to End. It is closed on the left and open on the right: [Start .. End). In the context of a Template it represents a span of text, but the Interval structure itself is independent of any particular text.

Initializes a new instance of an Interval with the given start point and length.

The starting point of the interval. The length of the interval. or is less than zero.

Gets the starting index of the span.

The starting index of the span.

Gets the end of the interval.

The interval is open-ended on the right side, so that Start + Length = End.

Gets the length of the interval, which is always non-negative.

The length of the interval, which is always non-negative.

Determines whether or not this interval is empty.

true if the length of the interval is zero, otherwise false.

Initializes a new instance of an Interval with the given start and end positions.

The start position of the new interval. The end position of the new interval. The new interval. is less than 0, or is less than .

Determines whether the position lies within the interval.

The position to check. true if the position is greater than or equal to Start and less than End, otherwise false.

Determines whether the specified interval falls completely within this interval.

The interval to check. true if the specified interval falls completely within this interval, otherwise false. Replace >\> with >> in s. Replace \>> unless prefix of \>>> with >>. Do NOT replace if it's <\\> Given index into string, compute the line and char position in line A hash table that maps a key to a list of elements not just a single.

Builds an accessor for an indexer property that returns a takes a string argument.

Used for semantic errors that occur at compile time not during interpretation. For Template parsing ONLY not group parsing.

token inside group file

Upon error, Template creates an TemplateMessage or subclass instance and notifies the listener. This root class is used for IO and internal errors. @see TemplateRuntimeMessage @see TemplateCompiletimeMessage if in debug mode, has created instance, Add attr events and eval template events.

For the expression a.b, object a has no b property.

Used to track errors that occur in the Template interpreter. Where error occurred in bytecode memory Given an ip (code location), get it's range in source template then return it's template line:col. If an instance of x is enclosed in a y which is in a z, return a String of these instance names in order from topmost to lowest; here that would be "[z y x]". A group derived from a string not a file or dir. A renderer for java.util.Date and Calendar objects. It understands a variety of format names as shown in formatToInt field. By default it assumes "short" format. A prefix of date: or time: shows only those components of the time object. This class knows how to execute template bytecodes relative to a particular TemplateGroup. To execute the byte codes, we need an output stream and a reference to an Template an instance. That instance's impl field points at a CompiledTemplate, which contains all of the byte codes and other information relevant to execution. This interpreter is a stack-based bytecode interpreter. All operands go onto an operand stack. If the group that we're executing relative to has debug set, we track interpreter events. For now, I am only tracking instance creation events. These are used by STViz to pair up output chunks with the template expressions that generate them. We create a new interpreter for each Template.Render(), DebugTemplate.Visualize, or DebugTemplate.GetEvents() invocation. Dump bytecode instructions as we execute them? Exec st with respect to this group. Once set in Template.ToString(), it should be fixed. Template has group also. For renderers, we have to pass in the culture Operand stack, grows upwards If trace mode, track trace here Track events inside templates and in this.events Track everything happening in interp if debug across all templates. The last event in this field is the EvalTemplateEvent for the root template. Execute template self and return how many characters it wrote to out Write out an expression result that doesn't use expression options. E.g., <name> Write out an expression result that uses expression options. E.g., <names; separator=", "> Generic method to emit text for an object. It differentiates between templates, iterable objects, and plain old Java objects (POJOs) Return the first attribute if multiple valued or the attribute itself if single-valued. Used in <names:First()> Return the last attribute if multiple valued or the attribute itself if single-valued. Unless it's a list or array, this is pretty slow as it iterates until the last element. Return everything but the first attribute if multiple valued or null if single-valued. Return all but the last element. Trunc(x)=null if x is single-valued. Return a new list w/o null values. Return a list with the same elements as v but in reverse order. null values are NOT stripped out. use Reverse(Strip(v)) to do that. Return the length of a mult-valued attribute or 1 if it is a single attribute. If attribute is null return 0. Special case several common collections and primitive arrays for speed. This method by Kay Roepke from v3. Find an attr via dynamic scoping up enclosing scope chain. If not found, look for a map. So attributes sent in to a template override dictionary names. Set any default argument values that were not set by the invoking template or by setAttribute directly. Note that the default values may be templates. The evaluation context is the template enclosing invokedST. For every event, we track in overall list and in self's event list so that each template has a list of events used to create it. If EvalTemplateEvent, store in parent's childEvalTemplateEvents list for STViz tree view. An object that knows how to convert property references to appropriate actions on a model object. Some models, like JDBC, are interface based (we aren't supposed to care about implementation classes). Some other models don't follow getter method naming convention. So, if we have an object of type M with property method foo() (not getFoo()), we register a model adaptor object, adap, that converts foo lookup to foo(). Given <a.foo>, we look up foo via the adaptor if "a instanceof(M)". See unit tests. Lookup property name in o and return its value. It's a good idea to cache a Method or Field reflection object to make this fast after the first look up. property is normally a String but doesn't have to be. E.g., if o is Map, property could be any key type. If we need to convert to string, then it's done by Template and passed in here. Just pass through the text Works with Byte, Short, Integer, Long, and BigInteger as well as Float, Double, and BigDecimal. You pass in a Format string suitable for Formatter object: http://java.sun.com/j2se/1.5.0/docs/api/java/util/Formatter.html For example, "%10d" emits a number as a decimal int padding to 10 char. This can even do long to date conversions using the Format string. An instance of the StringTemplate. It consists primarily of a reference to its implementation (shared among all instances) and a hash table of attributes. Because of dynamic scoping, we also need a reference to any enclosing instance. For example, in a deeply nested template for an HTML page body, we could still reference the title attribute defined in the outermost page template. To use templates, you create one (usually via TemplateGroup) and then inject attributes using Add(). To Render its attacks, use Render(). <@r()>, <@r>...<@end>, and @t.r() ::= "..." defined manually by coder

The region is defined by <@r()>

The region is defined by <@r>...<@end>

The region is defined by @t.r ::= "..."

When there are no formal args for template t and you map t across some values, t implicitly gets arg "it". E.g., "$it$" The implementation for this template among all instances of same tmpelate . Safe to simultaneously Write via Add, which is synchronized. Reading during exec is, however, NOT synchronized. So, not thread safe to Add attributes while it is being evaluated. Initialized to EmptyAttribute to distinguish null from empty. Created as instance of which group? We need this to init interpreter via Render. So, we create st and then it needs to know which group created it for sake of polymorphism: st = skin1.GetInstanceOf("searchbox"); result = st.Render(); // knows skin1 created it Say we have a group, g1, with template t and import t and u templates from another group, g2. g1.GetInstanceOf("u") finds u in g2 but remembers that g1 created it. If u includes t, it should create g1.t not g2.t. g1 = {t(), u()} | v g2 = {t()} If Interpreter.trackCreationEvents, track creation, add-attr events for each object. Create this object on first use. Just an alias for ArrayList, but this way I can track whether a list is something Template created or it's an incoming list. Used by group creation routine, not by users Used to make templates inline in code for simple things like SQL or log records. No formal args are set and there is no enclosing instance. Create Template using non-default delimiters; each one of these will live in it's own group since you're overriding a default; don't want to alter TemplateGroup.defaultGroup. Clone a prototype template. Copy all fields except DebugState. Inject an attribute (name/value pair). If there is already an attribute with that name, this method turns the attribute into an AttributeList with both the previous and the new attribute as elements. This method will never alter a List that you inject. If you send in a List and then inject a single value element, Add() copies original list and adds the new value. Return self so we can chain. t.add("x", 1).add("y", "hi"); Split "aggrName.{propName1,propName2}" into list [propName1,propName2] and the aggrName. Spaces are allowed around ','. Remove an attribute value entirely (can't Remove attribute definitions). Set this.locals attr value when you only know the name, not the index. This is ultimately invoked by calling Template.Add() from outside so toss an exception to notify them. Find an attr in this template only. Events during template hierarchy construction (not evaluation) Record who made us? ConstructionEvent creates Exception to grab stack Track construction-time add attribute "events"; used for ST user-level debugging How to handle messages A directory or directory tree of .st template files and/or group files. Individual template files contain formal template definitions. In a sense, it's like a single group file broken into multiple files, one for each template. Template v3 had just the pure template inside, not the template name and header. Name inside must match filename (minus suffix). When we use key as a value in a dictionary, this is how we signify. Load files using what encoding? Every group can import templates/dictionaries from other groups. The list must be synchronized (see ImportTemplates). Maps template name to StringTemplate object. synchronized. Maps dict names to HashMap objects. This is the list of dictionaries defined by the user like typeInitMap ::= ["int":"0"] A dictionary that allows people to register a renderer for a particular kind of object for any template evaluated relative to this group. For example, a date should be formatted differently depending on the culture. You can set Date.class to an object whose ToString(Object) method properly formats a Date attribute according to culture. Or you can have a different renderer object for each culture. Order of addition is recorded and matters. If more than one renderer works for an object, the first registered has priority. Renderer associated with type t works for object o if t.isAssignableFrom(o.getClass()) // would assignment t = o work? So it works if o is subclass or implements t. This structure is synchronized. A dictionary that allows people to register a model adaptor for a particular kind of object (subclass or implementation). Applies for any template evaluated relative to this group. Template initializes with model adaptors that know how to pull properties out of Objects, Maps, and STs. Watch loading of groups and templates For debugging with STViz. Records where in code an ST was created and where code added attributes. v3 compatibility; used to iterate across values not keys like v4. But to convert ANTLR templates, it's too hard to find without static typing in templates. Used to indicate that the template doesn't exist. Prevents duplicate group file loads and unnecessary file checks. The error manager for entire group; all compilations and executions. This gets copied to parsers, walkers, and interpreters. The primary means of getting an instance of a template from this group. Names must be absolute, fully-qualified names like a/b Create singleton template for use with dictionary values Is this template defined in this group or from this group below? Names must be absolute, fully-qualified names like /a/b Look up a fully-qualified name "Unload" all templates and dictionaries but leave renderers, adaptors, and import relationships. This essentially forces next GetInstanceOf to reload templates. Load st from disk if dir or load whole group file if .stg file (then return just one template). name is fully-qualified. Force a load if it makes sense for the group Make name and alias for target. Replace any previous def of name Compile a template The "foo" of t() ::= "<@foo()>" is mangled to "/region__/t__foo" Return "t.foo" from "/region__/t__foo" Define a map for this group; not thread safe...do not keep adding these while you reference them. Make this group import templates/dictionaries from g. Make this group import templates/dictionaries from g. Import template files, directories, and group files. Priority is given to templates defined in the current group; this, in effect, provides inheritance. Polymorphism is in effect so that if an inherited template references template t() then we search for t() in the subgroup first. Templates are loaded on-demand from import dirs. Imported groups are loaded on-demand when searching for a template. The listener of this group is passed to the import group so errors found while loading imported element are sent to listener of this group. Load a group file with full path fileName; it's relative to root by prefix. Load template file into this group using absolute filename Load template stream into this group. unqualifiedFileName is "a.st". The prefix is path from group root to unqualifiedFileName like /subdir if file is in /subdir/a.st Add an adaptor for a kind of object so Template knows how to pull properties from them. Add adaptors in increasing order of specificity. Template adds Object, Map, and Template model adaptors for you first. Adaptors you Add have priority over default adaptors. If an adaptor for type T already exists, it is replaced by the adaptor arg. This must invalidate cache entries, so set your adaptors up before Render()ing your templates for efficiency. Register a renderer for all objects of a particular "kind" for all templates evaluated relative to this group. Use r to Render if object in question is instanceof(attributeType). Register a renderer for all objects of a particular "kind" for all templates evaluated relative to this group. Use r to Render if object in question is instanceof(attributeType). StringTemplate object factory; each group can have its own. differentiate so we can avoid having creation events for regions, map operations, and other "new ST" events used during interp. Return root dir if this is group dir; return dir containing group file if this is group file. This is derived from original incoming dir or filename. If it was absolute, this should come back as full absolute path. If only a URL is available, return URL of one dir up. A directory or directory tree full of templates and/or group files. We load files on-demand. If we fail to find a file, we look for it via the CLASSPATH as a resource. I track everything with URLs not file names.

Load a template from dir or group file. Group file is given precedence over dir with same name. is always fully qualified.

Load full path name .st file relative to root by prefix The internal representation of a single group file (which must end in ".stg"). If we fail to find a group file, look for it via the CLASSPATH as a resource.

Records how the user "spelled" the file name they wanted to load. The URI is the key field here for loading content. If they use the constructor with a URI argument, this field is .

Where to find the group file; non-null.

Load a file relative to current dir or from root or via CLASSPATH.

Pass in a URL with the location of a group file. E.g., TemplateGroup g = new TemplateGroupFile("file:///org/foo/templates/g.stg", Encoding.UTF8, '<', '>');

This Render knows to perform a few operations on String objects: upper, lower, cap, url-encode, xml-encode. Generic StringTemplate output writer filter. Literals and the elements of expressions are emitted via Write(). Separators are emitted via WriteSeparator() because they must be handled specially when wrapping lines (we don't want to wrap in between an element and it's separator). Return the absolute char index into the output of the char we're about to Write. Returns 0 if no char written yet. Write the string and return how many actual chars were written. With autoindentation and wrapping, more chars than length(str) can be emitted. No wrapping is done. Same as Write, but wrap lines using the indicated string as the wrap character (such as "\n"). Because we evaluate Template instance by invoking exec() again, we can't pass options in. So the WRITE instruction of an applied template (such as when we wrap in between template applications like <data:{v|[<v>]}; wrap>) we need to Write the wrap string before calling exec(). We expose just like for the separator. See Interpreter.WriteObject where it checks for Template instance. If POJO, WritePlainObject passes wrap to ITemplateWriter's Write(String str, String wrap) method. Can't pass to exec(). Write a separator. Same as Write() except that a \n cannot be inserted before emitting a separator.