/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.jexl3;

import java.math.MathContext;
import java.util.Collection;
import java.util.Collections;
import java.util.Map;

import org.apache.commons.jexl3.internal.Engine;

/**
 * Flags and properties that can alter the evaluation behavior.
 * The flags, briefly explained, are the following:
 * <ul>
 * <li>silent: whether errors throw exception</li>
 * <li>safe: whether navigation through null is <em>not</em> an error</li>
 * <li>cancellable: whether thread interruption is an error</li>
 * <li>lexical: whether redefining local variables is an error</li>
 * <li>lexicalShade: whether local variables shade global ones even outside their scope</li>
 * <li>strict: whether unknown or unsolvable identifiers are errors</li>
 * <li>strictArithmetic: whether null as operand is an error</li>
 * <li>sharedInstance: whether these options can be modified at runtime during execution (expert)</li>
 * <li>constCapture: whether captured variables will throw an error if an attempt is made to change their value</li>
 * <li>strictInterpolation: whether interpolation strings always return a string or attempt to parse and return integer</li>
 * <li>booleanLogical: whether logical expressions (&quot;&quot; , ||) coerce their result to boolean</li>
 * </ul>
 * The sensible default is cancellable, strict and strictArithmetic.
 * <p>This interface replaces the now deprecated JexlEngine.Options.
 *
 * @since 3.2
 */
public final class JexlOptions {

    /** The namespace auto-instantiation flag. */
    private static final int NAMESPACE_INSTANTIATE = 11;

    /** The boolean logical flag. */
    private static final int BOOLEAN_LOGICAL = 10;

    /** The interpolation string bit. */
    private static final int STRICT_INTERPOLATION= 9;

    /** The const capture bit. */
    private static final int CONST_CAPTURE = 8;

    /** The shared instance bit. */
    private static final int SHARED = 7;

    /** The local shade bit. */
    private static final int SHADE = 6;

    /** The antish var bit. */
    private static final int ANTISH = 5;

    /** The lexical scope bit. */
    private static final int LEXICAL = 4;

    /** The safe bit. */
    private static final int SAFE = 3;

    /** The silent bit. */
    private static final int SILENT = 2;

    /** The strict bit. */
    private static final int STRICT = 1;

    /** The cancellable bit. */
    private static final int CANCELLABLE = 0;

    /** The flag names ordered. */
    private static final String[] NAMES = {
        "cancellable", "strict", "silent", "safe", "lexical", "antish",
        "lexicalShade", "sharedInstance", "constCapture", "strictInterpolation",
        "booleanShortCircuit", "namespaceInstantiation"
    };

    /** Default mask .*/
    private static int DEFAULT = 1 /*<< CANCELLABLE*/ | 1 << STRICT | 1 << ANTISH | 1 << SAFE
        | 1 << NAMESPACE_INSTANTIATE;

    /**
     * Checks the value of a flag in the mask.
     *
     * @param ordinal The flag ordinal
     * @param mask The flags mask
     * @return The mask value with this flag or-ed in
     */
    private static boolean isSet(final int ordinal, final int mask) {
        return (mask & 1 << ordinal) != 0;
    }

    /**
     * Parses flags by name.
     * <p>A '+flag' or 'flag' will set flag as true, '-flag' set as false.
     * The possible flag names are:
     * cancellable, strict, silent, safe, lexical, antish, lexicalShade
     *
     * @param initial The initial mask state
     * @param flags The flags to set
     * @return The flag mask updated
     */
    public static int parseFlags(final int initial, final String... flags) {
        int mask = initial;
        for (final String flag : flags) {
            boolean b = true;
            final String name;
            if (flag.charAt(0) == '+') {
                name = flag.substring(1);
            } else if (flag.charAt(0) == '-') {
                name = flag.substring(1);
                b = false;
            } else {
                name = flag;
            }
            for (int f = 0; f < NAMES.length; ++f) {
                if (NAMES[f].equals(name)) {
                    if (b) {
                        mask |= 1 << f;
                    } else {
                        mask &= ~(1 << f);
                    }
                    break;
                }
            }
        }
        return mask;
    }

    /**
     * Sets the value of a flag in a mask.
     *
     * @param ordinal The flag ordinal
     * @param mask The flags mask
     * @param value true or false
     * @return The new flags mask value
     */
    private static int set(final int ordinal, final int mask, final boolean value) {
        return value? mask | 1 << ordinal : mask & ~(1 << ordinal);
    }

    /**
     * Sets the default (static, shared) option flags.
     * <p>
     * Whenever possible, we recommend using JexlBuilder methods to unambiguously instantiate a JEXL
     * engine; this method should only be used for testing / validation.
     * <p>A '+flag' or 'flag' will set the option named 'flag' as true, '-flag' set as false.
     * The possible flag names are:
     * cancellable, strict, silent, safe, lexical, antish, lexicalShade
     * <p>Calling JexlBuilder.setDefaultOptions("+safe") once before JEXL engine creation
     * may ease validating JEXL3.2 in your environment.
     *
     * @param flags The flags to set
     */
    public static void setDefaultFlags(final String...flags) {
        DEFAULT = parseFlags(DEFAULT, flags);
    }

    /** The arithmetic math context. */
    private MathContext mathContext;

    /** The arithmetic math scale. */
    private int mathScale = Integer.MIN_VALUE;

    /** The arithmetic strict math flag. */
    private boolean strictArithmetic = true;

    /** The default flags, all but safe. */
    private int flags = DEFAULT;

    /** The namespaces .*/
    private Map<String, Object> namespaces = Collections.emptyMap();

    /** The imports. */
    private Collection<String> imports = Collections.emptySet();

    /**
     * Default ctor.
     */
    public JexlOptions() {
        // all inits in members declarations
    }

    /**
     * Creates a copy of this instance.
     *
     * @return A copy
     */
    public JexlOptions copy() {
        return new JexlOptions().set(this);
    }

    /**
     * Gets the optional set of imported packages.
     *
     * @return The set of imports, may be empty, not null
     */
    public Collection<String> getImports() {
        return imports;
    }

    /**
     * The MathContext instance used for +,-,/,*,% operations on big decimals.
     *
     * @return The math context
     */
    public MathContext getMathContext() {
        return mathContext;
    }

    /**
     * The BigDecimal scale used for comparison and coercion operations.
     *
     * @return The scale
     */
    public int getMathScale() {
        return mathScale;
    }

    /**
     * Gets the optional map of namespaces.
     *
     * @return The map of namespaces, may be empty, not null
     */
    public Map<String, Object> getNamespaces() {
        return namespaces;
    }

    /**
     * Checks whether evaluation will attempt resolving antish variable names.
     *
     * @return true if antish variables are solved, false otherwise
     */
    public boolean isAntish() {
        return isSet(ANTISH, flags);
    }

    /**
     * Gets whether logical expressions (&quot;&quot; , ||) coerce their result to boolean; if set,
     * an expression like (3 &quot;&quot; 4 &quot;&quot; 5) will evaluate to true. If not, it will evaluate to 5.
     * To preserve strict compatibility with 3.4, set the flag to true.
     *
     * @return true if short-circuit logicals coerce their result to boolean, false otherwise
     * @since 3.5.0
     */
    public boolean isBooleanLogical() {
        return isSet(BOOLEAN_LOGICAL, flags);
    }

    /**
     * Checks whether evaluation will throw JexlException.Cancel (true) or
     * return null (false) if interrupted.
     *
     * @return true when cancellable, false otherwise
     */
    public boolean isCancellable() {
        return isSet(CANCELLABLE, flags);
    }

    /**
     * Are lambda captured-variables const?
     *
     * @return true if lambda captured-variables are const, false otherwise
     */
    public boolean isConstCapture() {
        return isSet(CONST_CAPTURE, flags);
    }

    /**
     * Is reflective auto-instantiation of a namespace functor from a class/class-name
     * binding allowed?
     *
     * @return true if namespace auto-instantiation is allowed, false otherwise
     * @since 3.7.1
     */
    public boolean isNamespaceInstantiation() {
        return isSet(NAMESPACE_INSTANTIATE, flags);
    }

    /**
     * Checks whether runtime variable scope is lexical.
     * <p>If true, lexical scope applies to local variables and parameters.
     * Redefining a variable in the same lexical unit will generate errors.
     *
     * @return true if scope is lexical, false otherwise
     */
    public boolean isLexical() {
        return isSet(LEXICAL, flags);
    }

    /**
     * Checks whether local variables shade global ones.
     * <p>After a symbol is defined as local, dereferencing it outside its
     * scope will trigger an error instead of seeking a global variable of the
     * same name. To further reduce potential naming ambiguity errors,
     * global variables (ie non-local) must be declared to be assigned {@link JexlContext#has(String)}
     * when this flag is on; attempting to set an undeclared global variables will
     * raise an error.
     *
     * @return true if lexical shading is applied, false otherwise
     */
    public boolean isLexicalShade() {
        return isSet(SHADE, flags);
    }

    /**
     * Checks whether the engine considers null in navigation expression as
     * errors during evaluation.
     *
     * @return true if safe, false otherwise
     */
    public boolean isSafe() {
        return isSet(SAFE, flags);
    }

    /**
     * Gets sharing state.
     *
     * @return false if a copy of these options is used during execution,
     * true if those can potentially be modified
     */
    public boolean isSharedInstance() {
        return isSet(SHARED, flags);
    }

    /**
     * Checks whether the engine will throw a {@link JexlException} when an
     * error is encountered during evaluation.
     *
     * @return true if silent, false otherwise
     */
    public boolean isSilent() {
        return isSet(SILENT, flags);
    }

    /**
     * Checks whether the engine considers unknown variables, methods and
     * constructors as errors during evaluation.
     *
     * @return true if strict, false otherwise
     */
    public boolean isStrict() {
        return isSet(STRICT, flags);
    }

    /**
     * Checks whether the arithmetic triggers errors during evaluation when null
     * is used as an operand.
     *
     * @return true if strict, false otherwise
     */
    public boolean isStrictArithmetic() {
        return strictArithmetic;
    }

    /**
     * Gets the strict-interpolation flag of this options instance.
     *
     * @return true if interpolation strings always return string, false otherwise
     */
    public boolean isStrictInterpolation() {
        return isSet(STRICT_INTERPOLATION, flags);
    }

    /**
     * Sets options from engine.
     *
     * @param jexl The engine
     * @return {@code this} instance
     */
    public JexlOptions set(final JexlEngine jexl) {
        if (jexl instanceof Engine) {
            return ((Engine) jexl).optionsSet(this);
        }
        throw new UnsupportedOperationException("JexlEngine is not an Engine instance: " + jexl.getClass().getName());
    }

    /**
     * Sets options from options.
     *
     * @param src The options
     * @return {@code this} instance
     */
    public JexlOptions set(final JexlOptions src) {
        mathContext = src.mathContext;
        mathScale = src.mathScale;
        strictArithmetic = src.strictArithmetic;
        flags = src.flags;
        namespaces = src.namespaces;
        imports = src.imports;
        return this;
    }

    /**
     * Sets whether the engine will attempt solving antish variable names from
     * context.
     *
     * @param flag true if antish variables are solved, false otherwise
     */
    public void setAntish(final boolean flag) {
        flags = set(ANTISH, flags, flag);
    }

    /**
     * Sets whether logical expressions (&quot;&quot; , ||) coerce their result to boolean.
     *
     * @param flag true or false
     */
    public void setBooleanLogical(final boolean flag) {
        flags = set(BOOLEAN_LOGICAL, flags, flag);
    }

    /**
     * Sets whether the engine will throw JexlException.Cancel (true) or return
     * null (false) when interrupted during evaluation.
     *
     * @param flag true when cancellable, false otherwise
     */
    public void setCancellable(final boolean flag) {
        flags = set(CANCELLABLE, flags, flag);
    }

    /**
     * Sets whether lambda captured-variables are const or not.
     * <p>
     * When disabled, lambda-captured variables are implicitly converted to read-write local variable (let),
     * when enabled, those are implicitly converted to read-only local variables (const).
     * </p>
     *
     * @param flag true to enable, false to disable
     */
    public void setConstCapture(final boolean flag) {
        flags = set(CONST_CAPTURE, flags, flag);
    }

    /**
     * Sets whether a namespace bound to a class or class-name may be reflectively
     * auto-instantiated into a functor.
     *
     * @param flag true to enable, false to disable
     * @since 3.7.1
     */
    public void setNamespaceInstantiation(final boolean flag) {
        flags = set(NAMESPACE_INSTANTIATE, flags, flag);
    }

    /**
     * Sets this option flags using the +/- syntax.
     *
     * @param opts The option flags
     */
    public void setFlags(final String... opts) {
        flags = parseFlags(flags, opts);
    }

    /**
     * Sets the optional set of imports.
     *
     * @param imports The imported packages
     */
    public void setImports(final Collection<String> imports) {
        this.imports = imports == null || imports.isEmpty()? Collections.emptySet() : imports;
    }

    /**
     * Sets whether the engine uses a strict block lexical scope during
     * evaluation.
     *
     * @param flag true if lexical scope is used, false otherwise
     */
    public void setLexical(final boolean flag) {
        flags = set(LEXICAL, flags, flag);
    }

    /**
     * Sets whether the engine strictly shades global variables.
     * Local symbols shade globals after definition and creating global
     * variables is prohibited during evaluation.
     * If setting to lexical shade, lexical scope is also set.
     *
     * @param flag true if creation is allowed, false otherwise
     */
    public void setLexicalShade(final boolean flag) {
        flags = set(SHADE, flags, flag);
        if (flag) {
            flags = set(LEXICAL, flags, true);
        }
    }

    /**
     * Sets the arithmetic math context.
     *
     * @param mcontext The context
     */
    public void setMathContext(final MathContext mcontext) {
        this.mathContext = mcontext;
    }

    /**
     * Sets the arithmetic math scale.
     *
     * @param mscale The scale
     */
    public void setMathScale(final int mscale) {
        this.mathScale = mscale;
    }

    /**
     * Sets the optional map of namespaces.
     *
     * @param ns A namespaces map
     */
    public void setNamespaces(final Map<String, Object> ns) {
        this.namespaces = ns == null || ns.isEmpty()? Collections.emptyMap() : ns;
    }

    /**
     * Sets whether the engine considers null in navigation expression as null or as errors
     * during evaluation.
     * <p>If safe, encountering null during a navigation expression - dereferencing a method or a field through a null
     * object or property - will <em>not</em> be considered an error but evaluated as <em>null</em>. It is recommended
     * to use <em>setSafe(false)</em> as an explicit default.</p>
     *
     * @param flag true if safe, false otherwise
     */
    public void setSafe(final boolean flag) {
        flags = set(SAFE, flags, flag);
    }

    /**
     * Sets wether these options are immutable at runtime.
     * <p>Expert mode; allows instance handled through context to be shared
     * instead of copied.
     *
     * @param flag true if shared, false if not
     */
    public void setSharedInstance(final boolean flag) {
        flags = set(SHARED, flags, flag);
    }

    /**
     * Sets whether the engine will throw a {@link JexlException} when an error
     * is encountered during evaluation.
     *
     * @param flag true if silent, false otherwise
     */
    public void setSilent(final boolean flag) {
        flags = set(SILENT, flags, flag);
    }

    /**
     * Sets whether the engine considers unknown variables, methods and
     * constructors as errors during evaluation.
     *
     * @param flag true if strict, false otherwise
     */
    public void setStrict(final boolean flag) {
        flags = set(STRICT, flags, flag);
    }

    /**
     * Sets the strict arithmetic flag.
     *
     * @param stricta true or false
     */
    public void setStrictArithmetic(final boolean stricta) {
        this.strictArithmetic = stricta;
    }

    /**
     * Sets the strict interpolation flag.
     * <p>When strict, interpolation strings composed only of an expression (ie `${...}`) are evaluated
     * as strings; when not strict, integer results are left untouched.</p>
     * This can affect the results of expressions like <code>map.`${key}`</code> when key is
     * an integer (or a string); it is almost always possible to use <code>map[key]</code> to ensure
     * that the key type is not altered.
     *
     * @param strict true or false
     */
    public void setStrictInterpolation(final boolean strict) {
        flags = set(STRICT_INTERPOLATION, flags, strict);
    }

    @Override public String toString() {
        final StringBuilder strb = new StringBuilder();
        for(int i = 0; i < NAMES.length; ++i) {
            if (i > 0) {
                strb.append(' ');
            }
            strb.append((flags & 1 << i) != 0? '+':'-');
            strb.append(NAMES[i]);
        }
        return strb.toString();
    }

}