File indexing completed on 2025-02-09 04:28:37

 /*
   This file is part of the KTextTemplate library
 
   SPDX-FileCopyrightText: 2009, 2010 Stephen Kelly <steveire@gmail.com>
 
   SPDX-License-Identifier: LGPL-2.1-or-later
 
 */
 
 #ifndef KTEXTTEMPLATE_CONTEXT_H
 #define KTEXTTEMPLATE_CONTEXT_H
 
 #include "abstractlocalizer.h"
 #include "ktexttemplate_export.h"
 
 #include <QVariantHash>
 
 namespace KTextTemplate
 {
 
 class RenderContext;
 
 class ContextPrivate;
 
 /// @headerfile context.h <KTextTemplate/Context>
 
 /**
   @brief The **%Context** class holds the context to render a Template with.
 
   For application developers, using the **%Context** class is a matter of
   inserting keys and values as appropriate for rendering a Template using the
   @ref insert method.
 
   @code
     auto t = engine->newTemplate(
         "Name is {% name %} and age is {% age %}.", "some_template" );
 
     Context c1;
     c1.insert( "name", "Tom" );
     c1.insert( "age", 34 );
 
     Context c2;
     c2.insert( "name", "Harry" );
     c2.insert( "age", 43 );
 
     t->render(c1); // Returns "Name is Tom and age is 43."
     t->render(c2); // Returns "Name is Harry and age is 34."
   @endcode
 
   Note that one Template may be rendered multiple times with different contexts.
   Note also that any QVariant may be inserted into a **%Context** object. Most
   commonly, QObjects will be used here.
   @see @ref custom_objects
 
   @section context_stack Context Stack.
 
   For template tag developers, some other **%Context** API is relevant.
 
   It is possible to @ref push and @ref pop layers of context while a template
   is being rendered.  This is useful if your template tag makes additional
   variables temporarily available in a part of a template.  %Template tags
   should only modify layers of context that they @ref push themselves, and
   should @ref pop any layers created before finishing its rendering step.
 
   See for example the @gr_tag{with} tag. In a template such as
 
   @code
     Some content
     {% with person.name|toUpper as lowerName %}
       Name is {% lowerName %}
     {% endwith %}
   @endcode
 
   In this case, lowerName is available in the context only between the
   @gr_tag{with} and @gr_tag{endwith} tags. The implementation of
   the @gr_tag{with} tag render method is:
 
   @code
     void WithNode::render( OutputStream *stream, Context *c ) const
     {
       c->push();
       // {% with m_filterExpression as m_name %}
       c->insert( m_name, m_filterExpression.resolve( c ) );
       m_list.render( stream, c );
       c->pop(); // The section of context defining m_name is removed.
     }
   @endcode
 
   Note that a **%Context** may temporarily override a variable in a parent
   context. This is why it is important to @ref push a new context when adding
   items to context and @ref pop it when finished.
 
   @code
     Some content
     {% with "foo" as var %}
       Var is {% var %}         // Var is "foo"
       {% with "bar" as var %}
         Var is {% var %}       // Var is "bar"
       {% endwith %}
       Var is {% var %}         // Var is "foo"
     {% endwith %}
   @endcode
 
   @author Stephen Kelly <steveire@gmail.com>
 */
 class KTEXTTEMPLATE_EXPORT Context
 {
 public:
     /**
       Creates an empty context
     */
     Context();
     /**
       Sets every key in the hash as a property name with the variant as the
       value.
     */
     explicit Context(const QVariantHash &hash);
 
     /**
       Copy Constructor
     */
     Context(const Context &other);
 
     /**
       Assignmant operator
     */
     Context &operator=(const Context &other);
 
 #ifndef K_DOXYGEN
     /**
       @internal
 
       Whether to automatically escape all context content. This is not usually
       used directly. Use the @gr_tag{autoescape} tag instead.
     */
     bool autoEscape() const;
 
     /**
       @internal
 
       Sets whether to automatically escape all context content. This is not
       usually used directly. Use the @gr_tag{autoescape} tag instead.
     */
     void setAutoEscape(bool autoescape);
 #endif
     /**
       Destructor
     */
     ~Context();
 
     /**
       Returns the context object identified by the key @p str
     */
     QVariant lookup(const QString &str) const;
 
     /**
       Insert the context object @p object identified by @p name into
       the **%Context**.
     */
     void insert(const QString &name, QObject *object);
 
     /**
       Insert the context object @p variant identified by @p name into
       the **%Context**.
     */
     void insert(const QString &name, const QVariant &variant);
 
     /**
       Pushes a new context.
       @see @ref context_stack
     */
     void push();
 
     /**
       Pops the context.
       @see @ref context_stack
     */
     void pop();
 
 #ifndef K_DOXYGEN
     /**
       @internal Returns the context hash at depth @p depth.
     */
     QVariantHash stackHash(int depth) const;
 
     /**
       @internal
       Returns whether template being rendered is being mutated.
     */
     bool isMutating() const;
 
     /**
       @internal
       Sets whether template being rendered is being mutated to @p mutating.
     */
     void setMutating(bool mutating);
 
     /**
       @internal
     */
     void addExternalMedia(const QString &absolutePart, const QString &relativePart);
 
     /**
       @internal
     */
     void clearExternalMedia();
 #endif
 
     /**
       Sets the @p localizer to be used.
 
       The **%Context** takes ownerwhip of the localizer.
     */
     void setLocalizer(QSharedPointer<AbstractLocalizer> localizer);
 
     /**
       Returns the localizer currently in use.
     */
     QSharedPointer<AbstractLocalizer> localizer() const;
 
     /**
       Returns the external media encountered in the Template while rendering.
     */
     QList<std::pair<QString, QString>> externalMedia() const;
 
     /**
       The type of urls to external media that should be put in the template.
     */
     enum UrlType {
         AbsoluteUrls, ///< Absolute URLs should be put in the template.
         RelativeUrls ///< Relative URLs should be put in the template.
     };
 
     /**
       Sets the type of external media URL to be used in the template to @p type.
       @see @ref media_finder_tag
     */
     void setUrlType(UrlType type);
 
     /**
       The type of URL used in the template.
     */
     UrlType urlType() const;
 
     /**
       Sets the relative path to external media to be used in templates to @p
       relativePath
 
       @see @ref media_finder_tag
     */
     void setRelativeMediaPath(const QString &relativePath);
 
     /**
       The relative path to external media to be used in templates.
     */
     QString relativeMediaPath() const;
 
     /**
       Returns a modifiable RenderContext. This may be used to make
       Template rendering threadsafe so that render state does not need to be
       stored in the Node implementation itself.
      */
     RenderContext *renderContext() const;
 
 private:
     Q_DECLARE_PRIVATE(Context)
     ContextPrivate *const d_ptr;
 };
 }
 
 #endif