/*
    * Copyright 2012-2013 smartics, Kronseder & Reiner GmbH
    *
    * Licensed 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 de.smartics.properties.utils;
  
  import java.util.Arrays;
  import java.util.HashSet;
  import java.util.Set;
  import java.util.regex.Matcher;
  import java.util.regex.Pattern;
  
  import org.apache.commons.lang.StringUtils;
  
  /**
   * Utilities to normalize Javadoc comments.
   */
  public final class JavadocCommentHelper
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    /**
     * The pattern matches inline Javadoc tags. In group 1 is the text that is to
     * be used and surrounded with {@link #prefix1} and {@link #suffix1}, if there
     * is no match for group 2. If group 2 is present, the text is to be used
     * without prefix/suffix 2.
     */
    private static final Pattern INLINE_PATTERN = Pattern.compile(
        "\\{@[\\w]+\\s*([#\\.\\w]+(\\([^)]*\\))?)\\s*([^}]+)?\\}",
        Pattern.MULTILINE);
  
    /**
     * The elements that are of type block.
     */
    private static final Set<String> BLOCK_ELEMENTS = new HashSet<String>(
        Arrays.asList(new String[] { "address", "blockquote", "center", "del",
                                    "dir", "div", "dl", "fieldset", "form", "h1",
                                    "h2", "h3", "h4", "h5", "h5", "hr", "ins",
                                    "isindex", "menu", "noframes", "noscript",
                                    "ol", "p", "pre", "table", "ul" }));
  
    // --- members --------------------------------------------------------------
  
    /**
     * The prefix for group 1 match.
     */
    private final String prefix1;
  
    /**
     * The suffix for group 1 match.
     */
    private final String suffix1;
  
    /**
     * The prefix for group 2 match.
     */
    private final String prefix2;
  
    /**
     * The suffix for group 2 match.
     */
    private final String suffix2;
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Default constructor.
     *
     * @param prefix1 the prefix for group 1 match.
     * @param suffix1 the suffix for group 1 match.
     * @param prefix2 the prefix for group 2 match.
     * @param suffix2 the suffix for group 2 match.
     */
    public JavadocCommentHelper(final String prefix1, final String suffix1,
        final String prefix2, final String suffix2)
    {
      this.prefix1 = prefix1;
      this.suffix1 = suffix1;
      this.prefix2 = prefix2;
      this.suffix2 = suffix2;
    }
  
    // ****************************** Inner Classes *****************************
  
   // ********************************* Methods ********************************
 
   // --- init -----------------------------------------------------------------
 
   // --- create ---------------------------------------------------------------
 
   /**
    * Creates a default helper for normalizing in an HTML context.
    *
    * @return the HTML version of the helper.
    */
   public static JavadocCommentHelper createHtml()
   {
     return new JavadocCommentHelper("<tt>", "</tt>", "<i>", "</i>");
   }
 
   /**
    * Creates a default helper for normalizing in text context.
    *
    * @return the text version of the helper.
    */
   public static JavadocCommentHelper createText()
   {
     return new JavadocCommentHelper("'", "'", "", "");
   }
 
   // --- get&set --------------------------------------------------------------
 
   // --- business -------------------------------------------------------------
 
   /**
    * Usually the first paragraph in a Javadoc comment is not tagged as a
    * paragraph to reduce the markup. This helper probes if the block tag is
    * present and if not adds it.
    *
    * @param fragment the javadoc fragment to check.
    * @return the cleaned fragment.
    */
   public String expandFirstBlock(final String fragment)
   {
     if (StringUtils.isBlank(fragment))
     {
       return fragment;
     }
 
     final String norm = fragment.trim();
     if (isStartingWithTag(norm))
     {
       final String elementName = calcElementName(norm);
       if (isBlockElement(elementName))
       {
         final int index = norm.indexOf("</" + elementName);
         return createBlock(norm, index);
       }
     }
     else
     {
       final int index = calcIndexOfFirstBlockElement(norm);
       return createBlock(norm, index);
     }
 
     return fragment;
   }
 
   private static int calcIndexOfFirstBlockElement(final String fragment)
   {
     int index = Integer.MAX_VALUE;
     for (final String elementName : BLOCK_ELEMENTS)
     {
       final int currentIndex = fragment.indexOf('<' + elementName);
       if (currentIndex != -1)
       {
         index = Math.min(currentIndex, index);
       }
     }
 
     return index != Integer.MAX_VALUE ? index : -1;
   }
 
   private static String createBlock(final String fragment, final int index)
   {
     if (index != -1)
     {
       final String firstBlock = fragment.substring(0, index);
       final String rest = fragment.substring(index);
       return "<p>" + firstBlock + "</p>\n" + rest;
     }
     else
     {
       return "<p>" + fragment + "</p>";
     }
   }
 
   private static boolean isStartingWithTag(final String fragment)
   {
     return fragment.startsWith("<");
   }
 
   private static String calcElementName(final String fragment)
   {
     final StringBuilder buffer = new StringBuilder();
     final int end = fragment.length();
     int i = 1;
     while (i < end)
     {
       final char ch = fragment.charAt(i++);
       if (Character.isLetterOrDigit(ch))
       {
         buffer.append(ch);
       }
     }
 
     final String name = buffer.toString();
     return name;
   }
 
   private static boolean isBlockElement(final String elementName)
   {
     return BLOCK_ELEMENTS.contains(elementName);
   }
 
   /**
    * Replaces Javadoc inline tags.
    *
    * @param fragment the fragment with inline tags.
    * @return the normalized fragment.
    */
   public String replaceJavadocInlines(final String fragment)
   {
     if (StringUtils.isBlank(fragment))
     {
       return fragment;
     }
 
     final StringBuffer buffer = new StringBuffer(fragment.length());
     final Matcher matcher = INLINE_PATTERN.matcher(fragment);
 
     while (matcher.find())
     {
       final String group2 = matcher.group(3);
       if (group2 != null)
       {
         final String replacement = prefix2 + group2 + suffix2;
         matcher.appendReplacement(buffer, replacement);
       }
       else
       {
         String group1 = matcher.group(1);
         if (group1.length() > 1 && group1.charAt(0) == '#')
         {
           group1 = group1.substring(1);
         }
         final String replacement = prefix1 + group1 + suffix1;
         matcher.appendReplacement(buffer, replacement);
       }
     }
     matcher.appendTail(buffer);
 
     return buffer.toString();
   }
 
   // --- object basics --------------------------------------------------------
 
 }