Quellcode

001/*
002 * Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package org.jdrupes.mdoclet.internal.doclets.toolkit.util;
027
028import javax.lang.model.element.ModuleElement;
029import javax.lang.model.element.PackageElement;
030import javax.lang.model.element.TypeElement;
031
032/**
033 * Standard DocPath objects.
034 */
035public class DocPaths {
036    private final String moduleSeparator;
037    private final Utils utils;
038
039    public DocPaths(Utils utils) {
040        this.utils = utils;
041        moduleSeparator = "/module-";
042    }
043
044    public static final DocPath DOT_DOT = DocPath.create("..");
045
046    /** The name of the file for all classes index. */
047    public static final DocPath ALLCLASSES_INDEX
048        = DocPath.create("allclasses-index.html");
049
050    /** The name of the file for all packages index. */
051    public static final DocPath ALLPACKAGES_INDEX
052        = DocPath.create("allpackages-index.html");
053
054    /** The name of the sub-directory for storing class usage info. */
055    public static final DocPath CLASS_USE = DocPath.create("class-use");
056
057    /** The name of the file for constant values. */
058    public static final DocPath CONSTANT_VALUES
059        = DocPath.create("constant-values.html");
060
061    /** The name of the file for deprecated elements. */
062    public static final DocPath DEPRECATED_LIST
063        = DocPath.create("deprecated-list.html");
064
065    /** The name of the subdirectory for user-provided additional documentation files. */
066    public static final DocPath DOC_FILES = DocPath.create("doc-files");
067
068    /** The name of the file for the element list. */
069    public static final DocPath ELEMENT_LIST = DocPath.create("element-list");
070
071    /** The name of the file for all references to external specifications. */
072    public static final DocPath EXTERNAL_SPECS
073        = DocPath.create("external-specs.html");
074
075    /** The name of the image file showing a magnifying glass on the search box. */
076    public static final DocPath GLASS_IMG = DocPath.create("glass.png");
077
078    /** The name of the file for help info. */
079    public static final DocPath HELP_DOC = DocPath.create("help-doc.html");
080
081    /** The name of the main index file. */
082    public static final DocPath INDEX = DocPath.create("index.html");
083
084    /** The name of the single index file for all classes. */
085    public static final DocPath INDEX_ALL = DocPath.create("index-all.html");
086
087    /** The name of the directory for the split index files. */
088    public static final DocPath INDEX_FILES = DocPath.create("index-files");
089
090    /**
091     * Generate the name of one of the files in the split index.
092     * @param n the position in the index
093     * @return the path
094     */
095    public static DocPath indexN(int n) {
096        return DocPath.create("index-" + n + ".html");
097    }
098
099    /** The name of the default javascript file. */
100    public static final DocPath JAVASCRIPT = DocPath.create("script.js");
101
102    /** The name of the copy-to-clipboard icon file. */
103    public static final DocPath CLIPBOARD_SVG = DocPath.create("copy.svg");
104
105    /** The name of the link icon file. */
106    public static final DocPath LINK_SVG = DocPath.create("link.svg");
107
108    /** The name of the default jQuery javascript file. */
109    public static final DocPath JQUERY_JS
110        = DocPath.create("jquery-3.6.1.min.js");
111
112    /** The name of the default jQuery UI stylesheet file. */
113    public static final DocPath JQUERY_UI_CSS
114        = DocPath.create("jquery-ui.min.css");
115
116    /** The name of the default jQuery UI javascript file. */
117    public static final DocPath JQUERY_UI_JS
118        = DocPath.create("jquery-ui.min.js");
119
120    /** The name of the directory for legal files. */
121    public static final DocPath LEGAL = DocPath.create("legal");
122
123    /** The name of the member search index js file. */
124    public static final DocPath MEMBER_SEARCH_INDEX_JS
125        = DocPath.create("member-search-index.js");
126
127    /** The name of the module search index js file. */
128    public static final DocPath MODULE_SEARCH_INDEX_JS
129        = DocPath.create("module-search-index.js");
130
131    /** The name of the file for new elements. */
132    public static final DocPath NEW_LIST = DocPath.create("new-list.html");
133
134    /** The name of the file for the overview summary. */
135    public static final DocPath OVERVIEW_SUMMARY
136        = DocPath.create("overview-summary.html");
137
138    /** The name of the file for the overview tree. */
139    public static final DocPath OVERVIEW_TREE
140        = DocPath.create("overview-tree.html");
141
142    /** The name of the file for the package list. This is to support the legacy mode. */
143    public static final DocPath PACKAGE_LIST = DocPath.create("package-list");
144
145    /** The name of the package search index js file. */
146    public static final DocPath PACKAGE_SEARCH_INDEX_JS
147        = DocPath.create("package-search-index.js");
148
149    /** The name of the file for the package summary. */
150    public static final DocPath PACKAGE_SUMMARY
151        = DocPath.create("package-summary.html");
152
153    /** The name of the file for the package tree. */
154    public static final DocPath PACKAGE_TREE
155        = DocPath.create("package-tree.html");
156
157    /** The name of the file for the package usage info. */
158    public static final DocPath PACKAGE_USE
159        = DocPath.create("package-use.html");
160
161    /** The name of the file for preview elements. */
162    public static final DocPath PREVIEW_LIST
163        = DocPath.create("preview-list.html");
164
165    /** The name of the directory for the script files. */
166    public static final DocPath SCRIPT_DIR = DocPath.create("script-dir");
167
168    /** The name of the file for search page. */
169    public static final DocPath SEARCH_PAGE = DocPath.create("search.html");
170
171    /** The name of the file for all system properties. */
172    public static final DocPath SYSTEM_PROPERTIES
173        = DocPath.create("system-properties.html");
174
175    /**
176     * Returns the path for a type element.
177     * For example, if the type element is {@code java.lang.Object},
178     * the path is {@code java/lang/Object.html}.
179     *
180     * @param typeElement the type element
181     * @return the path
182     */
183    public DocPath forClass(TypeElement typeElement) {
184        return (typeElement == null)
185            ? DocPath.empty
186            : forPackage(utils.containingPackage(typeElement))
187                .resolve(forName(typeElement));
188    }
189
190    /**
191     * Returns the path for the simple name of a type element.
192     * For example, if the type element is {@code java.lang.Object},
193     * the path is {@code Object.html}.
194     *
195     * @param typeElement the type element
196     * @return the path
197     */
198    public DocPath forName(TypeElement typeElement) {
199        return (typeElement == null)
200            ? DocPath.empty
201            : new DocPath(utils.getSimpleName(typeElement) + ".html");
202    }
203
204    public static DocPath forModule(ModuleElement mdle) {
205        return mdle == null || mdle.isUnnamed()
206            ? DocPath.empty
207            : DocPath.create(mdle.getQualifiedName().toString());
208    }
209
210    /**
211     * Returns the path for the package of a type element.
212     * For example, if the type element is {@code java.lang.Object},
213     * the path is {@code java/lang}.
214     *
215     * @param typeElement the type element
216     * @return the path
217     */
218    public DocPath forPackage(TypeElement typeElement) {
219        return (typeElement == null)
220            ? DocPath.empty
221            : forPackage(utils.containingPackage(typeElement));
222    }
223
224    /**
225     * Returns the path for a package.
226     * For example, if the package is {@code java.lang},
227     * the path is {@code java/lang}.
228     *
229     * @param pkgElement the package element
230     * @return the path
231     */
232    public DocPath forPackage(PackageElement pkgElement) {
233        if (pkgElement == null || pkgElement.isUnnamed()) {
234            return DocPath.empty;
235        }
236
237        DocPath pkgPath = DocPath
238            .create(pkgElement.getQualifiedName().toString().replace('.', '/'));
239        ModuleElement mdle = (ModuleElement) pkgElement.getEnclosingElement();
240        return forModule(mdle).resolve(pkgPath);
241    }
242
243    /**
244     * Returns the inverse path for a package.
245     * For example, if the package is {@code java.lang},
246     * the inverse path is {@code ../..}.
247     *
248     * @param pkgElement the package element
249     * @return the path
250     */
251    public static DocPath forRoot(PackageElement pkgElement) {
252        String name = (pkgElement == null || pkgElement.isUnnamed())
253            ? ""
254            : pkgElement.getQualifiedName().toString();
255        return new DocPath(name.replace('.', '/').replaceAll("[^/]+", ".."));
256    }
257
258    /**
259     * Returns a relative path from one package to another.
260     *
261     * @param from the origin of the relative path
262     * @param to the destination of the relative path
263     * @return the path
264     */
265    public DocPath relativePath(PackageElement from, PackageElement to) {
266        return forRoot(from).resolve(forPackage(to));
267    }
268
269    /**
270     * Returns the path for a file within a module documentation output directory.
271     * @param mdle the module
272     * @param path the path to append to the module path
273     * @return the module documentation path
274     */
275    public DocPath modulePath(ModuleElement mdle, String path) {
276        return DocPath.create(mdle.getQualifiedName().toString()).resolve(path);
277    }
278
279    /**
280     * The path for the file for a module's summary page.
281     * @param mdle the module
282     * @return the path
283     */
284    public DocPath moduleSummary(ModuleElement mdle) {
285        return createModulePath(mdle, "summary.html");
286    }
287
288    /**
289     * The path for the file for a module's summary page.
290     * @param mdleName the module
291     * @return the path
292     */
293    public DocPath moduleSummary(String mdleName) {
294        return createModulePath(mdleName, "summary.html");
295    }
296
297    private DocPath createModulePath(ModuleElement mdle, String path) {
298        return DocPath.create(mdle.getQualifiedName() + moduleSeparator + path);
299    }
300
301    private DocPath createModulePath(String moduleName, String path) {
302        return DocPath.create(moduleName + moduleSeparator + path);
303    }
304
305    /** The name of the sub-package from which resources are read. */
306    public static final DocPath RESOURCES = DocPath.create("resources");
307
308    /** The name of the search javascript file. */
309    public static final DocPath SEARCH_JS = DocPath.create("search.js");
310
311    /** The name of the template for the search javascript file. */
312    public static final DocPath SEARCH_JS_TEMPLATE
313        = DocPath.create("search.js.template");
314
315    /** The name of the search javascript file. */
316    public static final DocPath SEARCH_PAGE_JS
317        = DocPath.create("search-page.js");
318
319    /** The name of the file for the serialized form info. */
320    public static final DocPath SERIALIZED_FORM
321        = DocPath.create("serialized-form.html");
322
323    /** The name of the directory in which HTML versions of the source code
324     *  are generated.
325     */
326    public static final DocPath SOURCE_OUTPUT = DocPath.create("src-html");
327
328    /** The name of the default stylesheet. */
329    public static final DocPath STYLESHEET = DocPath.create("stylesheet.css");
330
331    /** The name of the tag search index js file. */
332    public static final DocPath TAG_SEARCH_INDEX_JS
333        = DocPath.create("tag-search-index.js");
334
335    /** The name of the type search index js file. */
336    public static final DocPath TYPE_SEARCH_INDEX_JS
337        = DocPath.create("type-search-index.js");
338
339    /** The name of the image file for undo button on the search box. */
340    public static final DocPath X_IMG = DocPath.create("x.png");
341
342}