/*
    * SPDX-FileCopyrightText: none
    * SPDX-License-Identifier: CC0-1.0
    */
   
   package gov.nist.secauto.metaschema.core.metapath.function;
   
   import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
   import gov.nist.secauto.metaschema.core.metapath.ISequence;
  import gov.nist.secauto.metaschema.core.metapath.MetapathException;
  import gov.nist.secauto.metaschema.core.metapath.item.IItem;
  import gov.nist.secauto.metaschema.core.util.ObjectUtils;
  
  import java.net.URI;
  import java.util.ArrayList;
  import java.util.EnumSet;
  import java.util.LinkedList;
  import java.util.List;
  import java.util.Objects;
  import java.util.Set;
  import java.util.stream.Collectors;
  
  import javax.xml.namespace.QName;
  
  import edu.umd.cs.findbugs.annotations.NonNull;
  
  /**
   * A common interface for all Metapath functions.
   */
  public interface IFunction {
    /**
     * Details specific characteristics of a function.
     */
    enum FunctionProperty {
      /**
       * Indicates that the function will produce identical results for the same
       * arguments (see XPath 3.1 <a href=
       * "https://www.w3.org/TR/xpath-functions-31/#dt-deterministic">deterministic</a>).
       * If not assigned to a function definition, a function call with the same
       * arguments is not guaranteed to produce the same results in the same order for
       * subsequent calls within the same execution context.
       */
      DETERMINISTIC,
      /**
       * Indicates that the result of the function depends on property values within
       * the static or dynamic context and the provided arguments (see XPath 3.1
       * <a href=
       * "https://www.w3.org/TR/xpath-functions-31/#dt-context-dependent">context-dependent</a>).
       * If not assigned to a function definition, a call will not be affected by the
       * property values within the static or dynamic context and will not have any
       * arguments.
       */
      CONTEXT_DEPENDENT,
      /**
       * Indicates that the result of the function depends on the current focus (see
       * XPath 3.1 <a href=
       * "https://www.w3.org/TR/xpath-functions-31/#dt-focus-independent">focus-dependent</a>).
       * If not assigned to a function definition, a call will not be affected by the
       * current focus.
       */
      FOCUS_DEPENDENT,
      /**
       * The function allows the last argument to be repeated any number of times.
       */
      UNBOUNDED_ARITY;
    }
  
    /**
     * Retrieve the name of the function.
     *
     * @return the function's name
     */
    @NonNull
    default String getName() {
      return ObjectUtils.notNull(getQName().getLocalPart());
    }
  
    /**
     * Retrieve the namespace qualified name of the function.
     *
     * @return the namespace qualified name
     */
    @NonNull
    QName getQName();
  
    /**
     * Retrieve the set of assigned function properties.
     *
     * @return the set of properties or an empty set
     */
    @NonNull
    Set<FunctionProperty> getProperties();
  
    /**
     * Retrieve the list of function arguments.
     *
     * @return the function arguments or an empty list if there are none
     */
    @NonNull
   List<IArgument> getArguments();
 
   /**
    * Determine the number of arguments the function has.
    *
    * @return the number of function arguments
    */
   int arity();
 
   /**
    * Determines if the result of the function call will produce identical results
    * when provided the same implicit or explicit arguments.
    *
    * @return {@code true} if function is deterministic or {@code false} otherwise
    * @see FunctionProperty#DETERMINISTIC
    */
   default boolean isDeterministic() {
     return getProperties().contains(FunctionProperty.DETERMINISTIC);
   }
 
   /**
    * Determines if the result of the function call depends on property values
    * within the static or dynamic context and the provided arguments.
    *
    * @return {@code true} if function is context dependent or {@code false}
    *         otherwise
    * @see FunctionProperty#CONTEXT_DEPENDENT
    */
   default boolean isContextDepenent() {
     return getProperties().contains(FunctionProperty.CONTEXT_DEPENDENT);
   }
 
   /**
    * Determines if the result of the function call depends on the current focus.
    *
    * @return {@code true} if function is focus dependent or {@code false}
    *         otherwise
    * @see FunctionProperty#FOCUS_DEPENDENT
    */
   default boolean isFocusDepenent() {
     return getProperties().contains(FunctionProperty.FOCUS_DEPENDENT);
   }
 
   /**
    * Determines if the final argument can be repeated.
    *
    * @return {@code true} if the final argument can be repeated or {@code false}
    *         otherwise
    * @see FunctionProperty#UNBOUNDED_ARITY
    */
   default boolean isArityUnbounded() {
     return getProperties().contains(FunctionProperty.UNBOUNDED_ARITY);
   }
 
   /**
    * Retrieve the function result sequence type.
    *
    * @return the function result sequence type
    */
   @NonNull
   ISequenceType getResult();
 
   // /**
   // * Determines by static analysis if the function supports the expression
   // arguments provided.
   // *
   // * @param arguments
   // * the expression arguments to evaluate
   // * @return {@code true} if the arguments are supported or {@code false}
   // otherwise
   // */
   // boolean isSupported(List<IExpression<?>> arguments);
 
   /**
    * Execute the function with the provided {@code arguments}, using the provided
    * {@code DynamicContext} and {@code focus}.
    *
    * @param arguments
    *          the function arguments or an empty list if there are no arguments
    * @param dynamicContext
    *          the dynamic evaluation context
    * @param focus
    *          the current focus or an empty sequence if there is no focus
    * @return the function result
    * @throws MetapathException
    *           if an error occurred while executing the function
    */
   @NonNull
   ISequence<?> execute(
       @NonNull List<ISequence<?>> arguments,
       @NonNull DynamicContext dynamicContext,
       @NonNull ISequence<?> focus);
 
   /**
    * Get the signature of the function as a string.
    *
    * @return the signature
    */
   @NonNull
   default String toSignature() {
     return ObjectUtils.notNull(String.format("%s(%s) as %s",
         getQName(),
         getArguments().isEmpty() ? ""
             : getArguments().stream().map(IArgument::toSignature).collect(Collectors.joining(","))
                 + (isArityUnbounded() ? ", ..." : ""),
         getResult().toSignature()));
   }
 
   /**
    * Construct a new function signature builder.
    *
    * @return the new builder instance
    */
   @NonNull
   static Builder builder() {
     return new Builder();
   }
 
   /**
    * Used to create a function's signature using a builder pattern.
    */
   @SuppressWarnings("PMD.LooseCoupling")
   final class Builder {
     private String name;
     private String namespace;
     @SuppressWarnings("null")
     @NonNull
     private final EnumSet<FunctionProperty> properties = EnumSet.noneOf(FunctionProperty.class);
     @NonNull
     private final List<IArgument> arguments = new LinkedList<>();
     @NonNull
     private Class<? extends IItem> returnType = IItem.class;
     @NonNull
     private Occurrence returnOccurrence = Occurrence.ONE;
     private IFunctionExecutor functionHandler;
 
     private Builder() {
       // do nothing
     }
 
     /**
      * Define the name of the function.
      *
      * @param name
      *          the function's name
      * @return this builder
      */
     @NonNull
     public Builder name(@NonNull String name) {
       Objects.requireNonNull(name, "name");
       if (name.isBlank()) {
         throw new IllegalArgumentException("the name must be non-blank");
       }
       this.name = name.trim();
       return this;
     }
 
     /**
      * Define the namespace of the function.
      *
      * @param uri
      *          the function's namespace URI
      * @return this builder
      */
     @NonNull
     public Builder namespace(@NonNull URI uri) {
       return namespace(ObjectUtils.notNull(uri.toASCIIString()));
     }
 
     /**
      * Define the namespace of the function.
      *
      * @param name
      *          the function's namespace URI as a string
      * @return this builder
      */
     @NonNull
     public Builder namespace(@NonNull String name) {
       Objects.requireNonNull(name, "name");
       if (name.isBlank()) {
         throw new IllegalArgumentException("the name must be non-blank");
       }
       this.namespace = name.trim();
       return this;
     }
 
     /**
      * Mark the function as deterministic.
      *
      * @return this builder
      * @see IFunction.FunctionProperty#DETERMINISTIC
      */
     @NonNull
     public Builder deterministic() {
       properties.add(FunctionProperty.DETERMINISTIC);
       return this;
     }
 
     /**
      * Mark the function as non-deterministic.
      *
      * @return this builder
      * @see IFunction.FunctionProperty#DETERMINISTIC
      */
     @NonNull
     public Builder nonDeterministic() {
       properties.remove(FunctionProperty.DETERMINISTIC);
       return this;
     }
 
     /**
      * Mark the function as context dependent.
      *
      * @return this builder
      * @see IFunction.FunctionProperty#CONTEXT_DEPENDENT
      */
     @NonNull
     public Builder contextDependent() {
       properties.add(FunctionProperty.CONTEXT_DEPENDENT);
       return this;
     }
 
     /**
      * Mark the function as context independent.
      *
      * @return this builder
      * @see IFunction.FunctionProperty#CONTEXT_DEPENDENT
      */
     @NonNull
     public Builder contextIndependent() {
       properties.remove(FunctionProperty.CONTEXT_DEPENDENT);
       return this;
     }
 
     /**
      * Mark the function as focus dependent.
      *
      * @return this builder
      * @see IFunction.FunctionProperty#FOCUS_DEPENDENT
      */
     @NonNull
     public Builder focusDependent() {
       properties.add(FunctionProperty.FOCUS_DEPENDENT);
       return this;
     }
 
     /**
      * Mark the function as focus independent.
      *
      * @return this builder
      * @see IFunction.FunctionProperty#FOCUS_DEPENDENT
      */
     @NonNull
     public Builder focusIndependent() {
       properties.remove(FunctionProperty.FOCUS_DEPENDENT);
       return this;
     }
 
     /**
      * Indicate if the last argument can be repeated.
      *
      * @param allow
      *          if {@code true} then the the last argument can be repeated an
      *          unlimited number of times, or {@code false} otherwise
      * @return this builder
      */
     @NonNull
     public Builder allowUnboundedArity(boolean allow) {
       if (allow) {
         properties.add(FunctionProperty.UNBOUNDED_ARITY);
       } else {
         properties.remove(FunctionProperty.UNBOUNDED_ARITY);
       }
       return this;
     }
 
     /**
      * Define the return sequence Java type of the function.
      *
      * @param type
      *          the function's return Java type
      * @return this builder
      */
     @NonNull
     public Builder returnType(@NonNull Class<? extends IItem> type) {
       Objects.requireNonNull(type, "type");
       this.returnType = type;
       return this;
     }
 
     /**
      * Indicate the sequence returned will contain zero or one items.
      *
      * @return this builder
      */
     @NonNull
     public Builder returnZeroOrOne() {
       return returnOccurrence(Occurrence.ZERO_OR_ONE);
     }
 
     /**
      * Indicate the sequence returned will contain one item.
      *
      * @return this builder
      */
     @NonNull
     public Builder returnOne() {
       return returnOccurrence(Occurrence.ONE);
     }
 
     /**
      * Indicate the sequence returned will contain zero or more items.
      *
      * @return this builder
      */
     @NonNull
     public Builder returnZeroOrMore() {
       return returnOccurrence(Occurrence.ZERO_OR_MORE);
     }
 
     /**
      * Indicate the sequence returned will contain one or more items.
      *
      * @return this builder
      */
     @NonNull
     public Builder returnOneOrMore() {
       return returnOccurrence(Occurrence.ONE_OR_MORE);
     }
 
     @NonNull
     private Builder returnOccurrence(@NonNull Occurrence occurrence) {
       Objects.requireNonNull(occurrence, "occurrence");
       this.returnOccurrence = occurrence;
       return this;
     }
 
     /**
      * Add an argument based on the provided {@code builder}.
      *
      * @param builder
      *          the argument builder
      * @return this builder
      */
     @NonNull
     public Builder argument(@NonNull IArgument.Builder builder) {
       return argument(builder.build());
     }
 
     /**
      * Add an argument based on the provided {@code argument} signature.
      *
      * @param argument
      *          the argument
      * @return this builder
      */
     @NonNull
     public Builder argument(@NonNull IArgument argument) {
       Objects.requireNonNull(argument, "argument");
       this.arguments.add(argument);
       return this;
     }
 
     /**
      * Specify the static function to call when executing the function.
      *
      * @param handler
      *          a method implementing the {@link IFunctionExecutor} functional
      *          interface
      * @return this builder
      */
     @NonNull
     public Builder functionHandler(@NonNull IFunctionExecutor handler) {
       Objects.requireNonNull(handler, "handler");
       this.functionHandler = handler;
       return this;
     }
 
     /**
      * Builds the function's signature.
      *
      * @return the function's signature
      */
     @NonNull
     public IFunction build() {
       if (properties.contains(FunctionProperty.UNBOUNDED_ARITY) && arguments.isEmpty()) {
         throw new IllegalStateException("to allow unbounded arity, at least one argument must be provided");
       }
 
       return new DefaultFunction(
           ObjectUtils.requireNonNull(name, "the name must not be null"),
           ObjectUtils.requireNonNull(namespace, "the namespace must not be null"),
           properties,
           new ArrayList<>(arguments),
           ISequenceType.of(returnType, returnOccurrence),
           ObjectUtils.requireNonNull(functionHandler, "the function handler must not be null"));
     }
   }
 }