TemplateRepository.swift

// The MIT License
//
// Copyright (c) 2015 Gwendal Roué
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.


import Foundation

/// See the documentation of the `TemplateRepositoryDataSource` protocol.
public typealias TemplateID = String

/// The protocol for a TemplateRepository's dataSource.
/// 
/// The dataSource's responsability is to provide Mustache template strings for
/// template and partial names.
public protocol TemplateRepositoryDataSource {
    
    /// Returns a template ID, that is to say a string that uniquely identifies
    /// a template or a template partial.
    /// 
    /// The meaning of this String is opaque: your implementation of a
    /// `TemplateRepositoryDataSource` would define, for itself, how strings
    /// would identity a template or a partial. For example, a file-based data
    /// source may use paths to the templates.
    /// 
    /// The return value of this method can be nil: the library user will then
    /// eventually catch a missing template error.
    /// 
    /// ### Template hierarchies
    /// 
    /// Whenever relevant, template and partial hierarchies are supported via
    /// the baseTemplateID parameter: it contains the template ID of the
    /// enclosing template, or nil when the data source is asked for a
    /// template ID from a raw template string (see
    /// TemplateRepository.template(string:error:)).
    /// 
    /// Not all data sources have to implement hierarchies: they can simply
    /// ignore this parameter.
    /// 
    /// *Well-behaved* data sources that support hierarchies should support
    /// "absolute paths to partials". For example, the built-in directory-based
    /// data source lets users write both `{{> relative/path/to/partial}}` and
    /// `{{> /absolute/path/tp/partial}}`tags.
    /// 
    /// ### Unique IDs
    /// 
    /// Each template must be identified by a single template ID. For example, a
    /// file-based data source which uses path IDs must normalize paths. Not
    /// following this rule yields undefined behavior.
    /// 
    /// - parameter name: The name of the template or template partial.
    /// - parameter baseTemplateID: The template ID of the enclosing template.
    /// - returns: A template ID.
    func templateIDForName(_ name: String, relativeToTemplateID baseTemplateID: TemplateID?) -> TemplateID?
    
    /// Returns the Mustache template string that matches the template ID.
    /// 
    /// - parameter templateID: The template ID of the template.
    /// - throws: MustacheError
    /// - returns: A Mustache template string.
    func templateStringForTemplateID(_ templateID: TemplateID) throws -> String
}

/// A template repository represents a set of sibling templates and partials.
/// 
/// You don't have to instanciate template repositories, because GRMustache
/// provides implicit ones whenever you load templates with methods like
/// `Template(named:error:)`, for example.
/// 
/// However, you may like to use one for your profit. Template repositories
/// provide:
/// 
/// - custom template data source
/// - custom `Configuration`
/// - a cache of template parsings
/// - absolute paths to ease loading of partial templates in a hierarchy of
///   directories and template files
final public class TemplateRepository {
    
    // =========================================================================
    // MARK: - Creating Template Repositories
    
    /// Creates a TemplateRepository which loads template through the provided
    /// dataSource.
    /// 
    /// The dataSource is optional, but repositories without dataSource can not
    /// load templates by name, and can only parse template strings that do not
    /// contain any `{{> partial }}` tag.
    /// 
    ///     let repository = TemplateRepository()
    ///     let template = try! repository.template(string: "Hello {{name}}")
    public init(dataSource: TemplateRepositoryDataSource? = nil, configuration: Configuration = .default) {
        self.configuration = configuration
        templateASTCache = [:]
        self.dataSource = dataSource
    }
    
    /// Creates a TemplateRepository that loads templates from a dictionary.
    /// 
    ///     let templates = ["template": "Hulk Hogan has a Mustache."]
    ///     let repository = TemplateRepository(templates: templates)
    /// 
    ///     // Renders "Hulk Hogan has a Mustache." twice
    ///     try! repository.template(named: "template").render()
    ///     try! repository.template(string: "{{>template}}").render()
    /// 
    /// - parameter templates: A dictionary whose keys are template names and
    ///   values template strings.
    /// - parameter configuration: The configuration for rendering. If the configuration is not specified, `Configuration.default` is used.
    convenience public init(templates: [String: String], configuration: Configuration = .default) {
        self.init(dataSource: DictionaryDataSource(templates: templates), configuration: configuration)
    }
    
    /// Creates a TemplateRepository that loads templates from a directory.
    /// 
    ///     let repository = TemplateRepository(directoryPath: "/path/to/templates")
    /// 
    ///     // Loads /path/to/templates/template.mustache
    ///     let template = try! repository.template(named: "template")
    /// 
    /// 
    /// Eventual partial tags in template files refer to sibling template files.
    /// 
    /// If the target directory contains a hierarchy of template files and
    /// sub-directories, you can navigate through this hierarchy with both
    /// relative and absolute paths to partials. For example, given the
    /// following hierarchy:
    /// 
    /// - /path/to/templates
    ///     - a.mustache
    ///     - partials
    ///         - b.mustache
    /// 
    /// The a.mustache template can embed b.mustache with both
    /// `{{> partials/b }}` and `{{> /partials/b }}` partial tags.
    /// 
    /// The b.mustache template can embed a.mustache with both `{{> ../a }}` and
    /// `{{> /a }}` partial tags.
    /// 
    /// 
    /// - parameter directoryPath: The path to the directory containing
    ///   template files.
    /// - parameter templateExtension: The extension of template files. Default
    ///   extension is "mustache".
    /// - parameter encoding: The encoding of template files. Default encoding
    ///   is UTF-8.
    /// - parameter configuration: The configuration for rendering. If the configuration is not specified, `Configuration.default` is used.
    convenience public init(directoryPath: String, templateExtension: String? = "mustache", encoding: String.Encoding = String.Encoding.utf8, configuration: Configuration = .default) {
        self.init(dataSource: URLDataSource(baseURL: URL(fileURLWithPath: directoryPath, isDirectory: true), templateExtension: templateExtension, encoding: encoding), configuration: configuration)
    }
    
    /// Creates a TemplateRepository that loads templates from a URL.
    /// 
    ///     let templatesURL = NSURL.fileURLWithPath("/path/to/templates")!
    ///     let repository = TemplateRepository(baseURL: templatesURL)
    /// 
    ///     // Loads /path/to/templates/template.mustache
    ///     let template = try! repository.template(named: "template")
    /// 
    /// 
    /// Eventual partial tags in template files refer to sibling template files.
    /// 
    /// If the target directory contains a hierarchy of template files and
    /// sub-directories, you can navigate through this hierarchy with both
    /// relative and absolute paths to partials. For example, given the
    /// following hierarchy:
    /// 
    /// - /path/to/templates
    ///     - a.mustache
    ///     - partials
    ///         - b.mustache
    /// 
    /// The a.mustache template can embed b.mustache with both `{{> partials/b }}`
    /// and `{{> /partials/b }}` partial tags.
    /// 
    /// The b.mustache template can embed a.mustache with both `{{> ../a }}` and
    /// `{{> /a }}` partial tags.
    /// 
    /// 
    /// - parameter baseURL: The base URL where to look for templates.
    /// - parameter templateExtension: The extension of template resources.
    ///   Default extension is "mustache".
    /// - parameter encoding: The encoding of template resources. Default
    ///   encoding is UTF-8.
    /// - parameter configuration: The configuration for rendering. If the configuration is not specified, `Configuration.default` is used.
    convenience public init(baseURL: URL, templateExtension: String? = "mustache", encoding: String.Encoding = String.Encoding.utf8, configuration: Configuration = .default) {
        self.init(dataSource: URLDataSource(baseURL: baseURL, templateExtension: templateExtension, encoding: encoding), configuration: configuration)
    }
    
    /// Creates a TemplateRepository that loads templates stored as resources in
    /// a bundle.
    /// 
    ///     let repository = TemplateRepository(bundle: nil)
    /// 
    ///     // Loads the template.mustache resource of the main bundle:
    ///     let template = try! repository.template(named: "template")
    /// 
    /// - parameter bundle: The bundle that stores templates resources. Nil
    ///   stands for the main bundle.
    /// - parameter templateExtension: The extension of template resources.
    ///   Default extension is "mustache".
    /// - parameter encoding: The encoding of template resources. Default
    ///   encoding is UTF-8.
    /// - parameter configuration: The configuration for rendering. If the configuration is not specified, `Configuration.default` is used.
    convenience public init(bundle: Bundle?, templateExtension: String? = "mustache", encoding: String.Encoding = String.Encoding.utf8, configuration: Configuration = .default) {
        self.init(dataSource: BundleDataSource(bundle: bundle ?? Bundle.main, templateExtension: templateExtension, encoding: encoding), configuration: configuration)
    }
    
    
    // =========================================================================
    // MARK: - Configuring Template Repositories
    
    /// The configuration for all templates and partials built by
    /// the repository.
    /// 
    /// It is initialized with `Mustache.DefaultConfiguration`.
    /// 
    /// You can alter the repository's configuration, or set it to another
    /// value, before you load templates:
    /// 
    ///     // Reset the configuration to a factory configuration and change tag delimiters:
    ///     let repository = TemplateRepository()
    ///     repository.configuration = Configuration()
    ///     repository.configuration.tagDelimiterPair = ("<%", "%>")
    /// 
    ///     // Renders "Hello Luigi"
    ///     let template = try! repository.template(string: "Hello <%name%>")
    ///     try! template.render(["name": "Luigi"])
    /// 
    /// Changing the configuration has no effect after the repository has loaded
    /// one template.
    public var configuration: Configuration
    
    
    // =========================================================================
    // MARK: - Loading Templates from a Repository
    
    
    /// The template repository data source, responsible for loading template
    /// strings.
    public let dataSource: TemplateRepositoryDataSource?
    
    /// Creates a template from a template string.
    /// 
    /// Depending on the way the repository has been created, partial tags such
    /// as `{{>partial}}` load partial templates from URLs, file paths, keys in
    /// a dictionary, or whatever is relevant to the repository's data source.
    /// 
    /// - parameter templateString: A Mustache template string.
    /// - throws: MustacheError
    /// - returns: A Mustache Template.
    public func template(string: String) throws -> Template {
        let templateAST = try self.templateAST(string: string)
        return Template(repository: self, templateAST: templateAST, baseContext: lockedConfiguration.baseContext)
    }
    
    /// Creates a template, identified by its name.
    /// 
    /// Depending on the repository's data source, the name identifies a bundle
    /// resource, a URL, a file path, a key in a dictionary, etc.
    /// 
    /// Template repositories cache the parsing of their templates. However this
    /// method always return new Template instances, which you can further
    /// configure independently.
    /// 
    /// - parameter name: The template name.
    /// - throws: MustacheError
    /// - returns: A Mustache Template.
    /// 
    /// - seealso: reloadTemplates()
    public func template(named name: String) throws -> Template {
        let templateAST = try self.templateAST(named: name, relativeToTemplateID: nil)
        return Template(repository: self, templateAST: templateAST, baseContext: lockedConfiguration.baseContext)
    }
    
    /// Clears the cache of parsed template strings.
    /// 
    ///     // May reuse a cached parsing:
    ///     let template = try! repository.template(named:"profile")
    /// 
    ///     // Forces the reloading of the template:
    ///     repository.reloadTemplates();
    ///     let template = try! repository.template(named:"profile")
    /// 
    /// Note that previously created Template instances are not reloaded.
    public func reloadTemplates() {
        templateASTCache.removeAll()
    }
    
    
    // =========================================================================
    // MARK: - Not public
    
    func templateAST(named name: String, relativeToTemplateID baseTemplateID: TemplateID? = nil) throws -> TemplateAST {
        guard let dataSource = self.dataSource else {
            throw MustacheError(kind: .templateNotFound, message: "Missing dataSource", templateID: baseTemplateID)
        }
        
        guard let templateID = dataSource.templateIDForName(name, relativeToTemplateID: baseTemplateID) else {
            if let baseTemplateID = baseTemplateID {
                throw MustacheError(kind: .templateNotFound, message: "Template not found: \"\(name)\" from \(baseTemplateID)", templateID: baseTemplateID)
            } else {
                throw MustacheError(kind: .templateNotFound, message: "Template not found: \"\(name)\"")
            }
        }
        
        if let templateAST = templateASTCache[templateID] {
            // Return cached AST
            return templateAST
        }
        
        let templateString = try dataSource.templateStringForTemplateID(templateID)
        
        // Cache an empty AST for that name so that we support recursive
        // partials.
        let templateAST = TemplateAST()
        templateASTCache[templateID] = templateAST
        
        do {
            let compiledAST = try self.templateAST(string: templateString, templateID: templateID)
            // Success: update the empty AST
            templateAST.updateFromTemplateAST(compiledAST)
            return templateAST
        } catch {
            // Failure: remove the empty AST
            templateASTCache.removeValue(forKey: templateID)
            throw error
        }
    }

    @available(iOS 15.0, macOS 12.0, tvOS 15.0, *)
    func templateAST(named name: String, relativeToTemplateID baseTemplateID: TemplateID? = nil) async throws -> TemplateAST {
        guard let dataSource = self.dataSource else {
            throw MustacheError(kind: .templateNotFound, message: "Missing dataSource", templateID: baseTemplateID)
        }

        guard let templateID = dataSource.templateIDForName(name, relativeToTemplateID: baseTemplateID) else {
            if let baseTemplateID = baseTemplateID {
                throw MustacheError(kind: .templateNotFound, message: "Template not found: \"\(name)\" from \(baseTemplateID)", templateID: baseTemplateID)
            } else {
                throw MustacheError(kind: .templateNotFound, message: "Template not found: \"\(name)\"")
            }
        }

        if let templateAST = templateASTCache[templateID] {
            // Return cached AST
            return templateAST
        }

        let templateString = try await dataSource.templateStringForTemplateID(templateID)

        // Cache an empty AST for that name so that we support recursive
        // partials.
        let templateAST = TemplateAST()
        templateASTCache[templateID] = templateAST

        do {
            let compiledAST = try self.templateAST(string: templateString, templateID: templateID)
            // Success: update the empty AST
            templateAST.updateFromTemplateAST(compiledAST)
            return templateAST
        } catch {
            // Failure: remove the empty AST
            templateASTCache.removeValue(forKey: templateID)
            throw error
        }
    }

    func templateAST(string: String, templateID: TemplateID? = nil) throws -> TemplateAST {
        // A Compiler
        let compiler = TemplateCompiler(
            contentType: lockedConfiguration.contentType,
            repository: self,
            templateID: templateID)
        
        // A Parser that feeds the compiler
        let parser = TemplateParser(
            tokenConsumer: compiler,
            tagDelimiterPair: lockedConfiguration.tagDelimiterPair)
        
        // Parse...
        parser.parse(string, templateID: templateID)
        
        // ...and extract the result from the Compiler
        return try compiler.templateAST()
    }
    
    
    fileprivate var _lockedConfiguration: Configuration?
    fileprivate var lockedConfiguration: Configuration {
        // Changing mutable values within the repository's configuration no
        // longer has any effect.
        if _lockedConfiguration == nil {
            _lockedConfiguration = configuration
        }
        return _lockedConfiguration!
    }
    
    fileprivate var templateASTCache: [TemplateID: TemplateAST]
    
    
    // -------------------------------------------------------------------------
    // MARK: DictionaryDataSource
    
    fileprivate class DictionaryDataSource: TemplateRepositoryDataSource {
        let templates: [String: String]
        
        init(templates: [String: String]) {
            self.templates = templates
        }
        
        func templateIDForName(_ name: String, relativeToTemplateID baseTemplateID: TemplateID?) -> TemplateID? {
            return name
        }
        
        func templateStringForTemplateID(_ templateID: TemplateID) throws -> String {
            if let string = templates[templateID] {
                return string
            } else {
                throw MustacheError(kind: .templateNotFound, templateID: templateID)
            }
        }
    }
    
    
    // -------------------------------------------------------------------------
    // MARK: URLDataSource
    
    fileprivate class URLDataSource: TemplateRepositoryDataSource {
        let baseURLAbsoluteString: String
        let baseURL: URL
        let templateExtension: String?
        let encoding: String.Encoding
        
        init(baseURL: URL, templateExtension: String?, encoding: String.Encoding) {
            self.baseURL = baseURL
            self.baseURLAbsoluteString = baseURL.standardizedFileURL.absoluteString
            self.templateExtension = templateExtension
            self.encoding = encoding
        }
        
        func templateIDForName(_ name: String, relativeToTemplateID baseTemplateID: TemplateID?) -> TemplateID? {
            // Rebase template names starting with a /
            let normalizedName: String
            let normalizedBaseTemplateID: TemplateID?
            if !name.isEmpty && name[name.startIndex] == "/" {
                normalizedName = String(name[name.index(after: name.startIndex)...])
                normalizedBaseTemplateID = nil
            } else {
                normalizedName = name
                normalizedBaseTemplateID = baseTemplateID
            }
        
            if normalizedName.isEmpty {
                return normalizedBaseTemplateID
            }
            
            let templateFilename: String
            if let templateExtension = self.templateExtension , !templateExtension.isEmpty {
                templateFilename = (normalizedName as NSString).appendingPathExtension(templateExtension)!
            } else {
                templateFilename = normalizedName
            }
            
            let templateBaseURL: URL
            if let normalizedBaseTemplateID = normalizedBaseTemplateID {
                templateBaseURL = URL(string: normalizedBaseTemplateID)!
            } else {
                templateBaseURL = self.baseURL
            }

            let encodedURLPath = templateFilename.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed)!
            let templateURL = URL(string: encodedURLPath, relativeTo: templateBaseURL)!.standardizedFileURL
            let templateAbsoluteString = templateURL.absoluteString
            
            // Make sure partial relative paths can not escape repository root
            if templateAbsoluteString.range(of: baseURLAbsoluteString)?.lowerBound == templateAbsoluteString.startIndex {
                return templateAbsoluteString
            } else {
                return nil
            }
        }
        
        func templateStringForTemplateID(_ templateID: TemplateID) throws -> String {
            return try NSString(contentsOf: URL(string: templateID)!, encoding: encoding.rawValue) as String
        }

        @available(iOS 15.0, macOS 12.0, tvOS 15.0, *)
        func templateStringForTemplateID(_ templateID: TemplateID) async throws -> String {
            let (data, _) = try await URLSession.shared.data(from: URL(string: templateID)!)

            return (NSString(data: data, encoding: encoding.rawValue) ?? "") as String
        }
    }
    
    
    // -------------------------------------------------------------------------
    // MARK: BundleDataSource
    
    fileprivate class BundleDataSource: TemplateRepositoryDataSource {
        let bundle: Bundle
        let templateExtension: String?
        let encoding: String.Encoding
        
        init(bundle: Bundle, templateExtension: String?, encoding: String.Encoding) {
            self.bundle = bundle
            self.templateExtension = templateExtension
            self.encoding = encoding
        }
        
        func templateIDForName(_ name: String, relativeToTemplateID baseTemplateID: TemplateID?) -> TemplateID? {
            // Rebase template names starting with a /
            let normalizedName: String
            let normalizedBaseTemplateID: TemplateID?
            if !name.isEmpty && name[name.startIndex] == "/" {
                normalizedName = String(name[name.index(after: name.startIndex)...])
                normalizedBaseTemplateID = nil
            } else {
                normalizedName = name
                normalizedBaseTemplateID = baseTemplateID
            }
            
            if normalizedName.isEmpty {
                return normalizedBaseTemplateID
            }
            
            if let normalizedBaseTemplateID = normalizedBaseTemplateID {
                let relativePath = (normalizedBaseTemplateID as NSString).deletingLastPathComponent.replacingOccurrences(of: bundle.resourcePath!, with:"")
                return bundle.path(forResource: normalizedName, ofType: templateExtension, inDirectory: relativePath)
            } else {
                return bundle.path(forResource: normalizedName, ofType: templateExtension)
            }
        }
        
        func templateStringForTemplateID(_ templateID: TemplateID) throws -> String {
            return try NSString(contentsOfFile: templateID, encoding: encoding.rawValue) as String
        }
    }
}