/*
    * 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
    *
   *   http://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.rat.documentation.velocity;
  
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Comparator;
  import java.util.List;
  import java.util.Map;
  import java.util.Set;
  import java.util.TreeSet;
  import java.util.stream.Collectors;
  
  import org.apache.commons.cli.Option;
  import org.apache.commons.collections4.set.UnmodifiableSortedSet;
  import org.apache.commons.lang3.StringUtils;
  import org.apache.rat.CLIOption;
  import org.apache.rat.CLIOptionCollection;
  import org.apache.rat.Defaults;
  import org.apache.rat.OptionCollection;
  import org.apache.rat.api.EnvVar;
  import org.apache.rat.commandline.StyleSheets;
  import org.apache.rat.config.exclusion.StandardCollection;
  import org.apache.rat.config.parameters.ComponentType;
  import org.apache.rat.config.parameters.Description;
  import org.apache.rat.config.parameters.DescriptionBuilder;
  import org.apache.rat.configuration.MatcherBuilderTracker;
  import org.apache.rat.documentation.options.AntOption;
  import org.apache.rat.documentation.options.AntOptionCollection;
  import org.apache.rat.documentation.options.MavenOption;
  import org.apache.rat.documentation.options.MavenOptionCollection;
  import org.apache.rat.help.AbstractHelp;
  import org.apache.rat.license.ILicense;
  import org.apache.rat.license.LicenseSetFactory;
  import org.apache.rat.ui.UIOption;
  import org.apache.velocity.tools.config.DefaultKey;
  import org.apache.velocity.tools.config.ValidScope;
  
  /**
   * The Velocity RAT plugin that provides access to the RAT data.
   * <p>
   * DEVHINT: Be careful when removing methods as this may invalidate contents and functionality of the velocity templates.
   * </p>
   */
  @SuppressWarnings("unused")
  @DefaultKey("rat")
  @ValidScope({"application"})
  public class RatTool {
  
      // TODO remove this when velocity-tools 3.3 is available // NOSONAR
      private static String[] charParser(final String charText) {
          char[] chars = charText.toCharArray();
          String[] result = new String[chars.length];
          for (int i = 0; i < chars.length; i++) {
              result[i] = String.valueOf(chars[i]);
          }
          return result;
      }
  
      /**
       * The characters to escape for Markdown.
       */
      // TODO remove this when velocity-tools 3.3 is available // NOSONAR
      private static final String[] MARKDOWN_CHARS = charParser("\\`*_{}[]<>()#+-.!|");
      /**
       * The characters to escape for APT (Almost Plain Text).
       */
      // TODO remove this when velocity-tools 3.3 is available // NOSONAR
      private static final String[] APT_CHARS = charParser("\\~=-+*[]<>{}");
  
      /**
       * The license factory this tool uses.
       */
      private final LicenseSetFactory licenseSetFactory;
  
      /**
       * The client option instance.
       */
      // visible for testing
      private final CLIOptionCollection cliOptions = new CLIOptionCollection();
  
      /**
       * The Ant option instance.
      */
     private final AntOptionCollection antOptions = new AntOptionCollection();
 
     /**
      * The Maven option instance.
      */
     private final MavenOptionCollection mavenOptions = new MavenOptionCollection();
 
     /**
      * Constructor.
      */
     public RatTool() {
         Defaults defaults = Defaults.builder().build();
         licenseSetFactory = defaults.getLicenseSetFactory();
     }
 
     /**
      * Gets the list of command line options.
      * @return the list of command line options.
      */
     public List<Option> options() {
         return cliOptions.getMappedOptions()
         .map(UIOption::getOption).toList();
     }
 
     /**
      * Gets a map client option name to Ant Option.
      * @return a map client option name to Ant Option.
      */
     public Map<String, AntOption> antOptions() {
         return antOptions.getOptionMap();
     }
 
     /**
      * Gets a map client option name to CLI Option.
      * @return a map client option name to CLI Option.
      */
     public Map<String, CLIOption> cliOptions() {
         return cliOptions.getOptionMap();
     }
 
     /**
      * Gets a map client option name to Maven Option.
      * @return a map client option name to Maven Option.
      */
     public Map<String, MavenOption> mvnOptions() {
         return mavenOptions.getOptionMap();
     }
 
     /**
      * Escapes a text string.
      * @param text the text to escape.
      * @param chars the characters to escape.
      * @return the escaped string.
      */
     private String escape(final String text, final String[] chars) {
         if (text == null) {
             return "";
         }
         String result = text;
         for (String c : chars) {
             result = result.replace(c, "\\" + c);
         }
         return result;
     }
 
     /**
      * Escapes a string for Markdown.
      * @param text the text to escape.
      * @return the text with the Markdown specific characters escaped.
      */
     public String markdownEscape(final String text) {
         return escape(text, MARKDOWN_CHARS);
     }
 
     /**
      * Escapes a string for APT (almost plain text).
      * @param text the text to escape.
      * @return the text with the APT specific characters escaped.
      */
     public String aptEscape(final String text) {
         return escape(text, APT_CHARS);
     }
 
     /**
      * Gets the list of argument types.
      * @return a list of argument types.
      */
     public List<OptionCollection.ArgumentType> argumentTypes() {
         return Arrays.stream(OptionCollection.ArgumentType.values()).filter(t -> t != OptionCollection.ArgumentType.NONE)
                 .sorted(Comparator.comparing(OptionCollection.ArgumentType::getDisplayName))
                 .collect(Collectors.toList());
     }
 
     /**
      * Gets the list of environment variables.
      * @return a list of environment variables.
      */
     public List<EnvVar> environmentVariables() {
         return Arrays.stream(EnvVar.values())
                 .sorted(Comparator.comparing(EnvVar::name))
                 .collect(Collectors.toList());
     }
 
     /**
      * Gets the set of matchers.
      * @return the set of matchers.
      */
     public Set<Matcher> matchers() {
         Set<Matcher> documentationSet = new TreeSet<>(Comparator.comparing(Matcher::getName));
         for (Class<?> clazz : MatcherBuilderTracker.instance().getClasses()) {
             Description desc = DescriptionBuilder.buildMap(clazz);
             documentationSet.add(new Matcher(desc, null));
         }
         return documentationSet;
     }
 
     /**
      * Gets the list of standard collections.
      * @return the list of standard collections.
      */
     public List<StandardCollection> standardCollections() {
         return Arrays.stream(org.apache.rat.config.exclusion.StandardCollection.values())
                 .sorted(Comparator.comparing(Enum::name))
                 .collect(Collectors.toList());
     }
 
     /**
      * Gets the list of stylesheets.
      * @return the list of stylesheets.
      */
     public List<StyleSheets> styleSheets() {
         return Arrays.stream(StyleSheets.values())
                 .sorted(Comparator.comparing(StyleSheets::arg))
                 .collect(Collectors.toList());
     }
 
     /**
      * Gets the {@link StringUtils} object in order to work with it in RAT Velocity templates.
      * @return the org.apache.commons.lang3 StringUtils object.
      * @see org.apache.commons.lang3.StringUtils
      */
     public StringUtils stringUtils() {
         return new StringUtils();
     }
 
     /**
      * Gets a tab character.
      * @return the tab character.
      */
     public String tab() {
         return "\t";
     }
 
     /**
      * Gets two new lines.
      * @return a string containing two new lines.
      */
     public String doubleLine() {
         return "\n\n";
     }
 
     /**
      * Gets a list of license property descriptions.
      * @return a list of license property descriptions.
      */
     public List<Description> licenseProperties() {
         UnmodifiableSortedSet<ILicense> licenses = licenseSetFactory.getLicenses(LicenseSetFactory.LicenseFilter.ALL);
         Description licenseDescription = DescriptionBuilder.build(licenses.first());
         List<Description> descriptions = new ArrayList<>(licenseDescription.filterChildren(d -> d.getType() == ComponentType.PARAMETER));
         descriptions.sort(Comparator.comparing(Description::getCommonName));
         return descriptions;
     }
 
     /**
      * Gets the list of defined licenses.
      * @return the list of defined licenses.
      */
     public List<License> licenses() {
         UnmodifiableSortedSet<ILicense> licenses = licenseSetFactory.getLicenses(LicenseSetFactory.LicenseFilter.ALL);
         return licenses.stream().map(License::new).collect(Collectors.toList());
     }
 
     /**
      * Creates a string of spaces of the specified length.
      * @param length the length of the string.
      * @return a string of spaces of the specified length.
      */
     public String pad(final int length) {
         return AbstractHelp.createPadding(length);
     }
 }