package DTDDoc;
   
   import java.util.HashMap;
   import java.util.Map;
   
   import com.wutka.dtd.DTDComment;
   
   /** <p>This class contains several tools used for parsing javadoc-like
    *  comments  (tags) appearing in XML comments.</p>
   *
   *  <p>Such a comment
   *  is made of text and "tags". A tag is a \@ immediately followed by
   *  a word and preceeded by at least a space.
   *  This function will return a map that associate
   *  tags to their text. The text associated to a tag is the one
   *  that follows it and that precedes the next tag or the end
   *  of the comment. The text that appears before the first
   *  tag will automatically associated to the "comment" tag.</p>
   *  <p>Right now, only "attr" tag can appear multiple times :
   *  other tags can appear once and only once!</p>
   *  <p>It is guaranteed that there are no spaces at the beginning or
   *  at the end of the tag's value.</p>
   *
   *  @see #getUniqueTagValue(String)
   *	@see #getMultipleTagValue(String)
   *  @author Stefan Champailler */
  
  public class CommentParser {
  
      private final Logger log;
  
      /** The character preceding each of the tag recognized in our comment
       *  system. */
  
      private static final char BEGIN_TAG = DTDCommenter.BEGIN_TAG;
  
      /** The tag starting a comment. This one is put in front on the
       *  XML comments by default. */
  
      private static final String COMMENT_TAG = DTDCommenter.COMMENT_TAG;
  
      /** A mapping between each "@" tag and its value.
       * @see #putTagValue(String, String)
       */
      private final Map values = new HashMap();
  
      /** This function parses a javaDoc-like comment:the resulting
       *  mapping between each tag and its value is added in {@link #values} Map attribute.
       *
       *  @param comment the comment
       *  @param getAroundNetBeanComments If true, we replace &lt;!--- with
       *  &lt;!-- (and thus interpreting NetBeans comments as they should, as
       *    explained <a
       *    href="http://sourceforge.net/mailarchive/forum.php?thread_id=23713463&forum_id=33177">here</a>.)
       */
  
      private void parseComment( String comment, boolean
          getAroundNetBeanComments) {
  
          int start = 0;
          // it was reported that Netbeans generates DTD documentation as
          // "<!--- ..." instead of "<!-- ..."
          // see http://sourceforge.net/mailarchive/forum.php?thread_id=23713463&forum_id=33177
          // => simple workaround to remove this extra leading '-', since no real
          // user documentation starts in such a way
          if( getAroundNetBeanComments && comment.startsWith("-")) {
              comment = comment.substring(1);
          }
  
          // We prefix the comment with the comment tag so that we can generalize
          // our code better later on.
  
          comment = COMMENT_TAG+" "+comment;
  
      //log.debug("comment = "+comment);
  
          while( start < comment.length()) {
  
              int tagNameStart = comment.indexOf( BEGIN_TAG, start);
  
              // To work with "substring", the index of the last char
              // of the tagname is one char further than truth.
              int tagNameEnd = comment.indexOf( ' ', tagNameStart);
  
              if( tagNameStart >= start && tagNameEnd > tagNameStart) {
                  // We do have a tag, and its name is ...
  
                  String tagName = comment.substring( tagNameStart, tagNameEnd);
  
                  // The value of a tag goes from the end of that tag
                  // to the beginning of the next tag.
  
                  int tagValueStart = tagNameEnd + 1;
                  int tagValueEnd = comment.indexOf( BEGIN_TAG, tagValueStart);
  
                  // If a tag is not followed by another tag, then the value goes
                  // from the end of the tag to the end of the comment.
  
                  if( tagValueEnd == -1)
                     tagValueEnd = comment.length();
 
                 // Now we check if there's a value for the tag. There must be
                 // one and it must not be spaces.
 
                 if( tagValueEnd > tagValueStart &&
                     comment.substring( tagValueStart, tagValueEnd)
                            .trim().length() > 0) {
                     // There's a value and it's no spaces.
                     String tagValue = comment.substring( tagValueStart, tagValueEnd).trim();
                     putTagValue( tagName, tagValue);
                 } else if (! COMMENT_TAG.equals(tagName)) {
                     // only the "main" tag can be empty (for attributes,
                     // for example)
                     log.warn("The tag "+tagName+" can not be empty.");
                 }
 
                 start = tagNameEnd + 1;
 
             } else
                 start = comment.length();
         }
     }
 
     public String getUniqueTagValue( String tagName) {
 
         Object v = values.get( tagName);
 
         if( v == null)
             return null;
         else if( v instanceof String)
             return (String) v;
         else if( v instanceof Map) {
             log.warn("Expected a unique value for tag " + BEGIN_TAG + tagName);
             return null;
         } else {
             log.error("Internal error, unexpected type for" +
                 " tag " + BEGIN_TAG + tagName + "'s value.");
             return null;
         }
     }
 
     public Map getMultipleTagValue( String tagName) {
         Object v = values.get( tagName);
 
         if( v == null)
             return null;
         else if( v instanceof Map)
             return (Map) v;
         else if( v instanceof String) {
             log.warn("Expected a multiple value for tag " + BEGIN_TAG + tagName);
             return null;
         } else {
             log.error("Unexpected type for" +
                 " tag " + BEGIN_TAG + tagName + "'s value.");
             return null;
         }
     }
 
     private void putTagValue( String name, String content) {
 
         if( name == null)
             throw new IllegalArgumentException("putTagValue(): null tag name !");
 
         if( "@attr".equalsIgnoreCase( name)) {
             // @attr is the only tag supporting multiple occurences: one time per attribute documented
             if( content == null)
                 throw new IllegalArgumentException("putTagValue(): content null for "+name+" !");
 
             String key = null;
             String value = null;
             int firstSpaceIndex = content.indexOf(' ');
 
             if( firstSpaceIndex != -1 && firstSpaceIndex+1 < content.length()) {
                 key = content.substring( 0, firstSpaceIndex);
                 value = content.substring( firstSpaceIndex+1, content.length());
             } else {
                 log.warn("The tag " + name + " requires a key and a value !");
                 return;
             }
 
             Map current = (Map) values.get( name);
             if( current == null) {
                 current = new HashMap();
                 values.put( name, current);
             }
             current.put( key, value);
         } else {
             //log.debug("putTagValue(): name="+name+" value="+content);
             values.put( name, content);
         }
     }
 
     public CommentParser( DTDComment comment, Logger log, boolean
         getAroundNetBeanComments) {
         this.log = log;
         parseComment( comment.getText(), getAroundNetBeanComments);
     }
 }