tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

PathUtils.webidl (4390B)

      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 };