text-template.hpp

Go to the documentation of this file.

/*
  TEXT-TEMPLATE.hpp  -  minimalistic text substitution engine
 
   Copyright (C)
     2024,            Hermann Vosseler <Ichthyostega@web.de>
 
 **Lumiera** is free software; you can redistribute it and/or modify it
 under the terms of the GNU General Public License as published by the
 Free Software Foundation; either version 2 of the License, or (at your
 option) any later version. See the file COPYING for further details.
 
*/
 
 
#ifndef LIB_TEXT_TEMPLATE_H
#define LIB_TEXT_TEMPLATE_H
 
 
#include "lib/error.hpp"
#include "lib/nocopy.hpp"
#include "lib/index-iter.hpp"
#include "lib/iter-explorer.hpp"
#include "lib/format-string.hpp"
#include "lib/format-util.hpp"
#include "lib/regex.hpp"
#include "lib/util.hpp"
 
#include <memory>
#include <string>
#include <vector>
#include <stack>
#include <map>
 
 
namespace lib {
  namespace error = lumiera::error;
  
  namespace test {  // declared friend for test access
    class TextTemplate_test;
  }
  
  using std::string;
  using StrView = std::string_view;
  
  using util::_Fmt;
  using util::isnil;
  using util::unConst;
  
  
  namespace text_template { 
    
    //-----------Syntax-for-iteration-control-in-map------
    const string MATCH_DATA_TOKEN = R"~(([^,;"\s]*)\s*)~";
    const string MATCH_DELIMITER  = R"~((?:^|,|;)\s*)~"  ;
    const regex ACCEPT_DATA_ELM   {MATCH_DELIMITER + MATCH_DATA_TOKEN};
    
    inline auto
    iterNestedKeys (string key, StrView const& iterDef)
    {
      return explore (util::RegexSearchIter{iterDef, ACCEPT_DATA_ELM})
                .transform ([key](smatch mat){ return key+"."+string{mat[1]}+"."; });
    }
    
    //-----------Syntax-for-key-value-data-from-string------
    const string MATCH_BINDING_KEY = R"~(([\w\.]+))~";
    const string MATCH_BINDING_VAL = R"~(([^,;"\s]+)\s*)~";
    const string MATCH_QUOTED_VAL  = R"~("([^"]+)"\s*)~";
    const string MATCH_BINDING_TOK = MATCH_BINDING_KEY+"\\s*=\\s*(?:"+MATCH_BINDING_VAL+"|"+MATCH_QUOTED_VAL+")";
    const regex ACCEPT_BINDING_ELM {MATCH_DELIMITER + MATCH_BINDING_TOK};
    
    inline auto
    iterBindingSeq (string const& dataDef)
    {
      return explore (util::RegexSearchIter{dataDef, ACCEPT_BINDING_ELM})
                .transform ([&](smatch mat){ return std::make_pair (string{mat[1]}
                                                                   ,string{mat[3].matched? mat[3]:mat[2]}); });
    }
 
    
    //-----------Syntax-for-TextTemplate-tags--------
    const string MATCH_SINGLE_KEY = "[A-Za-z_]+\\w*";
    const string MATCH_KEY_PATH   = MATCH_SINGLE_KEY+"(?:\\."+MATCH_SINGLE_KEY+")*";
    const string MATCH_LOGIC_TOK  = "if|for";
    const string MATCH_END_TOK    = "end\\s*";
    const string MATCH_ELSE_TOK   = "else";
    const string MATCH_SYNTAX     = "("+MATCH_ELSE_TOK+")|(?:("+MATCH_END_TOK+")?("+MATCH_LOGIC_TOK+")\\s*)?("+MATCH_KEY_PATH+")?";
    const string MATCH_FIELD      = "\\$\\{\\s*(?:"+MATCH_SYNTAX+")\\s*\\}";
    const string MATCH_ESCAPE     = R"~((\\\$))~";
    
    const regex ACCEPT_MARKUP { MATCH_ESCAPE+"|"+MATCH_FIELD
                              , regex::ECMAScript|regex::optimize
                              };
                             // Sub-Matches: 1 = ESCAPE; 2 = ELSE; 3 = END; 4 = LOGIC; 5 = KEY;
    
    struct TagSyntax
      {
        enum Keyword{ ESCAPE
                    , KEYID
                    , IF
                    , END_IF
                    , FOR
                    , END_FOR
                    , ELSE
                    };
        Keyword syntax{ESCAPE};
        StrView lead;
        StrView tail;
        string key;
      };
    
    inline auto
    parse (string const& input)
    {
      auto classify = [rest=StrView(input)]
                      (smatch mat) mutable -> TagSyntax
                        {
                          REQUIRE (not mat.empty());
                          TagSyntax tag;
                          auto restAhead = mat.length() + mat.suffix().length();
                          auto pre = rest.length() - restAhead;
                          tag.lead = rest.substr(0, pre);
                          rest = rest.substr(tag.lead.length());
                          if (mat[5].matched)
                            tag.key = mat[5];
                          if (mat[1].matched)
                            rest = rest.substr(1);  // strip escape
                          else
                            { // not escaped but indeed active field
                              rest = rest.substr(mat.length());
                              if (mat[4].matched)
                                { // detected a logic keyword...
                                  if ("if" == mat[4])
                                    tag.syntax = mat[3].matched? TagSyntax::END_IF : TagSyntax::IF;
                                  else
                                  if ("for" == mat[4])
                                    tag.syntax = mat[3].matched? TagSyntax::END_FOR : TagSyntax::FOR;
                                  else
                                    throw error::Logic{_Fmt{"unexpected keyword \"%s\""} % mat[4]};
                                }
                              else
                              if (mat[2].matched)
                                tag.syntax = TagSyntax::ELSE;
                              else
                              if ("end" == mat[5])
                                throw error::Invalid{_Fmt{"unqualified \"end\" without logic-keyword:"
                                                          " ...%s${end |↯|}"} % tag.lead};
                              else
                                tag.syntax = TagSyntax::KEYID;
                            }
                          tag.tail = rest;
                          return tag;
                        };
      
      return explore (util::RegexSearchIter{input, ACCEPT_MARKUP})
               .transform (classify);
    }
    
    
    template<class DAT, typename SEL=void>
    class DataSource;
    
  }//(namespace) text_template
  
  
  
  
  
  
  /*************************************************/
  class TextTemplate
    : util::MoveOnly
    {
      enum Clause {
          IF, FOR
        };
      enum Code {
          TEXT, KEY, COND, JUMP, ITER, LOOP
        };
      
      using Idx = size_t;
      
      template<class SRC>
      class InstanceCore;
      
      struct ParseCtx
        {
          Clause clause;
          Idx begin{0};
          Idx after{0};
        };
      using ScopeStack = std::stack<ParseCtx, std::vector<ParseCtx>>;
      
      struct Action
        {
          Code code{TEXT};
          string val{};
          Idx refIDX{0};
          
          template<class SRC>
          auto instantiate (InstanceCore<SRC>&)  const;
        };
      
      using ActionSeq = std::vector<Action>;
      
      class ActionCompiler;
      
      template<class SRC>
      class InstanceCore
        {
          using ActionIter = IndexIter<const ActionSeq>;
          using DataCtxIter = SRC::Iter;
          using NestedCtx = std::pair<DataCtxIter, SRC>;
          using CtxStack = std::stack<NestedCtx, std::vector<NestedCtx>>;
          using Value   = SRC::Value;
          
          SRC        dataSrc_;
          ActionIter actionIter_;
          CtxStack   ctxStack_;
          Value      rendered_;
          
        public:
          InstanceCore (ActionSeq const& actions, SRC);
          
          bool checkPoint() const;
          auto& yield()  const;
          void iterNext();
          
          Value instantiateNext();
          Value reInstatiate (Idx =Idx(-1));
          Value getContent(string key);
          bool conditional (string key);
          bool openIteration (string key);
          bool loopFurther();
          void focusNested();
        };
      
      
      ActionSeq actions_;
      
    public:
      TextTemplate(string spec)
        : actions_{compile (spec)}
        { }
      
      template<class DAT>
      auto
      submit (DAT const& data)  const;
      
      template<class DAT>
      string
      render (DAT const& data)  const;
      
      template<class DAT>
      static string
      apply (string spec, DAT const& data);
      
      auto keys()  const;
      
      static ActionSeq compile (string const&);
      friend class test::TextTemplate_test;
    };
  
  
  
  
  /* ======= Parser / Compiler pipeline ======= */
  
  class TextTemplate::ActionCompiler
    {
      ScopeStack scope_{};
      
    public:
      template<class PAR>
      ActionSeq
      buildActions (PAR&& parseIter)
        {
          ActionSeq actions;
          while (parseIter)
              compile (parseIter, actions);
          return actions;
        }
      
    private:
      template<class PAR>
      void
      compile (PAR& parseIter, ActionSeq& actions)
        {
          auto currIDX     = [&]{ return actions.size(); };
          auto valid       = [&](Idx i){ return 0 < i and i < actions.size(); };
          auto clause      = [](Clause c)-> string { return c==IF? "if" : "for"; };
          auto scopeClause = [&]{ return scope_.empty()? "??" : clause(scope_.top().clause); };
          
           //  Support for bracketing constructs (if / for)
          auto beginIdx    = [&]{ return scope_.empty()? 0 : scope_.top().begin; };                    // Index of action where scope was opened
          auto scopeKey    = [&]{ return valid(beginIdx())? actions[beginIdx()].val : "";};            // Key controlling the if-/for-Scope
          auto keyMatch    = [&]{ return isnil(parseIter->key) or parseIter->key == scopeKey(); };     // Key matches in opening and closing tag
          auto clauseMatch = [&](Clause c){ return not scope_.empty() and scope_.top().clause == c; }; // Kind of closing tag matches innermost scope
          auto scopeMatch  = [&](Clause c){ return clauseMatch(c) and keyMatch(); };
          
          auto lead        = [&]{ return parseIter->lead; };
          auto clashLead   = [&]{ return actions[scope_.top().after - 1].val; };                       // (for diagnostics: lead before a conflicting other "else")
          auto abbrev      = [&](auto s){ return s.length()<16? s : s.substr(s.length()-15); };        // (shorten lead display to 15 chars)
          
           //  Syntax / consistency checks...
          auto __requireKey    = [&](string descr)
                                      {
                                        if (isnil (parseIter->key))
                                          throw error::Invalid{_Fmt{"Tag without key: ...%s${%s |↯|}"}
                                                                   % abbrev(lead()) % descr
                                      };                      };
          auto __checkBalanced = [&](Clause c)
                                      {
                                        if (not scopeMatch(c))
                                          throw error::Invalid{_Fmt{"Unbalanced Logic: expect ${end %s %s}"
                                                                    " -- found ...%s${end |↯|%s %s}"}
                                                                   % scopeClause() % scopeKey()
                                                                   % abbrev(lead())
                                                                   % clause(c) % parseIter->key
                                      };                      };
          auto __checkInScope  = [&]  {
                                        if (scope_.empty())
                                          throw error::Invalid{_Fmt{"Misplaced ...%s|↯|${else}"}
                                                                   % abbrev(lead())};
                                      };
          auto __checkNoDup    = [&]  {
                                        if (scope_.top().after != 0)
                                          throw error::Invalid{_Fmt{"Conflicting ...%s${else} ⟷ ...%s|↯|${else}"}
                                                                   % abbrev(clashLead()) % abbrev(lead())};
                                      };
          auto __checkClosed   = [&]  {
                                        if (not scope_.empty())
                                          throw error::Invalid{_Fmt{"Unclosed Logic tags: |↯|${end %s %s} missing"}
                                                                   % scopeClause() % scopeKey()};
                                      };
          
           //  Primitives used for code generation....
          auto add             = [&](Code c, string v){ actions.push_back (Action{c,v});};
          auto addCode         = [&](Code c)  { add (   c, parseIter->key);             };   // add code token and transfer key picked up by parser
          auto addLead         = [&]          { add (TEXT, string{parseIter->lead});    };   // add TEXT token to represent the static part before this tag
          auto openScope       = [&](Clause c){ scope_.push (ParseCtx{c, currIDX()});   };   // start nested scope for bracketing construct (if / for)
          auto closeScope      = [&]          { scope_.pop();                           };   // close innermost nested scope
          
          auto linkElseToStart = [&]{ actions[beginIdx()].refIDX = currIDX();           };   // link the start position of the else-branch into opening logic code
          auto markJumpInScope = [&]{ scope_.top().after = currIDX();                   };   // memorise jump before else-branch for later linkage
          auto linkLoopBack    = [&]{ actions.back().refIDX = scope_.top().begin;       };   // fill in the back-jump position at loop end
          auto linkJumpToNext  = [&]{ actions[scope_.top().after].refIDX = currIDX();   };   // link jump to the position after the end of the logic bracket
          
          auto hasElse         = [&]{ return scope_.top().after != 0; };                     // a jump code to link was only marked if there was an else tag
          
          using text_template::TagSyntax;
          
          /* === Code Generation === */
          switch (parseIter->syntax) {
            case TagSyntax::ESCAPE:
              addLead();
              break;
            case TagSyntax::KEYID:
              __requireKey("<placeholder>");
              addLead();
              addCode(KEY);
              break;
            case TagSyntax::IF:
              __requireKey("if <conditional>");
              addLead();
              openScope(IF);
              addCode(COND);
              break;
            case TagSyntax::END_IF:
              addLead();
              __checkBalanced(IF);
              if (hasElse())
                linkJumpToNext();
              else
                linkElseToStart();
              closeScope();
              break;
            case TagSyntax::FOR:
              __requireKey("for <data-id>");
              addLead();
              openScope(FOR);
              addCode(ITER);
              break;
            case TagSyntax::END_FOR:
              addLead();
              __checkBalanced(FOR);
              if (hasElse())
                linkJumpToNext();
              else
                { // no else-branch; end active loop here
                  addCode(LOOP);
                  linkLoopBack();
                  linkElseToStart();  // jump behind when iteration turns out empty
                }
              closeScope();
              break;
            case TagSyntax::ELSE:
              addLead();
              __checkInScope();
              __checkNoDup();
              if (IF == scope_.top().clause)
                {
                  markJumpInScope();
                  addCode(JUMP);
                  linkElseToStart();
                }
              else
                {
                  addCode(LOOP);
                  linkLoopBack();
                  markJumpInScope();
                  addCode(JUMP);
                  linkElseToStart();  // jump to else-block when iteration turns out empty
                }
              break;
            default:
              NOTREACHED ("uncovered TagSyntax keyword while compiling a TextTemplate.");
            }
          
          StrView tail = parseIter->tail;
          ++parseIter;
          if (not parseIter)
            {//add final action to supply text after last active tag
              add (TEXT, string{tail});
              __checkClosed();
            }
        }
    };
  
  inline TextTemplate::ActionSeq
  TextTemplate::compile (string const& spec)
  {
    ActionSeq code = ActionCompiler().buildActions (text_template::parse (spec));
    if (isnil (code))
      throw error::Invalid ("TextTemplate spec without active placeholders.");
    return code;
  }
  
  
  
  
  
  
  /* ======= preconfigured data bindings ======= */
  
  namespace text_template {
    
    template<class DAT, typename SEL>
    struct DataSource
      {
        static_assert (not sizeof(DAT),
                       "unable to bind this data source "
                       "for TextTemplate instantiation");
        
        DataSource (DAT const&);
      };
    
    using MapS = std::map<string,string>;
    
    template<>
    struct DataSource<MapS>
      {
        MapS const * data_{nullptr};
        string keyPrefix_{};
        
        bool isSubScope() { return not isnil (keyPrefix_); }
        
        DataSource()  = default;
        DataSource(MapS const& map)
          : data_{&map}
          { }
        
        
        using Value = std::string_view;
        using Iter = decltype(iterNestedKeys("",""));
        
        bool
        contains (string key)
          {
            return (isSubScope() and util::contains (*data_, keyPrefix_+key))
                or util::contains (*data_, key);
          }
        
        Value
        retrieveContent (string key)
          {
            MapS::const_iterator elm;
            if (isSubScope())
              {
                elm = data_->find (keyPrefix_+key);
                if (elm == data_->end())
                  elm = data_->find (key);
              }
            else
              elm = data_->find (key);
            ENSURE (elm != data_->end());
            return elm->second;
          }
        
        Iter
        getSequence (string key)
          {
            if (not contains(key))
              return Iter{};
            else
              return iterNestedKeys (key, retrieveContent(key));
          }
        
        DataSource
        openContext (Iter& iter)
          {
            REQUIRE (iter);
            DataSource nested{*this};
            nested.keyPrefix_ += *iter;
            return nested;
          }
      };
    
    
    using PairS = std::pair<string,string>;
    
    template<>
    struct DataSource<string>
      : DataSource<MapS>
      {
        std::shared_ptr<MapS> spec_;
        
        DataSource (string const& dataSpec)
          : spec_{new MapS}
          {
            data_ = spec_.get();
            explore (iterBindingSeq (dataSpec))
              .foreach([this](PairS const& bind){ spec_->insert (bind); });
          }
        
        DataSource
        openContext (Iter& iter)
          {
            DataSource nested(*this);
            auto nestedBase = DataSource<MapS>::openContext (iter);
            nested.keyPrefix_ = nestedBase.keyPrefix_;
            return nested;
          }
      };
    
    template<class STR,                 typename = meta::enable_if<meta::is_StringLike<STR>> >
    DataSource(STR const&) -> DataSource<string>;
    
  }// namespace text_template
  
  
  
  
  
  /* ======= implementation of the instantiation state ======= */
  
  template<class SRC>
  inline auto
  TextTemplate::Action::instantiate (InstanceCore<SRC>& core)  const
  {
    using Result = decltype (core.getContent(val));
    switch (code) {
      case TEXT:
        return Result(val);
      case KEY:
        return core.getContent (val);
      case COND:
        return core.conditional (val)? core.reInstatiate()                  // next is the conditional content
                                     : core.reInstatiate(refIDX);           // points to start of else-block (or after)
      case JUMP:
        return core.reInstatiate(refIDX);
      case ITER:
        return core.openIteration(val)? core.reInstatiate()                 // looping initiated => continue with next
                                      : core.reInstatiate(refIDX);          // points to start of else-block (or after)
      case LOOP:
        return core.loopFurther()     ? core.reInstatiate(refIDX+1)         // start with one after the loop opening
                                      : core.reInstatiate();                // continue with next -> jump over else-block
      default:
        NOTREACHED ("uncovered Activity verb in activation function.");
      }
  }
  
  
  
  template<class SRC>
  TextTemplate::InstanceCore<SRC>::InstanceCore (TextTemplate::ActionSeq const& actions, SRC s)
    : dataSrc_{s}
    , actionIter_{actions}
    , ctxStack_{}
    , rendered_{}
    {
      rendered_ = instantiateNext();
    }
  
  template<class SRC>
  inline bool
  TextTemplate::InstanceCore<SRC>::checkPoint()  const
  {
    return bool(actionIter_);
  }
  
  template<class SRC>
  inline auto&
  TextTemplate::InstanceCore<SRC>::yield()  const
  {
    return unConst(this)->rendered_;
  }
  
  template<class SRC>
  inline void
  TextTemplate::InstanceCore<SRC>::iterNext()
  {
    ++actionIter_;
    rendered_ = instantiateNext();
  }
  
  
  template<class SRC>
  inline SRC::Value
  TextTemplate::InstanceCore<SRC>::instantiateNext()
  {
    return actionIter_? actionIter_->instantiate(*this)
                      : Value{};
  }
  
  template<class SRC>
  inline SRC::Value
  TextTemplate::InstanceCore<SRC>::reInstatiate (Idx nextCode)
  {
    if (nextCode == Idx(-1))
      ++actionIter_;
    else
      actionIter_.setIDX (nextCode);
    return instantiateNext();
  }
  
  template<class SRC>
  inline SRC::Value
  TextTemplate::InstanceCore<SRC>::getContent (string key)
  {
    static Value nil{};
    return dataSrc_.contains(key)? dataSrc_.retrieveContent(key) : nil;
  }
  
  template<class SRC>
  inline bool
  TextTemplate::InstanceCore<SRC>::conditional (string key)
  {
    return not util::isNo (string{getContent (key)});
  }
  
  template<class SRC>
  inline bool
  TextTemplate::InstanceCore<SRC>::openIteration (string key)
  {
    if (conditional (key))
      if (DataCtxIter dataIter = dataSrc_.getSequence(key))
        {
          ctxStack_.push (NestedCtx{move (dataIter)
                                   ,dataSrc_});
          focusNested();
          return true;
        }
    return false;
  }
  
  template<class SRC>
  inline bool
  TextTemplate::InstanceCore<SRC>::loopFurther()
  {
    DataCtxIter& dataIter = ctxStack_.top().first;
    ++dataIter;
    if (dataIter)
      {             // open next nested context *from enclosing context*
        focusNested();
        return true;
      }
    else
      {         // restore original data context
        using std::swap;
        swap (dataSrc_, ctxStack_.top().second);
        ctxStack_.pop();
        return false;
      }
  }
  
  template<class SRC>
  inline void
  TextTemplate::InstanceCore<SRC>::focusNested()
  {
    REQUIRE (not ctxStack_.empty());
    NestedCtx& innermostScope = ctxStack_.top();
    DataCtxIter& currentDataItem = innermostScope.first;
    SRC&         parentDataSrc = innermostScope.second;
    
    this->dataSrc_ = parentDataSrc.openContext (currentDataItem);
  }
  
  
  
  
  
  template<class DAT>
  inline auto
  TextTemplate::submit (DAT const& data)  const
  {
    return explore (InstanceCore{actions_, text_template::DataSource(data)});
  }
  
  template<class DAT>
  inline string
  TextTemplate::render (DAT const& data)  const
  {
    return util::join (submit (data), "");
  }
  
  template<class DAT>
  inline string
  TextTemplate::apply (string spec, DAT const& data)
  {
    return TextTemplate(spec).render (data);
  }
  
  inline auto
  TextTemplate::keys()  const
  {
    return explore (actions_)
              .filter   ([](Action const& a){ return a.code == KEY or a.code == COND or a.code == ITER; })
              .transform([](Action const& a){ return a.val; });
  }
  
  
}// namespace lib
#endif /*LIB_TEXT_TEMPLATE_H*/