dom/chrome-webidl/PathUtils.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /**
   8  * PathUtils is a set of utilities for operating on absolute paths.
   9  */
  10 [ChromeOnly, Exposed=(Window, Worker)]
  11 namespace PathUtils {
  12   /**
  13    * Return the last path component.
  14    *
  15    * @param path An absolute path.
  16    *
  17    * @returns The last path component.
  18    */
  19   [Throws]
  20   DOMString filename(DOMString path);
  21
  22   /**
  23    * Return an ancestor directory of the given path.
  24    *
  25    * @param path An absolute path.
  26    * @param depth The number of ancestors to remove, defaulting to 1 (i.e., the
  27    *              parent).
  28    *
  29    * @return The ancestor directory.
  30    *
  31    *         If the path provided is a root path (e.g., `C:` on Windows or `/`
  32    *         on *NIX), then null is returned.
  33    */
  34   [Throws]
  35   DOMString? parent(DOMString path, optional long depth = 1);
  36
  37   /**
  38    * Join the given components into a full path.
  39    *
  40    * @param components The path components. The first component must be an
  41    *                   absolute path. There must be at least one component.
  42    */
  43   [Throws]
  44   DOMString join(DOMString... components);
  45
  46   /**
  47    * Join the given relative path to the base path.
  48    *
  49    * @param base The base path. This must be an absolute path.
  50    * @param relativePath A relative path to join to the base path.
  51    */
  52   [Throws]
  53   DOMString joinRelative(DOMString base, DOMString relativePath);
  54
  55   /**
  56    * Creates an adjusted path using a path whose length is already close
  57    * to MAX_PATH. For windows only.
  58    *
  59    * @param path An absolute path.
  60    */
  61   [Throws]
  62   DOMString toExtendedWindowsPath(DOMString path);
  63
  64   /**
  65    * Normalize a path by removing multiple separators and `..` and `.`
  66    * directories.
  67    *
  68    * On UNIX platforms, the path must exist as symbolic links will be resolved.
  69    *
  70    * @param path The absolute path to normalize.
  71    *
  72    */
  73   [Throws]
  74   DOMString normalize(DOMString path);
  75
  76   /**
  77    * Split a path into its components.
  78    *
  79    * @param path An absolute path.
  80    */
  81   [Throws]
  82   sequence<DOMString> split(DOMString path);
  83
  84   /**
  85    * Split a relative path into its components.
  86    *
  87    * @param path A relative path.
  88    */
  89   [Throws]
  90   sequence<DOMString> splitRelative(DOMString path, optional SplitRelativeOptions options = {});
  91
  92   /**
  93    * Transform a file path into a file: URI
  94    *
  95    * @param path An absolute path.
  96    *
  97    * @return The file: URI as a string.
  98    */
  99   [Throws]
 100   UTF8String toFileURI(DOMString path);
 101
 102   /**
 103    * Determine if the given path is an absolute or relative path.
 104    *
 105    * @param path A file path that is either relative or absolute.
 106    *
 107    * @return Whether or not the path is absolute.
 108    */
 109   boolean isAbsolute(DOMString path);
 110 };
 111
 112 [Exposed=Window]
 113 partial namespace PathUtils {
 114   /**
 115    * The profile directory.
 116    */
 117   [Throws, BinaryName="ProfileDirSync"]
 118   readonly attribute DOMString profileDir;
 119
 120   /**
 121    * The local-specific profile directory.
 122    */
 123   [Throws, BinaryName="LocalProfileDirSync"]
 124   readonly attribute DOMString localProfileDir;
 125
 126   /**
 127    * The OS temporary directory.
 128    */
 129   [Throws, BinaryName="TempDirSync"]
 130   readonly attribute DOMString tempDir;
 131
 132   /**
 133    * The libxul path.
 134    */
 135   [Throws, BinaryName="XulLibraryPathSync"]
 136   readonly attribute DOMString xulLibraryPath;
 137 };
 138
 139 [Exposed=Worker]
 140 partial namespace PathUtils {
 141   /**
 142    * The profile directory.
 143    */
 144   [NewObject, BinaryName="GetProfileDirAsync"]
 145   Promise<DOMString> getProfileDir();
 146
 147   /**
 148    * The local-specific profile directory.
 149    */
 150   [NewObject, BinaryName="GetLocalProfileDirAsync"]
 151   Promise<DOMString> getLocalProfileDir();
 152
 153   /**
 154    * The OS temporary directory.
 155    */
 156   [NewObject, BinaryName="GetTempDirAsync"]
 157   Promise<DOMString> getTempDir();
 158
 159   /**
 160    * The libxul path.
 161    */
 162   [NewObject, BinaryName="GetXulLibraryPathAsync"]
 163   Promise<DOMString> getXulLibraryPath();
 164 };
 165
 166 dictionary SplitRelativeOptions {
 167   /** Allow for a path that contains empty components. */
 168   boolean allowEmpty = false;
 169
 170   /** Allow for a path that contains ".." components. */
 171   boolean allowParentDir = false;
 172
 173   /** Allow for a path that contains "." components. */
 174   boolean allowCurrentDir = false;
 175 };