DocumentMarkup.h

// WARNING: Changes to this file must be contributed back to Sawyer or else they will
//          be clobbered by the next update from Sawyer.  The Sawyer repository is at
//          https://github.com/matzke1/sawyer.
 
 
 
 
#ifndef Sawyer_Document_Markup_H
#define Sawyer_Document_Markup_H
 
#include <Sawyer/Exception.h>
#include <Sawyer/Lexer.h>
#include <Sawyer/LineVector.h>
#include <Sawyer/Map.h>
#include <Sawyer/Sawyer.h>
 
#include <boost/algorithm/string/join.hpp>
#include <boost/regex.hpp>
 
namespace Sawyer {
 
namespace Document {
 
namespace Markup {
 
class Grammar;
 
//                                      Token
 
enum TokenType {
    TOK_DATA,                                           // anything that's not markup
    TOK_FUNCTION,                                       // function name, like "code" scanned from "@code"
    TOK_LEFT,                                           // unescaped left paren (escaped are part of TOK_DATA)
    TOK_RIGHT,                                          // unescaped right paren
    TOK_BLANK_LINE                                      // one or more lines with no non-white-space
};
 
typedef Lexer::Token<TokenType> Token;
 
//                                      TokenStream
 
class SAWYER_EXPORT TokenStream: public Lexer::TokenStream<Token> {
    static const char CHAR_LEFT = '{';
    static const char CHAR_RIGHT = '}';
    static const char CHAR_AT = '@';
 
public:
    explicit TokenStream(const std::string &s): Lexer::TokenStream<Token>(s) {}
    Token scanNextToken(const Container::LineVector &content, size_t &at /*in,out*/);
};
 
//                                      Function
 
class SAWYER_EXPORT Function: public SharedObject, public SharedFromThis<Function> {
public:
    typedef SharedPointer<Function> Ptr;
 
private:
    // Declaration for a formal argument
    struct FormalArg {
        std::string name;                               // name of argument for diagnostics and debugging
        Optional<std::string> dflt;                     // default value
 
        explicit FormalArg(const std::string &name, const Optional<std::string> &dflt = Sawyer::Nothing())
            : name(name), dflt(dflt) {}
 
        bool isRequired() const { if (dflt) return false; else return true; }
        bool isOptional() const { return !isRequired(); }
    };
 
    std::string name_;                                  // name of function for diagnostics and debugging
    bool isMacro_;                                      // if true, then don't evaluate args before calling
    std::vector<FormalArg> formals_;                    // declarations of formal arguments
    size_t ellipsis_;                                   // max number of additional args
 
protected:
    explicit Function(const std::string &name, bool evalArgs = true)
        : name_(name), isMacro_(!evalArgs), ellipsis_(0) {}
 
public:
    const std::string& name() const;
 
    bool isMacro() const;
 
    Ptr arg(const std::string &name);
 
    Ptr arg(const std::string &name, const std::string &dflt);
 
    Ptr ellipsis(size_t n = (size_t)(-1));
 
    size_t nRequiredArgs() const;
 
    size_t nOptionalArgs() const;
 
    size_t nAdditionalArgs() const;
 
    size_t maxArgs() const;
 
    void validateArgs(std::vector<std::string> &actuals /*in,out*/, TokenStream&) const;
 
    virtual std::string eval(const Grammar&, const std::vector<std::string> &actuals) = 0;
};
 
//                                      Errors and exceptions
 
class SAWYER_EXPORT ErrorLocation {
    friend class Grammar;
 
    // Stack frame where error occurred
    struct Frame {
        std::string name;                               // like "in @foo at name_of_input"
        size_t lineIdx;                                 // zero-origin line number
        size_t offset;                                  // beginning position within the line
        std::string input;                              // line of input causing error
        Frame(TokenStream &where, const std::string &mesg);
    };
 
    // Use the destructor to add a record to the stack frame. We could have used try/catch but that would interfere with
    // debugging the exception.  The alternative is that each function that could add a stack frame does so like this:
    //     void some_function(ErrorLocation &eloc, TokenStream &tokens, ...) {
    //         Trap trap(eloc, tokens);
    //         do_something_that_might_throw();
    //         trap.passed();
    //     }
    //
    // Any failure to reach trap.passed() will add a stack frame to the location.
    class Trap {
        ErrorLocation &eloc_;
        TokenStream &tokens_;
        std::string mesg_;
        bool passed_;
 
    public:
        Trap(ErrorLocation &eloc, TokenStream &tokens, const std::string &mesg)
            : eloc_(eloc), tokens_(tokens), mesg_(mesg), passed_(false) {}
        ~Trap() { if (!passed_) eloc_.push(Frame(tokens_, mesg_)); }
        void passed() { passed_ = true; }
    };
 
private:
    std::vector<Frame> frames_;
 
    void push(const Frame &frame) {
        frames_.push_back(frame);
    }
 
public:
    std::string toString() const;
};
 
class SAWYER_EXPORT SyntaxError: public Sawyer::Exception::SyntaxError {
    ErrorLocation eloc_;
public:
    ~SyntaxError() throw () {}
 
    SyntaxError(const std::string &mesg)
        : Sawyer::Exception::SyntaxError(mesg) {}
 
    void errorLocation(const ErrorLocation &eloc) {
        eloc_ = eloc;
    }
};
 
//                                      Predefined functions
 
class SAWYER_EXPORT StaticContent: public Function {
    std::string resultString_;
protected:
    StaticContent(const std::string &name, const std::string &resultString)
        : Function(name), resultString_(resultString) {}
public:
    static Ptr instance(const std::string &name, const std::string str) {
        return Ptr(new StaticContent(name, str));
    }
    std::string eval(const Grammar&, const std::vector<std::string> &args);
};
 
class SAWYER_EXPORT Error: public Function {
protected:
    Error(const std::string &name): Function(name) {}
public:
    static Ptr instance(const std::string &name, const std::string dfltMesg = "error") {
        return Ptr(new Error(name))->arg("message", dfltMesg);
    }
    std::string eval(const Grammar&, const std::vector<std::string> &args);
};
 
class SAWYER_EXPORT Quote: public Function {
protected:
    Quote(const std::string &name): Function(name, false) {}
public:
    static Ptr instance(const std::string &name) {
        return Ptr(new Quote(name))->ellipsis();
    }
    std::string eval(const Grammar&, const std::vector<std::string> &args);
};
 
class SAWYER_EXPORT Eval: public Function {
protected:
    Eval(const std::string &name): Function(name) {}
public:
    static Ptr instance(const std::string &name) {
        return Ptr(new Eval(name))->ellipsis();
    }
    std::string eval(const Grammar &grammar, const std::vector<std::string> &args);
};
 
class SAWYER_EXPORT IfEq: public Function {
protected:
    IfEq(const std::string &name): Function(name, false) {}
public:
    static Ptr instance(const std::string &name) {
        return Ptr(new IfEq(name))->arg("val1")->arg("val2")->arg("if_part")->arg("else_part", "");
    }
    std::string eval(const Grammar &grammar, const std::vector<std::string> &args);
};
 
class SAWYER_EXPORT Concat: public Function {
protected:
    Concat(const std::string &name): Function(name) {}
public:
    static Ptr instance(const std::string &name) {
        return Ptr(new Concat(name))->ellipsis();
    }
    std::string eval(const Grammar &grammar, const std::vector<std::string> &args);
};
 
//                                      Reflow
 
class SAWYER_EXPORT Reflow {
    size_t indentLevel_;
    std::string indentation_;                           // string for one level of indentation
    std::ostringstream out_;
    size_t column_;
    std::string spaces_;                                // accumulated white space
    std::string nonspaces_;                             // non-spaces following accumulated space
    size_t pageWidth_;
    size_t nLineFeeds_;                                 // number of consecutive linefeeds
 
public:
    explicit Reflow(size_t pageWidth = 80)
        : indentLevel_(0), indentation_("    "), column_(0), pageWidth_(pageWidth), nLineFeeds_(0) {}
 
    size_t pageWidth() const { return pageWidth_; }
    Reflow& pageWidth(size_t n) { pageWidth_ = std::max(n, (size_t)20); return *this; }
    const std::string& indentationString() const { return indentation_; }
    Reflow& indentationString(const std::string &s) { indentation_ = s; return *this; }
    Reflow& operator++();
    Reflow& operator--();
    Reflow& lineBreak();
 
    Reflow& operator()(const std::string &s);
 
    std::string toString();
 
private:
    void emitIndentation();               // indent if we're at the beginning of a line. Also discards accumulated white space.
    void emitAccumulated();               // optionally indent and emit accumulated space and non-space
    void emitNewLine();                   // advance to the next line without emitting accumulated text or indentation.
};
    
//                                      Grammar
 
class SAWYER_EXPORT Grammar {
    Container::Map<std::string, Function::Ptr> functions_;         // functions indexed by their names
    static const bool CONSUME = true;
    static const bool LEAVE = false;
 
public:
    virtual ~Grammar() {}
 
    Grammar& with(const Function::Ptr&);
 
    virtual std::string operator()(const std::string &s) const;
 
    static std::string unescape(const std::string &s);
 
    static std::string escape(const std::string &s);
    
private:
    // Evaluate an entire token stream. Throws an exception if an error occurs.
    std::string eval(TokenStream &tokens, ErrorLocation&) const;
 
    // Returns a string up to (and possibly including) the next CHAR_RIGHT that is not balanced by a CHAR_LEFT encountered
    // during the scanning.  The TOK_RIGHT is consumed if requireRight is set, and an error is thrown if that token is not
    // found.
    std::string readArgument(TokenStream&, ErrorLocation&, bool requireRight) const;
 
    // Parse one argument by parsing up to (and possibly including) the next unbalanced TOK_RIGHT.  The TOK_RIGHT is consumed
    // if requireRight is set, and an error is thrown if that token is not found.
    std::string evalArgument(TokenStream&, ErrorLocation&, bool requireRight) const;
    
    // Parse one function.  The current token should be a TOK_FUNCTION.
    std::string evalFunction(TokenStream&, ErrorLocation&) const;
};
 
} // namespace
} // namespace
} // namespace
 
#endif