001package Torello.HTML.Tools.JavaDoc;
002
003import Torello.HTML.*;
004import Torello.HTML.NodeSearch.*;
005
006import java.util.*;
007
008/**
009 * <CODE>TopDescription - Documentation.</CODE><BR /><BR />
010 * <EMBED CLASS="external-html" DATA-FILE-ID="TD">.
011 */
012@StaticFunctional
013public class TopDescription
014{
015    private TopDescription() { }
016
017    /**
018     * <EMBED CLASS="external-html" DATA-FILE-ID="TDDAT">
019     * 
020     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
021     * 
022     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
023     * ending-position in a vectorized-html web-page, in this case an HTML page generated by Java's
024     * 'javadoc' executable utility for generating code-documentation, ... <I><B>to the
025     * class-description section at the top of the page.</B></I>
026     * 
027     * <BR /><BR /><B>NOTE:</B> If any insertion of HTML is going to happen, it is usually better
028     * to insert such elements inside of an {@code <LI>...</LI>} pair <I><B>inside the HTML
029     * Un-Ordered List</B></I> - which is the only element inside the HTML DIV element in a javadoc
030     * generated HTML class-description page.
031     * 
032     * @see #dividerInsideDescriptionAtTop(Vector)
033     * @see InnerTagFindInclusive
034     * @see TextComparitor
035     */
036    public static DotPair descriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
037    {
038        return InnerTagFindInclusive.first
039            (javaDocHTMLCIETPage, "div", "class", TextComparitor.C, "description");
040    }
041
042    /**
043     * It becomes difficult to explain, but the "Description Divider" (at the top of a javadoc
044     * created HTML class-file) actually just, sort-of, 'wraps' and another HTML "divider"
045     * ({@code <DIV ...> </DIV>}) element.  If, by some chance, a programmer has decided to
046     * <I>insert HTML</I> into the top of an HTML java-doc class-description file, and he / she
047     * would like to preserve / utilize the CSS-Styling that is (automatically) assigned by JavaDoc
048     * to the rest of content in that page, then inserting at the beginning or end of the HTML
049     * "Description Divider" - rather than the internal "block" divider  will produce a situation
050     * where the inserted HTML <I>is not formatted the same way, using the same fonts <B>as the
051     * rest of the text in the class-description</I></B>
052     *
053     * <BR /><BR /><B>SUMMARY:</B> If a programmer wants to 'borrow' or 'inherit' the style &amp;
054     * font assignments that are assigned by the CSS definition to the HTML text being inserted,
055     * use method:
056     * 
057     * <DIV CLASS="METHODSIGNATURE">{@code
058     * public static DotPair dividerInsideDescriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
059     * }</DIV>
060     *
061     * <BR /><B><I>Rather than the method:</I></B>
062     *
063     * <DIV CLASS="METHODSIGNATURE">{@code
064     * public static DotPair descriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
065     * }</DIV>
066     * 
067     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
068     * 
069     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
070     * ending-position in a vectorized-html web-page, in this case an HTML page generated by Java's
071     * 'javadoc' executable utility for generating code-documentation, ... <I><B>to the HTML
072     * {@code <DIV CLASS='block'>...</DIV>} class-description section at the top  of the
073     * page.</B></I>
074     * 
075     * @see #descriptionAtTop(Vector)
076     * @see InnerTagFindInclusive
077     * @see TextComparitor
078     */
079    public static DotPair dividerInsideDescriptionAtTop(Vector<HTMLNode> javaDocHTMLCIETPage)
080    {
081        DotPair dp = descriptionAtTop(javaDocHTMLCIETPage);
082
083        if (dp == null) return null;
084
085        return InnerTagFindInclusive.first
086            (javaDocHTMLCIETPage, dp.start, dp.end + 1, "div", "class", TextComparitor.C, "block");
087    }
088
089    /**
090     * This returns a DotPair (start &amp; end integer vector-index pointers) to the HTML "title"
091     * element that contains the "Class, Interface, or Enumerated-Type Name" that is at the top of
092     * all Java-Doc Generated Web-Page.  What the HTML actually looks like is included in the
093     * HTML-Snippet below:
094     * 
095     * <DIV CLASS="HTML">{@code
096     * <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: -->
097     * <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2>
098     * }</DIV>
099     * 
100     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
101     * 
102     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
103     * ending-position in a vectorized-html web-page of the "title" ({@code <h2 title="Class
104     * HTMLNode" class="title"> ... title ...</h2>}) for any class, interface or enumerated-type
105     * JavaDoc Generated Web-Page.
106     * 
107     * @see CommentNodeFind
108     * @see InnerTagFindInclusive
109     * @see TextComparitor
110     */
111    public static DotPair title(Vector<HTMLNode> javaDocHTMLCIETPage)
112    {
113        int pos = CommentNodeFind.first
114            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
115
116        if (pos == -1) return null;
117
118        return InnerTagFindInclusive.first
119            (javaDocHTMLCIETPage, "h2", "class", TextComparitor.C, "title");
120    }
121
122    /**
123     * This returns the Title of this JavaDoc HTML Documentation Page as a String.  This String
124     * will have the "Class, Interface, or Enumerated-Type Name" that is at the top of all Java-Doc
125     * Generated Web-Pages.  What the HTML actually looks like is included in the HTML-Snippet
126     * below:
127     * 
128     * <DIV CLASS="HTML">{@code
129     * <!-- In any Java-Doc Generated HTML-Description Web-Page, the "Title" HTML looks like this: -->
130     * <h2 title="Class HTMLNode" class="title">Class HTMLNode</h2>
131     * }</DIV>
132     * 
133     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
134     * 
135     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
136     * ending-position in a vectorized-html web-page of the "title" ({@code <h2 title="Class
137     * HTMLNode" class="title"> ... title ...</h2>}) for any class, interface or enumerated-type
138     * JavaDoc Generated Web-Page.
139     * 
140     * @see Util#textNodesString(Vector)
141     * @see CommentNodeFind
142     * @see InnerTagFindInclusive
143     * @see TextComparitor
144     */
145    public static String titleAsString(Vector<HTMLNode> javaDocHTMLCIETPage)
146    {
147        int pos = CommentNodeFind.first
148            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
149
150        if (pos == -1) return null;
151
152        Vector<HTMLNode> v = InnerTagGetInclusive.first
153            (javaDocHTMLCIETPage, "h2", "class", TextComparitor.C, "title");
154
155        return Escape.replace(Util.textNodesString(v));
156    }
157
158    /**
159     * This returns a DotPair (start &amp; end integer vector-index pointers) to the HTML
160     * "Unordered List" element that contains the "Class or Interface Inheritance Specification"
161     * which is at the top of all Java-Doc Generated Class or Interface Description Web-Pages.
162     * What the HTML actually looks like is included in the hilited code below:
163     * 
164     * <DIV CLASS="HTML">{@code
165     * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Inheritance List" HTML looks like: -->
166     * <!-- In this particular case, "class CommentNode" (which inherits from HTMLNode) is used -->
167     * <ul class="inheritance">
168     * <li>Torello.HTML.HTMLNode</li>
169     * </ul>
170     * }</DIV>
171     * 
172     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
173     * 
174     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
175     * ending-position in a vectorized-html web-page of the "inheritance Unordered List"
176     * ({@code <ul class="inheritance"> ... </ul>}) for any class or interface JavaDoc Generated
177     * Web-Page.  If this web-page is not a javaDoc generated web-page, or is a part of a web-page
178     * that does not contain the information, then this method will return null, gracefully. No
179     * Exceptions will be thrown.
180     * 
181     * @see CommentNodeFind
182     * @see InnerTagPeekInclusive
183     * @see TextComparitor
184     */
185    public static Vector<SubSection> inheritance(Vector<HTMLNode> javaDocHTMLCIETPage)
186    {
187        int pos = CommentNodeFind.first
188            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
189
190        if (pos == -1) return null;
191
192        return InnerTagPeekInclusive.all
193            (javaDocHTMLCIETPage, pos, -1, "ul", "class", TextComparitor.C, "inheritance");
194    }
195
196    /**
197     * This returns a DotPair (start &amp; end integer vector-index pointers) to the HTML
198     * Divider-Element ({@code "<DIV ...>"}) that contains the "Package Name" in which this class,
199     * interface, or enumerated-type is located.  The package information is located at the top of
200     * all Java-Doc Generated Class or Interface Description Web-Pages.  What the HTML actually
201     * looks like is included in the hilited code below:
202     * 
203     * <DIV CLASS="HTML">{@code
204     * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like: -->
205     * <div class="subTitle">Torello.HTML</div>
206     * }</DIV>
207     * 
208     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
209     * 
210     * @return A {@code 'DotPair'} pointer that holds pointers to the starting-position and
211     * ending-position in a vectorized-html web-page of the "Package Information"
212     * ({@code <div class="subTitle"> ... </div>}) for any class, interface, or enumerated-type
213     * JavaDoc Generated Web-Page.  If this web-page is not a javaDoc generated web-page, or is a
214     * part of a web-page that does not contain the information, then this method will return null,
215     * gracefully; and no exceptions will be thrown.
216     * 
217     * @see CommentNodeFind
218     * @see InnerTagFindInclusive
219     * @see TextComparitor
220     */
221    public static DotPair packageInfo(Vector<HTMLNode> javaDocHTMLCIETPage)
222    {
223        int pos = CommentNodeFind.first
224            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
225
226        if (pos == -1) return null;
227
228        return InnerTagFindInclusive.first
229            (javaDocHTMLCIETPage, pos, -1, "div", "class", TextComparitor.C, "subTitle");
230    }
231
232    /**
233     * Rather than returning an vectorized-html sublist - <I>which is what method
234     * {@code 'package(Vector<HTMLNode>)'} does</I> - this method finds the "Package Name" itself
235     * and returns that as a regular java-string.  This operation can be performed on a class,
236     * interface, or enumerated-type.  This package-information is located at the top of all
237     * Java-Doc Description Web-Pages.  What the HTML actually looks like is included in the
238     * hilited code below:
239     * 
240     * <DIV CLASS="HTML">{@code
241     * <!-- In Java-Doc Generated HTML-Description Web-Pages, the "Containing Package" HTML looks like:
242     * <div class="subTitle">Torello.HTML</div>
243     * }</DIV>
244     * 
245     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
246     * 
247     * @return A string that contains "Package Information" for any class, interface, or
248     * enumerated-type JavaDoc Generated Web-Page. If this web-page is not a javaDoc generated
249     * web-page, or is a part of a web-page that does not contain the information, then this method
250     * will return null, gracefully; and no exceptions will throw.
251     * 
252     * @see Util#textNodesString(Vector)
253     * @see CommentNodeFind
254     * @see InnerTagGetInclusive
255     * @see TextComparitor
256     */
257    public static String packageInfoAsString(Vector<HTMLNode> javaDocHTMLCIETPage)
258    {
259        int pos = CommentNodeFind.first
260            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
261
262        if (pos == -1) return null;
263
264        Vector<HTMLNode> v = InnerTagGetInclusive.first
265            (javaDocHTMLCIETPage, pos, -1, "class", TextComparitor.C, "subTitle");
266
267        return Escape.replace(Util.textNodesString(v));
268    }
269
270    /**
271     * Returns all of the HTML Element "{@code <DL> ... </DL>}" sublists at the top of a CIET
272     * (Class, Interface, or Enumerated-Type) java web-page.  This contains a plethora of variants,
273     * depending on  whether the particular documentation page is for a class, an interface, a
274     * function-interface, a static-inner-class, an enumerated type, etc.  Below is an example
275     * piece of HTML for the class "CommentNode."  There are many other versions for this sub-list,
276     * and it would be best to run this method-operation on different HTML Documentation Pages to
277     * see all the possible versions of {@code <DD> and <DT>} definitions that are possible in this
278     * {@code <DL> ... </DL>} sublist occurring in the "Description-at-Top" of a javadoc web-pge.
279     *
280     * <DIV CLASS="HTML">{@code
281     * <!-- In Java-Doc Generated HTML-Description Web-Pages, the top "DL" HTML Element looks like: -->
282     * <dl>
283     * <dt>All Implemented Interfaces:</dt>
284     * <dd>java.io.Serializable, java.lang.CharSequence, java.lang.Cloneable</dd>
285     * </dl>
286     * <dl>
287     * <dt>Direct Known Subclasses:</dt>
288     * <dd><a href="../../Torello/HTML/CommentNode.html" title="class in Torello.HTML">CommentNode</a>, <a href="../../Torello/HTML/TagNode.html" title="class in Torello.HTML">TagNode</a>, <a href="../../Torello/HTML/TextNode.html" title="class in Torello.HTML">TextNode</a></dd>
289     * </dl>
290     * }</DIV>
291     * 
292     * @param javaDocHTMLCIETPage <EMBED CLASS="external-html" DATA-FILE-ID="JDHCIETP">
293     * 
294     * @see CommentNodeFind
295     * @see TagNodeFindInclusive
296     * @see TextComparitor
297     */
298    public static Vector<DotPair> allTopDLs(Vector<HTMLNode> javaDocHTMLCIETPage)
299    {
300        int sPos = CommentNodeFind.first
301            (javaDocHTMLCIETPage, TextComparitor.CN, "== START OF CLASS DATA ==");
302
303        if (sPos == -1) return null;
304
305        int ePos = TagNodeFind.first(javaDocHTMLCIETPage, sPos, -1, TC.OpeningTags, "hr");
306
307        if (ePos == -1) return null;
308
309        return TagNodeFindInclusive.all(javaDocHTMLCIETPage, sPos, ePos, "dl");
310    }
311
312}