platform/projectModel-impl/src/com/intellij/openapi/components/PathMacroSubstitutor.java

   1 // Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
   2 package com.intellij.openapi.components;
   3
   4 import org.jdom.Element;
   5 import org.jetbrains.annotations.Contract;
   6 import org.jetbrains.annotations.NotNull;
   7 import org.jetbrains.annotations.Nullable;
   8
   9 /**
  10  * Provides methods to convert paths from absolute to portable form and vice versa.
  11  *
  12  * @see com.intellij.openapi.application.PathMacros
  13  */
  14 public interface PathMacroSubstitutor {
  15   /**
  16    * Convert path to absolute by replacing all names of path variables by its values
  17    */
  18   @Contract("null -> null; !null -> !null")
  19   String expandPath(@Nullable String text);
  20
  21   @Contract("null -> null; !null -> !null")
  22   default String collapsePath(@Nullable String text) {
  23     return collapsePath(text, false);
  24   }
  25
  26   /**
  27    * Convert paths inside {@code text} to portable form by replacing all values of path variables by their names.
  28    * @param recursively if {@code true} all occurrences of paths inside {@code text} will be processed, otherwise {@code text} will be converted
  29    *                    only if its entire content is a path (or URL)
  30    */
  31   @Contract("null, _ -> null; !null, _ -> !null")
  32   String collapsePath(@Nullable String text, boolean recursively);
  33
  34   /**
  35    * Process sub tags of {@code element} recursively and convert paths to absolute forms in all tag texts and attribute values.
  36    */
  37   void expandPaths(@NotNull Element element);
  38
  39   default void collapsePaths(@NotNull Element element) {
  40     collapsePaths(element, false);
  41   }
  42
  43   default void collapsePathsRecursively(@NotNull Element element) {
  44     collapsePaths(element, true);
  45   }
  46
  47   /**
  48    * Process sub tags of {@code element} recursively and convert paths to portable forms in all tag texts and attribute values.
  49    * @param recursively if {@code true} all occurrences of paths inside tag texts and attribute values will be processed, otherwise
  50    * they will be converted only if their entire content is a path (or URL)
  51    */
  52   void collapsePaths(@NotNull Element element, boolean recursively);
  53
  54   @Contract("null -> null; !null -> !null")
  55   default String collapsePathsRecursively(@Nullable String text) {
  56     return collapsePath(text, true);
  57   }
  58 }