Release 0.12.0

Errors logs improvements

CHANGELOG.md

@@ -1,5 +1,94 @@
 # Stencil Changelog
 
+## 0.12.0
+
+### Enhancements
+
+- Added an optional second parameter to the `include` tag for passing a sub context to the included file.  
+  [Yonas Kolb](https://github.com/yonaskolb)
+  [#214](https://github.com/stencilproject/Stencil/pull/214)
+- Variables now support the subscript notation. For example, if you have a variable `key = "name"`, and an
+  object `item = ["name": "John"]`, then `{{ item[key] }}` will evaluate to "John".  
+  [David Jennes](https://github.com/djbe)
+  [#215](https://github.com/stencilproject/Stencil/pull/215)
+- Adds support for using spaces in filter expression.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#178](https://github.com/stencilproject/Stencil/pull/178)
+- Improvements in error reporting.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#167](https://github.com/stencilproject/Stencil/pull/167)
+
+### Bug Fixes
+
+- Fixed using quote as a filter parameter.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#210](https://github.com/stencilproject/Stencil/pull/210)
+
+
+## 0.11.0 (2018-04-04)
+
+### Enhancements
+
+- Added support for resolving superclass properties for not-NSObject subclasses.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#152](https://github.com/stencilproject/Stencil/pull/152)
+- The `{% for %}` tag can now iterate over tuples, structures and classes via
+  their stored properties.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#172](https://github.com/stencilproject/Stencil/pull/173)
+- Added `split` filter.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#187](https://github.com/stencilproject/Stencil/pull/187)
+- Allow default string filters to be applied to arrays.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#190](https://github.com/stencilproject/Stencil/pull/190)
+- Similar filters are suggested when unknown filter is used.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#186](https://github.com/stencilproject/Stencil/pull/186)
+- Added `indent` filter.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#188](https://github.com/stencilproject/Stencil/pull/188)
+- Allow using new lines inside tags.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#202](https://github.com/stencilproject/Stencil/pull/202)
+- Added support for iterating arrays of tuples.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#177](https://github.com/stencilproject/Stencil/pull/177)
+- Added support for ranges in if-in expression.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#193](https://github.com/stencilproject/Stencil/pull/193)
+- Added property `forloop.length` to get number of items in the loop.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#171](https://github.com/stencilproject/Stencil/pull/171)
+- Now you can construct ranges for loops using `a...b` syntax, i.e. `for i in 1...array.count`.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#192](https://github.com/stencilproject/Stencil/pull/192)
+
+### Bug Fixes
+
+- Fixed rendering `{{ block.super }}` with several levels of inheritance.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#154](https://github.com/stencilproject/Stencil/pull/154)
+- Fixed checking dictionary values for nil in `default` filter.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#162](https://github.com/stencilproject/Stencil/pull/162)
+- Fixed comparing string variables with string literals, in Swift 4 string literals became `Substring` and thus couldn't be directly compared to strings.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#168](https://github.com/stencilproject/Stencil/pull/168)
+- Integer literals now resolve into Int values, not Float.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#181](https://github.com/stencilproject/Stencil/pull/181)
+- Fixed accessing properties of optional properties via reflection.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#204](https://github.com/stencilproject/Stencil/pull/204)
+- No longer render optional values in arrays as `Optional(..)`.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#205](https://github.com/stencilproject/Stencil/pull/205)
+- Fixed subscription tuples by value index, i.e. `{{ tuple.0 }}`.  
+  [Ilya Puchka](https://github.com/ilyapuchka)
+  [#172](https://github.com/stencilproject/Stencil/pull/172)
+
+
 ## 0.10.1
 
 ### Enhancements
@@ -198,10 +287,10 @@
 ### Bug Fixes
 
 - Variables (`{{ variable.5 }}`) that reference an array index at an unknown
-  index will now resolve to `nil` instead of causing a crash.
+  index will now resolve to `nil` instead of causing a crash.  
   [#72](https://github.com/kylef/Stencil/issues/72)
 
-- Templates can now extend templates that extend other templates.
+- Templates can now extend templates that extend other templates.  
   [#60](https://github.com/kylef/Stencil/issues/60)
 
 - If comparisons will now treat 0 and below numbers as negative.

Package.swift

@@ -1,11 +1,10 @@
+// swift-tools-version:3.1
 import PackageDescription
 
 let package = Package(
   name: "Stencil",
   dependencies: [
-    .Package(url: "https://github.com/kylef/PathKit.git", majorVersion: 0, minor: 8),
-
-    // https://github.com/apple/swift-package-manager/pull/597
-    .Package(url: "https://github.com/kylef/Spectre.git", majorVersion: 0, minor: 7),
+    .Package(url: "https://github.com/kylef/PathKit.git", majorVersion: 0, minor: 9),
+    .Package(url: "https://github.com/kylef/Spectre.git", majorVersion: 0, minor: 8),
   ]
 )

Package@swift-3.swift

@@ -0,0 +1,10 @@
+// swift-tools-version:3.1
+import PackageDescription
+
+let package = Package(
+  name: "Stencil",
+  dependencies: [
+    .Package(url: "https://github.com/kylef/PathKit.git", majorVersion: 0, minor: 8),
+    .Package(url: "https://github.com/kylef/Spectre.git", majorVersion: 0, minor: 7),
+  ]
+)

README.md

@@ -1,6 +1,6 @@
 # Stencil
 
-[![Build Status](https://travis-ci.org/kylef/Stencil.svg?branch=master)](https://travis-ci.org/kylef/Stencil)
+[![Build Status](https://travis-ci.org/stencilproject/Stencil.svg?branch=master)](https://travis-ci.org/stencilproject/Stencil)
 
 Stencil is a simple and powerful template language for Swift. It provides a
 syntax similar to Django and Mustache. If you're familiar with these, you will
@@ -63,6 +63,13 @@ Resources to help you integrate Stencil into a Swift project:
 - [API Reference](http://stencil.fuller.li/en/latest/api.html)
 - [Custom Template Tags and Filters](http://stencil.fuller.li/en/latest/custom-template-tags-and-filters.html)
 
+## Projects that use Stencil
+
+[Sourcery](https://github.com/krzysztofzablocki/Sourcery),
+[SwiftGen](https://github.com/SwiftGen/SwiftGen),
+[Kitura](https://github.com/IBM-Swift/Kitura),
+[Weaver](https://github.com/scribd/Weaver)
+
 ## License
 
 Stencil is licensed under the BSD license. See [LICENSE](LICENSE) for more

Sources/Context.swift

@@ -3,7 +3,7 @@ public class Context {
   var dictionaries: [[String: Any?]]
 
   public let environment: Environment
-
+  
   init(dictionary: [String: Any]? = nil, environment: Environment? = nil) {
     if let dictionary = dictionary {
       dictionaries = [dictionary]

Sources/Environment.swift

@@ -4,7 +4,10 @@ public struct Environment {
 
   public var loader: Loader?
 
-  public init(loader: Loader? = nil, extensions: [Extension]? = nil, templateClass: Template.Type = Template.self) {
+  public init(loader: Loader? = nil,
+              extensions: [Extension]? = nil,
+              templateClass: Template.Type = Template.self) {
+
     self.templateClass = templateClass
     self.loader = loader
     self.extensions = (extensions ?? []) + [DefaultExtension()]
@@ -28,11 +31,18 @@ public struct Environment {
 
   public func renderTemplate(name: String, context: [String: Any]? = nil) throws -> String {
     let template = try loadTemplate(name: name)
-    return try template.render(context)
+    return try render(template: template, context: context)
   }
 
   public func renderTemplate(string: String, context: [String: Any]? = nil) throws -> String {
     let template = templateClass.init(templateString: string, environment: self)
+    return try render(template: template, context: context)
+  }
+
+  func render(template: Template, context: [String: Any]?) throws -> String {
+    // update template environment as it can be created from string literal with default environment
+    template.environment = self
     return try template.render(context)
   }
+
 }

Sources/Errors.swift

@@ -17,3 +17,67 @@ public class TemplateDoesNotExist: Error, CustomStringConvertible {
     return "Template named `\(templates)` does not exist. No loaders found"
   }
 }
+
+public struct TemplateSyntaxError : Error, Equatable, CustomStringConvertible {
+  public let reason: String
+  public var description: String { return reason }
+  public internal(set) var token: Token?
+  public internal(set) var stackTrace: [Token]
+  public var templateName: String? { return token?.sourceMap.filename }
+  var allTokens: [Token] {
+    return stackTrace + (token.map({ [$0] }) ?? [])
+  }
+
+  public init(reason: String, token: Token? = nil, stackTrace: [Token] = []) {
+    self.reason = reason
+    self.stackTrace = stackTrace
+    self.token = token
+  }
+
+  public init(_ description: String) {
+    self.init(reason: description)
+  }
+
+  public static func ==(lhs:TemplateSyntaxError, rhs:TemplateSyntaxError) -> Bool {
+    return lhs.description == rhs.description && lhs.token == rhs.token && lhs.stackTrace == rhs.stackTrace
+  }
+
+}
+
+extension Error {
+  func withToken(_ token: Token?) -> Error {
+    if var error = self as? TemplateSyntaxError {
+      error.token = error.token ?? token
+      return error
+    } else {
+      return TemplateSyntaxError(reason: "\(self)", token: token)
+    }
+  }
+}
+
+public protocol ErrorReporter: class {
+  func renderError(_ error: Error) -> String
+}
+
+open class SimpleErrorReporter: ErrorReporter {
+
+  open func renderError(_ error: Error) -> String {
+    guard let templateError = error as? TemplateSyntaxError else { return error.localizedDescription }
+
+    func describe(token: Token) -> String {
+      let templateName = token.sourceMap.filename ?? ""
+      let line = token.sourceMap.line
+      let highlight = "\(String(Array(repeating: " ", count: line.offset)))^\(String(Array(repeating: "~", count: max(token.contents.characters.count - 1, 0))))"
+
+      return "\(templateName)\(line.number):\(line.offset): error: \(templateError.reason)\n"
+        + "\(line.content)\n"
+        + "\(highlight)\n"
+    }
+
+    var descriptions = templateError.stackTrace.reduce([]) { $0 + [describe(token: $1)] }
+    let description = templateError.token.map(describe(token:)) ?? templateError.reason
+    descriptions.append(description)
+    return descriptions.joined(separator: "\n")
+  }
+
+}

Sources/Expression.swift

@@ -88,33 +88,37 @@ final class NotExpression: Expression, PrefixOperator, CustomStringConvertible {
 final class InExpression: Expression, InfixOperator, CustomStringConvertible {
   let lhs: Expression
   let rhs: Expression
-  
+
   init(lhs: Expression, rhs: Expression) {
     self.lhs = lhs
     self.rhs = rhs
   }
-  
+
   var description: String {
     return "(\(lhs) in \(rhs))"
   }
-  
+
   func evaluate(context: Context) throws -> Bool {
     if let lhs = lhs as? VariableExpression, let rhs = rhs as? VariableExpression {
       let lhsValue = try lhs.variable.resolve(context)
       let rhsValue = try rhs.variable.resolve(context)
-      
+
       if let lhs = lhsValue as? AnyHashable, let rhs = rhsValue as? [AnyHashable] {
         return rhs.contains(lhs)
+      } else if let lhs = lhsValue as? Int, let rhs = rhsValue as? CountableClosedRange<Int> {
+        return rhs.contains(lhs)
+      } else if let lhs = lhsValue as? Int, let rhs = rhsValue as? CountableRange<Int> {
+        return rhs.contains(lhs)
       } else if let lhs = lhsValue as? String, let rhs = rhsValue as? String {
         return rhs.contains(lhs)
       } else if lhsValue == nil && rhsValue == nil {
         return true
       }
     }
-    
+
     return false
   }
-  
+
 }
 
 final class OrExpression: Expression, InfixOperator, CustomStringConvertible {

Sources/Extension.swift

@@ -15,7 +15,7 @@ open class Extension {
   /// Registers a simple template tag with a name and a handler
   public func registerSimpleTag(_ name: String, handler: @escaping (Context) throws -> String) {
     registerTag(name, parser: { parser, token in
-      return SimpleNode(handler: handler)
+      return SimpleNode(token: token, handler: handler)
     })
   }
 
@@ -42,9 +42,9 @@ class DefaultExtension: Extension {
     registerTag("for", parser: ForNode.parse)
     registerTag("if", parser: IfNode.parse)
     registerTag("ifnot", parser: IfNode.parse_ifnot)
-#if !os(Linux)
-    registerTag("now", parser: NowNode.parse)
-#endif
+    #if !os(Linux)
+      registerTag("now", parser: NowNode.parse)
+    #endif
     registerTag("include", parser: IncludeNode.parse)
     registerTag("extends", parser: ExtendsNode.parse)
     registerTag("block", parser: BlockNode.parse)
@@ -57,6 +57,8 @@ class DefaultExtension: Extension {
     registerFilter("uppercase", filter: uppercase)
     registerFilter("lowercase", filter: lowercase)
     registerFilter("join", filter: joinFilter)
+    registerFilter("split", filter: splitFilter)
+    registerFilter("indent", filter: indentFilter)
   }
 }
 

Sources/FilterTag.swift

@@ -1,6 +1,7 @@
 class FilterNode : NodeType {
   let resolvable: Resolvable
   let nodes: [NodeType]
+  let token: Token?
 
   class func parse(_ parser: TokenParser, token: Token) throws -> NodeType {
     let bits = token.components()
@@ -15,20 +16,21 @@ class FilterNode : NodeType {
       throw TemplateSyntaxError("`endfilter` was not found.")
     }
 
-    let resolvable = try parser.compileFilter("filter_value|\(bits[1])")
-    return FilterNode(nodes: blocks, resolvable: resolvable)
+    let resolvable = try parser.compileFilter("filter_value|\(bits[1])", containedIn: token)
+    return FilterNode(nodes: blocks, resolvable: resolvable, token: token)
   }
 
-  init(nodes: [NodeType], resolvable: Resolvable) {
+  init(nodes: [NodeType], resolvable: Resolvable, token: Token) {
     self.nodes = nodes
     self.resolvable = resolvable
+    self.token = token
   }
 
   func render(_ context: Context) throws -> String {
     let value = try renderNodes(nodes, context)
 
     return try context.push(dictionary: ["filter_value": value]) {
-      return try VariableNode(variable: resolvable).render(context)
+      return try VariableNode(variable: resolvable, token: token).render(context)
     }
   }
 }

Sources/Filters.swift

@@ -1,17 +1,30 @@
 func capitalise(_ value: Any?) -> Any? {
-  return stringify(value).capitalized
+  if let array = value as? [Any?] {
+    return array.map { stringify($0).capitalized }
+  } else {
+    return stringify(value).capitalized
+  }
 }
 
 func uppercase(_ value: Any?) -> Any? {
-  return stringify(value).uppercased()
+  if let array = value as? [Any?] {
+    return array.map { stringify($0).uppercased() }
+  } else {
+    return stringify(value).uppercased()
+  }
 }
 
 func lowercase(_ value: Any?) -> Any? {
-  return stringify(value).lowercased()
+  if let array = value as? [Any?] {
+    return array.map { stringify($0).lowercased() }
+  } else {
+    return stringify(value).lowercased()
+  }
 }
 
 func defaultFilter(value: Any?, arguments: [Any?]) -> Any? {
-  if let value = value {
+  // value can be optional wrapping nil, so this way we check for underlying value
+  if let value = value, String(describing: value) != "nil" {
     return value
   }
 
@@ -39,3 +52,62 @@ func joinFilter(value: Any?, arguments: [Any?]) throws -> Any? {
 
   return value
 }
+
+func splitFilter(value: Any?, arguments: [Any?]) throws -> Any? {
+  guard arguments.count < 2 else {
+    throw TemplateSyntaxError("'split' filter takes a single argument")
+  }
+
+  let separator = stringify(arguments.first ?? " ")
+  if let value = value as? String {
+    return value.components(separatedBy: separator)
+  }
+
+  return value
+}
+
+func indentFilter(value: Any?, arguments: [Any?]) throws -> Any? {
+  guard arguments.count <= 3 else {
+    throw TemplateSyntaxError("'indent' filter can take at most 3 arguments")
+  }
+
+  var indentWidth = 4
+  if arguments.count > 0 {
+    guard let value = arguments[0] as? Int else {
+      throw TemplateSyntaxError("'indent' filter width argument must be an Integer (\(String(describing: arguments[0])))")
+    }
+    indentWidth = value
+  }
+
+  var indentationChar = " "
+  if arguments.count > 1 {
+    guard let value = arguments[1] as? String else {
+      throw TemplateSyntaxError("'indent' filter indentation argument must be a String (\(String(describing: arguments[1]))")
+    }
+    indentationChar = value
+  }
+
+  var indentFirst = false
+  if arguments.count > 2 {
+    guard let value = arguments[2] as? Bool else {
+      throw TemplateSyntaxError("'indent' filter indentFirst argument must be a Bool")
+    }
+    indentFirst = value
+  }
+
+  let indentation = [String](repeating: indentationChar, count: indentWidth).joined(separator: "")
+  return indent(stringify(value), indentation: indentation, indentFirst: indentFirst)
+}
+
+
+func indent(_ content: String, indentation: String, indentFirst: Bool) -> String {
+  guard !indentation.isEmpty else { return content }
+
+  var lines = content.components(separatedBy: .newlines)
+  let firstLine = (indentFirst ? indentation : "") + lines.removeFirst()
+  let result = lines.reduce([firstLine]) { (result, line) in
+    return result + [(line.isEmpty ? "" : "\(indentation)\(line)")]
+  }
+  return result.joined(separator: "\n")
+}
+

Sources/ForTag.swift

@@ -6,23 +6,33 @@ class ForNode : NodeType {
   let nodes:[NodeType]
   let emptyNodes: [NodeType]
   let `where`: Expression?
+  let token: Token?
 
   class func parse(_ parser:TokenParser, token:Token) throws -> NodeType {
     let components = token.components()
 
-    guard components.count >= 3 && components[2] == "in" &&
-        (components.count == 4 || (components.count >= 6 && components[4] == "where")) else {
-      throw TemplateSyntaxError("'for' statements should use the following 'for x in y where condition' `\(token.contents)`.")
+    func hasToken(_ token: String, at index: Int) -> Bool {
+      return components.count > (index + 1) && components[index] == token
+    }
+
+    func endsOrHasToken(_ token: String, at index: Int) -> Bool {
+      return components.count == index || hasToken(token, at: index)
+    }
+
+    guard hasToken("in", at: 2) && endsOrHasToken("where", at: 4) else {
+      throw TemplateSyntaxError("'for' statements should use the syntax: `for <x> in <y> [where <condition>]`.")
     }
 
     let loopVariables = components[1].characters
       .split(separator: ",")
       .map(String.init)
-      .map { $0.trimmingCharacters(in: CharacterSet.whitespaces) }
+      .map { $0.trim(character: " ") }
 
-    let variable = components[3]
+    let resolvable = try parser.compileResolvable(components[3], containedIn: token)
 
-    var emptyNodes = [NodeType]()
+    let `where` = hasToken("where", at: 4)
+      ? try parseExpression(components: Array(components.suffix(from: 5)), tokenParser: parser, token: token)
+      : nil
 
     let forNodes = try parser.parse(until(["endfor", "empty"]))
 
@@ -30,48 +40,44 @@ class ForNode : NodeType {
       throw TemplateSyntaxError("`endfor` was not found.")
     }
 
+    var emptyNodes = [NodeType]()
     if token.contents == "empty" {
       emptyNodes = try parser.parse(until(["endfor"]))
       _ = parser.nextToken()
     }
 
-    let filter = try parser.compileFilter(variable)
-    let `where`: Expression?
-    if components.count >= 6 {
-      `where` = try parseExpression(components: Array(components.suffix(from: 5)), tokenParser: parser)
-    } else {
-      `where` = nil
-    }
-    return ForNode(resolvable: filter, loopVariables: loopVariables, nodes: forNodes, emptyNodes:emptyNodes, where: `where`)
+    return ForNode(resolvable: resolvable, loopVariables: loopVariables, nodes: forNodes, emptyNodes: emptyNodes, where: `where`, token: token)
   }
 
-  init(resolvable: Resolvable, loopVariables: [String], nodes:[NodeType], emptyNodes:[NodeType], where: Expression? = nil) {
+  init(resolvable: Resolvable, loopVariables: [String], nodes: [NodeType], emptyNodes: [NodeType], where: Expression? = nil, token: Token? = nil) {
     self.resolvable = resolvable
     self.loopVariables = loopVariables
     self.nodes = nodes
     self.emptyNodes = emptyNodes
     self.where = `where`
+    self.token = token
   }
 
-  func push<Result>(value: Any, context: Context, closure: () throws -> (Result)) rethrows -> Result {
+  func push<Result>(value: Any, context: Context, closure: () throws -> (Result)) throws -> Result {
     if loopVariables.isEmpty {
       return try context.push() {
         return try closure()
       }
     }
 
-    if let value = value as? (Any, Any) {
-      let first = loopVariables[0]
-
-      if loopVariables.count == 2 {
-        let second = loopVariables[1]
-
-        return try context.push(dictionary: [first: value.0, second: value.1]) {
-          return try closure()
-        }
+    let valueMirror = Mirror(reflecting: value)
+    if case .tuple? = valueMirror.displayStyle {
+      if loopVariables.count > Int(valueMirror.children.count) {
+        throw TemplateSyntaxError("Tuple '\(value)' has less values than loop variables")
       }
+      var variablesContext = [String: Any]()
+      valueMirror.children.prefix(loopVariables.count).enumerated().forEach({ (offset, element) in
+        if loopVariables[offset] != "_" {
+          variablesContext[loopVariables[offset]] = element.value
+        }
+      })
 
-      return try context.push(dictionary: [first: value.0]) {
+      return try context.push(dictionary: variablesContext) {
         return try closure()
       }
     }
@@ -94,6 +100,22 @@ class ForNode : NodeType {
       values = Array(range)
     } else if let range = resolved as? CountableRange<Int> {
       values = Array(range)
+    } else if let resolved = resolved {
+      let mirror = Mirror(reflecting: resolved)
+      switch mirror.displayStyle {
+      case .struct?, .tuple?:
+        values = Array(mirror.children)
+      case .class?:
+        var children = Array(mirror.children)
+        var currentMirror: Mirror? = mirror
+        while let superclassMirror = currentMirror?.superclassMirror {
+          children.append(contentsOf: superclassMirror.children)
+          currentMirror = superclassMirror
+        }
+        values = Array(children)
+      default:
+        values = []
+      }
     } else {
       values = []
     }
@@ -115,6 +137,7 @@ class ForNode : NodeType {
           "last": index == (count - 1),
           "counter": index + 1,
           "counter0": index,
+          "length": count
         ]
 
         return try context.push(dictionary: ["forloop": forContext]) {
@@ -122,7 +145,7 @@ class ForNode : NodeType {
             try renderNodes(nodes, context)
           }
         }
-      }.joined(separator: "")
+        }.joined(separator: "")
     }
 
     return try context.push {

Sources/IfTag.swift

@@ -53,7 +53,7 @@ enum IfToken {
     case .variable(_):
       return 0
     case .end:
-        return 0
+      return 0
     }
   }
 
@@ -100,7 +100,7 @@ final class IfExpressionParser {
   let tokens: [IfToken]
   var position: Int = 0
 
-  init(components: [String], tokenParser: TokenParser) throws {
+  init(components: [String], tokenParser: TokenParser, token: Token) throws {
     self.tokens = try components.map { component in
       if let op = findOperator(name: component) {
         switch op {
@@ -111,7 +111,7 @@ final class IfExpressionParser {
         }
       }
 
-      return .variable(try tokenParser.compileFilter(component))
+      return .variable(try tokenParser.compileResolvable(component, containedIn: token))
     }
   }
 
@@ -155,8 +155,8 @@ final class IfExpressionParser {
 }
 
 
-func parseExpression(components: [String], tokenParser: TokenParser) throws -> Expression {
-  let parser = try IfExpressionParser(components: components, tokenParser: tokenParser)
+func parseExpression(components: [String], tokenParser: TokenParser, token: Token) throws -> Expression {
+  let parser = try IfExpressionParser(components: components, tokenParser: tokenParser, token: token)
   return try parser.parse()
 }
 
@@ -182,49 +182,51 @@ final class IfCondition {
 
 class IfNode : NodeType {
   let conditions: [IfCondition]
+  let token: Token?
 
   class func parse(_ parser: TokenParser, token: Token) throws -> NodeType {
     var components = token.components()
     components.removeFirst()
 
-    let expression = try parseExpression(components: components, tokenParser: parser)
+    let expression = try parseExpression(components: components, tokenParser: parser, token: token)
     let nodes = try parser.parse(until(["endif", "elif", "else"]))
     var conditions: [IfCondition] = [
       IfCondition(expression: expression, nodes: nodes)
     ]
 
-    var token = parser.nextToken()
-    while let current = token, current.contents.hasPrefix("elif") {
+    var nextToken = parser.nextToken()
+    while let current = nextToken, current.contents.hasPrefix("elif") {
       var components = current.components()
       components.removeFirst()
-      let expression = try parseExpression(components: components, tokenParser: parser)
+      let expression = try parseExpression(components: components, tokenParser: parser, token: current)
 
       let nodes = try parser.parse(until(["endif", "elif", "else"]))
-      token = parser.nextToken()
+      nextToken = parser.nextToken()
       conditions.append(IfCondition(expression: expression, nodes: nodes))
     }
 
-    if let current = token, current.contents == "else" {
+    if let current = nextToken, current.contents == "else" {
       conditions.append(IfCondition(expression: nil, nodes: try parser.parse(until(["endif"]))))
-      token = parser.nextToken()
+      nextToken = parser.nextToken()
     }
 
-    guard let current = token, current.contents == "endif" else {
+    guard let current = nextToken, current.contents == "endif" else {
       throw TemplateSyntaxError("`endif` was not found.")
     }
 
-    return IfNode(conditions: conditions)
+    return IfNode(conditions: conditions, token: token)
   }
 
   class func parse_ifnot(_ parser: TokenParser, token: Token) throws -> NodeType {
     var components = token.components()
     guard components.count == 2 else {
-      throw TemplateSyntaxError("'ifnot' statements should use the following 'ifnot condition' `\(token.contents)`.")
+      throw TemplateSyntaxError("'ifnot' statements should use the following syntax 'ifnot condition'.")
     }
     components.removeFirst()
     var trueNodes = [NodeType]()
     var falseNodes = [NodeType]()
 
+    let expression = try parseExpression(components: components, tokenParser: parser, token: token)
     falseNodes = try parser.parse(until(["endif", "else"]))
 
     guard let token = parser.nextToken() else {
@@ -236,15 +238,15 @@ class IfNode : NodeType {
       _ = parser.nextToken()
     }
 
-    let expression = try parseExpression(components: components, tokenParser: parser)
     return IfNode(conditions: [
       IfCondition(expression: expression, nodes: trueNodes),
       IfCondition(expression: nil, nodes: falseNodes),
-    ])
+      ], token: token)
   }
 
-  init(conditions: [IfCondition]) {
+  init(conditions: [IfCondition], token: Token? = nil) {
     self.conditions = conditions
+    self.token = token
   }
 
   func render(_ context: Context) throws -> String {

Sources/Include.swift

@@ -3,19 +3,23 @@ import PathKit
 
 class IncludeNode : NodeType {
   let templateName: Variable
+  let includeContext: String?
+  let token: Token?
 
   class func parse(_ parser: TokenParser, token: Token) throws -> NodeType {
     let bits = token.components()
 
-    guard bits.count == 2 else {
-      throw TemplateSyntaxError("'include' tag takes one argument, the template file to be included")
+    guard bits.count == 2 || bits.count == 3 else {
+      throw TemplateSyntaxError("'include' tag requires one argument, the template file to be included. A second optional argument can be used to specify the context that will be passed to the included file")
     }
 
-    return IncludeNode(templateName: Variable(bits[1]))
+    return IncludeNode(templateName: Variable(bits[1]), includeContext: bits.count == 3 ? bits[2] : nil, token: token)
   }
 
-  init(templateName: Variable) {
+  init(templateName: Variable, includeContext: String? = nil, token: Token) {
     self.templateName = templateName
+    self.includeContext = includeContext
+    self.token = token
   }
 
   func render(_ context: Context) throws -> String {
@@ -25,8 +29,17 @@ class IncludeNode : NodeType {
 
     let template = try context.environment.loadTemplate(name: templateName)
 
-    return try context.push {
-      return try template.render(context)
+    do {
+      let subContext = includeContext.flatMap { context[$0] as? [String: Any] }
+      return try context.push(dictionary: subContext) {
+        return try template.render(context)
+      }
+    } catch {
+      if let error = error as? TemplateSyntaxError {
+        throw TemplateSyntaxError(reason: error.reason, stackTrace: error.allTokens)
+      } else {
+        throw error
+      }
     }
   }
 }

Sources/Inheritence.swift

@@ -1,14 +1,35 @@
 class BlockContext {
   class var contextKey: String { return "block_context" }
 
-  var blocks: [String: BlockNode]
+  // contains mapping of block names to their nodes and templates where they are defined
+  var blocks: [String: [BlockNode]]
 
   init(blocks: [String: BlockNode]) {
-    self.blocks = blocks
+    self.blocks = [:]
+    blocks.forEach { self.blocks[$0.key] = [$0.value] }
+  }
+
+  func push(_ block: BlockNode, forKey blockName: String) {
+    if var blocks = blocks[blockName] {
+      blocks.append(block)
+      self.blocks[blockName] = blocks
+    } else {
+      self.blocks[blockName] = [block]
+    }
   }
 
   func pop(_ blockName: String) -> BlockNode? {
-    return blocks.removeValue(forKey: blockName)
+    if var blocks = blocks[blockName] {
+      let block = blocks.removeFirst()
+      if blocks.isEmpty {
+        self.blocks.removeValue(forKey: blockName)
+      } else {
+        self.blocks[blockName] = blocks
+      }
+      return block
+    } else {
+      return nil
+    }
   }
 }
 
@@ -29,6 +50,7 @@ extension Collection {
 class ExtendsNode : NodeType {
   let templateName: Variable
   let blocks: [String:BlockNode]
+  let token: Token?
 
   class func parse(_ parser: TokenParser, token: Token) throws -> NodeType {
     let bits = token.components()
@@ -50,12 +72,13 @@ class ExtendsNode : NodeType {
       return dict
     }
 
-    return ExtendsNode(templateName: Variable(bits[1]), blocks: nodes)
+    return ExtendsNode(templateName: Variable(bits[1]), blocks: nodes, token: token)
   }
 
-  init(templateName: Variable, blocks: [String: BlockNode]) {
+  init(templateName: Variable, blocks: [String: BlockNode], token: Token) {
     self.templateName = templateName
     self.blocks = blocks
+    self.token = token
   }
 
   func render(_ context: Context) throws -> String {
@@ -63,23 +86,33 @@ class ExtendsNode : NodeType {
       throw TemplateSyntaxError("'\(self.templateName)' could not be resolved as a string")
     }
 
-    let template = try context.environment.loadTemplate(name: templateName)
+    let baseTemplate = try context.environment.loadTemplate(name: templateName)
 
     let blockContext: BlockContext
-    if let context = context[BlockContext.contextKey] as? BlockContext {
-      blockContext = context
-
-      for (key, value) in blocks {
-        if !blockContext.blocks.keys.contains(key) {
-          blockContext.blocks[key] = value
-        }
+    if let currentBlockContext = context[BlockContext.contextKey] as? BlockContext {
+      blockContext = currentBlockContext
+      for (name, block) in blocks {
+        blockContext.push(block, forKey: name)
       }
     } else {
       blockContext = BlockContext(blocks: blocks)
     }
 
-    return try context.push(dictionary: [BlockContext.contextKey: blockContext]) {
-      return try template.render(context)
+    do {
+      // pushes base template and renders it's content
+      // block_context contains all blocks from child templates
+      return try context.push(dictionary: [BlockContext.contextKey: blockContext]) {
+        return try baseTemplate.render(context)
+      }
+    } catch {
+      // if error template is already set (see catch in BlockNode)
+      // and it happend in the same template as current template
+      // there is no need to wrap it in another error
+      if let error = error as? TemplateSyntaxError, error.templateName != token?.sourceMap.filename {
+        throw TemplateSyntaxError(reason: error.reason, stackTrace: error.allTokens)
+      } else {
+        throw error
+      }
     }
   }
 }
@@ -88,6 +121,7 @@ class ExtendsNode : NodeType {
 class BlockNode : NodeType {
   let name: String
   let nodes: [NodeType]
+  let token: Token?
 
   class func parse(_ parser: TokenParser, token: Token) throws -> NodeType {
     let bits = token.components()
@@ -99,21 +133,57 @@ class BlockNode : NodeType {
     let blockName = bits[1]
     let nodes = try parser.parse(until(["endblock"]))
     _ = parser.nextToken()
-    return BlockNode(name:blockName, nodes:nodes)
+    return BlockNode(name:blockName, nodes:nodes, token: token)
   }
 
-  init(name: String, nodes: [NodeType]) {
+  init(name: String, nodes: [NodeType], token: Token) {
     self.name = name
     self.nodes = nodes
+    self.token = token
   }
 
   func render(_ context: Context) throws -> String {
-    if let blockContext = context[BlockContext.contextKey] as? BlockContext, let node = blockContext.pop(name) {
-      return try context.push(dictionary: ["block": ["super": self]]) {
-        return try node.render(context)
+    if let blockContext = context[BlockContext.contextKey] as? BlockContext, let child = blockContext.pop(name) {
+      let childContext = try self.childContext(child, blockContext: blockContext, context: context)
+      // render extension node
+      do {
+        return try context.push(dictionary: childContext) {
+          return try child.render(context)
+        }
+      } catch {
+        throw error.withToken(child.token)
       }
     }
 
     return try renderNodes(nodes, context)
   }
+
+  // child node is a block node from child template that extends this node (has the same name)
+  func childContext(_ child: BlockNode, blockContext: BlockContext, context: Context) throws -> [String: Any?] {
+    var childContext: [String: Any?] = [BlockContext.contextKey: blockContext]
+
+    if let blockSuperNode = child.nodes.first(where: {
+      if case .variable(let variable, _)? = $0.token, variable == "block.super" { return true }
+      else { return false}
+    }) {
+      do {
+        // render base node so that its content can be used as part of child node that extends it
+        childContext["block"] = ["super": try self.render(context)]
+      } catch {
+        if let error = error as? TemplateSyntaxError {
+          throw TemplateSyntaxError(
+            reason: error.reason,
+            token: blockSuperNode.token,
+            stackTrace: error.allTokens)
+        } else {
+          throw TemplateSyntaxError(
+            reason: "\(error)",
+            token: blockSuperNode.token,
+            stackTrace: [])
+        }
+      }
+    }
+    return childContext
+  }
+
 }

Sources/KeyPath.swift

@@ -0,0 +1,112 @@
+import Foundation
+
+/// A structure used to represent a template variable, and to resolve it in a given context.
+final class KeyPath {
+  private var components = [String]()
+  private var current = ""
+  private var partialComponents = [String]()
+  private var subscriptLevel = 0
+
+  let variable: String
+  let context: Context
+
+  // Split the keypath string and resolve references if possible
+  init(_ variable: String, in context: Context) {
+    self.variable = variable
+    self.context = context
+  }
+
+  func parse() throws -> [String] {
+    defer {
+      components = []
+      current = ""
+      partialComponents = []
+      subscriptLevel = 0
+    }
+
+    for c in variable.characters {
+      switch c {
+      case "." where subscriptLevel == 0:
+        try foundSeparator()
+      case "[":
+        try openBracket()
+      case "]":
+        try closeBracket()
+      default:
+        try addCharacter(c)
+      }
+    }
+    try finish()
+
+    return components
+  }
+
+  private func foundSeparator() throws {
+    if !current.isEmpty {
+      partialComponents.append(current)
+    }
+
+    guard !partialComponents.isEmpty else {
+      throw TemplateSyntaxError("Unexpected '.' in variable '\(variable)'")
+    }
+
+    components += partialComponents
+    current = ""
+    partialComponents = []
+  }
+
+  // when opening the first bracket, we must have a partial component
+  private func openBracket() throws {
+    guard !partialComponents.isEmpty || !current.isEmpty else {
+      throw TemplateSyntaxError("Unexpected '[' in variable '\(variable)'")
+    }
+
+    if subscriptLevel > 0 {
+      current.append("[")
+    } else if !current.isEmpty {
+      partialComponents.append(current)
+      current = ""
+    }
+
+    subscriptLevel += 1
+  }
+
+  // for a closing bracket at root level, try to resolve the reference
+  private func closeBracket() throws {
+    guard subscriptLevel > 0 else {
+      throw TemplateSyntaxError("Unbalanced ']' in variable '\(variable)'")
+    }
+
+    if subscriptLevel > 1 {
+      current.append("]")
+    } else if !current.isEmpty,
+      let value = try Variable(current).resolve(context) {
+      partialComponents.append("\(value)")
+      current = ""
+    } else {
+      throw TemplateSyntaxError("Unable to resolve subscript '\(current)' in variable '\(variable)'")
+    }
+
+    subscriptLevel -= 1
+  }
+
+  private func addCharacter(_ c: Character) throws {
+    guard partialComponents.isEmpty || subscriptLevel > 0 else {
+      throw TemplateSyntaxError("Unexpected character '\(c)' in variable '\(variable)'")
+    }
+
+    current.append(c)
+  }
+
+  private func finish() throws {
+    // check if we have a last piece
+    if !current.isEmpty {
+      partialComponents.append(current)
+    }
+    components += partialComponents
+
+    guard subscriptLevel == 0 else {
+      throw TemplateSyntaxError("Unbalanced subscript brackets in variable '\(variable)'")
+    }
+  }
+}

Sources/Lexer.swift

@@ -1,27 +1,45 @@
+import Foundation
+
 struct Lexer {
+  let templateName: String?
   let templateString: String
 
-  init(templateString: String) {
+  init(templateName: String? = nil, templateString: String) {
+    self.templateName = templateName
     self.templateString = templateString
   }
 
-  func createToken(string: String) -> Token {
+  func createToken(string: String, at range: Range<String.Index>) -> Token {
     func strip() -> String {
       guard string.characters.count > 4 else { return "" }
       let start = string.index(string.startIndex, offsetBy: 2)
       let end = string.index(string.endIndex, offsetBy: -2)
-      return String(string[start..<end]).trim(character: " ")
+      let trimmed = String(string[start..<end])
+        .components(separatedBy: "\n")
+        .filter({ !$0.isEmpty })
+        .map({ $0.trim(character: " ") })
+        .joined(separator: " ")
+      return trimmed
     }
 
-    if string.hasPrefix("{{") {
-      return .variable(value: strip())
-    } else if string.hasPrefix("{%") {
-      return .block(value: strip())
-    } else if string.hasPrefix("{#") {
-      return .comment(value: strip())
+    if string.hasPrefix("{{") || string.hasPrefix("{%") || string.hasPrefix("{#") {
+      let value = strip()
+      let range = templateString.range(of: value, range: range) ?? range
+      let line = templateString.rangeLine(range)
+      let sourceMap = SourceMap(filename: templateName, line: line)
+
+      if string.hasPrefix("{{") {
+        return .variable(value: value, at: sourceMap)
+      } else if string.hasPrefix("{%") {
+        return .block(value: value, at: sourceMap)
+      } else if string.hasPrefix("{#") {
+        return .comment(value: value, at: sourceMap)
+      }
     }
 
-    return .text(value: string)
+    let line = templateString.rangeLine(range)
+    let sourceMap = SourceMap(filename: templateName, line: line)
+    return .text(value: string, at: sourceMap)
   }
 
   /// Returns an array of tokens from a given template string.
@@ -34,33 +52,37 @@ struct Lexer {
       "{{": "}}",
       "{%": "%}",
       "{#": "#}",
-    ]
+      ]
 
     while !scanner.isEmpty {
       if let text = scanner.scan(until: ["{{", "{%", "{#"]) {
         if !text.1.isEmpty {
-          tokens.append(createToken(string: text.1))
+          tokens.append(createToken(string: text.1, at: scanner.range))
         }
 
         let end = map[text.0]!
         let result = scanner.scan(until: end, returnUntil: true)
-        tokens.append(createToken(string: result))
+        tokens.append(createToken(string: result, at: scanner.range))
       } else {
-        tokens.append(createToken(string: scanner.content))
+        tokens.append(createToken(string: scanner.content, at: scanner.range))
         scanner.content = ""
       }
     }
 
     return tokens
   }
+
 }
 
-
 class Scanner {
+  let originalContent: String
   var content: String
+  var range: Range<String.Index>
 
   init(_ content: String) {
+    self.originalContent = content
     self.content = content
+    range = content.startIndex..<content.startIndex
   }
 
   var isEmpty: Bool {
@@ -68,27 +90,31 @@ class Scanner {
   }
 
   func scan(until: String, returnUntil: Bool = false) -> String {
+    var index = content.startIndex
+
     if until.isEmpty {
       return ""
     }
 
-    var index = content.startIndex
+    range = range.upperBound..<range.upperBound
     while index != content.endIndex {
       let substring = content.substring(from: index)
 
       if substring.hasPrefix(until) {
         let result = content.substring(to: index)
-        content = substring
 
         if returnUntil {
-          content = content.substring(from: until.endIndex)
+          range = range.lowerBound..<originalContent.index(range.upperBound, offsetBy: until.characters.count)
+          content = substring.substring(from: until.endIndex)
           return result + until
         }
 
+        content = substring
         return result
       }
 
       index = content.index(after: index)
+      range = range.lowerBound..<originalContent.index(after: range.upperBound)
     }
 
     content = ""
@@ -101,6 +127,7 @@ class Scanner {
     }
 
     var index = content.startIndex
+    range = range.upperBound..<range.upperBound
     while index != content.endIndex {
       let substring = content.substring(from: index)
       for string in until {
@@ -112,6 +139,7 @@ class Scanner {
       }
 
       index = content.index(after: index)
+      range = range.lowerBound..<originalContent.index(after: range.upperBound)
     }
 
     return nil
@@ -151,4 +179,23 @@ extension String {
     let last = findLastNot(character: character) ?? endIndex
     return String(self[first..<last])
   }
+
+  public func rangeLine(_ range: Range<String.Index>) -> RangeLine {
+    var lineNumber: UInt = 0
+    var offset: Int = 0
+    var lineContent = ""
+
+    for line in components(separatedBy: CharacterSet.newlines) {
+      lineNumber += 1
+      lineContent = line
+      if let rangeOfLine = self.range(of: line), rangeOfLine.contains(range.lowerBound) {
+        offset = distance(from: rangeOfLine.lowerBound, to: range.lowerBound)
+        break
+      }
+    }
+
+    return (lineContent, lineNumber, offset)
+  }
 }
+
+public typealias RangeLine = (content: String, number: UInt, offset: Int)

Sources/Node.swift

@@ -1,35 +1,31 @@
 import Foundation
 
-
-public struct TemplateSyntaxError : Error, Equatable, CustomStringConvertible {
-  public let description:String
-
-  public init(_ description:String) {
-    self.description = description
-  }
-}
-
-
-public func ==(lhs:TemplateSyntaxError, rhs:TemplateSyntaxError) -> Bool {
-  return lhs.description == rhs.description
-}
-
-
 public protocol NodeType {
   /// Render the node in the given context
   func render(_ context:Context) throws -> String
+
+  /// Reference to this node's token
+  var token: Token? { get }
 }
 
 
 /// Render the collection of nodes in the given context
 public func renderNodes(_ nodes:[NodeType], _ context:Context) throws -> String {
-  return try nodes.map { try $0.render(context) }.joined(separator: "")
+  return try nodes.map {
+    do {
+      return try $0.render(context)
+    } catch {
+      throw error.withToken($0.token)
+    }
+    }.joined(separator: "")
 }
 
 public class SimpleNode : NodeType {
   public let handler:(Context) throws -> String
+  public let token: Token?
 
-  public init(handler: @escaping (Context) throws -> String) {
+  public init(token: Token, handler: @escaping (Context) throws -> String) {
+    self.token = token
     self.handler = handler
   }
 
@@ -41,9 +37,11 @@ public class SimpleNode : NodeType {
 
 public class TextNode : NodeType {
   public let text:String
+  public let token: Token?
 
   public init(text:String) {
     self.text = text
+    self.token = nil
   }
 
   public func render(_ context:Context) throws -> String {
@@ -59,13 +57,16 @@ public protocol Resolvable {
 
 public class VariableNode : NodeType {
   public let variable: Resolvable
+  public var token: Token?
 
-  public init(variable: Resolvable) {
+  public init(variable: Resolvable, token: Token? = nil) {
     self.variable = variable
+    self.token = token
   }
 
-  public init(variable: String) {
+  public init(variable: String, token: Token? = nil) {
     self.variable = Variable(variable)
+    self.token = token
   }
 
   public func render(_ context: Context) throws -> String {
@@ -78,6 +79,8 @@ public class VariableNode : NodeType {
 func stringify(_ result: Any?) -> String {
   if let result = result as? String {
     return result
+  } else if let array = result as? [Any?] {
+    return unwrap(array).description
   } else if let result = result as? CustomStringConvertible {
     return result.description
   } else if let result = result as? NSObject {
@@ -86,3 +89,16 @@ func stringify(_ result: Any?) -> String {
 
   return ""
 }
+
+func unwrap(_ array: [Any?]) -> [Any] {
+  return array.map { (item: Any?) -> Any in
+    if let item = item {
+      if let items = item as? [Any?] {
+        return unwrap(items)
+      } else {
+        return item
+      }
+    }
+    else { return item as Any }
+  }
+}

Sources/NowTag.swift

@@ -4,23 +4,25 @@ import Foundation
 
 class NowNode : NodeType {
   let format:Variable
+  let token: Token?
 
   class func parse(_ parser:TokenParser, token:Token) throws -> NodeType {
     var format:Variable?
 
     let components = token.components()
     guard components.count <= 2 else {
-      throw TemplateSyntaxError("'now' tags may only have one argument: the format string `\(token.contents)`.")
+      throw TemplateSyntaxError("'now' tags may only have one argument: the format string.")
     }
     if components.count == 2 {
       format = Variable(components[1])
     }
 
-    return NowNode(format:format)
+    return NowNode(format:format, token: token)
   }
 
-  init(format:Variable?) {
+  init(format:Variable?, token: Token? = nil) {
     self.format = format ?? Variable("\"yyyy-MM-dd 'at' HH:mm\"")
+    self.token = token
   }
 
   func render(_ context: Context) throws -> String {

Sources/Parser.swift

@@ -37,10 +37,11 @@ public class TokenParser {
       let token = nextToken()!
 
       switch token {
-      case .text(let text):
+      case .text(let text, _):
         nodes.append(TextNode(text: text))
       case .variable:
-        nodes.append(VariableNode(variable: try compileFilter(token.contents)))
+        let filter = try compileResolvable(token.contents, containedIn: token)
+        nodes.append(VariableNode(variable: filter, token: token))
       case .block:
         if let parse_until = parse_until , parse_until(self, token) {
           prependToken(token)
@@ -48,8 +49,13 @@ public class TokenParser {
         }
 
         if let tag = token.components().first {
-          let parser = try findTag(name: tag)
-          nodes.append(try parser(self, token))
+          do {
+            let parser = try findTag(name: tag)
+            let node = try parser(self, token)
+            nodes.append(node)
+          } catch {
+            throw error.withToken(token)
+          }
         }
       case .comment:
         continue
@@ -88,11 +94,103 @@ public class TokenParser {
       }
     }
 
-    throw TemplateSyntaxError("Unknown filter '\(name)'")
+    let suggestedFilters = self.suggestedFilters(for: name)
+    if suggestedFilters.isEmpty {
+      throw TemplateSyntaxError("Unknown filter '\(name)'.")
+    } else {
+      throw TemplateSyntaxError("Unknown filter '\(name)'. Found similar filters: \(suggestedFilters.map({ "'\($0)'" }).joined(separator: ", ")).")
+    }
   }
 
+  private func suggestedFilters(for name: String) -> [String] {
+    let allFilters = environment.extensions.flatMap({ $0.filters.keys })
+
+    let filtersWithDistance = allFilters
+                .map({ (filterName: $0, distance: $0.levenshteinDistance(name)) })
+                // do not suggest filters which names are shorter than the distance
+                .filter({ $0.filterName.characters.count > $0.distance })
+    guard let minDistance = filtersWithDistance.min(by: { $0.distance < $1.distance })?.distance else {
+      return []
+    }
+    // suggest all filters with the same distance
+    return filtersWithDistance.filter({ $0.distance == minDistance }).map({ $0.filterName })
+  }
+
+  public func compileFilter(_ filterToken: String, containedIn containingToken: Token) throws -> Resolvable {
+    do {
+      return try FilterExpression(token: filterToken, parser: self)
+    } catch {
+      guard var syntaxError = error as? TemplateSyntaxError, syntaxError.token == nil else {
+        throw error
+      }
+      // find offset of filter in the containing token so that only filter is highligted, not the whole token
+      if let filterTokenRange = containingToken.contents.range(of: filterToken) {
+        var rangeLine = containingToken.sourceMap.line
+        rangeLine.offset += containingToken.contents.distance(from: containingToken.contents.startIndex, to: filterTokenRange.lowerBound)
+        syntaxError.token = .variable(value: filterToken, at: SourceMap(filename: containingToken.sourceMap.filename, line: rangeLine))
+      } else {
+        syntaxError.token = containingToken
+      }
+      throw syntaxError
+    }
+  }
+
+  @available(*, deprecated, message: "Use compileFilter(_:containedIn:)")
   public func compileFilter(_ token: String) throws -> Resolvable {
     return try FilterExpression(token: token, parser: self)
   }
 
+  @available(*, deprecated, message: "Use compileResolvable(_:containedIn:)")
+  public func compileResolvable(_ token: String) throws -> Resolvable {
+    return try RangeVariable(token, parser: self)
+      ?? compileFilter(token)
+  }
+
+  public func compileResolvable(_ token: String, containedIn containingToken: Token) throws -> Resolvable {
+    return try RangeVariable(token, parser: self, containedIn: containingToken)
+        ?? compileFilter(token, containedIn: containingToken)
+  }
+
+}
+
+// https://en.wikipedia.org/wiki/Levenshtein_distance#Iterative_with_two_matrix_rows
+extension String {
+
+  subscript(_ i: Int) -> Character {
+    return self[self.index(self.startIndex, offsetBy: i)]
+  }
+
+  func levenshteinDistance(_ target: String) -> Int {
+    // create two work vectors of integer distances
+    var last, current: [Int]
+
+    // initialize v0 (the previous row of distances)
+    // this row is A[0][i]: edit distance for an empty s
+    // the distance is just the number of characters to delete from t
+    last = [Int](0...target.characters.count)
+    current = [Int](repeating: 0, count: target.characters.count + 1)
+
+    for i in 0..<self.characters.count {
+      // calculate v1 (current row distances) from the previous row v0
+
+      // first element of v1 is A[i+1][0]
+      //   edit distance is delete (i+1) chars from s to match empty t
+      current[0] = i + 1
+
+      // use formula to fill in the rest of the row
+      for j in 0..<target.characters.count {
+        current[j+1] = Swift.min(
+          last[j+1] + 1,
+          current[j] + 1,
+          last[j] + (self[i] == target[j] ? 0 : 1)
+        )
+      }
+
+      // copy v1 (current row) to v0 (previous row) for next iteration
+      last = current
+    }
+
+    return current[target.characters.count]
+  }
+
 }

Sources/Template.swift

@@ -7,7 +7,8 @@ let NSFileNoSuchFileError = 4
 
 /// A class representing a template
 open class Template: ExpressibleByStringLiteral {
-  let environment: Environment
+  let templateString: String
+  internal(set) var environment: Environment
   let tokens: [Token]
 
   /// The name of the loaded Template if the Template was loaded from a Loader
@@ -17,8 +18,9 @@ open class Template: ExpressibleByStringLiteral {
   public required init(templateString: String, environment: Environment? = nil, name: String? = nil) {
     self.environment = environment ?? Environment()
     self.name = name
+    self.templateString = templateString
 
-    let lexer = Lexer(templateString: templateString)
+    let lexer = Lexer(templateName: name, templateString: templateString)
     tokens = lexer.tokenize()
   }
 

Sources/Tokenizer.swift

@@ -10,6 +10,21 @@ extension String {
     var singleQuoteCount = 0
     var doubleQuoteCount = 0
 
+    let specialCharacters = ",|:"
+    func appendWord(_ word: String) {
+      if components.count > 0 {
+        if let precedingChar = components.last?.characters.last, specialCharacters.characters.contains(precedingChar) {
+          components[components.count-1] += word
+        } else if specialCharacters.contains(word) {
+          components[components.count-1] += word
+        } else {
+          components.append(word)
+        }
+      } else {
+        components.append(word)
+      }
+    }
+
     for character in self.characters {
       if character == "'" { singleQuoteCount += 1 }
       else if character == "\"" { doubleQuoteCount += 1 }
@@ -18,8 +33,8 @@ extension String {
 
         if separate != separator {
           word.append(separate)
-        } else if singleQuoteCount % 2 == 0 && doubleQuoteCount % 2 == 0 && !word.isEmpty {
-          components.append(word)
+        } else if (singleQuoteCount % 2 == 0 || doubleQuoteCount % 2 == 0) && !word.isEmpty {
+          appendWord(word)
           word = ""
         }
 
@@ -33,66 +48,86 @@ extension String {
     }
 
     if !word.isEmpty {
-      components.append(word)
+      appendWord(word)
     }
 
     return components
   }
 }
 
+public struct SourceMap: Equatable {
+  public let filename: String?
+  public let line: RangeLine
+
+  init(filename: String? = nil, line: RangeLine = ("", 0, 0)) {
+    self.filename = filename
+    self.line = line
+  }
+
+  static let unknown = SourceMap()
+
+  public static func ==(lhs: SourceMap, rhs: SourceMap) -> Bool {
+    return lhs.filename == rhs.filename && lhs.line == rhs.line
+  }
+}
 
 public enum Token : Equatable {
   /// A token representing a piece of text.
-  case text(value: String)
+  case text(value: String, at: SourceMap)
 
   /// A token representing a variable.
-  case variable(value: String)
+  case variable(value: String, at: SourceMap)
 
   /// A token representing a comment.
-  case comment(value: String)
+  case comment(value: String, at: SourceMap)
 
   /// A token representing a template block.
-  case block(value: String)
+  case block(value: String, at: SourceMap)
 
   /// Returns the underlying value as an array seperated by spaces
   public func components() -> [String] {
     switch self {
-    case .block(let value):
-      return value.smartSplit()
-    case .variable(let value):
-      return value.smartSplit()
-    case .text(let value):
-      return value.smartSplit()
-    case .comment(let value):
+    case .block(let value, _),
+         .variable(let value, _),
+         .text(let value, _),
+         .comment(let value, _):
       return value.smartSplit()
     }
   }
 
   public var contents: String {
     switch self {
-    case .block(let value):
-      return value
-    case .variable(let value):
-      return value
-    case .text(let value):
-      return value
-    case .comment(let value):
+    case .block(let value, _),
+         .variable(let value, _),
+         .text(let value, _),
+         .comment(let value, _):
       return value
     }
   }
+
+  public var sourceMap: SourceMap {
+    switch self {
+    case .block(_, let sourceMap),
+         .variable(_, let sourceMap),
+         .text(_, let sourceMap),
+         .comment(_, let sourceMap):
+      return sourceMap
+    }
+  }
+
 }
 
 
 public func == (lhs: Token, rhs: Token) -> Bool {
   switch (lhs, rhs) {
-  case (.text(let lhsValue), .text(let rhsValue)):
-    return lhsValue == rhsValue
-  case (.variable(let lhsValue), .variable(let rhsValue)):
-    return lhsValue == rhsValue
-  case (.block(let lhsValue), .block(let rhsValue)):
-    return lhsValue == rhsValue
-  case (.comment(let lhsValue), .comment(let rhsValue)):
-    return lhsValue == rhsValue
+  case let (.text(lhsValue, lhsAt), .text(rhsValue, rhsAt)):
+    return lhsValue == rhsValue && lhsAt == rhsAt
+  case let (.variable(lhsValue, lhsAt), .variable(rhsValue, rhsAt)):
+    return lhsValue == rhsValue && lhsAt == rhsAt
+  case let (.block(lhsValue, lhsAt), .block(rhsValue, rhsAt)):
+    return lhsValue == rhsValue && lhsAt == rhsAt
+  case let (.comment(lhsValue, lhsAt), .comment(rhsValue, rhsAt)):
+    return lhsValue == rhsValue && lhsAt == rhsAt
   default:
     return false
   }

Sources/Variable.swift

@@ -11,8 +11,6 @@ class FilterExpression : Resolvable {
   init(token: String, parser: TokenParser) throws {
     let bits = token.characters.split(separator: "|").map({ String($0).trim(character: " ") })
     if bits.isEmpty {
-      filters = []
-      variable = Variable("")
       throw TemplateSyntaxError("Variable tags must include at least 1 argument")
     }
 
@@ -50,8 +48,10 @@ public struct Variable : Equatable, Resolvable {
     self.variable = variable
   }
 
-  fileprivate func lookup() -> [String] {
-    return variable.characters.split(separator: ".").map(String.init)
+  // Split the lookup string and resolve references if possible
+  fileprivate func lookup(_ context: Context) throws -> [String] {
+    let keyPath = KeyPath(variable, in: context)
+    return try keyPath.parse()
   }
 
   /// Resolve the variable in the given context
@@ -60,15 +60,22 @@ public struct Variable : Equatable, Resolvable {
 
     if (variable.hasPrefix("'") && variable.hasSuffix("'")) || (variable.hasPrefix("\"") && variable.hasSuffix("\"")) {
       // String literal
-      return variable[variable.characters.index(after: variable.startIndex) ..< variable.characters.index(before: variable.endIndex)]
+      return String(variable[variable.characters.index(after: variable.startIndex) ..< variable.characters.index(before: variable.endIndex)])
     }
 
+    // Number literal
+    if let int = Int(variable) {
+      return int
+    }
     if let number = Number(variable) {
-      // Number literal
       return number
     }
+    // Boolean literal
+    if let bool = Bool(variable) {
+      return bool
+    }
 
-    for bit in lookup() {
+    for bit in try lookup(context) {
       current = normalize(current)
 
       if let context = current as? Context {
@@ -94,20 +101,14 @@ public struct Variable : Equatable, Resolvable {
           current = array.count
         }
       } else if let object = current as? NSObject {  // NSKeyValueCoding
-#if os(Linux)
-        return nil
-#else
-        current = object.value(forKey: bit)
-#endif
-      } else if let value = current {
-        let mirror = Mirror(reflecting: value)
-        current = mirror.descendant(bit)
-
-        if current == nil {
+        #if os(Linux)
           return nil
-          // mirror returns non-nil value even for nil-containing properties
-          // so we have to check if its value is actually nil or not
-        } else if let current = current, String(describing: current) == "nil" {
+        #else
+          current = object.value(forKey: bit)
+        #endif
+      } else if let value = current {
+        current = Mirror(reflecting: value).getValue(for: bit)
+        if current == nil {
           return nil
         }
       } else {
@@ -129,6 +130,53 @@ public func ==(lhs: Variable, rhs: Variable) -> Bool {
   return lhs.variable == rhs.variable
 }
 
+/// A structure used to represet range of two integer values expressed as `from...to`.
+/// Values should be numbers (they will be converted to integers).
+/// Rendering this variable produces array from range `from...to`.
+/// If `from` is more than `to` array will contain values of reversed range.
+public struct RangeVariable: Resolvable {
+  public let from: Resolvable
+  public let to: Resolvable
+
+  @available(*, deprecated, message: "Use init?(_:parser:containedIn:)")
+  public init?(_ token: String, parser: TokenParser) throws {
+    let components = token.components(separatedBy: "...")
+    guard components.count == 2 else {
+      return nil
+    }
+
+    self.from = try parser.compileFilter(components[0])
+    self.to = try parser.compileFilter(components[1])
+  }
+
+  public init?(_ token: String, parser: TokenParser, containedIn containingToken: Token) throws {
+    let components = token.components(separatedBy: "...")
+    guard components.count == 2 else {
+      return nil
+    }
+
+    self.from = try parser.compileFilter(components[0], containedIn: containingToken)
+    self.to = try parser.compileFilter(components[1], containedIn: containingToken)
+  }
+
+  public func resolve(_ context: Context) throws -> Any? {
+    let fromResolved = try from.resolve(context)
+    let toResolved = try to.resolve(context)
+
+    guard let from = fromResolved.flatMap(toNumber(value:)).flatMap(Int.init) else {
+      throw TemplateSyntaxError("'from' value is not an Integer (\(fromResolved ?? "nil"))")
+    }
+
+    guard let to = toResolved.flatMap(toNumber(value:)).flatMap(Int.init) else {
+      throw TemplateSyntaxError("'to' value is not an Integer (\(toResolved ?? "nil") )")
+    }
+
+    let range = min(from, to)...max(from, to)
+    return from > to ? Array(range.reversed()) : Array(range)
+  }
+
+}
+
 
 func normalize(_ current: Any?) -> Any? {
   if let current = current as? Normalizable {
@@ -172,10 +220,47 @@ extension Dictionary : Normalizable {
 
 func parseFilterComponents(token: String) -> (String, [Variable]) {
   var components = token.smartSplit(separator: ":")
-  let name = components.removeFirst()
+  let name = components.removeFirst().trim(character: " ")
   let variables = components
     .joined(separator: ":")
     .smartSplit(separator: ",")
-    .map { Variable($0) }
+    .map { Variable($0.trim(character: " ")) }
   return (name, variables)
 }
+
+extension Mirror {
+  func getValue(for key: String) -> Any? {
+    let result = descendant(key) ?? Int(key).flatMap({ descendant($0) })
+    if result == nil {
+      // go through inheritance chain to reach superclass properties
+      return superclassMirror?.getValue(for: key)
+    } else if let result = result {
+      guard String(describing: result) != "nil" else {
+        // mirror returns non-nil value even for nil-containing properties
+        // so we have to check if its value is actually nil or not
+        return nil
+      }
+      if let result = (result as? AnyOptional)?.wrapped {
+        return result
+      } else {
+        return result
+      }
+    }
+    return result
+  }
+}
+
+protocol AnyOptional {
+  var wrapped: Any? { get }
+}
+
+extension Optional: AnyOptional {
+  var wrapped: Any? {
+    switch self {
+    case let .some(value): return value
+    case .none: return nil
+    }
+  }
+}
+
+

Stencil.podspec.json

@@ -1,6 +1,6 @@
 {
   "name": "Stencil",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "summary": "Stencil is a simple and powerful template language for Swift.",
   "homepage": "https://stencil.fuller.li",
   "license": {
@@ -12,8 +12,8 @@
   },
   "social_media_url": "https://twitter.com/kylefuller",
   "source": {
-    "git": "https://github.com/kylef/Stencil.git",
-    "tag": "0.10.1"
+    "git": "https://github.com/stencilproject/Stencil.git",
+    "tag": "0.12.0"
   },
   "source_files": [
     "Sources/*.swift"
@@ -25,6 +25,8 @@
   },
   "requires_arc": true,
   "dependencies": {
-    "PathKit": [ "~> 0.8.0" ]
+    "PathKit": [
+      "~> 0.8.0"
+    ]
   }
 }

Tests/StencilTests/EnvironmentSpec.swift

@@ -1,10 +1,17 @@
 import Spectre
-import Stencil
+import PathKit
+@testable import Stencil
 
 
 func testEnvironment() {
   describe("Environment") {
-    let environment = Environment(loader: ExampleLoader())
+    var environment: Environment!
+    var template: Template!
+    
+    $0.before {
+      environment =  Environment(loader: ExampleLoader())
+      template = nil
+    }
 
     $0.it("can load a template from a name") {
       let template = try environment.loadTemplate(name: "example.html")
@@ -32,9 +39,309 @@ func testEnvironment() {
 
       try expect(result) == "here"
     }
+
+    func expectedSyntaxError(token: String, template: Template, description: String) -> TemplateSyntaxError {
+      guard let range = template.templateString.range(of: token) else {
+        fatalError("Can't find '\(token)' in '\(template)'")
+      }
+      let rangeLine = template.templateString.rangeLine(range)
+      let sourceMap = SourceMap(filename: template.name, line: rangeLine)
+      let token = Token.block(value: token, at: sourceMap)
+      return TemplateSyntaxError(reason: description, token: token, stackTrace: [])
+    }
+
+    func expectError(reason: String, token: String,
+                     file: String = #file, line: Int = #line, function: String = #function) throws {
+      let expectedError = expectedSyntaxError(token: token, template: template, description: reason)
+      
+      let error = try expect(environment.render(template: template, context: ["names": ["Bob", "Alice"], "name": "Bob"]),
+                             file: file, line: line, function: function).toThrow() as TemplateSyntaxError
+      let reporter = SimpleErrorReporter()
+      try expect(reporter.renderError(error), file: file, line: line, function: function) == reporter.renderError(expectedError)
+    }
+
+    $0.context("given syntax error") {
+
+      $0.it("reports syntax error on invalid for tag syntax") {
+        template = "Hello {% for name in %}{{ name }}, {% endfor %}!"
+        try expectError(reason: "'for' statements should use the syntax: `for <x> in <y> [where <condition>]`.", token: "for name in")
+      }
+      
+      $0.it("reports syntax error on missing endfor") {
+        template = "{% for name in names %}{{ name }}"
+        try expectError(reason: "`endfor` was not found.", token: "for name in names")
+      }
+      
+      $0.it("reports syntax error on unknown tag") {
+        template = "{% for name in names %}{{ name }}{% end %}"
+        try expectError(reason: "Unknown template tag 'end'", token: "end")
+      }
+
+    }
+    
+    $0.context("given unknown filter") {
+      
+      $0.it("reports syntax error in for tag") {
+        template = "{% for name in names|unknown %}{{ name }}{% endfor %}"
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.", token: "names|unknown")
+      }
+      
+      $0.it("reports syntax error in for-where tag") {
+        template = "{% for name in names where name|unknown %}{{ name }}{% endfor %}"
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.", token: "name|unknown")
+      }
+      
+      $0.it("reports syntax error in if tag") {
+        template = "{% if name|unknown %}{{ name }}{% endif %}"
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.", token: "name|unknown")
+      }
+      
+      $0.it("reports syntax error in elif tag") {
+        template = "{% if name %}{{ name }}{% elif name|unknown %}{% endif %}"
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.", token: "name|unknown")
+      }
+      
+      $0.it("reports syntax error in ifnot tag") {
+        template = "{% ifnot name|unknown %}{{ name }}{% endif %}"
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.", token: "name|unknown")
+      }
+      
+      $0.it("reports syntax error in filter tag") {
+        template = "{% filter unknown %}Text{% endfilter %}"
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.", token: "filter unknown")
+      }
+      
+      $0.it("reports syntax error in variable tag") {
+        template = "{{ name|unknown }}"
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.", token: "name|unknown")
+      }
+      
+    }
+    
+    $0.context("given rendering error") {
+      
+      $0.it("reports rendering error in variable filter") {
+        let filterExtension = Extension()
+        filterExtension.registerFilter("throw") { (value: Any?) in
+          throw TemplateSyntaxError("filter error")
+        }
+        environment.extensions += [filterExtension]
+
+        template = Template(templateString: "{{ name|throw }}", environment: environment)
+        try expectError(reason: "filter error", token: "name|throw")
+      }
+      
+      $0.it("reports rendering error in filter tag") {
+        let filterExtension = Extension()
+        filterExtension.registerFilter("throw") { (value: Any?) in
+          throw TemplateSyntaxError("filter error")
+        }
+        environment.extensions += [filterExtension]
+
+        template = Template(templateString: "{% filter throw %}Test{% endfilter %}", environment: environment)
+        try expectError(reason: "filter error", token: "filter throw")
+      }
+      
+      $0.it("reports rendering error in simple tag") {
+        let tagExtension = Extension()
+        tagExtension.registerSimpleTag("simpletag") { context in
+          throw TemplateSyntaxError("simpletag error")
+        }
+        environment.extensions += [tagExtension]
+
+        template = Template(templateString: "{% simpletag %}", environment: environment)
+        try expectError(reason: "simpletag error", token: "simpletag")
+      }
+      
+      $0.it("reporsts passing argument to simple filter") {
+        template = "{{ name|uppercase:5 }}"
+        try expectError(reason: "cannot invoke filter with an argument", token: "name|uppercase:5")
+      }
+      
+      $0.it("reports rendering error in custom tag") {
+        let tagExtension = Extension()
+        tagExtension.registerTag("customtag") { parser, token in
+          return ErrorNode(token: token)
+        }
+        environment.extensions += [tagExtension]
+        
+        template = Template(templateString: "{% customtag %}", environment: environment)
+        try expectError(reason: "Custom Error", token: "customtag")
+      }
+      
+      $0.it("reports rendering error in for body") {
+        let tagExtension = Extension()
+        tagExtension.registerTag("customtag") { parser, token in
+          return ErrorNode(token: token)
+        }
+        environment.extensions += [tagExtension]
+
+        template = Template(templateString: "{% for name in names %}{% customtag %}{% endfor %}", environment: environment)
+        try expectError(reason: "Custom Error", token: "customtag")
+      }
+      
+      $0.it("reports rendering error in block") {
+        let tagExtension = Extension()
+        tagExtension.registerTag("customtag") { parser, token in
+          return ErrorNode(token: token)
+        }
+        environment.extensions += [tagExtension]
+
+        template = Template(templateString: "{% block some %}{% customtag %}{% endblock %}", environment: environment)
+        try expectError(reason: "Custom Error", token: "customtag")
+      }
+    }
+    
+    $0.context("given included template") {
+      let path = Path(#file) + ".." + "fixtures"
+      let loader = FileSystemLoader(paths: [path])
+      var environment = Environment(loader: loader)
+      var template: Template!
+      var includedTemplate: Template!
+      
+      $0.before {
+        environment = Environment(loader: loader)
+        template = nil
+        includedTemplate = nil
+      }
+      
+      func expectError(reason: String, token: String, includedToken: String,
+                       file: String = #file, line: Int = #line, function: String = #function) throws {
+        var expectedError = expectedSyntaxError(token: token, template: template, description: reason)
+        expectedError.stackTrace = [expectedSyntaxError(token: includedToken, template: includedTemplate, description: reason).token!]
+        
+        let error = try expect(environment.render(template: template, context: ["target": "World"]),
+                               file: file, line: line, function: function).toThrow() as TemplateSyntaxError
+        let reporter = SimpleErrorReporter()
+        try expect(reporter.renderError(error), file: file, line: line, function: function) == reporter.renderError(expectedError)
+      }
+      
+      $0.it("reports syntax error in included template") {
+        template = Template(templateString: "{% include \"invalid-include.html\" %}", environment: environment)
+        includedTemplate = try environment.loadTemplate(name: "invalid-include.html")
+
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.",
+                        token: "include \"invalid-include.html\"",
+                        includedToken: "target|unknown")
+      }
+      
+      $0.it("reports runtime error in included template") {
+        let filterExtension = Extension()
+        filterExtension.registerFilter("unknown", filter: {  (_: Any?) in
+          throw TemplateSyntaxError("filter error")
+        })
+        environment.extensions += [filterExtension]
+        
+        template = Template(templateString: "{% include \"invalid-include.html\" %}", environment: environment)
+        includedTemplate = try environment.loadTemplate(name: "invalid-include.html")
+
+        try expectError(reason: "filter error",
+                        token: "include \"invalid-include.html\"",
+                        includedToken: "target|unknown")
+      }
+      
+    }
+    
+    $0.context("given base and child templates") {
+      let path = Path(#file) + ".." + "fixtures"
+      let loader = FileSystemLoader(paths: [path])
+      var environment: Environment!
+      var childTemplate: Template!
+      var baseTemplate: Template!
+
+      $0.before {
+        environment = Environment(loader: loader)
+        childTemplate = nil
+        baseTemplate = nil
+      }
+      
+      func expectError(reason: String, childToken: String, baseToken: String?,
+                       file: String = #file, line: Int = #line, function: String = #function) throws {
+        var expectedError = expectedSyntaxError(token: childToken, template: childTemplate, description: reason)
+        if let baseToken = baseToken {
+          expectedError.stackTrace = [expectedSyntaxError(token: baseToken, template: baseTemplate, description: reason).token!]
+        }
+        let error = try expect(environment.render(template: childTemplate, context: ["target": "World"]),
+                               file: file, line: line, function: function).toThrow() as TemplateSyntaxError
+        let reporter = SimpleErrorReporter()
+        try expect(reporter.renderError(error), file: file, line: line, function: function) == reporter.renderError(expectedError)
+      }
+
+      $0.it("reports syntax error in base template") {
+        childTemplate = try environment.loadTemplate(name: "invalid-child-super.html")
+        baseTemplate = try environment.loadTemplate(name: "invalid-base.html")
+        
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.",
+                        childToken: "extends \"invalid-base.html\"",
+                        baseToken: "target|unknown")
+      }
+      
+      $0.it("reports runtime error in base template") {
+        let filterExtension = Extension()
+        filterExtension.registerFilter("unknown", filter: {  (_: Any?) in
+          throw TemplateSyntaxError("filter error")
+        })
+        environment.extensions += [filterExtension]
+
+        childTemplate = try environment.loadTemplate(name: "invalid-child-super.html")
+        baseTemplate = try environment.loadTemplate(name: "invalid-base.html")
+
+        try expectError(reason: "filter error",
+                        childToken: "block.super",
+                        baseToken: "target|unknown")
+      }
+      
+      $0.it("reports syntax error in child template") {
+        childTemplate = Template(templateString: "{% extends \"base.html\" %}\n" +
+          "{% block body %}Child {{ target|unknown }}{% endblock %}", environment: environment, name: nil)
+        
+        try expectError(reason: "Unknown filter 'unknown'. Found similar filters: 'uppercase'.",
+                        childToken: "target|unknown",
+                        baseToken: nil)
+      }
+      
+      $0.it("reports runtime error in child template") {
+        let filterExtension = Extension()
+        filterExtension.registerFilter("unknown", filter: {  (_: Any?) in
+          throw TemplateSyntaxError("filter error")
+        })
+        environment.extensions += [filterExtension]
+
+        childTemplate = Template(templateString: "{% extends \"base.html\" %}\n" +
+          "{% block body %}Child {{ target|unknown }}{% endblock %}", environment: environment, name: nil)
+
+        try expectError(reason: "filter error",
+                        childToken: "target|unknown",
+                        baseToken: nil)
+      }
+      
+    }
+    
   }
 }
 
+extension Expectation {
+  @discardableResult
+  func toThrow<T: Error>() throws -> T {
+    var thrownError: Error? = nil
+    
+    do {
+      _ = try expression()
+    } catch {
+      thrownError = error
+    }
+    
+    if let thrownError = thrownError {
+      if let thrownError = thrownError as? T {
+        return thrownError
+      } else {
+        throw failure("\(thrownError) is not \(T.self)")
+      }
+    } else {
+      throw failure("expression did not throw an error")
+    }
+  }
+}
 
 fileprivate class ExampleLoader: Loader {
   func loadTemplate(name: String, environment: Environment) throws -> Template {

Tests/StencilTests/ExpressionSpec.swift

@@ -105,19 +105,19 @@ func testExpressions() {
 
     $0.describe("expression parsing") {
       $0.it("can parse a variable expression") {
-        let expression = try parseExpression(components: ["value"], tokenParser: parser)
+        let expression = try parseExpression(components: ["value"], tokenParser: parser, token: .text(value: "", at: .unknown))
         try expect(expression.evaluate(context: Context())).to.beFalse()
         try expect(expression.evaluate(context: Context(dictionary: ["value": true]))).to.beTrue()
       }
 
       $0.it("can parse a not expression") {
-        let expression = try parseExpression(components: ["not", "value"], tokenParser: parser)
+        let expression = try parseExpression(components: ["not", "value"], tokenParser: parser, token: .text(value: "", at: .unknown))
         try expect(expression.evaluate(context: Context())).to.beTrue()
         try expect(expression.evaluate(context: Context(dictionary: ["value": true]))).to.beFalse()
       }
 
       $0.describe("and expression") {
-        let expression = try! parseExpression(components: ["lhs", "and", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", "and", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to false with lhs false") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": false, "rhs": true]))).to.beFalse()
@@ -137,7 +137,7 @@ func testExpressions() {
       }
 
       $0.describe("or expression") {
-        let expression = try! parseExpression(components: ["lhs", "or", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", "or", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to true with lhs true") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": true, "rhs": false]))).to.beTrue()
@@ -157,7 +157,7 @@ func testExpressions() {
       }
 
       $0.describe("equality expression") {
-        let expression = try! parseExpression(components: ["lhs", "==", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", "==", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to true with equal lhs/rhs") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": "a", "rhs": "a"]))).to.beTrue()
@@ -193,7 +193,7 @@ func testExpressions() {
       }
 
       $0.describe("inequality expression") {
-        let expression = try! parseExpression(components: ["lhs", "!=", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", "!=", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to true with inequal lhs/rhs") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": "a", "rhs": "b"]))).to.beTrue()
@@ -205,7 +205,7 @@ func testExpressions() {
       }
 
       $0.describe("more than expression") {
-        let expression = try! parseExpression(components: ["lhs", ">", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", ">", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to true with lhs > rhs") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": 5.0, "rhs": 4]))).to.beTrue()
@@ -217,7 +217,7 @@ func testExpressions() {
       }
 
       $0.describe("more than equal expression") {
-        let expression = try! parseExpression(components: ["lhs", ">=", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", ">=", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to true with lhs == rhs") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": 5.0, "rhs": 5]))).to.beTrue()
@@ -229,7 +229,7 @@ func testExpressions() {
       }
 
       $0.describe("less than expression") {
-        let expression = try! parseExpression(components: ["lhs", "<", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", "<", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to true with lhs < rhs") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": 4, "rhs": 4.5]))).to.beTrue()
@@ -241,7 +241,7 @@ func testExpressions() {
       }
 
       $0.describe("less than equal expression") {
-        let expression = try! parseExpression(components: ["lhs", "<=", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", "<=", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to true with lhs == rhs") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": 5.0, "rhs": 5]))).to.beTrue()
@@ -253,7 +253,7 @@ func testExpressions() {
       }
 
       $0.describe("multiple expression") {
-        let expression = try! parseExpression(components: ["one", "or", "two", "and", "not", "three"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["one", "or", "two", "and", "not", "three"], tokenParser: parser, token: .text(value: "", at: .unknown))
 
         $0.it("evaluates to true with one") {
           try expect(expression.evaluate(context: Context(dictionary: ["one": true]))).to.beTrue()
@@ -281,18 +281,22 @@ func testExpressions() {
       }
       
       $0.describe("in expression") {
-        let expression = try! parseExpression(components: ["lhs", "in", "rhs"], tokenParser: parser)
+        let expression = try! parseExpression(components: ["lhs", "in", "rhs"], tokenParser: parser, token: .text(value: "", at: .unknown))
         
         $0.it("evaluates to true when rhs contains lhs") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": 1, "rhs": [1, 2, 3]]))).to.beTrue()
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": "a", "rhs": ["a", "b", "c"]]))).to.beTrue()
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": "a", "rhs": "abc"]))).to.beTrue()
+          try expect(expression.evaluate(context: Context(dictionary: ["lhs": 1, "rhs": 1...3]))).to.beTrue()
+          try expect(expression.evaluate(context: Context(dictionary: ["lhs": 1, "rhs": 1..<3]))).to.beTrue()
         }
         
         $0.it("evaluates to false when rhs does not contain lhs") {
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": 1, "rhs": [2, 3, 4]]))).to.beFalse()
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": "a", "rhs": ["b", "c", "d"]]))).to.beFalse()
           try expect(expression.evaluate(context: Context(dictionary: ["lhs": "a", "rhs": "bcd"]))).to.beFalse()
+          try expect(expression.evaluate(context: Context(dictionary: ["lhs": 4, "rhs": 1...3]))).to.beFalse()
+          try expect(expression.evaluate(context: Context(dictionary: ["lhs": 3, "rhs": 1..<3]))).to.beFalse()
         }
       }
     }

Tests/StencilTests/FilterSpec.swift

@@ -62,7 +62,7 @@ func testFilter() {
       }
 
       let context = Context(dictionary: context, environment: Environment(extensions: [repeatExtension]))
-      try expect(try template.render(context)).toThrow(TemplateSyntaxError("No Repeat"))
+      try expect(try template.render(context)).toThrow(TemplateSyntaxError(reason: "No Repeat", token: template.tokens.first))
     }
 
     $0.it("allows you to override a default filter") {
@@ -78,9 +78,9 @@ func testFilter() {
     }
 
     $0.it("allows whitespace in expression") {
-      let template = Template(templateString: "{{ name | uppercase }}")
-      let result = try template.render(Context(dictionary: ["name": "kyle"]))
-      try expect(result) == "KYLE"
+      let template = Template(templateString: "{{ value | join : \", \" }}")
+      let result = try template.render(Context(dictionary: ["value": ["One", "Two"]]))
+      try expect(result) == "One, Two"
     }
 
     $0.it("throws when you pass arguments to simple filter") {
@@ -89,32 +89,45 @@ func testFilter() {
     }
   }
 
+  describe("string filters") {
+    $0.context("given string") {
+      $0.it("transforms a string to be capitalized") {
+        let template = Template(templateString: "{{ name|capitalize }}")
+        let result = try template.render(Context(dictionary: ["name": "kyle"]))
+        try expect(result) == "Kyle"
+      }
 
-  describe("capitalize filter") {
-    let template = Template(templateString: "{{ name|capitalize }}")
+      $0.it("transforms a string to be uppercase") {
+        let template = Template(templateString: "{{ name|uppercase }}")
+        let result = try template.render(Context(dictionary: ["name": "kyle"]))
+        try expect(result) == "KYLE"
+      }
 
-    $0.it("capitalizes a string") {
-      let result = try template.render(Context(dictionary: ["name": "kyle"]))
-      try expect(result) == "Kyle"
+      $0.it("transforms a string to be lowercase") {
+        let template = Template(templateString: "{{ name|lowercase }}")
+        let result = try template.render(Context(dictionary: ["name": "Kyle"]))
+        try expect(result) == "kyle"
+      }
     }
-  }
 
+    $0.context("given array of strings") {
+      $0.it("transforms a string to be capitalized") {
+        let template = Template(templateString: "{{ names|capitalize }}")
+        let result = try template.render(Context(dictionary: ["names": ["kyle", "kyle"]]))
+        try expect(result) == "[\"Kyle\", \"Kyle\"]"
+      }
 
-  describe("uppercase filter") {
-    let template = Template(templateString: "{{ name|uppercase }}")
+      $0.it("transforms a string to be uppercase") {
+        let template = Template(templateString: "{{ names|uppercase }}")
+        let result = try template.render(Context(dictionary: ["names": ["kyle", "kyle"]]))
+        try expect(result) == "[\"KYLE\", \"KYLE\"]"
+      }
 
-    $0.it("transforms a string to be uppercase") {
-      let result = try template.render(Context(dictionary: ["name": "kyle"]))
-      try expect(result) == "KYLE"
-    }
-  }
-
-  describe("lowercase filter") {
-    let template = Template(templateString: "{{ name|lowercase }}")
-
-    $0.it("transforms a string to be lowercase") {
-      let result = try template.render(Context(dictionary: ["name": "Kyle"]))
-      try expect(result) == "kyle"
+      $0.it("transforms a string to be lowercase") {
+        let template = Template(templateString: "{{ names|lowercase }}")
+        let result = try template.render(Context(dictionary: ["names": ["Kyle", "Kyle"]]))
+        try expect(result) == "[\"kyle\", \"kyle\"]"
+      }
     }
   }
 
@@ -136,6 +149,26 @@ func testFilter() {
       let result = try template.render(Context(dictionary: [:]))
       try expect(result) == "Hello World"
     }
+
+    $0.it("can use int as default") {
+      let template = Template(templateString: "{{ value|default:1 }}")
+      let result = try template.render(Context(dictionary: [:]))
+      try expect(result) == "1"
+    }
+
+    $0.it("can use float as default") {
+      let template = Template(templateString: "{{ value|default:1.5 }}")
+      let result = try template.render(Context(dictionary: [:]))
+      try expect(result) == "1.5"
+    }
+
+    $0.it("checks for underlying nil value correctly") {
+      let template = Template(templateString: "Hello {{ user.name|default:\"anonymous\" }}")
+      let nilName: String? = nil
+      let user: [String: Any?] = ["name": nilName]
+      let result = try template.render(Context(dictionary: ["user": user]))
+      try expect(result) == "Hello anonymous"
+    }
   }
 
   describe("join filter") {
@@ -163,4 +196,98 @@ func testFilter() {
       try expect(result) == "OneTwo"
     }
   }
+
+  describe("split filter") {
+    let template = Template(templateString: "{{ value|split:\", \" }}")
+
+    $0.it("split a string into array") {
+      let result = try template.render(Context(dictionary: ["value": "One, Two"]))
+      try expect(result) == "[\"One\", \"Two\"]"
+    }
+
+    $0.it("can split without arguments") {
+      let template = Template(templateString: "{{ value|split }}")
+      let result = try template.render(Context(dictionary: ["value": "One, Two"]))
+      try expect(result) == "[\"One,\", \"Two\"]"
+    }
+  }
+
+
+  describe("filter suggestion") {
+    var template: Template!
+    var filterExtension: Extension!
+
+    func expectedSyntaxError(token: String, template: Template, description: String) -> TemplateSyntaxError {
+      guard let range = template.templateString.range(of: token) else {
+        fatalError("Can't find '\(token)' in '\(template)'")
+      }
+      let rangeLine = template.templateString.rangeLine(range)
+      let sourceMap = SourceMap(filename: template.name, line: rangeLine)
+      let token = Token.block(value: token, at: sourceMap)
+      return TemplateSyntaxError(reason: description, token: token, stackTrace: [])
+    }
+
+    func expectError(reason: String, token: String,
+                     file: String = #file, line: Int = #line, function: String = #function) throws {
+      let expectedError = expectedSyntaxError(token: token, template: template, description: reason)
+      let environment = Environment(extensions: [filterExtension])
+
+      let error = try expect(environment.render(template: template, context: [:]),
+                             file: file, line: line, function: function).toThrow() as TemplateSyntaxError
+      let reporter = SimpleErrorReporter()
+      try expect(reporter.renderError(error), file: file, line: line, function: function) == reporter.renderError(expectedError)
+    }
+
+    $0.it("made for unknown filter") {
+      template = Template(templateString: "{{ value|unknownFilter }}")
+
+      filterExtension = Extension()
+      filterExtension.registerFilter("knownFilter") { value, _ in value }
+
+      try expectError(reason: "Unknown filter 'unknownFilter'. Found similar filters: 'knownFilter'.", token: "value|unknownFilter")
+    }
+
+    $0.it("made for multiple similar filters") {
+      template = Template(templateString: "{{ value|lowerFirst }}")
+
+      filterExtension = Extension()
+      filterExtension.registerFilter("lowerFirstWord") { value, _ in value }
+      filterExtension.registerFilter("lowerFirstLetter") { value, _ in value }
+
+      try expectError(reason: "Unknown filter 'lowerFirst'. Found similar filters: 'lowerFirstWord', 'lowercase'.", token: "value|lowerFirst")
+    }
+
+    $0.it("not made when can't find similar filter") {
+      template = Template(templateString: "{{ value|unknownFilter }}")
+      try expectError(reason: "Unknown filter 'unknownFilter'. Found similar filters: 'lowerFirstWord'.", token: "value|unknownFilter")
+    }
+
+  }
+
+
+  describe("indent filter") {
+    $0.it("indents content") {
+      let template = Template(templateString: "{{ value|indent:2 }}")
+      let result = try template.render(Context(dictionary: ["value": "One\nTwo"]))
+      try expect(result) == "One\n  Two"
+    }
+
+    $0.it("can indent with arbitrary character") {
+      let template = Template(templateString: "{{ value|indent:2,\"\t\" }}")
+      let result = try template.render(Context(dictionary: ["value": "One\nTwo"]))
+      try expect(result) == "One\n\t\tTwo"
+    }
+
+    $0.it("can indent first line") {
+      let template = Template(templateString: "{{ value|indent:2,\" \",true }}")
+      let result = try template.render(Context(dictionary: ["value": "One\nTwo"]))
+      try expect(result) == "  One\n  Two"
+    }
+
+    $0.it("does not indent empty lines") {
+      let template = Template(templateString: "{{ value|indent }}")
+      let result = try template.render(Context(dictionary: ["value": "One\n\n\nTwo\n\n"]))
+      try expect(result) == "One\n\n\n    Two\n\n"
+    }
+  }
 }

Tests/StencilTests/FilterTagSpec.swift

@@ -17,9 +17,29 @@ func testFilterTag() {
     }
 
     $0.it("errors without a filter") {
-      let template = Template(templateString: "{% filter %}Test{% endfilter %}")
+      let template = Template(templateString: "Some {% filter %}Test{% endfilter %}")
       try expect(try template.render()).toThrow()
     }
 
+    $0.it("can render filters with arguments") {
+      let ext = Extension()
+      ext.registerFilter("split", filter: {
+        return ($0 as! String).components(separatedBy: $1[0] as! String)
+      })
+      let env = Environment(extensions: [ext])
+      let result = try env.renderTemplate(string: "{% filter split:\",\"|join:\";\"  %}{{ items|join:\",\" }}{% endfilter %}", context: ["items": [1, 2]])
+      try expect(result) == "1;2"
+    }
+
+    $0.it("can render filters with quote as an argument") {
+        let ext = Extension()
+        ext.registerFilter("replace", filter: {
+            print($1[0] as! String)
+            return ($0 as! String).replacingOccurrences(of: $1[0] as! String, with: $1[1] as! String)
+        })
+        let env = Environment(extensions: [ext])
+        let result = try env.renderTemplate(string: "{% filter replace:'\"',\"\" %}{{ items|join:\",\" }}{% endfilter %}", context: ["items": ["\"1\"", "\"2\""]])
+        try expect(result) == "1,2"
+    }
   }
 }

Tests/StencilTests/ForNodeSpec.swift

@@ -11,8 +11,9 @@ func testForNode() {
       "dict": [
         "one": "I",
         "two": "II",
-      ]
-    ])
+      ],
+      "tuples": [(1, 2, 3), (4, 5, 6)]
+      ])
 
     $0.it("renders the given nodes for each item") {
       let nodes: [NodeType] = [VariableNode(variable: "item")]
@@ -30,7 +31,7 @@ func testForNode() {
     $0.it("renders a context variable of type Array<Any>") {
       let any_context = Context(dictionary: [
         "items": ([1, 2, 3] as [Any])
-      ])
+        ])
 
       let nodes: [NodeType] = [VariableNode(variable: "item")]
       let node = ForNode(resolvable: Variable("items"), loopVariables: ["item"], nodes: nodes, emptyNodes: [])
@@ -53,17 +54,17 @@ func testForNode() {
       try expect(try node.render(context)) == "123"
     }
 
-#if os(OSX)
+    #if os(OSX)
     $0.it("renders a context variable of type NSArray") {
       let nsarray_context = Context(dictionary: [
         "items": NSArray(array: [1, 2, 3])
-      ])
+        ])
 
       let nodes: [NodeType] = [VariableNode(variable: "item")]
       let node = ForNode(resolvable: Variable("items"), loopVariables: ["item"], nodes: nodes, emptyNodes: [])
       try expect(try node.render(nsarray_context)) == "123"
     }
-#endif
+    #endif
 
     $0.it("renders the given nodes while providing if the item is first in the context") {
       let nodes: [NodeType] = [VariableNode(variable: "item"), VariableNode(variable: "forloop.first")]
@@ -89,32 +90,38 @@ func testForNode() {
       try expect(try node.render(context)) == "102132"
     }
 
+    $0.it("renders the given nodes while providing loop length") {
+      let nodes: [NodeType] = [VariableNode(variable: "item"), VariableNode(variable: "forloop.length")]
+      let node = ForNode(resolvable: Variable("items"), loopVariables: ["item"], nodes: nodes, emptyNodes: [])
+      try expect(try node.render(context)) == "132333"
+    }
+
     $0.it("renders the given nodes while filtering items using where expression") {
-        let nodes: [NodeType] = [VariableNode(variable: "item"), VariableNode(variable: "forloop.counter")]
-        let `where` = try parseExpression(components: ["item", ">", "1"], tokenParser: TokenParser(tokens: [], environment: Environment()))
-        let node = ForNode(resolvable: Variable("items"), loopVariables: ["item"], nodes: nodes, emptyNodes: [], where: `where`)
-        try expect(try node.render(context)) == "2132"
+      let nodes: [NodeType] = [VariableNode(variable: "item"), VariableNode(variable: "forloop.counter")]
+      let `where` = try parseExpression(components: ["item", ">", "1"], tokenParser: TokenParser(tokens: [], environment: Environment()), token: .text(value: "", at: .unknown))
+      let node = ForNode(resolvable: Variable("items"), loopVariables: ["item"], nodes: nodes, emptyNodes: [], where: `where`)
+      try expect(try node.render(context)) == "2132"
     }
 
     $0.it("renders the given empty nodes when all items filtered out with where expression") {
-        let nodes: [NodeType] = [VariableNode(variable: "item")]
-        let emptyNodes: [NodeType] = [TextNode(text: "empty")]
-        let `where` = try parseExpression(components: ["item", "==", "0"], tokenParser: TokenParser(tokens: [], environment: Environment()))
-        let node = ForNode(resolvable: Variable("emptyItems"), loopVariables: ["item"], nodes: nodes, emptyNodes: emptyNodes, where: `where`)
-        try expect(try node.render(context)) == "empty"
+      let nodes: [NodeType] = [VariableNode(variable: "item")]
+      let emptyNodes: [NodeType] = [TextNode(text: "empty")]
+      let `where` = try parseExpression(components: ["item", "==", "0"], tokenParser: TokenParser(tokens: [], environment: Environment()), token: .text(value: "", at: .unknown))
+      let node = ForNode(resolvable: Variable("emptyItems"), loopVariables: ["item"], nodes: nodes, emptyNodes: emptyNodes, where: `where`)
+      try expect(try node.render(context)) == "empty"
     }
 
-    $0.it("can render a filter") {
-      let templateString = "{% for article in ars|default:articles %}" +
+    $0.it("can render a filter with spaces") {
+      let templateString = "{% for article in ars | default: a, b , articles %}" +
         "- {{ article.title }} by {{ article.author }}.\n" +
-        "{% endfor %}\n"
+      "{% endfor %}\n"
 
       let context = Context(dictionary: [
         "articles": [
           Article(title: "Migrating from OCUnit to XCTest", author: "Kyle Fuller"),
           Article(title: "Memory Management with ARC", author: "Kyle Fuller"),
         ]
-      ])
+        ])
 
       let template = Template(templateString: templateString)
       let result = try template.render(context)
@@ -122,46 +129,188 @@ func testForNode() {
       let fixture = "" +
         "- Migrating from OCUnit to XCTest by Kyle Fuller.\n" +
         "- Memory Management with ARC by Kyle Fuller.\n" +
-        "\n"
+      "\n"
 
       try expect(result) == fixture
     }
 
-    $0.it("can iterate over dictionary") {
-      let templateString = "{% for key,value in dict %}" +
-        "{{ key }}: {{ value }}\n" +
+    $0.context("given array of tuples") {
+      $0.it("can iterate over all tuple values") {
+        let templateString = "{% for first,second,third in tuples %}" +
+          "{{ first }}, {{ second }}, {{ third }}\n" +
         "{% endfor %}\n"
 
+        let template = Template(templateString: templateString)
+        let result = try template.render(context)
+
+        let fixture = "1, 2, 3\n4, 5, 6\n\n"
+        try expect(result) == fixture
+      }
+
+      $0.it("can iterate with less number of variables") {
+        let templateString = "{% for first,second in tuples %}" +
+          "{{ first }}, {{ second }}\n" +
+        "{% endfor %}\n"
+
+        let template = Template(templateString: templateString)
+        let result = try template.render(context)
+
+        let fixture = "1, 2\n4, 5\n\n"
+        try expect(result) == fixture
+      }
+
+      $0.it("can use _ to skip variables") {
+        let templateString = "{% for first,_,third in tuples %}" +
+          "{{ first }}, {{ third }}\n" +
+        "{% endfor %}\n"
+
+        let template = Template(templateString: templateString)
+        let result = try template.render(context)
+
+        let fixture = "1, 3\n4, 6\n\n"
+        try expect(result) == fixture
+      }
+
+      $0.it("throws when number of variables is more than number of tuple values") {
+        let templateString = "{% for key,value,smth in dict %}" +
+        "{% endfor %}\n"
+
+        let template = Template(templateString: templateString)
+        try expect(template.render(context)).toThrow()
+      }
+
+    }
+
+    $0.it("can iterate over dictionary") {
+      let templateString = "{% for key, value in dict %}" +
+        "{{ key }}: {{ value }}," +
+      "{% endfor %}"
+
       let template = Template(templateString: templateString)
       let result = try template.render(context)
 
-      let fixture = "one: I\ntwo: II\n\n"
-      try expect(result) == fixture
+      let sortedResult = result.characters.split(separator: ",").map(String.init).sorted(by: <)
+      try expect(sortedResult) == ["one: I", "two: II"]
     }
 
     $0.it("renders supports iterating over dictionary") {
-      let nodes: [NodeType] = [VariableNode(variable: "key")]
+      let nodes: [NodeType] = [
+        VariableNode(variable: "key"),
+        TextNode(text: ","),
+        ]
       let emptyNodes: [NodeType] = [TextNode(text: "empty")]
       let node = ForNode(resolvable: Variable("dict"), loopVariables: ["key"], nodes: nodes, emptyNodes: emptyNodes, where: nil)
-      try expect(try node.render(context)) == "onetwo"
+      let result = try node.render(context)
+
+      let sortedResult = result.characters.split(separator: ",").map(String.init).sorted(by: <)
+      try expect(sortedResult) == ["one", "two"]
     }
 
     $0.it("renders supports iterating over dictionary") {
-      let nodes: [NodeType] = [VariableNode(variable: "key"), VariableNode(variable: "value")]
+      let nodes: [NodeType] = [
+        VariableNode(variable: "key"),
+        TextNode(text: "="),
+        VariableNode(variable: "value"),
+        TextNode(text: ","),
+        ]
       let emptyNodes: [NodeType] = [TextNode(text: "empty")]
       let node = ForNode(resolvable: Variable("dict"), loopVariables: ["key", "value"], nodes: nodes, emptyNodes: emptyNodes, where: nil)
-      try expect(try node.render(context)) == "oneItwoII"
+
+      let result = try node.render(context)
+
+      let sortedResult = result.characters.split(separator: ",").map(String.init).sorted(by: <)
+      try expect(sortedResult) == ["one=I", "two=II"]
     }
 
     $0.it("handles invalid input") {
-      let tokens: [Token] = [
-          .block(value: "for i"),
-      ]
-      let parser = TokenParser(tokens: tokens, environment: Environment())
-      let error = TemplateSyntaxError("'for' statements should use the following 'for x in y where condition' `for i`.")
+      let token = Token.block(value: "for i", at: .unknown)
+      let parser = TokenParser(tokens: [token], environment: Environment())
+      let error = TemplateSyntaxError(reason: "'for' statements should use the syntax: `for <x> in <y> [where <condition>]`.", token: token)
       try expect(try parser.parse()).toThrow(error)
     }
+
+    $0.it("can iterate over struct properties") {
+      struct MyStruct {
+        let string: String
+        let number: Int
+      }
+
+      let context = Context(dictionary: [
+        "struct": MyStruct(string: "abc", number: 123)
+        ])
+
+      let nodes: [NodeType] = [
+        VariableNode(variable: "property"),
+        TextNode(text: "="),
+        VariableNode(variable: "value"),
+        TextNode(text: "\n"),
+        ]
+      let node = ForNode(resolvable: Variable("struct"), loopVariables: ["property", "value"], nodes: nodes, emptyNodes: [])
+      let result = try node.render(context)
+
+      try expect(result) == "string=abc\nnumber=123\n"
+    }
+
+    $0.it("can iterate tuple items") {
+      let context = Context(dictionary: [
+        "tuple": (one: 1, two: "dva"),
+        ])
+
+      let nodes: [NodeType] = [
+        VariableNode(variable: "label"),
+        TextNode(text: "="),
+        VariableNode(variable: "value"),
+        TextNode(text: "\n"),
+        ]
+
+      let node = ForNode(resolvable: Variable("tuple"), loopVariables: ["label", "value"], nodes: nodes, emptyNodes: [])
+      let result = try node.render(context)
+
+      try expect(result) == "one=1\ntwo=dva\n"
+    }
+
+    $0.it("can iterate over class properties") {
+      class MyClass {
+        var baseString: String
+        var baseInt: Int
+        init(_ string: String, _ int: Int) {
+          baseString = string
+          baseInt = int
+        }
+      }
+
+      class MySubclass: MyClass {
+        var childString: String
+        init(_ childString: String, _ string: String, _ int: Int) {
+          self.childString = childString
+          super.init(string, int)
+        }
+      }
+
+      let context = Context(dictionary: [
+        "class": MySubclass("child", "base", 1)
+        ])
+
+      let nodes: [NodeType] = [
+        VariableNode(variable: "label"),
+        TextNode(text: "="),
+        VariableNode(variable: "value"),
+        TextNode(text: "\n"),
+        ]
+      
+      let node = ForNode(resolvable: Variable("class"), loopVariables: ["label", "value"], nodes: nodes, emptyNodes: [])
+      let result = try node.render(context)
+
+      try expect(result) == "childString=child\nbaseString=base\nbaseInt=1\n"
+    }
+
+    $0.it("can iterate in range of variables") {
+      let template: Template = "{% for i in 1...j %}{{ i }}{% endfor %}"
+      try expect(try template.render(Context(dictionary: ["j": 3]))) == "123"
+    }
+
   }
+
 }
 
 

Tests/StencilTests/IfNodeSpec.swift

@@ -7,9 +7,9 @@ func testIfNode() {
     $0.describe("parsing") {
       $0.it("can parse an if block") {
         let tokens: [Token] = [
-          .block(value: "if value"),
-          .text(value: "true"),
-          .block(value: "endif")
+          .block(value: "if value", at: .unknown),
+          .text(value: "true", at: .unknown),
+          .block(value: "endif", at: .unknown)
         ]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -25,11 +25,11 @@ func testIfNode() {
 
       $0.it("can parse an if with else block") {
         let tokens: [Token] = [
-          .block(value: "if value"),
-          .text(value: "true"),
-          .block(value: "else"),
-          .text(value: "false"),
-          .block(value: "endif")
+          .block(value: "if value", at: .unknown),
+          .text(value: "true", at: .unknown),
+          .block(value: "else", at: .unknown),
+          .text(value: "false", at: .unknown),
+          .block(value: "endif", at: .unknown)
         ]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -50,13 +50,13 @@ func testIfNode() {
 
       $0.it("can parse an if with elif block") {
         let tokens: [Token] = [
-          .block(value: "if value"),
-          .text(value: "true"),
-          .block(value: "elif something"),
-          .text(value: "some"),
-          .block(value: "else"),
-          .text(value: "false"),
-          .block(value: "endif")
+          .block(value: "if value", at: .unknown),
+          .text(value: "true", at: .unknown),
+          .block(value: "elif something", at: .unknown),
+          .text(value: "some", at: .unknown),
+          .block(value: "else", at: .unknown),
+          .text(value: "false", at: .unknown),
+          .block(value: "endif", at: .unknown)
         ]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -81,11 +81,11 @@ func testIfNode() {
 
       $0.it("can parse an if with elif block without else") {
         let tokens: [Token] = [
-          .block(value: "if value"),
-          .text(value: "true"),
-          .block(value: "elif something"),
-          .text(value: "some"),
-          .block(value: "endif")
+          .block(value: "if value", at: .unknown),
+          .text(value: "true", at: .unknown),
+          .block(value: "elif something", at: .unknown),
+          .text(value: "some", at: .unknown),
+          .block(value: "endif", at: .unknown)
         ]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -106,15 +106,15 @@ func testIfNode() {
 
       $0.it("can parse an if with multiple elif block") {
         let tokens: [Token] = [
-          .block(value: "if value"),
-          .text(value: "true"),
-          .block(value: "elif something1"),
-          .text(value: "some1"),
-          .block(value: "elif something2"),
-          .text(value: "some2"),
-          .block(value: "else"),
-          .text(value: "false"),
-          .block(value: "endif")
+          .block(value: "if value", at: .unknown),
+          .text(value: "true", at: .unknown),
+          .block(value: "elif something1", at: .unknown),
+          .text(value: "some1", at: .unknown),
+          .block(value: "elif something2", at: .unknown),
+          .text(value: "some2", at: .unknown),
+          .block(value: "else", at: .unknown),
+          .text(value: "false", at: .unknown),
+          .block(value: "endif", at: .unknown)
         ]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -144,9 +144,9 @@ func testIfNode() {
 
       $0.it("can parse an if with complex expression") {
         let tokens: [Token] = [
-          .block(value: "if value == \"test\" and not name"),
-          .text(value: "true"),
-          .block(value: "endif")
+          .block(value: "if value == \"test\" and not name", at: .unknown),
+          .text(value: "true", at: .unknown),
+          .block(value: "endif", at: .unknown)
         ]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -156,11 +156,11 @@ func testIfNode() {
 
       $0.it("can parse an ifnot block") {
         let tokens: [Token] = [
-          .block(value: "ifnot value"),
-          .text(value: "false"),
-          .block(value: "else"),
-          .text(value: "true"),
-          .block(value: "endif")
+          .block(value: "ifnot value", at: .unknown),
+          .text(value: "false", at: .unknown),
+          .block(value: "else", at: .unknown),
+          .text(value: "true", at: .unknown),
+          .block(value: "endif", at: .unknown)
         ]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -179,22 +179,18 @@ func testIfNode() {
       }
 
       $0.it("throws an error when parsing an if block without an endif") {
-        let tokens: [Token] = [
-          .block(value: "if value"),
-        ]
+        let tokens: [Token] = [.block(value: "if value", at: .unknown)]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
-        let error = TemplateSyntaxError("`endif` was not found.")
+        let error = TemplateSyntaxError(reason: "`endif` was not found.", token: tokens.first)
         try expect(try parser.parse()).toThrow(error)
       }
 
       $0.it("throws an error when parsing an ifnot without an endif") {
-        let tokens: [Token] = [
-            .block(value: "ifnot value"),
-        ]
+        let tokens: [Token] = [.block(value: "ifnot value", at: .unknown)]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
-        let error = TemplateSyntaxError("`endif` was not found.")
+        let error = TemplateSyntaxError(reason: "`endif` was not found.", token: tokens.first)
         try expect(try parser.parse()).toThrow(error)
       }
     }
@@ -242,9 +238,9 @@ func testIfNode() {
 
     $0.it("supports variable filters in the if expression") {
         let tokens: [Token] = [
-          .block(value: "if value|uppercase == \"TEST\""),
-          .text(value: "true"),
-          .block(value: "endif")
+          .block(value: "if value|uppercase == \"TEST\"", at: .unknown),
+          .text(value: "true", at: .unknown),
+          .block(value: "endif", at: .unknown)
         ]
 
         let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -256,9 +252,9 @@ func testIfNode() {
     
     $0.it("evaluates nil properties as false") {
       let tokens: [Token] = [
-        .block(value: "if instance.value"),
-        .text(value: "true"),
-        .block(value: "endif")
+        .block(value: "if instance.value", at: .unknown),
+        .text(value: "true", at: .unknown),
+        .block(value: "endif", at: .unknown)
       ]
       
       let parser = TokenParser(tokens: tokens, environment: Environment())
@@ -270,5 +266,22 @@ func testIfNode() {
       let result = try renderNodes(nodes, Context(dictionary: ["instance": SomeType()]))
       try expect(result) == ""
     }
+
+    $0.it("supports closed range variables") {
+      let tokens: [Token] = [
+        .block(value: "if value in 1...3", at: .unknown),
+        .text(value: "true", at: .unknown),
+        .block(value: "else", at: .unknown),
+        .text(value: "false", at: .unknown),
+        .block(value: "endif", at: .unknown)
+      ]
+
+      let parser = TokenParser(tokens: tokens, environment: Environment())
+      let nodes = try parser.parse()
+
+      try expect(renderNodes(nodes, Context(dictionary: ["value": 3]))) == "true"
+      try expect(renderNodes(nodes, Context(dictionary: ["value": 4]))) == "false"
+    }
+
   }
 }

Tests/StencilTests/IncludeSpec.swift

@@ -11,15 +11,15 @@ func testInclude() {
 
     $0.describe("parsing") {
       $0.it("throws an error when no template is given") {
-        let tokens: [Token] = [ .block(value: "include") ]
+        let tokens: [Token] = [ .block(value: "include", at: .unknown) ]
         let parser = TokenParser(tokens: tokens, environment: Environment())
 
-        let error = TemplateSyntaxError("'include' tag takes one argument, the template file to be included")
+        let error = TemplateSyntaxError(reason: "'include' tag requires one argument, the template file to be included. A second optional argument can be used to specify the context that will be passed to the included file", token: tokens.first)
         try expect(try parser.parse()).toThrow(error)
       }
 
       $0.it("can parse a valid include block") {
-        let tokens: [Token] = [ .block(value: "include \"test.html\"") ]
+        let tokens: [Token] = [ .block(value: "include \"test.html\"", at: .unknown) ]
         let parser = TokenParser(tokens: tokens, environment: Environment())
 
         let nodes = try parser.parse()
@@ -31,7 +31,7 @@ func testInclude() {
 
     $0.describe("rendering") {
       $0.it("throws an error when rendering without a loader") {
-        let node = IncludeNode(templateName: Variable("\"test.html\""))
+        let node = IncludeNode(templateName: Variable("\"test.html\""), token: .block(value: "", at: .unknown))
 
         do {
           _ = try node.render(Context())
@@ -41,7 +41,7 @@ func testInclude() {
       }
 
       $0.it("throws an error when it cannot find the included template") {
-        let node = IncludeNode(templateName: Variable("\"unknown.html\""))
+        let node = IncludeNode(templateName: Variable("\"unknown.html\""), token: .block(value: "", at: .unknown))
 
         do {
           _ = try node.render(Context(environment: environment))
@@ -51,11 +51,18 @@ func testInclude() {
       }
 
       $0.it("successfully renders a found included template") {
-        let node = IncludeNode(templateName: Variable("\"test.html\""))
+        let node = IncludeNode(templateName: Variable("\"test.html\""), token: .block(value: "", at: .unknown))
         let context = Context(dictionary: ["target": "World"], environment: environment)
         let value = try node.render(context)
         try expect(value) == "Hello World!"
       }
+
+      $0.it("successfully passes context") {
+        let template = Template(templateString: "{% include \"test.html\" child %}")
+        let context = Context(dictionary: ["child": ["target": "World"]], environment: environment)
+        let value = try template.render(context)
+        try expect(value) == "Hello World!"
+      }
     }
   }
 }

Tests/StencilTests/InheritenceSpec.swift

@@ -11,17 +11,17 @@ func testInheritence() {
 
     $0.it("can inherit from another template") {
       let template = try environment.loadTemplate(name: "child.html")
-      try expect(try template.render()) == "Header\nChild"
+      try expect(try template.render()) == "Super_Header Child_Header\nChild_Body"
     }
 
     $0.it("can inherit from another template inheriting from another template") {
       let template = try environment.loadTemplate(name: "child-child.html")
-      try expect(try template.render()) == "Child Child Header\nChild"
+      try expect(try template.render()) == "Super_Header Child_Header Child_Child_Header\nChild_Body"
     }
 
     $0.it("can inherit from a template that calls a super block") {
       let template = try environment.loadTemplate(name: "child-super.html")
-      try expect(try template.render()) == "Header\nChild Body"
+      try expect(try template.render()) == "Header\nChild_Body"
     }
   }
 }

Tests/StencilTests/LexerSpec.swift

@@ -9,7 +9,7 @@ func testLexer() {
       let tokens = lexer.tokenize()
 
       try expect(tokens.count) == 1
-      try expect(tokens.first) == .text(value: "Hello World")
+      try expect(tokens.first) == .text(value: "Hello World", at: SourceMap(line: ("Hello World", 1, 0)))
     }
 
     $0.it("can tokenize a comment") {
@@ -17,7 +17,7 @@ func testLexer() {
       let tokens = lexer.tokenize()
 
       try expect(tokens.count) == 1
-      try expect(tokens.first) == .comment(value: "Comment")
+      try expect(tokens.first) == .comment(value: "Comment", at: SourceMap(line: ("{# Comment #}", 1, 3)))
     }
 
     $0.it("can tokenize a variable") {
@@ -25,34 +25,37 @@ func testLexer() {
       let tokens = lexer.tokenize()
 
       try expect(tokens.count) == 1
-      try expect(tokens.first) == .variable(value: "Variable")
+      try expect(tokens.first) == .variable(value: "Variable", at: SourceMap(line: ("{{ Variable }}", 1, 3)))
     }
 
     $0.it("can tokenize unclosed tag by ignoring it") {
-      let lexer = Lexer(templateString: "{{ thing")
+      let templateString = "{{ thing"
+      let lexer = Lexer(templateString: templateString)
       let tokens = lexer.tokenize()
 
       try expect(tokens.count) == 1
-      try expect(tokens.first) == .text(value: "")
+      try expect(tokens.first) == .text(value: "", at: SourceMap(line: ("{{ thing", 1, 0)))
     }
 
     $0.it("can tokenize a mixture of content") {
-      let lexer = Lexer(templateString: "My name is {{ name }}.")
+      let templateString = "My name is {{ myname }}."
+      let lexer = Lexer(templateString: templateString)
       let tokens = lexer.tokenize()
 
       try expect(tokens.count) == 3
-      try expect(tokens[0]) == Token.text(value: "My name is ")
-      try expect(tokens[1]) == Token.variable(value: "name")
-      try expect(tokens[2]) == Token.text(value: ".")
+      try expect(tokens[0]) == Token.text(value: "My name is ", at: SourceMap(line: templateString.rangeLine(templateString.range(of: "My name is ")!)))
+      try expect(tokens[1]) == Token.variable(value: "myname", at: SourceMap(line: templateString.rangeLine(templateString.range(of: "myname")!)))
+      try expect(tokens[2]) == Token.text(value: ".", at: SourceMap(line: templateString.rangeLine(templateString.range(of: ".")!)))
     }
 
     $0.it("can tokenize two variables without being greedy") {
-      let lexer = Lexer(templateString: "{{ thing }}{{ name }}")
+      let templateString = "{{ thing }}{{ name }}"
+      let lexer = Lexer(templateString: templateString)
       let tokens = lexer.tokenize()
 
       try expect(tokens.count) == 2
-      try expect(tokens[0]) == Token.variable(value: "thing")
-      try expect(tokens[1]) == Token.variable(value: "name")
+      try expect(tokens[0]) == Token.variable(value: "thing", at: SourceMap(line: templateString.rangeLine(templateString.range(of: "thing")!)))
+      try expect(tokens[1]) == Token.variable(value: "name", at: SourceMap(line: templateString.rangeLine(templateString.range(of: "name")!)))
     }
 
     $0.it("can tokenize an unclosed block") {
@@ -64,5 +67,28 @@ func testLexer() {
       let lexer = Lexer(templateString: "{{}}")
       let _ = lexer.tokenize()
     }
+
+    $0.it("can tokenize with new lines") {
+      let templateString =
+        "My name is {%\n" +
+          "    if name\n" +
+          "     and\n" +
+          "    name\n" +
+          "%}{{\n" +
+          "name\n" +
+          "}}{%\n" +
+      "endif %}."
+
+      let lexer = Lexer(templateString: templateString)
+
+      let tokens = lexer.tokenize()
+
+      try expect(tokens.count) == 5
+      try expect(tokens[0]) == Token.text(value: "My name is ", at: SourceMap(line: templateString.rangeLine(templateString.range(of: "My name is")!)))
+      try expect(tokens[1]) == Token.block(value: "if name and name", at: SourceMap(line: templateString.rangeLine(templateString.range(of: "{%")!)))
+      try expect(tokens[2]) == Token.variable(value: "name", at: SourceMap(line: templateString.rangeLine(templateString.range(of: "name", options: [.backwards])!)))
+      try expect(tokens[3]) == Token.block(value: "endif", at: SourceMap(line: templateString.rangeLine(templateString.range(of: "endif")!)))
+      try expect(tokens[4]) == Token.text(value: ".", at: SourceMap(line: templateString.rangeLine(templateString.range(of: ".")!)))
+    }
   }
 }

Tests/StencilTests/NodeSpec.swift

@@ -3,6 +3,11 @@ import Spectre
 
 
 class ErrorNode : NodeType {
+  let token: Token?
+  init(token: Token? = nil) {
+    self.token = token
+  }
+
   func render(_ context: Context) throws -> String {
     throw TemplateSyntaxError("Custom Error")
   }

Tests/StencilTests/NowNodeSpec.swift

@@ -8,7 +8,7 @@ func testNowNode() {
   describe("NowNode") {
     $0.describe("parsing") {
       $0.it("parses default format without any now arguments") {
-        let tokens: [Token] = [ .block(value: "now") ]
+        let tokens: [Token] = [ .block(value: "now", at: .unknown) ]
         let parser = TokenParser(tokens: tokens, environment: Environment())
 
         let nodes = try parser.parse()
@@ -18,7 +18,7 @@ func testNowNode() {
       }
 
       $0.it("parses now with a format") {
-        let tokens: [Token] = [ .block(value: "now \"HH:mm\"") ]
+        let tokens: [Token] = [ .block(value: "now \"HH:mm\"", at: .unknown) ]
         let parser = TokenParser(tokens: tokens, environment: Environment())
         let nodes = try parser.parse()
         let node = nodes.first as? NowNode

Tests/StencilTests/ParserSpec.swift

@@ -6,7 +6,7 @@ func testTokenParser() {
   describe("TokenParser") {
     $0.it("can parse a text token") {
       let parser = TokenParser(tokens: [
-        .text(value: "Hello World")
+        .text(value: "Hello World", at: .unknown)
       ], environment: Environment())
 
       let nodes = try parser.parse()
@@ -18,7 +18,7 @@ func testTokenParser() {
 
     $0.it("can parse a variable token") {
       let parser = TokenParser(tokens: [
-        .variable(value: "'name'")
+        .variable(value: "'name'", at: .unknown)
       ], environment: Environment())
 
       let nodes = try parser.parse()
@@ -30,7 +30,7 @@ func testTokenParser() {
 
     $0.it("can parse a comment token") {
       let parser = TokenParser(tokens: [
-        .comment(value: "Secret stuff!")
+        .comment(value: "Secret stuff!", at: .unknown)
       ], environment: Environment())
 
       let nodes = try parser.parse()
@@ -44,7 +44,7 @@ func testTokenParser() {
       }
 
       let parser = TokenParser(tokens: [
-        .block(value: "known"),
+        .block(value: "known", at: .unknown),
       ], environment: Environment(extensions: [simpleExtension]))
 
       let nodes = try parser.parse()
@@ -52,11 +52,10 @@ func testTokenParser() {
     }
 
     $0.it("errors when parsing an unknown tag") {
-      let parser = TokenParser(tokens: [
-        .block(value: "unknown"),
-      ], environment: Environment())
+      let tokens: [Token] = [.block(value: "unknown", at: .unknown)]
+      let parser = TokenParser(tokens: tokens, environment: Environment())
 
-      try expect(try parser.parse()).toThrow(TemplateSyntaxError("Unknown template tag 'unknown'"))
+      try expect(try parser.parse()).toThrow(TemplateSyntaxError(reason: "Unknown template tag 'unknown'", token: tokens.first))
     }
   }
 }

Tests/StencilTests/StencilSpec.swift

@@ -2,7 +2,8 @@ import Spectre
 import Stencil
 
 
-fileprivate class CustomNode : NodeType {
+fileprivate struct CustomNode : NodeType {
+  let token: Token?
   func render(_ context:Context) throws -> String {
     return "Hello World"
   }
@@ -24,7 +25,7 @@ func testStencil() {
     }
 
     exampleExtension.registerTag("customtag") { parser, token in
-      return CustomNode()
+      return CustomNode(token: token)
     }
 
     let environment = Environment(extensions: [exampleExtension])

Tests/StencilTests/TemplateSpec.swift

@@ -1,5 +1,5 @@
 import Spectre
-import Stencil
+@testable import Stencil
 
 
 func testTemplate() {
@@ -15,5 +15,6 @@ func testTemplate() {
         let result = try template.render([ "name": "Kyle" ])
         try expect(result) == "Hello World"
     }
+    
   }
 }

Tests/StencilTests/TokenSpec.swift

@@ -1,11 +1,11 @@
 import Spectre
-import Stencil
+@testable import Stencil
 
 
 func testToken() {
   describe("Token") {
     $0.it("can split the contents into components") {
-      let token = Token.text(value: "hello world")
+      let token = Token.text(value: "hello world", at: .unknown)
       let components = token.components()
 
       try expect(components.count) == 2
@@ -14,7 +14,7 @@ func testToken() {
     }
 
     $0.it("can split the contents into components with single quoted strings") {
-      let token = Token.text(value: "hello 'kyle fuller'")
+      let token = Token.text(value: "hello 'kyle fuller'", at: .unknown)
       let components = token.components()
 
       try expect(components.count) == 2
@@ -23,7 +23,7 @@ func testToken() {
     }
 
     $0.it("can split the contents into components with double quoted strings") {
-      let token = Token.text(value: "hello \"kyle fuller\"")
+      let token = Token.text(value: "hello \"kyle fuller\"", at: .unknown)
       let components = token.components()
 
       try expect(components.count) == 2

Tests/StencilTests/VariableSpec.swift

@@ -4,8 +4,11 @@ import Spectre
 
 
 #if os(OSX)
-@objc class Object : NSObject {
-  let title = "Hello World"
+@objc class Superclass: NSObject {
+  @objc let name = "Foo"
+}
+@objc class Object : Superclass {
+  @objc let title = "Hello World"
 }
 #endif
 
@@ -17,6 +20,14 @@ fileprivate struct Article {
   let author: Person
 }
 
+fileprivate class WebSite {
+  let url: String = "blog.com"
+}
+
+fileprivate class Blog: WebSite {
+  let articles: [Article] = [Article(author: Person(name: "Kyle"))]
+  let featuring: Article? = Article(author: Person(name: "Jhon"))
+}
 
 func testVariable() {
   describe("Variable") {
@@ -29,12 +40,14 @@ func testVariable() {
       "counter": [
         "count": "kylef",
         ],
-      "article": Article(author: Person(name: "Kyle"))
+      "article": Article(author: Person(name: "Kyle")),
+      "tuple": (one: 1, two: 2)
     ])
 
 #if os(OSX)
     context["object"] = Object()
 #endif
+    context["blog"] = Blog()
 
     $0.it("can resolve a string literal with double quotes") {
       let variable = Variable("\"name\"")
@@ -50,7 +63,7 @@ func testVariable() {
 
     $0.it("can resolve an integer literal") {
       let variable = Variable("5")
-      let result = try variable.resolve(context) as? Number
+      let result = try variable.resolve(context) as? Int
       try expect(result) == 5
     }
 
@@ -60,6 +73,13 @@ func testVariable() {
       try expect(result) == 3.14
     }
 
+    $0.it("can resolve boolean literal") {
+      try expect(Variable("true").resolve(context) as? Bool) == true
+      try expect(Variable("false").resolve(context) as? Bool) == false
+      try expect(Variable("0").resolve(context) as? Int) == 0
+      try expect(Variable("1").resolve(context) as? Int) == 1
+    }
+
     $0.it("can resolve a string variable") {
       let variable = Variable("name")
       let result = try variable.resolve(context) as? String
@@ -122,6 +142,193 @@ func testVariable() {
       let result = try variable.resolve(context) as? String
       try expect(result) == "Hello World"
     }
+
+    $0.it("can resolve a superclass value via KVO") {
+      let variable = Variable("object.name")
+      let result = try variable.resolve(context) as? String
+      try expect(result) == "Foo"
+    }
 #endif
+
+    $0.it("can resolve a value via reflection") {
+      let variable = Variable("blog.articles.0.author.name")
+      let result = try variable.resolve(context) as? String
+      try expect(result) == "Kyle"
+    }
+
+    $0.it("can resolve a superclass value via reflection") {
+      let variable = Variable("blog.url")
+      let result = try variable.resolve(context) as? String
+      try expect(result) == "blog.com"
+    }
+
+    $0.it("can resolve optional variable property using reflection") {
+      let variable = Variable("blog.featuring.author.name")
+      let result = try variable.resolve(context) as? String
+      try expect(result) == "Jhon"
+    }
+
+    $0.it("does not render Optional") {
+      var array: [Any?] = [1, nil]
+      array.append(array)
+      let context = Context(dictionary: ["values": array])
+
+      try expect(VariableNode(variable: "values").render(context)) == "[1, nil, [1, nil]]"
+      try expect(VariableNode(variable: "values.1").render(context)) == ""
+    }
+
+    $0.it("can subscript tuple by index") {
+      let variable = Variable("tuple.0")
+      let result = try variable.resolve(context) as? Int
+      try expect(result) == 1
+    }
+
+    $0.it("can subscript tuple by label") {
+      let variable = Variable("tuple.two")
+      let result = try variable.resolve(context) as? Int
+      try expect(result) == 2
+    }
+
+    $0.describe("Subrscripting") {
+      $0.it("can resolve a property subscript via reflection") {
+        try context.push(dictionary: ["property": "name"]) {
+          let variable = Variable("article.author[property]")
+          let result = try variable.resolve(context) as? String
+          try expect(result) == "Kyle"
+        }
+      }
+
+      $0.it("can subscript an array with a valid index") {
+        try context.push(dictionary: ["property": 0]) {
+          let variable = Variable("contacts[property]")
+          let result = try variable.resolve(context) as? String
+          try expect(result) == "Katie"
+        }
+      }
+
+      $0.it("can subscript an array with an unknown index") {
+        try context.push(dictionary: ["property": 5]) {
+          let variable = Variable("contacts[property]")
+          let result = try variable.resolve(context) as? String
+          try expect(result).to.beNil()
+        }
+      }
+
+#if os(OSX)
+      $0.it("can resolve a subscript via KVO") {
+        try context.push(dictionary: ["property": "name"]) {
+          let variable = Variable("object[property]")
+          let result = try variable.resolve(context) as? String
+          try expect(result) == "Foo"
+        }
+      }
+#endif
+
+      $0.it("can resolve an optional subscript via reflection") {
+        try context.push(dictionary: ["property": "featuring"]) {
+          let variable = Variable("blog[property].author.name")
+          let result = try variable.resolve(context) as? String
+          try expect(result) == "Jhon"
+        }
+      }
+
+      $0.it("can resolve multiple subscripts") {
+        try context.push(dictionary: [
+          "prop1": "articles",
+          "prop2": 0,
+          "prop3": "name"
+        ]) {
+          let variable = Variable("blog[prop1][prop2].author[prop3]")
+          let result = try variable.resolve(context) as? String
+          try expect(result) == "Kyle" 
+        }
+      }
+
+      $0.it("can resolve nested subscripts") {
+        try context.push(dictionary: [
+          "prop1": "prop2",
+          "ref": ["prop2": "name"]
+        ]) {
+          let variable = Variable("article.author[ref[prop1]]")
+          let result = try variable.resolve(context) as? String
+          try expect(result) == "Kyle" 
+        }
+      }
+
+      $0.it("throws for invalid keypath syntax") {
+        try context.push(dictionary: ["prop": "name"]) {
+          let samples = [
+            ".",
+            "..",
+            ".test",
+            "test..test",
+            "[prop]",
+            "article.author[prop",
+            "article.author[[prop]",
+            "article.author[prop]]",
+            "article.author[]",
+            "article.author[[]]",
+            "article.author[prop][]",
+            "article.author[prop]comments",
+            "article.author[.]"
+          ]
+
+          for lookup in samples {
+            let variable = Variable(lookup)
+            try expect(variable.resolve(context)).toThrow()  
+          }
+        }
+      }
+    }
+  }
+
+  describe("RangeVariable") {
+
+    let context: Context = {
+      let ext = Extension()
+      ext.registerFilter("incr", filter: { (arg: Any?) in toNumber(value: arg!)! + 1 })
+      let environment = Environment(extensions: [ext])
+      return Context(dictionary: [:], environment: environment)
+    }()
+
+    func makeVariable(_ token: String) throws -> RangeVariable? {
+      let token = Token.variable(value: token, at: .unknown)
+      let parser = TokenParser(tokens: [token], environment: context.environment)
+      return try RangeVariable(token.contents, parser: parser, containedIn: token)
+    }
+
+    $0.it("can resolve closed range as array") {
+      let result = try makeVariable("1...3")?.resolve(context) as? [Int]
+      try expect(result) == [1, 2, 3]
+    }
+
+    $0.it("can resolve decreasing closed range as reversed array") {
+      let result = try makeVariable("3...1")?.resolve(context) as? [Int]
+      try expect(result) == [3, 2, 1]
+    }
+
+    $0.it("can use filter on range variables") {
+      let result = try makeVariable("1|incr...3|incr")?.resolve(context) as? [Int]
+      try expect(result) == [2, 3, 4]
+    }
+
+    $0.it("throws when left value is not int") {
+      let template: Template = "{% for i in k...j %}{{ i }}{% endfor %}"
+      try expect(try template.render(Context(dictionary: ["j": 3, "k": "1"]))).toThrow()
+    }
+
+    $0.it("throws when right value is not int") {
+      let variable = try makeVariable("k...j")
+      try expect(try variable?.resolve(Context(dictionary: ["j": "3", "k": 1]))).toThrow()
+    }
+
+    $0.it("throws is left range value is missing") {
+      try expect(makeVariable("...1")).toThrow()
+    }
+
+    $0.it("throws is right range value is missing") {
+      try expect(makeVariable("1...")).toThrow()
+    }
+
   }
 }

Tests/StencilTests/fixtures/child-child.html

@@ -1,2 +1,2 @@
 {% extends "child.html" %}
-{% block header %}Child Child Header{% endblock %}
+{% block header %}{{ block.super }} Child_Child_Header{% endblock %}

Tests/StencilTests/fixtures/child-super.html

@@ -1,3 +1,3 @@
 {% extends "base.html" %}
-{% block body %}Child {{ block.super }}{% endblock %}
+{% block body %}Child_{{ block.super }}{% endblock %}
 

Tests/StencilTests/fixtures/child.html

@@ -1,2 +1,3 @@
 {% extends "base.html" %}
-{% block body %}Child{% endblock %}
+{% block header %}Super_{{ block.super }} Child_Header{% endblock %}
+{% block body %}Child_Body{% endblock %}

Tests/StencilTests/fixtures/invalid-base.html

@@ -0,0 +1,2 @@
+{% block header %}Header{% endblock %}
+{% block body %}Body {{ target|unknown }} {% endblock %}

Tests/StencilTests/fixtures/invalid-child-super.html

@@ -0,0 +1,3 @@
+{% extends "invalid-base.html" %}
+{% block body %}Child {{ block.super }}{% endblock %}
+

Tests/StencilTests/fixtures/invalid-include.html

@@ -0,0 +1 @@
+Hello {{ target|unknown }}!

docs/builtins.rst

@@ -28,6 +28,18 @@ The ``for`` tag can iterate over dictionaries.
         <li>{{ key }}: {{ value }}</li>
       {% endfor %}
     </ul>
+    
+It can also iterate over ranges, tuple elements, structs' and classes' stored properties (using ``Mirror``).
+
+You can iterate over range literals created using ``N...M`` syntax, both in ascending and descending order:
+
+.. code-block:: html+django
+
+    <ul>
+      {% for i in 1...array.count %}
+        <li>{{ i }}</li>
+      {% endfor %}
+    </ul>
 
 The ``for`` tag can contain optional ``where`` expression to filter out
 elements on which this expression evaluates to false.
@@ -59,6 +71,7 @@ The for block sets a few variables available within the loop:
 - ``last`` - True if this is the last time through the loop
 - ``counter`` - The current iteration of the loop (1 indexed)
 - ``counter0`` - The current iteration of the loop (0 indexed)
+- ``length`` - The total length of the loop
 
 For example:
 
@@ -124,7 +137,7 @@ or to negate a variable.
     {% endif %}
 
 You may use ``and``, ``or`` and ``not`` multiple times together. ``not`` has
-higest prescidence followed by ``and``. For example:
+higest precedence followed by ``and``. For example:
 
 .. code-block:: html+django
 
@@ -247,6 +260,12 @@ You can include another template using the `include` tag.
 
     {% include "comment.html" %}
 
+By default the included file gets passed the current context. You can pass a sub context by using an optional 2nd parameter as a lookup in the current context.
+
+.. code-block:: html+django
+
+    {% include "comment.html" comment %}
+
 The `include` tag requires you to provide a loader which will be used to lookup
 the template.
 
@@ -281,7 +300,7 @@ Built-in Filters
 ~~~~~~~~~~~~~~
 
 The capitalize filter allows you to capitalize a string.
-For example, `stencil` to `Stencil`.
+For example, `stencil` to `Stencil`. Can be applied to array of strings to change each string.
 
 .. code-block:: html+django
 
@@ -291,7 +310,7 @@ For example, `stencil` to `Stencil`.
 ~~~~~~~~~~~~~
 
 The uppercase filter allows you to transform a string to uppercase.
-For example, `Stencil` to `STENCIL`.
+For example, `Stencil` to `STENCIL`. Can be applied to array of strings to change each string.
 
 .. code-block:: html+django
 
@@ -301,7 +320,7 @@ For example, `Stencil` to `STENCIL`.
 ~~~~~~~~~~~~~
 
 The uppercase filter allows you to transform a string to lowercase.
-For example, `Stencil` to `stencil`.
+For example, `Stencil` to `stencil`. Can be applied to array of strings to change each string.
 
 .. code-block:: html+django
 
@@ -326,4 +345,31 @@ Join an array of items.
 
     {{ value|join:", " }}
 
-.. note:: The value MUST be an array.
+.. note:: The value MUST be an array. Default argument value is empty string.
+
+``split``
+~~~~~~~~~
+
+Split string into substrings by separator.
+
+.. code-block:: html+django
+
+    {{ value|split:", " }}
+
+.. note:: The value MUST be a String. Default argument value is a single-space string.
+
+``indent``
+~~~~~~~~~
+
+Indents lines of rendered value or block.
+
+.. code-block:: html+django
+
+    {{ value|indent:2," ",true }}
+
+Filter accepts several arguments:
+
+* indentation width: number of indentation characters to indent lines with. Default is ``4``.
+* indentation character: character to be used for indentation. Default is a space.
+* indent first line: whether first line of output should be indented or not. Default is ``false``.
+

docs/templates.rst

@@ -31,6 +31,24 @@ For example, if `people` was an array:
     There are {{ people.count }} people. {{ people.first }} is the first
     person, followed by {{ people.1 }}.
 
+You can also use the subscript operator for indirect evaluation. The expression
+between brackets will be evaluated first, before the actual lookup will happen.
+
+For example, if you have the following context:
+
+.. code-block:: swift
+
+    [
+      "item": [
+        "name": "John"
+      ],
+      "key": "name"
+    ]
+
+.. code-block:: html+django
+
+    The result of {{ item[key] }} will be the same as {{ item.name }}. It will first evaluate the result of {{ key }}, and only then evaluate the lookup expression.
+
 Filters
 ~~~~~~~