├── .gitignore ├── .gitmodules ├── .travis.yml ├── LICENSE ├── README.md ├── bin └── build-soyutils.sh ├── dev └── user.clj ├── project.clj ├── resources └── soy-clj │ └── soyutils.js ├── src └── soy_clj │ └── core.clj └── test ├── example.js ├── example.soy ├── other-example.soy └── soy_clj ├── bench_test.clj └── core_test.clj /.gitignore: -------------------------------------------------------------------------------- 1 | /target 2 | /classes 3 | /checkouts 4 | pom.xml 5 | pom.xml.asc 6 | *.jar 7 | *.class 8 | /.lein-* 9 | /.nrepl-port 10 | .hgignore 11 | .hg/ 12 | node_modules 13 | deps 14 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/codahale/soy-clj/f6249512de7fc3943d522ad5a96ecd80f1145faa/.gitmodules -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | language: clojure 3 | jdk: 4 | - oraclejdk8 5 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC 2 | LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM 3 | CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. 4 | 5 | 1. DEFINITIONS 6 | 7 | "Contribution" means: 8 | 9 | a) in the case of the initial Contributor, the initial code and 10 | documentation distributed under this Agreement, and 11 | 12 | b) in the case of each subsequent Contributor: 13 | 14 | i) changes to the Program, and 15 | 16 | ii) additions to the Program; 17 | 18 | where such changes and/or additions to the Program originate from and are 19 | distributed by that particular Contributor. A Contribution 'originates' from 20 | a Contributor if it was added to the Program by such Contributor itself or 21 | anyone acting on such Contributor's behalf. Contributions do not include 22 | additions to the Program which: (i) are separate modules of software 23 | distributed in conjunction with the Program under their own license 24 | agreement, and (ii) are not derivative works of the Program. 25 | 26 | "Contributor" means any person or entity that distributes the Program. 27 | 28 | "Licensed Patents" mean patent claims licensable by a Contributor which are 29 | necessarily infringed by the use or sale of its Contribution alone or when 30 | combined with the Program. 31 | 32 | "Program" means the Contributions distributed in accordance with this 33 | Agreement. 34 | 35 | "Recipient" means anyone who receives the Program under this Agreement, 36 | including all Contributors. 37 | 38 | 2. GRANT OF RIGHTS 39 | 40 | a) Subject to the terms of this Agreement, each Contributor hereby grants 41 | Recipient a non-exclusive, worldwide, royalty-free copyright license to 42 | reproduce, prepare derivative works of, publicly display, publicly perform, 43 | distribute and sublicense the Contribution of such Contributor, if any, and 44 | such derivative works, in source code and object code form. 45 | 46 | b) Subject to the terms of this Agreement, each Contributor hereby grants 47 | Recipient a non-exclusive, worldwide, royalty-free patent license under 48 | Licensed Patents to make, use, sell, offer to sell, import and otherwise 49 | transfer the Contribution of such Contributor, if any, in source code and 50 | object code form. This patent license shall apply to the combination of the 51 | Contribution and the Program if, at the time the Contribution is added by the 52 | Contributor, such addition of the Contribution causes such combination to be 53 | covered by the Licensed Patents. The patent license shall not apply to any 54 | other combinations which include the Contribution. No hardware per se is 55 | licensed hereunder. 56 | 57 | c) Recipient understands that although each Contributor grants the licenses 58 | to its Contributions set forth herein, no assurances are provided by any 59 | Contributor that the Program does not infringe the patent or other 60 | intellectual property rights of any other entity. Each Contributor disclaims 61 | any liability to Recipient for claims brought by any other entity based on 62 | infringement of intellectual property rights or otherwise. As a condition to 63 | exercising the rights and licenses granted hereunder, each Recipient hereby 64 | assumes sole responsibility to secure any other intellectual property rights 65 | needed, if any. For example, if a third party patent license is required to 66 | allow Recipient to distribute the Program, it is Recipient's responsibility 67 | to acquire that license before distributing the Program. 68 | 69 | d) Each Contributor represents that to its knowledge it has sufficient 70 | copyright rights in its Contribution, if any, to grant the copyright license 71 | set forth in this Agreement. 72 | 73 | 3. REQUIREMENTS 74 | 75 | A Contributor may choose to distribute the Program in object code form under 76 | its own license agreement, provided that: 77 | 78 | a) it complies with the terms and conditions of this Agreement; and 79 | 80 | b) its license agreement: 81 | 82 | i) effectively disclaims on behalf of all Contributors all warranties and 83 | conditions, express and implied, including warranties or conditions of title 84 | and non-infringement, and implied warranties or conditions of merchantability 85 | and fitness for a particular purpose; 86 | 87 | ii) effectively excludes on behalf of all Contributors all liability for 88 | damages, including direct, indirect, special, incidental and consequential 89 | damages, such as lost profits; 90 | 91 | iii) states that any provisions which differ from this Agreement are offered 92 | by that Contributor alone and not by any other party; and 93 | 94 | iv) states that source code for the Program is available from such 95 | Contributor, and informs licensees how to obtain it in a reasonable manner on 96 | or through a medium customarily used for software exchange. 97 | 98 | When the Program is made available in source code form: 99 | 100 | a) it must be made available under this Agreement; and 101 | 102 | b) a copy of this Agreement must be included with each copy of the Program. 103 | 104 | Contributors may not remove or alter any copyright notices contained within 105 | the Program. 106 | 107 | Each Contributor must identify itself as the originator of its Contribution, 108 | if any, in a manner that reasonably allows subsequent Recipients to identify 109 | the originator of the Contribution. 110 | 111 | 4. COMMERCIAL DISTRIBUTION 112 | 113 | Commercial distributors of software may accept certain responsibilities with 114 | respect to end users, business partners and the like. While this license is 115 | intended to facilitate the commercial use of the Program, the Contributor who 116 | includes the Program in a commercial product offering should do so in a 117 | manner which does not create potential liability for other Contributors. 118 | Therefore, if a Contributor includes the Program in a commercial product 119 | offering, such Contributor ("Commercial Contributor") hereby agrees to defend 120 | and indemnify every other Contributor ("Indemnified Contributor") against any 121 | losses, damages and costs (collectively "Losses") arising from claims, 122 | lawsuits and other legal actions brought by a third party against the 123 | Indemnified Contributor to the extent caused by the acts or omissions of such 124 | Commercial Contributor in connection with its distribution of the Program in 125 | a commercial product offering. The obligations in this section do not apply 126 | to any claims or Losses relating to any actual or alleged intellectual 127 | property infringement. In order to qualify, an Indemnified Contributor must: 128 | a) promptly notify the Commercial Contributor in writing of such claim, and 129 | b) allow the Commercial Contributor tocontrol, and cooperate with the 130 | Commercial Contributor in, the defense and any related settlement 131 | negotiations. The Indemnified Contributor may participate in any such claim 132 | at its own expense. 133 | 134 | For example, a Contributor might include the Program in a commercial product 135 | offering, Product X. That Contributor is then a Commercial Contributor. If 136 | that Commercial Contributor then makes performance claims, or offers 137 | warranties related to Product X, those performance claims and warranties are 138 | such Commercial Contributor's responsibility alone. Under this section, the 139 | Commercial Contributor would have to defend claims against the other 140 | Contributors related to those performance claims and warranties, and if a 141 | court requires any other Contributor to pay any damages as a result, the 142 | Commercial Contributor must pay those damages. 143 | 144 | 5. NO WARRANTY 145 | 146 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON 147 | AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER 148 | EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR 149 | CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A 150 | PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the 151 | appropriateness of using and distributing the Program and assumes all risks 152 | associated with its exercise of rights under this Agreement , including but 153 | not limited to the risks and costs of program errors, compliance with 154 | applicable laws, damage to or loss of data, programs or equipment, and 155 | unavailability or interruption of operations. 156 | 157 | 6. DISCLAIMER OF LIABILITY 158 | 159 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY 160 | CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, 161 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION 162 | LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 163 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 164 | ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE 165 | EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY 166 | OF SUCH DAMAGES. 167 | 168 | 7. GENERAL 169 | 170 | If any provision of this Agreement is invalid or unenforceable under 171 | applicable law, it shall not affect the validity or enforceability of the 172 | remainder of the terms of this Agreement, and without further action by the 173 | parties hereto, such provision shall be reformed to the minimum extent 174 | necessary to make such provision valid and enforceable. 175 | 176 | If Recipient institutes patent litigation against any entity (including a 177 | cross-claim or counterclaim in a lawsuit) alleging that the Program itself 178 | (excluding combinations of the Program with other software or hardware) 179 | infringes such Recipient's patent(s), then such Recipient's rights granted 180 | under Section 2(b) shall terminate as of the date such litigation is filed. 181 | 182 | All Recipient's rights under this Agreement shall terminate if it fails to 183 | comply with any of the material terms or conditions of this Agreement and 184 | does not cure such failure in a reasonable period of time after becoming 185 | aware of such noncompliance. If all Recipient's rights under this Agreement 186 | terminate, Recipient agrees to cease use and distribution of the Program as 187 | soon as reasonably practicable. However, Recipient's obligations under this 188 | Agreement and any licenses granted by Recipient relating to the Program shall 189 | continue and survive. 190 | 191 | Everyone is permitted to copy and distribute copies of this Agreement, but in 192 | order to avoid inconsistency the Agreement is copyrighted and may only be 193 | modified in the following manner. The Agreement Steward reserves the right to 194 | publish new versions (including revisions) of this Agreement from time to 195 | time. No one other than the Agreement Steward has the right to modify this 196 | Agreement. The Eclipse Foundation is the initial Agreement Steward. The 197 | Eclipse Foundation may assign the responsibility to serve as the Agreement 198 | Steward to a suitable separate entity. Each new version of the Agreement will 199 | be given a distinguishing version number. The Program (including 200 | Contributions) may always be distributed subject to the version of the 201 | Agreement under which it was received. In addition, after a new version of 202 | the Agreement is published, Contributor may elect to distribute the Program 203 | (including its Contributions) under the new version. Except as expressly 204 | stated in Sections 2(a) and 2(b) above, Recipient receives no rights or 205 | licenses to the intellectual property of any Contributor under this 206 | Agreement, whether expressly, by implication, estoppel or otherwise. All 207 | rights in the Program not expressly granted under this Agreement are 208 | reserved. 209 | 210 | This Agreement is governed by the laws of the State of New York and the 211 | intellectual property laws of the United States of America. No party to this 212 | Agreement will bring a legal action under this Agreement more than one year 213 | after the cause of action arose. Each party waives its rights to a jury trial 214 | in any resulting litigation. 215 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # soy-clj 2 | 3 | ![Build Status](https://travis-ci.org/codahale/soy-clj.svg) 4 | 5 | An idiomatic Clojure wrapper for [Google's Closure templating system](https://developers.google.com/closure/templates/). 6 | 7 | ## What's A Google Closure Template? 8 | 9 | > Closure Templates are a client- and server-side templating system that helps 10 | > you dynamically build reusable HTML and UI elements. They have a simple syntax 11 | > that is natural for programmers, and you can customize them to fit your 12 | > application's needs. In contrast to traditional templating systems,in which 13 | > you must create one monolithic template per page, you can think of Closure 14 | > Templates as small components that you compose to form your user 15 | > interface. You can also use the built-in message support to easily localize 16 | > your applications. 17 | 18 | An example of what a Closure template looks like 19 | [can be found here](https://github.com/codahale/soy-clj/blob/master/test/example.soy). 20 | 21 | ### Security 22 | 23 | In addition, variables in Closure Templates are contextually escaped to almost 24 | entirely prevent XSS attacks. For example, consider the following template 25 | snippet: 26 | 27 | ```html 28 | {$name} 29 | ``` 30 | 31 | The first use of `name` is as a Javascript string inside a HTML attribute; the 32 | second use is as the content of an HTML element. These two contexts have very 33 | different syntactic requirements, which is what makes preventing XSS attacks so 34 | hard. 35 | 36 | An attacker, seeing this contextual nesting, could rename her profile to 37 | something like `', alert('XSS'), '`. A naive templating system will auto-escape 38 | everything as if it's the content of an HTML element: 39 | 40 | ```html 41 | ', alert('XSS'), ' 42 | ``` 43 | 44 | Because the browser parses HTML entities *before* parsing the Javascript, 45 | though, this is structurally equivalent to the following: 46 | 47 | ```html 48 | ', alert('XSS'), ' 49 | ``` 50 | 51 | The attacker, then, can run arbitrary Javascript when someone clicks that link. 52 | 53 | Closure templates, on the other hand, will automatically escape based on the 54 | context of the variable usage: 55 | 56 | ```html 57 | ', alert('XSS'), ' 58 | ``` 59 | 60 | This allows developers to nest CSS in Javascript in HTML in Javascript (etc. 61 | etc.) without needing to keep track of the context-specific syntax rules and 62 | their interaction effects. For more information on the security model behind 63 | Closure templates, 64 | [read this](http://js-quasis-libraries-and-repl.googlecode.com/svn/trunk/safetemplate.html). 65 | 66 | `soy-clj` is hard-coded to only render strictly-escaped templates. If you 67 | _absolutely_ must poke a hole in that, use the `ordain-as-safe` function to 68 | ordain bits of content as safe in a given context. 69 | 70 | If you have user input which must support some HTML markup for formatting 71 | purposes, use the `clean-html` function to pass all HTML tags through a strict 72 | whitelist. 73 | 74 | ### Performance 75 | 76 | Google Closure templates are compiled to actual bytecode, making them incredibly 77 | fast. Rendering a list of 1000 elements, for example, takes ~450µs on a laptop. 78 | A simple template with a single variable takes ~4µs. To reproduce this, run any 79 | of the [criterium](https://github.com/hugoduncan/criterium) benchmarks in 80 | `soy-clj/bench-test` or run `lein bench` on the command line. 81 | 82 | `soy-clj` uses Guava to cache compiled templates. By default it will cache every 83 | template for the lifetime of the process, which makes for fast rendering in 84 | production environments. For development environments, the cache can be disabled 85 | so that templates are recompiled on every request: 86 | 87 | ```clojure 88 | (soy-clj.core/set-cache-options! {:disabled? true}) 89 | ``` 90 | 91 | More information on Guava cache parameters can be found [here](https://google.github.io/guava/releases/21.0/api/docs/com/google/common/cache/CacheBuilder.html). 92 | 93 | Parsing and compiling templates takes 10-100ms, which makes using live templates 94 | in development relatively painless. 95 | 96 | To avoid a slow load on the first request, applications can pre-parse template 97 | files on startup: 98 | 99 | ```clojure 100 | ;;; preload templates 101 | (soy-clj.core/parse "main.soy") 102 | (soy-clj.core/parse "marketing.soy") 103 | ``` 104 | 105 | This has the additional benefit of preventing an application with malformed 106 | templates (e.g. a typo) from starting up successfully. 107 | 108 | ### Gotchas 109 | 110 | There are a few quirks of working with Google Closure templates. 111 | 112 | #### Curly Brackets 113 | 114 | Curly brackets (i.e. `{` and `}`) are used _exclusively_ for template directives 115 | (e.g. `{$name}` or `{if}`). If you need to use a curly bracket in your template, 116 | use the `{lb}` or `{rb}` directives. 117 | 118 | You can also enclose parts of your template with the `{literal}` directive: 119 | 120 | ```html 121 | 129 | ``` 130 | 131 | #### Whitespace 132 | 133 | Google Closure templates normalizes template text with something it calls 134 | [line joining](https://developers.google.com/closure/templates/docs/concepts#linejoining). 135 | You may notice this when it removes whitespace in your template that is 136 | semantically meaningful (e.g. the space in `foo bar`). You can add 137 | explicit whitespace using the `{sp}` directive: 138 | 139 | ```html 140 | foo{sp}bar 141 | ``` 142 | 143 | ## Usage 144 | 145 | ```clojure 146 | (require '[soy-clj.core :as soy]) 147 | 148 | ;;; compile a set of template files to Javascript 149 | (def js (soy/compile-to-js ["marketing.soy" "main.soy"])) 150 | 151 | ;;; parse a set of template files from ./resources 152 | (def web-templates (soy/parse ["marketing.soy" "main.soy"])) 153 | 154 | ;;; render a template 155 | (let [[content kind] (soy/render web-templates 156 | "com.example.marketing.newSplash" 157 | {:title "Hello World" 158 | :good-stuff ["Puppies" "Kitties"]})] 159 | (prn content) ; the rendered template as a string 160 | (prn kind) ; a symbol indicating the template's type (e.g. :html, :js, etc) 161 | 162 | ;; the MIME content type of the kind of template 163 | (prn (soy/content-type kind))) 164 | ``` 165 | 166 | ## License 167 | 168 | Copyright © 2015-2016 Coda Hale 169 | 170 | Distributed under the Eclipse Public License either version 1.0 or (at your 171 | option) any later version. 172 | -------------------------------------------------------------------------------- /bin/build-soyutils.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | rm -rf resources/soy-clj 3 | mkdir -p resources/soy-clj 4 | closure-compiler \ 5 | --js_output_file resources/soy-clj/soyutils.js \ 6 | --js deps/closure-library/closure/goog/base.js \ 7 | --js deps/closure-library/closure/goog/fs/url.js \ 8 | --js deps/closure-library/closure/goog/dom/nodetype.js \ 9 | --js deps/closure-library/closure/goog/debug/error.js \ 10 | --js deps/closure-library/closure/goog/string/string.js \ 11 | --js deps/closure-library/closure/goog/asserts/asserts.js \ 12 | --js deps/closure-library/closure/goog/string/typedstring.js \ 13 | --js deps/closure-library/closure/goog/string/const.js \ 14 | --js deps/closure-library/closure/goog/i18n/bidi.js \ 15 | --js deps/closure-library/closure/goog/html/safeurl.js \ 16 | --js deps/closure-library/closure/goog/array/array.js \ 17 | --js deps/closure-library/closure/goog/html/safestyle.js \ 18 | --js deps/closure-library/closure/goog/html/safescript.js \ 19 | --js deps/closure-library/closure/goog/html/trustedresourceurl.js \ 20 | --js deps/closure-library/closure/goog/html/safestylesheet.js \ 21 | --js deps/closure-library/closure/goog/object/object.js \ 22 | --js deps/closure-library/closure/goog/dom/tags.js \ 23 | --js deps/closure-library/closure/goog/dom/tagname.js \ 24 | --js deps/closure-library/closure/goog/labs/useragent/util.js \ 25 | --js deps/closure-library/closure/goog/labs/useragent/browser.js \ 26 | --js deps/closure-library/closure/goog/html/safehtml.js \ 27 | --js deps/closure-library/closure/goog/html/uncheckedconversions.js \ 28 | --js deps/closure-library/closure/goog/uri/utils.js \ 29 | --js deps/closure-library/closure/goog/uri/uri.js \ 30 | --js deps/closure-library/closure/goog/soy/data.js \ 31 | --js deps/closure-library/closure/goog/html/legacyconversions.js \ 32 | --js deps/closure-library/closure/goog/labs/useragent/platform.js \ 33 | --js deps/closure-library/closure/goog/labs/useragent/engine.js \ 34 | --js deps/closure-library/closure/goog/reflect/reflect.js \ 35 | --js deps/closure-library/closure/goog/useragent/useragent.js \ 36 | --js deps/closure-library/closure/goog/math/size.js \ 37 | --js deps/closure-library/closure/goog/dom/safe.js \ 38 | --js deps/closure-library/closure/goog/dom/browserfeature.js \ 39 | --js deps/closure-library/closure/goog/math/math.js \ 40 | --js deps/closure-library/closure/goog/math/coordinate.js \ 41 | --js deps/closure-library/closure/goog/dom/dom.js \ 42 | --js deps/closure-library/closure/goog/soy/soy.js \ 43 | --js deps/closure-library/closure/goog/string/stringbuffer.js \ 44 | --js deps/closure-library/closure/goog/structs/inversionmap.js \ 45 | --js deps/closure-library/closure/goog/i18n/graphemebreak.js \ 46 | --js deps/closure-library/closure/goog/format/format.js \ 47 | --js deps/closure-library/closure/goog/structs/collection.js \ 48 | --js deps/closure-library/closure/goog/structs/structs.js \ 49 | --js deps/closure-library/closure/goog/functions/functions.js \ 50 | --js deps/closure-library/closure/goog/iter/iter.js \ 51 | --js deps/closure-library/closure/goog/structs/map.js \ 52 | --js deps/closure-library/closure/goog/structs/set.js \ 53 | --js deps/closure-library/closure/goog/debug/debug.js \ 54 | --js deps/closure-library/closure/goog/i18n/bidiformatter.js \ 55 | --js deps/closure-templates/javascript/soyutils_usegoog.js 56 | -------------------------------------------------------------------------------- /dev/user.clj: -------------------------------------------------------------------------------- 1 | (ns user) 2 | 3 | (defn start 4 | []) 5 | 6 | (defn stop 7 | []) 8 | -------------------------------------------------------------------------------- /project.clj: -------------------------------------------------------------------------------- 1 | (defproject com.codahale/soy-clj "0.3.4-SNAPSHOT" 2 | :description "An idiomatic Clojure wrapper for Google's Closure templating system." 3 | :url "https://github.com/codahale/soy-clj" 4 | :license {:name "Eclipse Public License" 5 | :url "http://www.eclipse.org/legal/epl-v10.html"} 6 | :dependencies [[com.codahale/guava-cache-clj "0.1.2"] 7 | [com.google.template/soy "2017-02-01" 8 | :exclusions [args4j 9 | com.google.gwt/gwt-user 10 | com.google.guava/guava-testlib 11 | org.json/json 12 | com.google.code.gson/gson]]] 13 | :plugins [] 14 | :test-selectors {:default #(not-any? % [:bench]) 15 | :bench :bench} 16 | :aliases {"bench" ["test" ":bench"]} 17 | :deploy-repositories [["releases" :clojars] 18 | ["snapshots" :clojars]] 19 | :global-vars {*warn-on-reflection* true} 20 | :profiles {:dev [:project/dev :profiles/dev] 21 | :test [:project/test :profiles/test] 22 | :profiles/dev {:dependencies [[org.clojure/clojure "1.8.0"] 23 | [criterium "0.4.4"]]} 24 | :profiles/test {} 25 | :project/dev {:source-paths ["dev"] 26 | :repl-options {:init-ns user}} 27 | :project/test {:dependencies []}}) 28 | -------------------------------------------------------------------------------- /src/soy_clj/core.clj: -------------------------------------------------------------------------------- 1 | (ns soy-clj.core 2 | "An idiomatic Clojure wrapper for Google Closure templates." 3 | (:require [clojure.java.io :as io] 4 | [clojure.set :as set] 5 | [clojure.string :as string] 6 | [clojure.walk :as walk] 7 | [guava-cache-clj.core :as guava-cache]) 8 | (:import (java.net URL) 9 | (com.google.template.soy SoyFileSet SoyFileSet$Builder) 10 | (com.google.template.soy.data SanitizedContent$ContentKind 11 | UnsafeSanitizedContentOrdainer) 12 | (com.google.template.soy.jssrc SoyJsSrcOptions) 13 | (com.google.template.soy.jssrc.restricted JsExpr JsExprUtils) 14 | (com.google.template.soy.shared SoyGeneralOptions) 15 | (com.google.template.soy.shared.restricted Sanitizers 16 | TagWhitelist$OptionalSafeTag) 17 | (com.google.template.soy.tofu SoyTofu))) 18 | 19 | (def ^:private opts 20 | "Default to requiring autoescaped templates." 21 | (doto (SoyGeneralOptions.) 22 | (.setStrictAutoescapingRequired true))) 23 | 24 | (def ^:private js-opts 25 | "Use only the defaults for JS compilation." 26 | (SoyJsSrcOptions.)) 27 | 28 | (def ^:dynamic *builder-fn* 29 | "The function used to create a SoyFileSet$Builder." 30 | #(SoyFileSet/builder)) 31 | 32 | (def ^:dynamic *preprocessor-fn* 33 | "The function used to pre-process the template contents." 34 | identity) 35 | 36 | (defn- add-file 37 | [^SoyFileSet$Builder builder file] 38 | (if-let [res (if (instance? URL file) file (io/resource file))] 39 | (.add builder ^String (*preprocessor-fn* (slurp res)) (str file)) 40 | (throw (IllegalArgumentException. (str "Unable to open " file))))) 41 | 42 | (defn- ^SoyFileSet build 43 | "Builds a file set from the given files." 44 | [files] 45 | (let [^SoyFileSet$Builder builder (*builder-fn*)] 46 | (run! (partial add-file builder) files) 47 | (.setGeneralOptions builder opts) 48 | (.build builder))) 49 | 50 | (def ^:private prelude 51 | "A bit of required JS." 52 | "if(typeof goog == 'undefined') {var goog = {};}") 53 | 54 | (defn- cache-loader 55 | [[kind files]] 56 | (case kind 57 | :js (->> (.compileToJsSrc (build files) js-opts nil) 58 | (cons prelude) 59 | (string/join "\n")) 60 | :tofu (.. (build files) (compileToTofu)))) 61 | 62 | (def ^:private cache 63 | (atom nil)) 64 | 65 | (defn set-cache-options! 66 | "Sets the cache options for parsed templates and compiled JS." 67 | [opts] 68 | (reset! cache (guava-cache/build cache-loader opts))) 69 | 70 | (set-cache-options! {}) 71 | 72 | (defn compile-to-js 73 | "Given the filename (or a sequence of filenames) of a Closure template on the 74 | classpath, parses the templates and returns them as compiled Javascript." 75 | [file-or-files] 76 | (@cache [:js (vec (flatten (vector file-or-files)))])) 77 | 78 | (defn parse 79 | "Given the filename (or a sequence of filenames) of a Closure template on the 80 | classpath, parses the templates and returns them as compiled JVM bytecode." 81 | [file-or-files] 82 | (@cache [:tofu (vec (flatten (vector file-or-files)))])) 83 | 84 | (defn- camel-case 85 | "Converts a symbol like `:blah-blah` into a string like `blahBlah`." 86 | [s] 87 | (let [ss (string/split (name s) #"-")] 88 | (string/join (cons (string/lower-case (first ss)) 89 | (map string/capitalize (next ss)))))) 90 | 91 | (defn- camelize-keys 92 | "Recursively transforms a map, converting all keyword keys into camel-case 93 | strings." 94 | ^java.util.Map [m] 95 | (let [f (fn [[k v]] (if (keyword? k) [(camel-case k) v] [k v]))] 96 | (walk/postwalk (fn [x] (if (map? x) (into {} (map f x)) x)) m))) 97 | 98 | (defn content-type 99 | "The MIME content-type of the given kind." 100 | [kind] 101 | (case kind 102 | :css "text/css; charset=utf-8" 103 | :html "text/html; charset=utf-8" 104 | :js "text/javascript; charset=utf-8" 105 | "text/plain; charset=utf-8")) 106 | 107 | (def ^:private content-kind 108 | "A map of ContentKind enums to happy little symbols." 109 | {SanitizedContent$ContentKind/ATTRIBUTES :attributes 110 | SanitizedContent$ContentKind/CSS :css 111 | SanitizedContent$ContentKind/HTML :html 112 | SanitizedContent$ContentKind/JS :js 113 | SanitizedContent$ContentKind/TEXT :text 114 | SanitizedContent$ContentKind/TRUSTED_RESOURCE_URI :trusted-resource-uri 115 | SanitizedContent$ContentKind/URI :uri}) 116 | 117 | (def ^:private content-kind-enum 118 | "A map of happy little symbols to ContentKind enums." 119 | (set/map-invert content-kind)) 120 | 121 | (defn render 122 | "Given a parsed set of templates, renders the named template with the given 123 | data and returns the result as a string as well as the _kind_ of data in the 124 | template (e.g. `:html`). Data keys of the form `:one-two` are converted into 125 | template variables of the form `oneTwo`. Optionally, an expected kind may be 126 | passed. If none is given, `:html` is assumed." 127 | [^SoyTofu templates ^String template-name data & [kind]] 128 | (let [content (.. templates 129 | (newRenderer template-name) 130 | (setContentKind (content-kind-enum (or kind :html))) 131 | (setData (camelize-keys data)) 132 | (renderStrict))] 133 | [(.getContent content) (content-kind (.getContentKind content))])) 134 | 135 | (defn- safe-str 136 | [content kind] 137 | (UnsafeSanitizedContentOrdainer/ordainAsSafe content (content-kind-enum kind))) 138 | 139 | (defn- safe-jsexpr 140 | [content kind] 141 | (JsExprUtils/maybeWrapAsSanitizedContent (content-kind-enum kind) content)) 142 | 143 | (defn ordain-as-safe 144 | "Ordains the given content as safe content of the given kind which will not be 145 | escaped inside that kind's context. Use this sparingly, as it entirely 146 | bypasses Soy's XSS protection." 147 | [content kind] 148 | (cond 149 | (string? content) (safe-str content kind) 150 | (instance? JsExpr content) (safe-jsexpr content kind) 151 | :else (throw (ex-info "Unrecognized content type" 152 | {:content content :kind kind})))) 153 | 154 | (defn clean-html 155 | "Parses the given string as HTML and removes all tags except for basic 156 | formatting tags: ``, `
`, ``, ``, ``, ``, ``, 157 | ``. Additionally, the use of `
    `, `
      `, `
    1. `, and `` can be 158 | enabled by passing the symbols `:ul` etc. as additional arguments." 159 | [^String s & safe-tags] 160 | (Sanitizers/cleanHtml s ^java.util.Collection 161 | (vec (map #(TagWhitelist$OptionalSafeTag/fromTagName 162 | (name %)) safe-tags)))) 163 | -------------------------------------------------------------------------------- /test/example.js: -------------------------------------------------------------------------------- 1 | if(typeof goog == 'undefined') {var goog = {};} 2 | // This file was automatically generated from example.soy. 3 | // Please don't edit this file by hand. 4 | 5 | /** 6 | * @fileoverview Templates in namespace examples.simple. 7 | * @public 8 | */ 9 | 10 | if (typeof examples == 'undefined') { var examples = {}; } 11 | if (typeof examples.simple == 'undefined') { examples.simple = {}; } 12 | 13 | 14 | examples.simple.example = function(opt_data, opt_ignored, opt_ijData) { 15 | return soydata.VERY_UNSAFE.ordainSanitizedHtml('' + soy.$$escapeHtml(opt_data.name) + ''); 16 | }; 17 | if (goog.DEBUG) { 18 | examples.simple.example.soyTemplateName = 'examples.simple.example'; 19 | } 20 | 21 | 22 | examples.simple.exampleText = function(opt_data, opt_ignored, opt_ijData) { 23 | return soydata.markUnsanitizedText('Hello, ' + ('' + opt_data.name) + '!'); 24 | }; 25 | if (goog.DEBUG) { 26 | examples.simple.exampleText.soyTemplateName = 'examples.simple.exampleText'; 27 | } 28 | 29 | 30 | examples.simple.helloWorld = function(opt_data, opt_ignored, opt_ijData) { 31 | return soydata.VERY_UNSAFE.ordainSanitizedHtml('Hello world!'); 32 | }; 33 | if (goog.DEBUG) { 34 | examples.simple.helloWorld.soyTemplateName = 'examples.simple.helloWorld'; 35 | } 36 | 37 | 38 | examples.simple.helloName = function(opt_data, opt_ignored, opt_ijData) { 39 | return soydata.VERY_UNSAFE.ordainSanitizedHtml('

      Welcome' + ((! opt_data.greetingWord) ? 'Hello ' + soy.$$escapeHtml(opt_data.name) + '!' : soy.$$escapeHtml(opt_data.greetingWord) + ' ' + soy.$$escapeHtml(opt_data.name) + '!') + '

      '); 40 | }; 41 | if (goog.DEBUG) { 42 | examples.simple.helloName.soyTemplateName = 'examples.simple.helloName'; 43 | } 44 | 45 | 46 | examples.simple.helloNames = function(opt_data, opt_ignored, opt_ijData) { 47 | var output = examples.simple.helloName(opt_data, null, opt_ijData) + '
      '; 48 | var additionalNameList38 = opt_data.additionalNames; 49 | var additionalNameListLen38 = additionalNameList38.length; 50 | if (additionalNameListLen38 > 0) { 51 | for (var additionalNameIndex38 = 0; additionalNameIndex38 < additionalNameListLen38; additionalNameIndex38++) { 52 | var additionalNameData38 = additionalNameList38[additionalNameIndex38]; 53 | output += examples.simple.helloName({name: additionalNameData38}, null, opt_ijData) + ((! (additionalNameIndex38 == additionalNameListLen38 - 1)) ? '
      ' : ''); 54 | } 55 | } else { 56 | output += 'No additional people to greet.'; 57 | } 58 | return soydata.VERY_UNSAFE.ordainSanitizedHtml(output); 59 | }; 60 | if (goog.DEBUG) { 61 | examples.simple.helloNames.soyTemplateName = 'examples.simple.helloNames'; 62 | } 63 | 64 | 65 | examples.simple.autoNonce = function(opt_data, opt_ignored, opt_ijData) { 66 | return soydata.VERY_UNSAFE.ordainSanitizedHtml(' 70 | {/template} 71 | 72 | /** 73 | * A simple template for benchmarking. 74 | * @param bar a thingy 75 | */ 76 | {template .basic kind="html"} 77 | {$bar} 78 | {/template} 79 | 80 | /** 81 | * A list template for benchmarking. 82 | * @param items the items in the list 83 | */ 84 | {template .list kind="html"} 85 |
        86 | {foreach $item in $items} 87 |
      • {$item}
        • 88 | {/foreach} 89 |
      90 | {/template} 91 | -------------------------------------------------------------------------------- /test/other-example.soy: -------------------------------------------------------------------------------- 1 | {namespace example.other} 2 | 3 | /** 4 | * An additional example. 5 | * @param name A thing 6 | */ 7 | {template .addition kind="html"} 8 | Yes, {$name}. 9 | {/template} 10 | -------------------------------------------------------------------------------- /test/soy_clj/bench_test.clj: -------------------------------------------------------------------------------- 1 | (ns soy-clj.bench-test 2 | (:require [clojure.test :refer :all] 3 | [criterium.core :as c] 4 | [soy-clj.core :as soy])) 5 | 6 | (defn- sep 7 | [s] 8 | (printf "\n\n###### %s ######\n" s)) 9 | 10 | (deftest ^:bench parse-uncached-bench 11 | (sep "Parsing (uncached)") 12 | (soy/set-cache-options! {:disabled? true}) 13 | (c/bench (soy/parse "example.soy"))) 14 | 15 | (deftest ^:bench parse-cached-bench 16 | (sep "Parsing (cached)") 17 | (soy/set-cache-options! {}) 18 | (soy/parse "example.soy") 19 | (c/bench (soy/parse "example.soy"))) 20 | 21 | (deftest ^:bench render-big-bench 22 | (sep "Rendering (big list)") 23 | (let [templates (soy/parse "example.soy") 24 | data {:items (vec (map str (range 1 1000)))}] 25 | (c/bench (soy/render templates "examples.simple.list" data)))) 26 | 27 | (deftest ^:bench render-small-bench 28 | (sep "Rendering (small list)") 29 | (let [templates (soy/parse "example.soy") 30 | data {:items (vec (map str (range 1 50)))}] 31 | (c/bench (soy/render templates "examples.simple.list" data)))) 32 | 33 | (deftest ^:bench render-simple-bench 34 | (sep "Rendering (simple)") 35 | (let [templates (soy/parse "example.soy") 36 | data {:bar "bar"}] 37 | (c/bench (soy/render templates "examples.simple.basic" data)))) 38 | -------------------------------------------------------------------------------- /test/soy_clj/core_test.clj: -------------------------------------------------------------------------------- 1 | (ns soy-clj.core-test 2 | (:require [clojure.java.io :as io] 3 | [clojure.string :as string] 4 | [clojure.test :refer :all] 5 | [guava-cache-clj.core :as guava-cache] 6 | [soy-clj.core :refer :all :as soy-clj]) 7 | (:import (javax.script ScriptEngine ScriptEngineManager) 8 | (com.google.template.soy SoyFileSet SoyFileSet$Builder) 9 | (com.google.template.soy.data SanitizedContent 10 | SanitizedContent$ConstantContent) 11 | (com.google.template.soy.jssrc.restricted JsExpr))) 12 | 13 | (deftest ordain-as-safe-test 14 | (let [jsexpr (JsExpr. "''" Integer/MAX_VALUE)] 15 | (testing "marks html js expressions safe" 16 | (is (= "soydata.VERY_UNSAFE.ordainSanitizedHtml('')" 17 | (.getText ^JsExpr (ordain-as-safe jsexpr :html)))))) 18 | 19 | (testing "marks html safe" 20 | (is (instance? SanitizedContent (ordain-as-safe "" :html)))) 21 | 22 | (testing "renders safe html properly" 23 | (is (= "" (.getContent ^SanitizedContent$ConstantContent 24 | (ordain-as-safe "" :html)))))) 25 | 26 | (deftest content-type-test 27 | (is (= "text/css; charset=utf-8" (content-type :css))) 28 | (is (= "text/html; charset=utf-8" (content-type :html))) 29 | (is (= "text/javascript; charset=utf-8" (content-type :js))) 30 | (is (= "text/plain; charset=utf-8" (content-type :some-other-kind)))) 31 | 32 | (deftest clean-html-test 33 | (testing "Cleaning an HTML string" 34 | (is (= (ordain-as-safe "woo woo();" :html) 35 | (clean-html "woo
    2. woo();
      3. ")))) 36 | (testing "Cleaning an HTML string with optional safe tags" 37 | (is (= (ordain-as-safe "woo woo();" :html) 38 | (clean-html "woo woo();" :span))))) 39 | 40 | (deftest compile-to-js-test 41 | (testing "Compiling a missing template to Javascript" 42 | (is (thrown? IllegalArgumentException 43 | (compile-to-js "bad.soy")))) 44 | 45 | (testing "Compiling templates to Javascript" 46 | (set-cache-options! {}) 47 | (let [js (.. (ScriptEngineManager.) 48 | (getEngineByName "nashorn"))] 49 | (.eval js ^String (slurp "resources/soy-clj/soyutils.js")) 50 | (.eval js ^String (compile-to-js "example.soy")) 51 | (is (= "Hello world!" 52 | (.eval js "examples.simple.helloWorld().content")))) 53 | (is (= [[:js ["example.soy"]]] 54 | (keys (guava-cache/cache->map @@#'soy-clj/cache))))) 55 | 56 | (testing "Compiling cached templates to Javascript" 57 | (set-cache-options! {}) 58 | (compile-to-js "example.soy") 59 | (let [js (.. (ScriptEngineManager.) 60 | (getEngineByName "nashorn"))] 61 | (.eval js ^String (slurp "resources/soy-clj/soyutils.js")) 62 | (.eval js ^String (compile-to-js "example.soy")) 63 | (is (= "Hello world!" 64 | (.eval js "examples.simple.helloWorld().content")))) 65 | (is (= [[:js ["example.soy"]]] 66 | (keys (guava-cache/cache->map @@#'soy-clj/cache)))))) 67 | 68 | (deftest parse-test 69 | (testing "Parsing a template from a resource" 70 | (is (parse (io/resource "example.soy")))) 71 | (testing "Overriding the builder" 72 | (binding [*builder-fn* (fn [] (let [builder (SoyFileSet/builder)] 73 | (.add builder (io/file "test/example.soy")) 74 | builder))] 75 | (is (= ["Hello, Mr. World!" :text] 76 | (render (parse "other-example.soy") "examples.simple.exampleText" 77 | {:name "Mr. World"} 78 | :text))))) 79 | (testing "Preprocessing a template" 80 | (set-cache-options! {}) 81 | (binding [*preprocessor-fn* #(str % 82 | "\n\n" 83 | (->> (slurp "test/other-example.soy") 84 | (string/split-lines) 85 | (drop 1) 86 | (string/join "\n")))] 87 | (is (= ["Yes, boss." :html] 88 | (render (parse "example.soy") "examples.simple.addition" 89 | {:name "boss"})))))) 90 | 91 | (deftest render-test 92 | (testing "Rendering a template" 93 | (is (= [(str "

      Welcome" 94 | "Bonjour Mr. World!

      ") 95 | :html] 96 | (render (parse "example.soy") "examples.simple.helloName" 97 | {:name "Mr. World" 98 | :greeting-word "Bonjour"})))) 99 | (testing "Rendering a text template" 100 | (is (= ["Hello, Mr. World!" 101 | :text] 102 | (render (parse "example.soy") "examples.simple.exampleText" 103 | {:name "Mr. World"} 104 | :text)))) 105 | (testing "Contextually auto-escaping" 106 | (is (= [(str "', " 108 | "alert('XSS'), '") 109 | :html] 110 | (render (parse "example.soy") "examples.simple.example" 111 | {:name "', alert('XSS'), '"})))) 112 | (testing "Passing complex structures to nested templates" 113 | (is (= [(str "

      Welcome" 114 | "Hello Alice!


      " 115 | "WelcomeHello Bob!


      " 116 | "Welcome" 117 | "Hello Carol!


      " 118 | "WelcomeHello Dave!

      ") 119 | :html] 120 | (render (parse "example.soy") "examples.simple.helloNames" 121 | {"name" "Alice" 122 | :additional-names ["Bob" "Carol" "Dave"]})))) 123 | (testing "Passing pre-sanitized HTML" 124 | (is (= [(str "

      " 125 | "WelcomeBonjour Mr. World!

      ") 126 | :html] 127 | (render (parse "example.soy") "examples.simple.helloName" 128 | {:name (ordain-as-safe "Mr. World" :html) 129 | :greeting-word "Bonjour"}))))) 130 | --------------------------------------------------------------------------------