/*
 * 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.internal;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

/**
 * A script scope, stores the declaration of parameters and local variables as symbols.
 * <p>This also acts as the functional scope and variable definition store.</p>
 *
 * @since 3.0
 */
public final class Scope {

    /**
     * The value of an as-yet undeclared but variable, for instance: x; before var x;.
     */
    static final Object UNDECLARED = new Object() {
        @Override public String toString() {
            return "??";
        }
    };

    /**
     * The value of a declared but undefined variable, for instance: var x;.
     */
    static final Object UNDEFINED = new Object() {
        @Override public String toString() {
            return "?";
        }
    };

    /**
     * The empty string array.
     */
    private static final String[] EMPTY_STRS = {};

    /**
     * The parent scope.
     */
    private final Scope parent;

    /**
     * The number of parameters.
     */
    private int parms;

    /**
     * The number of local variables.
     */
    private int vars;

    /**
     * The map of named variables aka script parameters and local variables.
     * Each parameter is associated with a symbol and is materialized as an offset in the stacked array used
     * during evaluation.
     */
    private Map<String, Integer> namedVariables;

    /**
     * The map of local captured variables to parent scope variables, i.e., closure.
     */
    private Map<Integer, Integer> capturedVariables;

    /**
     * Let symbols.
     */
    private LexicalScope lexicalVariables;

    /**
     * Creates a new scope with a list of parameters.
     *
     * @param scope the parent scope if any
     * @param parameters the list of parameters
     */
    public Scope(final Scope scope, final String... parameters) {
        if (parameters != null) {
            parms = parameters.length;
            namedVariables = new LinkedHashMap<>();
            for (int p = 0; p < parms; ++p) {
                namedVariables.put(parameters[p], p);
            }
        } else {
            parms = 0;
        }
        vars = 0;
        parent = scope;
    }

    /**
     * Gets an unmodifiable view of a scope&quote;s symbols map.
     *
     * @param scope the scope
     * @return the symbols map
     */
     static Map<String, Integer> getSymbolsMap(final Scope scope) {
        if (scope != null && scope.namedVariables != null) {
            return Collections.unmodifiableMap(scope.namedVariables);
        }
        return Collections.emptyMap();
    }

    /**
     * Marks a symbol as lexical, declared through let or const.
     *
     * @param s the symbol
     * @return true if the symbol was not already present in the lexical set
     */
    public boolean addLexical(final int s) {
        if (lexicalVariables == null) {
            lexicalVariables = new LexicalScope();
        }
        return lexicalVariables.addSymbol(s);
    }

    /**
     * Creates a frame by copying values up to the number of parameters.
     * <p>This captures the captured variables values.</p>
     *
     * @param frame the caller frame
     * @param args the arguments
     * @return the arguments array
     */
    public Frame createFrame(final boolean ref, final Frame frame, final Object...args) {
        if (namedVariables == null) {
            return null;
        }
        final Object[] arguments = new Object[namedVariables.size()];
        Arrays.fill(arguments, UNDECLARED);
        final Frame newFrame;
        if (frame != null && capturedVariables != null && parent != null) {
            for (final Map.Entry<Integer, Integer> capture : capturedVariables.entrySet()) {
                final Integer target = capture.getKey();
                final Integer source = capture.getValue();
                final boolean lexical = lexicalVariables != null && lexicalVariables.hasSymbol(target);
                final Object arg = frame.capture(source, lexical);
                arguments[target] = arg;
            }
            newFrame = frame.newFrame(this, arguments, 0);
        } else {
            newFrame = ref
            ? new ReferenceFrame(this, arguments, 0)
            : new Frame(this, arguments, 0);
        }
        return newFrame.assign(args);
    }

    /**
     * Declares a parameter.
     * <p>
     * This method creates a new entry in the symbol map.
     * </p>
     *
     * @param param the parameter name
     * @return the register index storing this variable
     */
    public int declareParameter(final String param) {
        if (namedVariables == null) {
            namedVariables = new LinkedHashMap<>();
        } else if (vars > 0) {
            throw new IllegalStateException("cant declare parameters after variables");
        }
        return namedVariables.computeIfAbsent(param, name -> {
            final int register = namedVariables.size();
            parms += 1;
            return register;
        });
    }

    /**
     * Declares a local variable.
     * <p>
     * This method creates a new entry in the symbol map.
     * </p>
     *
     * @param varName the variable name
     * @return the register index storing this variable
     */
    public int declareVariable(final String varName) {
        if (namedVariables == null) {
            namedVariables = new LinkedHashMap<>();
        }
        return namedVariables.computeIfAbsent(varName, name -> {
           final int register = namedVariables.size();
            vars += 1;
            // check if local is redefining captured
            if (parent != null) {
                final Integer pr = parent.getSymbol(name, true);
                if (pr != null) {
                    if (capturedVariables == null) {
                        capturedVariables = new LinkedHashMap<>();
                    }
                    capturedVariables.put(register, pr);
                }
            }
            return register;
        });
    }

    /**
     * Gets the (maximum) number of arguments this script expects.
     *
     * @return the number of parameters
     */
    public int getArgCount() {
        return parms;
    }

    /**
     * Gets the captured index of a given symbol, i.e., the target index of a symbol in a child scope.
     *
     * @param symbol the symbol index
     * @return the target symbol index or null if the symbol is not captured
     */
    public Integer getCaptured(final int symbol) {
        if (capturedVariables != null) {
            for (final Map.Entry<Integer, Integer> capture : capturedVariables.entrySet()) {
                final Integer source = capture.getValue();
                if (source == symbol) {
                    return capture.getKey();
                }
            }
        }
        return null;
    }

    /**
     * Gets the index of a captured symbol, i.e., the source index of a symbol in a parent scope.
     *
     * @param symbol the symbol index
     * @return the source symbol index or -1 if the symbol is not captured
     */
    public int getCaptureDeclaration(final int symbol) {
        final Integer declared = capturedVariables != null ? capturedVariables.get(symbol)  : null;
        return declared != null ? declared : -1;
    }

    /**
     * Gets this script captured symbols names, i.e., local variables defined in outer scopes and used
     * by this scope.
     *
     * @return the captured names
     */
    public String[] getCapturedVariables() {
        if (capturedVariables != null) {
            final List<String> captured = new ArrayList<>(vars);
            for (final Map.Entry<String, Integer> entry : namedVariables.entrySet()) {
                final int symnum = entry.getValue();
                if (symnum >= parms && capturedVariables.containsKey(symnum)) {
                    captured.add(entry.getKey());
                }
            }
            if (!captured.isEmpty()) {
                return captured.toArray(new String[0]);
            }
        }
        return EMPTY_STRS;
    }

    /**
     * Gets this script local variable, i.e. symbols assigned to local variables excluding captured variables.
     *
     * @return the local variable names
     */
    public String[] getLocalVariables() {
        if (namedVariables == null || vars <= 0) {
            return EMPTY_STRS;
        }
        final List<String> locals = new ArrayList<>(vars);
        for (final Map.Entry<String, Integer> entry : namedVariables.entrySet()) {
            final int symnum = entry.getValue();
            if (symnum >= parms && (capturedVariables == null || !capturedVariables.containsKey(symnum))) {
                locals.add(entry.getKey());
            }
        }
        return locals.toArray(new String[0]);
    }

    /**
     * Gets this script parameters, i.e., symbols assigned before creating local variables.
     *
     * @return the parameter names
     */
    public String[] getParameters() {
        return getParameters(0);
    }

    /**
     * Gets this script parameters.
     *
     * @param bound number of known bound parameters (curry)
     * @return the parameter names
     */
     String[] getParameters(final int bound) {
        final int unbound = parms - bound;
        if (namedVariables == null || unbound <= 0) {
            return EMPTY_STRS;
        }
        final String[] pa = new String[unbound];
        int p = 0;
        for (final Map.Entry<String, Integer> entry : namedVariables.entrySet()) {
            final int argn = entry.getValue();
            if (argn >= bound && argn < parms) {
                pa[p++] = entry.getKey();
            }
        }
        return pa;
    }

    Scope getParent() {
        return parent;
    }

    /**
     * Checks whether an identifier is a local variable or argument, i.e., a symbol.
     * If this fails, look within parents for a symbol that can be captured.
     *
     * @param name the symbol name
     * @return the symbol index
     */
    public Integer getSymbol(final String name) {
        return getSymbol(name, true);
    }

    /**
     * Checks whether an identifier is a local variable or argument, i.e., a symbol.
     *
     * @param name the symbol name
     * @param capture whether solving by capturing a parent symbol is allowed
     * @return the symbol index
     */
    private Integer getSymbol(final String name, final boolean capture) {
        Integer register = namedVariables != null ? namedVariables.get(name) : null;
        if (register == null && capture && parent != null) {
            final Integer pr = parent.getSymbol(name, true);
            if (pr != null) {
                if (capturedVariables == null) {
                    capturedVariables = new LinkedHashMap<>();
                }
                if (namedVariables == null) {
                    namedVariables = new LinkedHashMap<>();
                }
                register = namedVariables.size();
                namedVariables.put(name, register);
                capturedVariables.put(register, pr);
            }
        }
        return register;
    }

    /**
     * Gets this script symbols names, i.e., parameters and local variables.
     *
     * @return the symbol names
     */
    public String[] getSymbols() {
        return namedVariables != null ? namedVariables.keySet().toArray(new String[0]) : EMPTY_STRS;
    }

    /**
     * Checks whether a given symbol is captured.
     *
     * @param symbol the symbol number
     * @return true if captured, false otherwise
     */
    public boolean isCapturedSymbol(final int symbol) {
        return capturedVariables != null && capturedVariables.containsKey(symbol);
    }

    /**
     * Checks whether a symbol is declared through a let or const.
     *
     * @param s the symbol
     * @return true if symbol was declared through let or const
     */
    public boolean isLexical(final int s) {
        return lexicalVariables != null && s >= 0 && lexicalVariables.hasSymbol(s);
    }
}
