azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

removed the old experiments for templating; so we now just create a StringTemplate object that can be converted to html or used with JDBC queries/statements etc

Browse Source
This commit is contained in:
James Strachan
2012-03-14 16:00:11 +00:00
parent 34c4808c76
commit e2d85427ce
15 changed files with 100 additions and 600 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/src/kotlin/template/ReadMe.md
-76
View File
@@ -1,76 +0,0 @@
## Warning experimental APIs
This package contains a couple of alternative experimental implementations of string templates.
These are not yet integrated into the language, but are here to compare implementation details,
suitability, code size, complexity and efficiency.
### Aims
* make it easy to generate various kinds of output such as text, text with internationalisation, HTML/XML, JSON, URL/URLs or make JDBC calls while reusing the same language templates with $ expressions
### Issues
* how many objects are created per call?
* how extensible & easy to reuse the concept of String Templates in other library features
* pass context into the template somehow; so that formatting options (Locales, nullText, JDBC Connection, converters or whatnot) can be customized
* avoid where possible lots of "if (value is SomeType)" runtime checks to determine what encoding strategy should be used
#### experiment1
Here we convert a string template into a function on some kind of builder object where we invoke the text() method for static text and expression() for dynamic expressions
* [example](https://github.com/JetBrains/kotlin/blob/master/libraries/testlib/test/template/experiment1/HtmlTemplateTest.kt#L17)
Pro:
* simple and efficient code is generated - no arrays
* no arrays are created for static and expression arguments
* static dispatch of encoding functions; no runtime instanceof checks on each argument
Cons:
* function may create an inner object/class (though the compiler may get smart enough to inline some of those - or maybe generate a custom function for the whole thing with parameters?)
* we can only use this strategy if the template expression is passed to a function and we can detect the function parameter takes a fn: (T) -> Unit; and T has suitable text() and expression() methods.
(We can use extension methods to allow regular builder-like classes such as java.lang.StringBuilder to be used to minimise redundant object creation) - so the code generation is a bit more complex
#### experiment2
Here we create a single StringTemplate object containing the constant text array and the values array. Then we use functions or extension functions as ways to do other things.
* [example](https://github.com/JetBrains/kotlin/blob/master/libraries/testlib/test/template/experiment2/HtmlTemplateTest.kt#L13)
Pros:
* really simple
* no real compiler magic required where the type depends on the context
Cons:
* requires runtime [instanceof checks](https://github.com/JetBrains/kotlin/blob/master/libraries/stdlib/src/kotlin/template/experiment2/Templates.kt#L66) on each expression value
* fair bit of object construction per call (2 arrays, a template object, then the string builder and lots of index lookup of arrays
#### experiment 3
The idea is we create a FooTemplate object with the static constant strings inside; so we can easily cache the immutable stuff on startup. Then we basically use pseudo code like
val template = StringTemplate("some ", " static ", "text")
...
val builder = template.builder()
builder.expression(foo)
builder.expression(bar)
val answer = builder.build()
Then based on the context - e.g. an annotation or a method parameter type or something; we determine which kind of template to create (StringTemplate, HtmlTemplate, JdbcTemplate etc)
Pros:
* fairly simple
Cons:
* quite a few different types (FooTemplate and FooBuilder)
* no way to pass in parameters to the FooBuilder class; for example the JDBC connection, or the Locale / NumberFormats to use for numeric formatting etc
* requires runtime instanceof checks on each expression value & array access etc
libraries/stdlib/src/kotlin/template/experiment2/Templates.kt → libraries/stdlib/src/kotlin/template/Templates.kt
+43 -33
View File
@@ -1,47 +1,57 @@
package kotlin.template.experiment2
package kotlin.template
import kotlin.dom.*
import org.w3c.dom.Node
import com.sun.org.apache.xalan.internal.xsltc.dom.UnionIterator
// TODO this class should move into the runtime
// in jet.StringTemplate
class StringTemplate(val values: Array<Any?>) {
/**
* Creates a string template from some constant string expressions and some dynamic expressions.
*/
class StringTemplate(val constantText : Array<String>, val expressions : Array<Any?>) {
/**
* Converts the given string template to a String
*/
fun toString(): String = toString(ToStringFormatter)
fun toString(formatter : ValueFormatter): String {
val buffer = StringBuilder()
append(buffer, formatter)
return buffer.toString() ?: ""
fun toString(): String {
val out = StringBuilder()
forEach{ out.append(it) }
return out.toString() ?: ""
}
fun append(buffer: Appendable, formatter: ValueFormatter): Unit {
val expressionSize = expressions.size
for (i in 0.upto(constantText.size - 1)) {
buffer.append(constantText[i])
if (i < expressionSize) {
val value = expressions[i]
formatter.format(buffer, value)
}
/**
* Performs the given function on each value in the collection
*/
fun forEach(fn: (Any?) -> Unit): Unit {
for (v in values) {
fn(v)
}
}
/**
* Converts the given template to HTML with an optional formatter
*/
fun toHtml(formatter: HtmlFormatter = HtmlFormatter()): String = toString(formatter)
/**
* Appends the HTML representation of this template to the given appendable
*/
fun appendHtml(buffer: Appendable, formatter: HtmlFormatter = HtmlFormatter()): String = toString(formatter)
}
fun StringTemplate.toString(formatter : ValueFormatter): String {
val buffer = StringBuilder()
append(buffer, formatter)
return buffer.toString() ?: ""
}
fun StringTemplate.append(out: Appendable, formatter: ValueFormatter): Unit {
var constantText = true
this.forEach {
if (constantText) {
if (it == null) {
throw IllegalStateException("No constant checks should be null");
} else {
val text = it.toString()
if (text != null) {
out.append(text)
}
}
} else {
formatter.format(out, it)
}
constantText = !constantText
}
}
fun StringTemplate.toHtml(formatter : HtmlFormatter = HtmlFormatter()): String = toString(formatter)
/**
* Represents a formatter of values in a [[StringTemplate]] which understands how to escape
* different types for different kinds of language
libraries/stdlib/src/kotlin/template/experiment1/Templates.kt
-155
View File
@@ -1,155 +0,0 @@
package kotlin.template.experiment1
import org.w3c.dom.Node
import kotlin.dom.toXmlString
import java.lang.Number
import java.text.DateFormat
import java.text.NumberFormat
import java.util.Date
import java.util.Locale
fun StringBuilder.text(value : String) : Unit {
this.append(value)
}
fun StringBuilder.expression(value : Any?) : Unit {
this.append(value)
}
/**
* Converts a [[StringTemplate]] to a String
*/
// TODO tried toString() but compiler error kicks in
fun format(fn : (StringBuilder) -> Unit) : String {
val builder = StringBuilder()
fn(builder)
return builder.toString() ?: ""
}
abstract class TextBuilder(val output : Appendable) {
/*
*/
/**
* Converts the given string template to a String
fun toString(fn: (T) -> Unit): String = toString(ToStringFormatter, fn)
fun toString(formatter : ValueFormatter, fn: (T) -> Unit): String {
fn(this)
return output.toString() ?: ""
}
*/
fun text(value : String) : Unit {
output.append(value)
}
}
open class I18nBuilder(output : Appendable, val formatter : I18nFormatter) : TextBuilder(output) {
fun expression(value : Any?) : Unit {
escape(formatter.format(value))
}
fun expression(value : Number) : Unit {
escape(formatter.formatNumber(value))
}
fun expression(value : Date) : Unit {
escape(formatter.formatDate(value))
}
/**
* By default does no escaping but inherited classes may escape text
*/
open fun escape(text : String) : Unit {
output.append(text)
}
}
open class HtmlBuilder(output : Appendable, formatter : I18nFormatter) : I18nBuilder(output, formatter) {
/**
* Nodes are assumed to already be properly HTML/XML encoded so don't escape
*/
fun expression(value : Node) : Unit {
text(value.toXmlString())
}
/**
* Escapes text using HTML escaping of sensitive tokens
*/
override fun escape(text : String) : Unit {
for (c in text) {
if (c == '<') output.append("&lt;")
else if (c == '>') output.append("&gt;")
else if (c == '&') output.append("&amp;")
else if (c == '"') output.append("&quot;")
else output.append(c)
}
}
}
/**
* Represents a formatter of values in a [[StringTemplate]] which understands how to escape
* different types for different kinds of language
*/
trait ValueFormatter {
fun format(val value : Any?) : String
}
open class ToStringFormatter : ValueFormatter {
var nullText : String = "null"
open fun toString() = "ToStringFormatter"
override fun format(value : Any?): String {
return if (value == null) nullText else value.toString()
}
}
open class I18nFormatter(val locale : Locale = Locale.getDefault().sure()): ToStringFormatter() {
override fun toString() = "I18nFormatter"
public var numberFormat : NumberFormat = NumberFormat.getInstance(locale).sure()
public var dateFormat : DateFormat = DateFormat.getDateTimeInstance(DateFormat.DEFAULT, DateFormat.DEFAULT, locale).sure()
fun formatNumber(number : Number): String {
return numberFormat.format(number) ?: ""
}
fun formatDate(date : Date): String {
return dateFormat.format(date) ?: ""
}
/**
* Generates the internationalised text for this formatter
*/
fun toString(fn : (I18nBuilder) -> Unit) : String {
val buffer = StringBuilder()
val builder = I18nBuilder(buffer, this)
fn(builder)
return buffer.toString() ?: ""
}
/**
* Generates the HTML for the given function
*/
fun toHtml(fn : (HtmlBuilder) -> Unit) : String {
val buffer = StringBuilder()
val html = HtmlBuilder(buffer, this)
fn(html)
return buffer.toString() ?: ""
}
}
libraries/stdlib/src/kotlin/template/experiment3/HtmlTemplate.kt
-64
View File
@@ -1,64 +0,0 @@
package kotlin.template.experiment3
import kotlin.dom.toXmlString
import org.w3c.dom.Node
/**
* Creates a string template from a string with $ expressions inside using HTML escaping of expressions.
*/
// TODO varargs on constructors seems to fail
//class HtmlTemplate(vararg val text: String) {
class HtmlTemplate(val constantText : Array<String>) {
/**
* Creates a builder of string expressions which use HTML encoding on expressions
*/
fun builder() : HtmlTemplateBuilder {
// TODO we should allow the caller to pass these in when we create the builder!
val options = HtmlTemplateOptions()
return HtmlTemplateBuilder(constantText, options)
}
}
class HtmlTemplateOptions() {
var nullText : String = ""
}
open class HtmlTemplateBuilder(constantText : Array<String>, val options : HtmlTemplateOptions) : StringTemplateBuilder(constantText) {
override fun expression(expression : Any) : Unit {
val text = if (expression != null) expression.toString() ?: "" else options.nullText
escape(text)
}
/**
* Appends the DOM node, no HTML escaping is done as we assume its already escaped
*/
fun expression(node : Node) : Unit {
// no need to escape
unescape(node.toXmlString(false))
}
/**
* Appends the given text escaped properly
*/
fun escape(text : String): Unit {
appendNextConstant()
for (c in text) {
if (c == '<') buffer.append("&lt;")
else if (c == '>') buffer.append("&gt;")
else if (c == '&') buffer.append("&amp;")
else if (c == '"') buffer.append("&quot;")
else buffer.append(c)
}
}
/**
* Appends the unescaped text
*/
fun unescape(text : String) {
appendNextConstant()
buffer.append(text)
}
}
libraries/stdlib/src/kotlin/template/experiment3/StringTemplate.kt
-44
View File
@@ -1,44 +0,0 @@
package kotlin.template.experiment3
/**
* Creates a string template from a string with $ expressions inside.
*/
// TODO varargs on constructors seems to fail
//class StringTemplate(vararg val text: String) {
open class StringTemplate(val constantText : Array<String>) {
/**
* Creates a builder of string expressions
*/
open fun builder() : StringTemplateBuilder = StringTemplateBuilder(constantText)
}
/**
* Used to build strings using expressions
*/
open class StringTemplateBuilder(val constantText : Array<String>){
protected val buffer: StringBuilder = StringBuilder()
var index : Int = 0
fun build() : String {
while (appendNextConstant()) {}
return buffer.toString() ?: ""
}
open fun expression(expression : Any) {
appendNextConstant()
buffer.append(expression)
}
/**
* Returns the next static text value from the template
*/
protected fun appendNextConstant(): Boolean {
if (index < constantText.size) {
buffer.append(constantText[index++])
return true
} else {
return false
}
}
}