PathMacros: more javadocs
[idea/community.git] / platform / projectModel-impl / src / com / intellij / openapi / components / PathMacroSubstitutor.java
1 /*
2  * Copyright 2000-2016 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.intellij.openapi.components;
17
18 import org.jdom.Element;
19 import org.jetbrains.annotations.NotNull;
20
21 /**
22  * Provides methods to convert paths from absolute to portable form and vice versa.
23  *
24  * @see com.intellij.openapi.application.PathMacros
25  */
26 public interface PathMacroSubstitutor {
27   /**
28    * Convert path to absolute by replacing all names of path variables by its values
29    */
30   String expandPath(String path);
31
32   @NotNull
33   default String collapsePath(@NotNull String text) {
34     return collapsePath(text, false);
35   }
36
37   /**
38    * Convert paths inside {@code text} to portable form by replacing all values of path variables by their names.
39    * @param recursively if {@code true} all occurrences of paths inside {@code text} will be processed, otherwise {@code text} will be converted
40    *                    only if its entire content is a path (or URL)
41    */
42   String collapsePath(@NotNull String text, boolean recursively);
43
44   /**
45    * Process sub tags of {@code element} recursively and convert paths to absolute forms in all tag texts and attribute values.
46    */
47   void expandPaths(@NotNull Element element);
48
49   default void collapsePaths(@NotNull Element element) {
50     collapsePaths(element, false);
51   }
52
53   default void collapsePathsRecursively(@NotNull Element element) {
54     collapsePaths(element, true);
55   }
56
57   /**
58    * Process sub tags of {@code element} recursively and convert paths to portable forms in all tag texts and attribute values.
59    * @param recursively if {@code true} all occurrences of paths inside tag texts and attribute values will be processed, otherwise
60    * they will be converted only if their entire content is a path (or URL)
61    */
62   void collapsePaths(@NotNull Element element, boolean recursively);
63
64   default String collapsePathsRecursively(@NotNull String string) {
65     return collapsePath(string, true);
66   }
67 }