Here's a single model, where both formatters and predicates work on sections and substitutions. This model is nice because it can do many things:
1) Prove that this is a specification error. http://code.google.com/p/json-template/issues/detail?id=21 . Right now substituting null's raises an UndefinedVariable, which isn't right. 2) Explains why sections can have formatters (they can't now, only substitutions can) 3) Explain why predicates can be applied to *both* sections and substitions, and why formatters can't be overloaded as predicates. 4) Explain why formatters can be chained but predicates can't, e.g. {foo|formatter1|formatter2} Definitions: A JSON value is as the standard says: null, true, false, number, string, list, object. A string is a special case of a JSON value. A substitution identifies a single name that may or may not be expanded into the output. A directive is a literal, substitution, or a section. A section identifies a sequence of directives that may or may not be expanded into the output. The *value* of a substitution is the value from the data dictionary with the corresponding name. Any dictionary node is a JSON value, hence the substitution's value is a JSON value. The *value* of a section is the value of the sequence of directives it contains, concatenated. This definition is recursive since sections can contain sections. The value of each directive must be a string, since only strings can be concatenated. Formatters are functions from an *arbitrary* JSON value -> JSON value (null is included in both domain and range!). This implies they can be chained. And it also implies that they may modify any other value. Any output can be replaced by applying the formatter to the output. (notice I make NO specific reference to either sections or substitutions, it's consistent!) (The default formatter is "str", which is the identity function on strings) Predicates are functions from arbitary JSON values to -> booleans (which are also a special case of JSON values). Predicates *decide* whether a value should be shown. (I also don't need to make any reference to sections or substitutions here). (The default predicate is like bool() in Python, which maps null, false, "", [], {} --> false, and everything else to true. This is how sections and repeated sections currently decide to expand the {.or} section) So then we have 2x2=4 combinations: {name|html} {.section program|html} if (n < 3 && m > 4) ... {.end} {num|plural?} -- shown iff Plural(num) is true {.section group|plural?} There are {num} people in group {name} {.or} There is one person in group {name} {.end} So they are orthogonal, and this implementation will be very clean, without special cases. Since sections can appear inside sections, conceptually there will be a stack of formatters. But all the implementations are recursive interpreters, so this stack will can just be the host language stack. I thought of this this morning, so there could be holes, but it looks very sound to me. It cleans up some specification errors, and there's an algebra of values and formatters. And it solves practical problems too! Andy On Fri, Jun 19, 2009 at 12:45 AM, Andy Chu<[email protected]> wrote: > I was talking with a co-worker today at lunch, and found this nice use > case. This is extremely annoying for our tech-writers: > > <pre> > if (n < 3 && m > 3) { > var s = "foo"; > } > </pre> > > The problem is escaping <>& in code, especially when having to go back > and edit it. It's very error prone. A very nice use of formatters > is: > > {.section snippet|html} > if (n < 3 && m > 3) { > var s = {s|js-string}; # I can also format a javascript string > here, and THEN escape it as HTML too! > } > {.end} > > > Here is another very nice use from my documentation: > > {.section template|json-template-code} # syntax highlight as JSON Template > {.end} > > {.section data-dictionary|json} # syntax highlight JSON dict > {.end} > > {.section result|html} # syntax highlight the expanded result as HTML > {.end} > > I use this all in the same doc. If you look at the scheme I use to > generate my docs docs, it's actually a bit awkward now: > > http://code.google.com/p/json-template/source/browse/#svn/trunk/doc > > > Generate a graph image inside an HTML doc: > > [.section graph|dot-format] > digraph { > ... > [variables] [here] [too] # expansion occurs before dot-format > } > [.end] > > The formatter could render the .dot file as an image graph, and then > return an <img src="rendered.png">. > > I have seen people do this type of thing with Javascript (including > google-code-prettify, which is used on code.google.com). However, > it's a lot faster to render if it's done on the server side (and > cacheable, etc.). > > Currently, you could do this with a static JSON file, but this is annoying: > > {"data-dictionary": "{\"name\": \"value\"}" > "template": "..." > "result": "<a href=\"...\"", > } > > So I think this feature is quite simple to implement, general, and > consistent with the rest of JSON Template. Also, I don't think other > template engines solve this problem. This would be a really nice > feature which would make JSON Template stand out in the (large) crowd. > People generally evaluate technologies by features, and unfortunately > minimalism is not considered a feature. Especially if there was an > add-on library of all these formatters, I could see it becoming quite > popular. > > Andy > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "JSON Template" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/json-template?hl=en -~----------~----~----~----~------~----~------~--~---
