/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/*
 * Options for JavaScript compilation.
 *
 * In the most common use case, a CompileOptions instance is allocated on the
 * stack, and holds non-owning references to non-POD option values: strings,
 * principals, objects, and so on.  The code declaring the instance guarantees
 * that such option values will outlive the CompileOptions itself: objects are
 * otherwise rooted, principals have had their reference counts bumped, and
 * strings won't be freed until the CompileOptions goes out of scope.  In this
 * situation, CompileOptions only refers to things others own, so it can be
 * lightweight.
 *
 * In some cases, however, we need to hold compilation options with a
 * non-stack-like lifetime.  For example, JS::CompileOffThread needs to save
 * compilation options where a worker thread can find them, then return
 * immediately.  The worker thread will come along at some later point, and use
 * the options.
 *
 * The compiler itself just needs to be able to access a collection of options;
 * it doesn't care who owns them, or what's keeping them alive.  It does its
 * own addrefs/copies/tracing/etc.
 *
 * Furthermore, in some cases compile options are propagated from one entity to
 * another (e.g. from a script to a function defined in that script).  This
 * involves copying over some, but not all, of the options.
 *
 * So we have a class hierarchy that reflects these four use cases:
 *
 * - TransitiveCompileOptions is the common base class, representing options
 *   that should get propagated from a script to functions defined in that
 *   script.  This class is abstract and is only ever used as a subclass.
 *
 * - ReadOnlyCompileOptions is the only subclass of TransitiveCompileOptions,
 *   representing a full set of compile options.  It can be used by code that
 *   simply needs to access options set elsewhere, like the compiler.  This
 *   class too is abstract and is only ever used as a subclass.
 *
 * - The usual CompileOptions class must be stack-allocated, and holds
 *   non-owning references to the filename, element, and so on. It's derived
 *   from ReadOnlyCompileOptions, so the compiler can use it.
 *
 * - OwningCompileOptions roots / copies / reference counts of all its values,
 *   and unroots / frees / releases them when it is destructed. It too is
 *   derived from ReadOnlyCompileOptions, so the compiler accepts it.
 */

#ifndef js_CompileOptions_h
#define js_CompileOptions_h

#include "mozilla/Attributes.h" // MOZ_MUST_USE
#include "mozilla/MemoryReporting.h" // mozilla::MallocSizeOf

#include <stddef.h> // size_t
#include <stdint.h> // uint8_t

#include "jstypes.h" // JS_PUBLIC_API

#include "js/RootingAPI.h" // JS::PersistentRooted, JS::Rooted

struct JSContext;
class JSObject;
class JSScript;
class JSString;

namespace JS {

enum class AsmJSOption : uint8_t
{
    Enabled,
    Disabled,
    DisabledByDebugger,
};

/**
 * The common base class for the CompileOptions hierarchy.
 *
 * Use this in code that needs to propagate compile options from one
 * compilation unit to another.
 */
class JS_PUBLIC_API(TransitiveCompileOptions)
{
  protected:
    /**
     * The Web Platform allows scripts to be loaded from arbitrary cross-origin
     * sources. This allows an attack by which a malicious website loads a
     * sensitive file (say, a bank statement) cross-origin (using the user's
     * cookies), and sniffs the generated syntax errors (via a window.onerror
     * handler) for juicy morsels of its contents.
     *
     * To counter this attack, HTML5 specifies that script errors should be
     * sanitized ("muted") when the script is not same-origin with the global
     * for which it is loaded. Callers should set this flag for cross-origin
     * scripts, and it will be propagated appropriately to child scripts and
     * passed back in JSErrorReports.
     */
    bool mutedErrors_ = false;

    const char* filename_ = nullptr;
    const char* introducerFilename_ = nullptr;
    const char16_t* sourceMapURL_ = nullptr;

  public:
    // POD options.
    bool selfHostingMode = false;
    bool canLazilyParse = true;
    bool strictOption = false;
    bool extraWarningsOption = false;
    bool werrorOption = false;
    AsmJSOption asmJSOption = AsmJSOption::Disabled;
    bool throwOnAsmJSValidationFailureOption = false;
    bool forceAsync = false;
    bool sourceIsLazy = false;
    bool allowHTMLComments = true;
    bool isProbablySystemCode = false;
    bool hideScriptFromDebugger = false;

    /**
     * |introductionType| is a statically allocated C string: one of "eval",
     * "Function", or "GeneratorFunction".
     */
    const char* introductionType = nullptr;

    unsigned introductionLineno = 0;
    uint32_t introductionOffset = 0;
    bool hasIntroductionInfo = false;

  protected:
    TransitiveCompileOptions() = default;

    // Set all POD options (those not requiring reference counts, copies,
    // rooting, or other hand-holding) to their values in |rhs|.
    void copyPODTransitiveOptions(const TransitiveCompileOptions& rhs);

  public:
    // Read-only accessors for non-POD options. The proper way to set these
    // depends on the derived type.
    bool mutedErrors() const { return mutedErrors_; }
    const char* filename() const { return filename_; }
    const char* introducerFilename() const { return introducerFilename_; }
    const char16_t* sourceMapURL() const { return sourceMapURL_; }
    virtual JSObject* element() const = 0;
    virtual JSString* elementAttributeName() const = 0;
    virtual JSScript* introductionScript() const = 0;

  private:
    void operator=(const TransitiveCompileOptions&) = delete;
};

class JS_PUBLIC_API(CompileOptions);

/**
 * The class representing a full set of compile options.
 *
 * Use this in code that only needs to access compilation options created
 * elsewhere, like the compiler.  Don't instantiate this class (the constructor
 * is protected anyway); instead, create instances only of the derived classes:
 * CompileOptions and OwningCompileOptions.
 */
class JS_PUBLIC_API(ReadOnlyCompileOptions)
  : public TransitiveCompileOptions
{
  public:
    // POD options.
    unsigned lineno  = 1;
    unsigned column = 0;

    // The offset within the ScriptSource's full uncompressed text of the first
    // character we're presenting for compilation with this CompileOptions.
    //
    // When we compile a LazyScript, we pass the compiler only the substring of
    // the source the lazy function occupies. With chunked decompression, we
    // may not even have the complete uncompressed source present in memory. But
    // parse node positions are offsets within the ScriptSource's full text,
    // and LazyScripts indicate their substring of the full source by its
    // starting and ending offsets within the full text. This
    // scriptSourceOffset field lets the frontend convert between these
    // offsets and offsets within the substring presented for compilation.
    unsigned scriptSourceOffset = 0;

    // isRunOnce only applies to non-function scripts.
    bool isRunOnce =  false;

    bool nonSyntacticScope = false;
    bool noScriptRval = false;
    bool allowSyntaxParser = true;


  private:
    friend class CompileOptions;

  protected:
    ReadOnlyCompileOptions() = default;

    // Set all POD options (those not requiring reference counts, copies,
    // rooting, or other hand-holding) to their values in |rhs|.
    void copyPODOptions(const ReadOnlyCompileOptions& rhs);

  public:
    // Read-only accessors for non-POD options. The proper way to set these
    // depends on the derived type.
    bool mutedErrors() const { return mutedErrors_; }
    const char* filename() const { return filename_; }
    const char* introducerFilename() const { return introducerFilename_; }
    const char16_t* sourceMapURL() const { return sourceMapURL_; }
    virtual JSObject* element() const override = 0;
    virtual JSString* elementAttributeName() const override = 0;
    virtual JSScript* introductionScript() const override = 0;

  private:
    void operator=(const ReadOnlyCompileOptions&) = delete;
};

/**
 * Compilation options, with dynamic lifetime. An instance of this type
 * makes a copy of / holds / roots all dynamically allocated resources
 * (principals; elements; strings) that it refers to. Its destructor frees
 * / drops / unroots them. This is heavier than CompileOptions, below, but
 * unlike CompileOptions, it can outlive any given stack frame.
 *
 * Note that this *roots* any JS values it refers to - they're live
 * unconditionally. Thus, instances of this type can't be owned, directly
 * or indirectly, by a JavaScript object: if any value that this roots ever
 * comes to refer to the object that owns this, then the whole cycle, and
 * anything else it entrains, will never be freed.
 */
class JS_PUBLIC_API(OwningCompileOptions) final
  : public ReadOnlyCompileOptions
{
    PersistentRooted<JSObject*> elementRoot;
    PersistentRooted<JSString*> elementAttributeNameRoot;
    PersistentRooted<JSScript*> introductionScriptRoot;

  public:
    // A minimal constructor, for use with OwningCompileOptions::copy.
    explicit OwningCompileOptions(JSContext* cx);
    ~OwningCompileOptions();

    JSObject* element() const override { return elementRoot; }
    JSString* elementAttributeName() const override { return elementAttributeNameRoot; }
    JSScript* introductionScript() const override { return introductionScriptRoot; }

    /** Set this to a copy of |rhs|.  Return false on OOM. */
    bool copy(JSContext* cx, const ReadOnlyCompileOptions& rhs);

    /* These setters make copies of their string arguments and are fallible. */
    MOZ_MUST_USE bool setFile(JSContext* cx, const char* f);
    MOZ_MUST_USE bool setFileAndLine(JSContext* cx, const char* f, unsigned l);
    MOZ_MUST_USE bool setSourceMapURL(JSContext* cx, const char16_t* s);
    MOZ_MUST_USE bool setIntroducerFilename(JSContext* cx, const char* s);

    /* These setters are infallible, and can be chained. */

    OwningCompileOptions& setLine(unsigned l) {
        lineno = l;
        return *this;
    }

    OwningCompileOptions& setElement(JSObject* e) {
        elementRoot = e;
        return *this;
    }

    OwningCompileOptions& setElementAttributeName(JSString* p) {
        elementAttributeNameRoot = p;
        return *this;
    }

    OwningCompileOptions& setIntroductionScript(JSScript* s) {
        introductionScriptRoot = s;
        return *this;
    }

    OwningCompileOptions& setMutedErrors(bool mute) {
        mutedErrors_ = mute;
        return *this;
    }

    OwningCompileOptions& setColumn(unsigned c) {
        column = c;
        return *this;
    }

    OwningCompileOptions& setScriptSourceOffset(unsigned o) {
        scriptSourceOffset = o;
        return *this;
    }

    OwningCompileOptions& setIsRunOnce(bool once) {
        isRunOnce = once;
        return *this;
    }

    OwningCompileOptions& setNoScriptRval(bool nsr) {
        noScriptRval = nsr;
        return *this;
    }

    OwningCompileOptions& setSelfHostingMode(bool shm) {
        selfHostingMode = shm;
        return *this;
    }

    OwningCompileOptions& setCanLazilyParse(bool clp) {
        canLazilyParse = clp;
        return *this;
    }

    OwningCompileOptions& setAllowSyntaxParser(bool clp) {
        allowSyntaxParser = clp;
        return *this;
    }

    OwningCompileOptions& setSourceIsLazy(bool l) {
        sourceIsLazy = l;
        return *this;
    }

    OwningCompileOptions& setNonSyntacticScope(bool n) {
        nonSyntacticScope = n;
        return *this;
    }

    OwningCompileOptions& setIntroductionType(const char* t) {
        introductionType = t;
        return *this;
    }

    bool setIntroductionInfo(JSContext* cx, const char* introducerFn,
                             const char* intro, unsigned line,
                             JSScript* script, uint32_t offset)
    {
        if (!setIntroducerFilename(cx, introducerFn)) {
            return false;
        }

        introductionType = intro;
        introductionLineno = line;
        introductionScriptRoot = script;
        introductionOffset = offset;
        hasIntroductionInfo = true;
        return true;
    }

    size_t sizeOfExcludingThis(mozilla::MallocSizeOf mallocSizeOf) const;

  private:
    void operator=(const CompileOptions& rhs) = delete;
};

/**
 * Compilation options stored on the stack. An instance of this type
 * simply holds references to dynamically allocated resources (element;
 * filename; source map URL) that are owned by something else. If you
 * create an instance of this type, it's up to you to guarantee that
 * everything you store in it will outlive it.
 */
class MOZ_STACK_CLASS JS_PUBLIC_API(CompileOptions) final
  : public ReadOnlyCompileOptions
{
  private:
    Rooted<JSObject*> elementRoot;
    Rooted<JSString*> elementAttributeNameRoot;
    Rooted<JSScript*> introductionScriptRoot;

  public:
    explicit CompileOptions(JSContext* cx);

    CompileOptions(JSContext* cx, const ReadOnlyCompileOptions& rhs)
      : ReadOnlyCompileOptions(),
        elementRoot(cx),
        elementAttributeNameRoot(cx),
        introductionScriptRoot(cx)
    {
        copyPODOptions(rhs);

        filename_ = rhs.filename();
        introducerFilename_ = rhs.introducerFilename();
        sourceMapURL_ = rhs.sourceMapURL();
        elementRoot = rhs.element();
        elementAttributeNameRoot = rhs.elementAttributeName();
        introductionScriptRoot = rhs.introductionScript();
    }

    CompileOptions(JSContext* cx, const TransitiveCompileOptions& rhs)
      : ReadOnlyCompileOptions(),
        elementRoot(cx),
        elementAttributeNameRoot(cx),
        introductionScriptRoot(cx)
    {
        copyPODTransitiveOptions(rhs);

        filename_ = rhs.filename();
        introducerFilename_ = rhs.introducerFilename();
        sourceMapURL_ = rhs.sourceMapURL();
        elementRoot = rhs.element();
        elementAttributeNameRoot = rhs.elementAttributeName();
        introductionScriptRoot = rhs.introductionScript();
    }

    JSObject* element() const override {
        return elementRoot;
    }

    JSString* elementAttributeName() const override {
        return elementAttributeNameRoot;
    }

    JSScript* introductionScript() const override {
        return introductionScriptRoot;
    }

    CompileOptions& setFile(const char* f) {
        filename_ = f;
        return *this;
    }

    CompileOptions& setLine(unsigned l) {
        lineno = l;
        return *this;
    }

    CompileOptions& setFileAndLine(const char* f, unsigned l) {
        filename_ = f;
        lineno = l;
        return *this;
    }

    CompileOptions& setSourceMapURL(const char16_t* s) {
        sourceMapURL_ = s;
        return *this;
    }

    CompileOptions& setElement(JSObject* e) {
        elementRoot = e;
        return *this;
    }

    CompileOptions& setElementAttributeName(JSString* p) {
        elementAttributeNameRoot = p;
        return *this;
    }

    CompileOptions& setIntroductionScript(JSScript* s) {
        introductionScriptRoot = s;
        return *this;
    }

    CompileOptions& setMutedErrors(bool mute) {
        mutedErrors_ = mute;
        return *this;
    }

    CompileOptions& setColumn(unsigned c) {
        column = c;
        return *this;
    }

    CompileOptions& setScriptSourceOffset(unsigned o) {
        scriptSourceOffset = o;
        return *this;
    }

    CompileOptions& setIsRunOnce(bool once) {
        isRunOnce = once;
        return *this;
    }

    CompileOptions& setNoScriptRval(bool nsr) {
        noScriptRval = nsr;
        return *this;
    }

    CompileOptions& setSelfHostingMode(bool shm) {
        selfHostingMode = shm;
        return *this;
    }

    CompileOptions& setCanLazilyParse(bool clp) {
        canLazilyParse = clp;
        return *this;
    }

    CompileOptions& setAllowSyntaxParser(bool clp) {
        allowSyntaxParser = clp;
        return *this;
    }

    CompileOptions& setSourceIsLazy(bool l) {
        sourceIsLazy = l;
        return *this;
    }

    CompileOptions& setNonSyntacticScope(bool n) {
        nonSyntacticScope = n;
        return *this;
    }

    CompileOptions& setIntroductionType(const char* t) {
        introductionType = t;
        return *this;
    }

    CompileOptions& setIntroductionInfo(const char* introducerFn,
                                        const char* intro, unsigned line,
                                        JSScript* script, uint32_t offset)
    {
        introducerFilename_ = introducerFn;
        introductionType = intro;
        introductionLineno = line;
        introductionScriptRoot = script;
        introductionOffset = offset;
        hasIntroductionInfo = true;
        return *this;
    }

    CompileOptions& maybeMakeStrictMode(bool strict) {
        strictOption = strictOption || strict;
        return *this;
    }

  private:
    void operator=(const CompileOptions& rhs) = delete;
};

} // namespace JS

#endif /* js_CompileOptions_h */