Source: xxe/res/URIUtil.js

  1. const CSRI_SEPARATOR_NO_AUTHORITY = ")@no-authority/";
  2. const CSRI_SEPARATOR_OPAQUE_URI = ")@opaque-uri/";
  3. const CSRI_SEPARATORS = [
  4.     CSRI_SEPARATOR_NO_AUTHORITY,
  5.     CSRI_SEPARATOR_OPAQUE_URI,
  6.     ")@",
  7.     ")"
  8. ];
  10. /**
  11.  * The file path separator on Windows , that is, <code>'\'</code>.
  12.  * @type string
  13.  */
  14. const WINDOWS_FILE_PATH_SEPARATOR = '\\';
  16. /**
  17.  * The platform specific file path separator, that is, <code>'\'</code>
  18.  * on Windows and <code>'/'</code> on the other platforms.
  19.  * @type string
  20.  */
  21. const FILE_PATH_SEPARATOR =
  22.       PLATFORM_IS_WINDOWS? WINDOWS_FILE_PATH_SEPARATOR : '/';
  24. /**
  25.  * Some helper functions (static methods) related to URIs and to file paths.
  26.  */
  27. /*TEST|export|TEST*/ class URIUtil {
  28.     // -----------------------------------------------------------------------
  29.     // "csri:" server specific URL to normal client URI
  30.     // -----------------------------------------------------------------------
  31.     
  32.     /**
  33.      * Converts specified URI to an actual URI if it's a "csri:" URL 
  34.      * <small>(Client Side Resource Identifier, an URL form common to 
  35.      * {@link XMLEditor} and XXE server of an URI managed by 
  36.      * client-code)</small>; returns specified URI as is otherwise.
  37.      * <p>"csri:" URL examples:
  38.      * <pre>csri://(file)@no-authority/tmp/doc.xml
  39.      *csri://(file)@myserver/share/docs/doc.xml
  40.      *csri://(urn)@opaque-uri/ietf:rfc:2648
  41.      *csri://(https)@www.xmlmind.com:80/xmleditor/index.html
  42.      *csri://(ftp)foo:bar@xmlmind.com/xmleditor/index.html</pre>
  43.      *
  44.      * @param {string} url - an URL, possibly a "csri:" one.
  45.      * @return {string} corresponding URI.
  46.      */
  47.     static csriURLToURI(url) {
  48.         if (url === null || !url.startsWith("csri://(")) {
  49.             return url;
  50.         }
  52.         let uri = url;
  53.         
  54.         for (let separ of CSRI_SEPARATORS) {
  55.             let pos = uri.indexOf(separ, 8);
  56.             if (pos > 8) {
  57.                 let scheme = uri.substring(8, pos).trim();
  58.                 if (scheme.length > 0) {
  59.                     let tail;
  60.                     if (CSRI_SEPARATOR_NO_AUTHORITY === separ) {
  61.                         tail = "///" + uri.substring(pos + separ.length);
  62.                     } else if (CSRI_SEPARATOR_OPAQUE_URI === separ) {
  63.                         tail = uri.substring(pos + separ.length);
  64.                     } else {
  65.                         tail = "//" + uri.substring(pos + separ.length);
  66.                     }
  68.                     uri = scheme + ":" + tail;
  69.                 }
  71.                 // Done.
  72.                 break;
  73.             }
  74.         }
  76.         return uri;
  77.     }
  78.     
  79.     // -----------------------------------------------------------------------
  80.     // URI utilities
  81.     // -----------------------------------------------------------------------
  82.     
  83.     /**
  84.      * Returns the basename, if any, of specified URI.
  85.      *
  86.      * @param {string} uri - a relative or absolute, <em>valid</em> URI.
  87.      * @return {string} the basename of specified URI <small>(decoded using 
  88.      * <code>decodeURIComponent</code>)</small> if any; 
  89.      * <code>null</code> otherwise.
  90.      */
  91.     static uriBasename(uri) {
  92.         let [scheme, authority, path, query, fragment] = URIUtil.splitURI(uri);
  93.         if (!path) {
  94.             return null;
  95.         }
  97.         let basename = URIUtil.pathBasename(path, '/');
  98.         return !basename? null : decodeURIComponent(basename);
  99.     }
  101.     /**
  102.      * Changes the basename of specified URI.
  103.      *
  104.      * @param {string} uri - a relative or absolute, <em>valid</em> URI.
  105.      * @param {string} basename - the new basename <small>(to be encoded using
  106.      * <code>encodeURIComponent</code>)</small>.
  107.      * @return {string} modified URI; <code>null</code> if specified 
  108.      * URI has no path.
  109.      */
  110.     static uriSetBasename(uri, basename) {
  111.         let [scheme, authority, path, query, fragment] = URIUtil.splitURI(uri);
  112.         if (!path) {
  113.             return null;
  114.         }
  116.         basename = encodeURIComponent(basename);
  117.         let parent = URIUtil.pathParent(path, '/', /*trailingSepar*/ true);
  118.         if (!parent) {
  119.             // Common case: uri consists in just a basename (e.g. "bin.dat").
  120.             path = basename;
  121.         } else {
  122.             path = parent + basename;
  123.         }
  124.         
  125.         return URIUtil.joinURI(scheme, authority, path, query, fragment);
  126.     }
  128.     /**
  129.      * Splits specified URI into its components: 
  130.      * scheme, authority, path, query, fragment.
  131.      * <p>Note that returned URI components are <em>NOT</em> decoded using 
  132.      * <code>decodeURIComponent</code>.
  133.      *
  134.      * @param {string} uri - a relative or absolute, <em>valid</em> URI.
  135.      * @return {array} an array containing scheme, authority, path, query, 
  136.      * fragment, each of this component possibly being <code>null</code> or 
  137.      * just the empty string.
  138.      */
  139.     static splitURI(uri) {
  140.         if (!uri) {
  141.             return [ null, null, null, null, null ];
  142.         }
  143.         
  144.         // Cannot simply use the URL API.
  145.         // The URL API consider any protocol other than "http", "https", "ftp"
  146.         // as being opaque.
  147.         // For example, (new URL(uri)).pathname for "foo://bar.com/gee/wiz.dat"
  148.         // would be "//bar.com/gee/wiz.dat".
  150.         let scheme = null;
  151.         let authority = null;
  152.         let path = null;
  153.         let query = null;
  154.         let fragment = null;
  156.         // Authority?
  157.         let pos = uri.indexOf("://");
  158.         if (pos < 0) {
  159.             // No authority. Example: "file:/tmp/server.log".
  160.             
  161.             pos = uri.indexOf(":");
  162.             if (pos < 0) {
  163.                 // No scheme. Example: "../foo/bar.txt".
  164.                 path = uri;
  165.             } else {
  166.                 // Example: "urn:isbn:8088451".
  167.                 scheme = uri.substring(0, pos);
  168.                 path = uri.substring(pos+1); 
  169.             }
  170.         } else {
  171.             // Example: "ftp://john@acme.com/foo/bar.txt".
  172.             scheme = uri.substring(0, uri.indexOf(":"));
  174.             pos += 3; // Skip "://".
  175.             let slash = uri.indexOf("/", pos);
  176.             if (slash < 0) {
  177.                 authority = uri.substring(pos);
  178.                 // Example: "http://acme.com". No path, but "" and not null
  179.                 // for consistency with the other cases.
  180.                 path = "";
  181.             } else {
  182.                 authority = uri.substring(pos, slash);
  183.                 // Path starting with "/".
  184.                 path = uri.substring(slash);
  185.             }
  186.         }
  188.         // Fragment?
  189.         if (path !== null) {
  190.             pos = path.lastIndexOf("#");
  191.             if (pos >= 0) {
  192.                 fragment = path.substring(pos+1);
  193.                 path = path.substring(0, pos);
  194.             }
  195.         }
  196.         
  197.         // Query?
  198.         if (path !== null) {
  199.             pos = path.lastIndexOf("?");
  200.             if (pos >= 0) {
  201.                 query = path.substring(pos+1);
  202.                 path = path.substring(0, pos);
  203.             }
  204.         }
  205.         
  206.         return [ scheme, authority, path, query, fragment ];
  207.     }
  209.     /**
  210.      * Returns the file extension, if any, of specified URI.
  211.      *
  212.      * @param {string} uri - a relative or absolute, <em>valid</em> URI.
  213.      * @return {string} the file extension of specified URI if any; 
  214.      * <code>null</code> otherwise.
  215.      */
  216.     static uriExtension(uri) {
  217.         let [scheme, authority, path, query, fragment] = URIUtil.splitURI(uri);
  218.         if (!path) {
  219.             return null;
  220.         }
  222.         let ext = URIUtil.pathExtension(path, '/');
  223.         return !ext? null : decodeURIComponent(ext);
  224.     }
  226.     /**
  227.      * Returns the parent, if any, of specified URI.
  228.      *
  229.      * @param {string} uri - a relative or absolute, <em>valid</em> URI.
  230.      * @param {string} [trailingSepar=true] trailingSepar - if 
  231.      * <code>true</code>,  returned URI has a path which ends with 
  232.      * a trailing <code>'/'</code> character.
  233.      * @return {string} the parent of specified URI if any; 
  234.      * <code>null</code> otherwise.
  235.      */
  236.     static uriParent(uri, trailingSepar=true) {
  237.         let [scheme, authority, path, query, fragment] = URIUtil.splitURI(uri);
  238.         if (!path) {
  239.             return null;
  240.         }
  242.         let parent = URIUtil.pathParent(path, '/', trailingSepar);
  243.         if (!parent) {
  244.             return null;
  245.         }
  246.         
  247.         return URIUtil.joinURI(scheme, authority, parent);
  248.     }
  249.     
  250.     /**
  251.      * Join specified URI components and return resulting URI.
  252.      * <p>Specified URI components are joined as is, that is, 
  253.      * without first encoding them using <code>encodeURIComponent</code>.
  254.      */
  255.     static joinURI(scheme, authority, path, query=null, fragment=null) {
  256.         let uri = "";
  257.         if (scheme) {
  258.             uri += scheme;
  259.             uri += ':';
  260.         }
  261.         if (authority) {
  262.             uri += "//";
  263.             uri += authority;
  264.         }
  265.         if (path) {
  266.             uri += path;
  267.         }
  268.         if (query) {
  269.             uri += '?';
  270.             uri += query;
  271.         }
  272.         if (fragment) {
  273.             uri += '#';
  274.             uri += fragment;
  275.         }
  276.         
  277.         return uri;
  278.     }
  280.     /**
  281.      * Tests whether specified URI is an absolute hierarchical URI.
  282.      * 
  283.      * @param {string} uri - a relative or absolute, <em>valid</em> URI.
  284.      * @return {boolean} <code>true</code> if it's an absolute 
  285.      * hierarchical URI; <code>false</code> otherwise.
  286.      */
  287.     static isAbsoluteURI(uri) {
  288.         let [scheme, authority, path, query, fragment] = URIUtil.splitURI(uri);
  289.         return (scheme && path && path.startsWith('/'))? true : false;
  290.     }
  291.     
  292.     /**
  293.      * Returns specified URI after making it relative to the other URI
  294.      * (when this is possible).
  295.      * 
  296.      * @param {string} uri - an absolute, <em>valid</em> URI.
  297.      * @param {string} baseURI - another absolute, <em>valid</em> URI
  298.      * which is used as a base URI.
  299.      * @return {string} the relative URI when possible; 
  300.      * specified uri as is otherwise (for example, when specified URIs
  301.      * don't have the same scheme or authority).
  302.      */
  303.     static relativizeURI(uri, baseURI) {
  304.         // uri and baseURI must be absolute URIs having the same scheme and
  305.         // authority (case-insensitive).
  306.         
  307.         let [scheme1, authority1, path1, query1, fragment1] =
  308.             URIUtil.splitURI(uri);
  309.         if (scheme1) {
  310.             scheme1 = scheme1.toLowerCase();
  311.         }
  312.         let auth1 = authority1;
  313.         if (!auth1) {
  314.             auth1 = null;
  315.         } else {
  316.             auth1 = auth1.toLowerCase();
  317.             if (scheme1 === "file" && auth1 === "localhost") {
  318.                 auth1 = null;
  319.             }
  320.         }
  321.         
  322.         let [scheme2, authority2, path2, query2, fragment2] =
  323.             URIUtil.splitURI(baseURI);
  324.         if (scheme2) {
  325.             scheme2 = scheme2.toLowerCase();
  326.         }
  327.         let auth2 = authority2;
  328.         if (!auth2) {
  329.             auth2 = null;
  330.         } else {
  331.             auth2 = auth2.toLowerCase();
  332.             if (scheme2 === "file" && auth2 === "localhost") {
  333.                 auth2 = null;
  334.             }
  335.         }
  336.         
  337.         if (!scheme1 || !path1 || !path1.startsWith('/') ||
  338.             !scheme2 || !path2 || !path2.startsWith('/') ||
  339.             scheme1 !== scheme2 || auth1 !== auth2) {
  340.             return uri;
  341.         }
  343.         // ---
  344.         
  345.         if (PLATFORM_IS_WINDOWS && scheme1 === "file") {
  346.             // On Windows, "file:" URLs may have different volumes (e.g.
  347.             // file:/C:/foo and file:/D:/bar). When this is the case, do not
  348.             // attempt to compute a relative path.
  350.             let drive1 = null;
  351.             let match = path1.match(/^\/([a-zA-Z]:)\//);
  352.             if (match !== null) {
  353.                 drive1 = match[1].toUpperCase(); // Not case-sensitive.
  354.                                                  // Normalize to upper-case.
  355.             }
  356.             
  357.             let drive2 = null;
  358.             match = path2.match(/^\/([a-zA-Z]:)\//);
  359.             if (match !== null) {
  360.                 drive2 = match[1].toUpperCase();
  361.             }
  363.             if (drive1 !== drive2) {
  364.                 return uri;
  365.             }
  366.         }
  368.         let relPath = URIUtil.relativizePath(path1, path2, '/');
  369.         return URIUtil.joinURI(/*scheme*/ null, /*authority*/ null,
  370.                                relPath, query1, fragment1);
  371.     }
  372.     
  373.     /**
  374.      * Returns specified relative URI after resolving it against the other URI.
  375.      * 
  376.      * @param {string} uri - a relative or absolute, <em>valid</em> URI.
  377.      * @param {string} baseURI - an absolute, <em>valid</em> URI
  378.      * which is used as a base URI.
  379.      * @return {string} the resolved URI when possible; 
  380.      * specified uri as is otherwise (for example, when specified URI 
  381.      * is already absolute).
  382.      */
  383.     static resolveURI(uri, baseURI) {
  384.         // baseURI must be an absolute URI.
  385.         let [scheme2, authority2, path2, query2, fragment2] =
  386.             URIUtil.splitURI(baseURI);
  387.         if (!scheme2 || !path2 || !path2.startsWith('/')) {
  388.             return uri;
  389.         }
  390.         
  391.         let [scheme1, authority1, path1, query1, fragment1] =
  392.             URIUtil.splitURI(uri);
  393.         if (scheme1 && path1 && path1.startsWith('/')) {
  394.             // Already absolute: nothing to do.
  395.             return uri;
  396.         }
  398.         let absPath = !path1? "/" : URIUtil.resolvePath(path1, path2, '/');
  399.         return URIUtil.joinURI(scheme2, authority2,
  400.                                absPath, query1, fragment1);
  401.     }
  403.     /**
  404.      * Returns specified absolute URI after normalizing its authority 
  405.      * if it's a "file:" URI. Otherwise returns specified URI as is.
  406.      */
  407.     static normalizeFileURI(uri) {
  408.         let uri2;
  409.         if (uri && (uri2 = uri.toLowerCase()).startsWith("file:/")) {
  410.             let matches = (new RegExp("^file://([^/]*)/")).exec(uri2);
  411.             if (matches === null) {
  412.                 // file:/PATH.
  413.                 uri = "file:///" + uri.substring(6);
  414.             } else {
  415.                 if (matches[1] === "localhost") {
  416.                     // file://localhost/PATH.
  417.                     uri = "file:///" + uri.substring(17);
  418.                 }
  419.                 // Otherwise, file:///PATH or file://AUTH/PATH. Leave it as is.
  420.             }
  421.         }
  422.         
  423.         return uri;
  424.     }
  425.     
  426.     // -----------------------------------------------------------------------
  427.     // URI to platform specific file path and the other way round
  428.     // -----------------------------------------------------------------------
  429.     
  430.     /**
  431.      * Returns the file path corresponding to specified absolute "file:" URI.
  432.      *
  433.      * @param {string} uri - an absolute, <em>valid</em>, "file:" URI.
  434.      * @param {string} [pathSepar=FILE_PATH_SEPARATOR] pathSepar - 
  435.      * the character used to separate file path segments 
  436.      * (that is, '\' on Windows).
  437.      * @return {string} corresponding absolute file path when possible, 
  438.      * <code>null</code> otherwise.
  439.      */
  440.     static uriToFilePath(uri, pathSepar=FILE_PATH_SEPARATOR) {
  441.         let [scheme, authority, path, query, fragment] = URIUtil.splitURI(uri);
  442.         if (!scheme || scheme !== "file") {
  443.             return null;
  444.         }
  445.         if (!path) {
  446.             path = "/";
  447.         }
  448.         
  449.         // Ignore authority, query and fragment.
  450.         let segments = path.split('/');
  451.         for (let i = segments.length-1; i >= 0; --i) {
  452.             segments[i] = decodeURIComponent(segments[i]);
  453.         }
  454.         let file = segments.join(pathSepar);
  455.         
  456.         if (pathSepar === WINDOWS_FILE_PATH_SEPARATOR) {
  457.             if (authority && authority !== "localhost") {
  458.                 // Special processing of "file://server/path".
  459.                 file = "\\\\" + authority + file;
  460.             } else {
  461.                 // "\C:" becomes "C:\".
  462.                 // "\C:\temp\foo" becomes "C:\temp\foo".
  463.                 
  464.                 if (file.match(/^\\[a-zA-Z]:/)) {
  465.                     if (file.length === 3) {
  466.                         file = file.substring(1) + "\\";
  467.                     } else if (file.charAt(3) === "\\") {
  468.                         file = file.substring(1);
  469.                     }
  470.                 }
  471.             }
  472.         }
  474.         return URIUtil.normalizePath(file, pathSepar);
  475.     }
  477.     /**
  478.      * Convert specified path to a "file:" URI.
  479.      * 
  480.      * @param {string} path - relative or absolute path.
  481.      * @param {string} [pathSepar=FILE_PATH_SEPARATOR] pathSepar - 
  482.      * the character used to separate file path segments 
  483.      * (that is, '\' on Windows).
  484.      * @return {string} corresponding relative or absolute "file:" URI.
  485.      * Note that if <code>path</code> is relative, this URI will have no
  486.      * "file:" scheme (e.g. returns "tmp/my%20doc.xml" for "tmp\\my doc.xml");
  487.      */
  488.     static pathToFileURI(path, pathSepar=FILE_PATH_SEPARATOR) {
  489.         let [drive, checkedPath] = URIUtil.checkPath(path, pathSepar);
  491.         let uri;
  492.         if (URIUtil.testIsAbsolute(drive, checkedPath, pathSepar)) {
  493.             uri = "file://";
  494.             if (drive !== null) {
  495.                 if (drive.match(/^[a-zA-Z]:/)) {
  496.                     uri += "/" + drive;
  497.                 } else {
  498.                     // UNC path like "\\serv\share\doc.xml".
  499.                     // Discard leading "\\".
  500.                     uri += drive.substring(2); 
  501.                 }
  502.                 // uri is something like "file:///C:" or "file://my-server".
  503.             }
  504.         } else {
  505.             // Relative path. Resulting uri will have no "file:" scheme.
  506.             uri = "";
  507.         }
  509.         let parts = checkedPath.split(pathSepar).map((part) => {
  510.             if (part.length > 0) {
  511.                 part = encodeURIComponent(part);
  512.             }
  513.             return part;
  514.         });
  516.         uri += parts.join('/');
  517.         
  518.         return uri;
  519.     }
  521.     static checkPath(path, pathSepar) {
  522.         let drive = null;
  523.         
  524.         if (pathSepar === WINDOWS_FILE_PATH_SEPARATOR) {
  525.             // Example: \\ComputerName\SharedFolder\Resource
  526.             let match = path.match(/^(\\\\[^\\]+)\\/);
  527.             if (match !== null) {
  528.                 drive = match[1].toUpperCase(); // Not case-sensitive.
  529.                                                 // Normalize to upper-case.
  530.                 path = path.substring(drive.length);
  531.             } else {
  532.                 // Example: C:\Folder\File
  533.                 // Drive relative paths like D:File not supported.
  534.                 let match = path.match(/^([a-zA-Z]:)\\/);
  535.                 if (match !== null) {
  536.                     drive = match[1].toUpperCase(); // Not case-sensitive.
  537.                                                     // Normalize to upper-case.
  538.                     path = path.substring(drive.length);
  539.                 }
  540.             }
  541.         }
  542.         // Otherwise, we have an absolute or relative path.
  544.         path = URIUtil.doNormalizePath(path, pathSepar);
  546.         return [drive, path];
  547.     }
  548.     
  549.     static doNormalizePath(path, pathSepar) {
  550.         const originalPath = path;
  551.         
  552.         const prependSlash = path.startsWith(pathSepar);
  553.         const appendSlash = path.endsWith(pathSepar);
  554.         if (prependSlash || appendSlash) {
  555.             let start = 0;
  556.             let end = path.length-1;
  558.             while (start <= end && path.charAt(start) === pathSepar) {
  559.                 ++start;
  560.             }
  561.             while (end >= start && path.charAt(end) === pathSepar) {
  562.                 --end;
  563.             }
  565.             if (start > end) {
  566.                 return pathSepar;
  567.             }
  569.             path = path.substring(start, end+1);
  570.             // This one does not start or end with pathSepar.
  571.         }
  573.         // ---
  575.         let twoPasses = false;
  576.         let buffer = "";
  578.         let parts = path.split(pathSepar);
  579.         for (let part of parts) {
  580.             if (part.length === 0 || 
  581.                 "." === part) { // e.g. "x//y", "x/./y"
  582.                 continue;
  583.             }
  585.             if (part.trim().length === 0) {
  586.                 // Malformed path. Give up.
  587.                 return originalPath;
  588.             }
  590.             if (buffer.length > 0) {
  591.                 buffer += pathSepar;
  592.             }
  593.             buffer += part;
  595.             if (".." === part) {
  596.                 twoPasses = true;
  597.             }
  598.         }
  599.         
  600.         path = buffer;
  601.         
  602.         // ---
  603.         
  604.         if (twoPasses) {
  605.             parts = path.split(pathSepar);
  606.             buffer = "";
  608.             for (let i = parts.length-1; i >= 0; --i) {
  609.                 let part = parts[i];
  611.                 if (".." === part) {
  612.                     // Count skipped levels: (i-j).
  614.                     let j = i;
  615.                     while (j >= 0 && ".." === parts[j]) {
  616.                         --j;
  617.                     }
  619.                     // Skip the ".." and the corresponding level: 2*(i-j).
  620.                     // (+1 because the for loop includes a --i.)
  622.                     i = i - 2*(i-j) + 1;
  624.                     if (i < 0) {
  625.                         // Malformed path. Give up.
  626.                         return originalPath;
  627.                     }
  628.                 } else {
  629.                     if (buffer.length > 0) {
  630.                         buffer = pathSepar + buffer;
  631.                     }
  632.                     buffer = part + buffer;
  633.                 }
  634.             }
  635.         }
  636.         
  637.         path = buffer;
  638.         
  639.         // ---
  640.         
  641.         if (prependSlash) {
  642.             path = pathSepar + path;
  643.         }
  644.         if (appendSlash) {
  645.             path = path + pathSepar;
  646.         }
  648.         return path;
  649.     }
  650.     
  651.     static testIsAbsolute(drive, checkedPath, pathSepar) {
  652.         if (pathSepar === WINDOWS_FILE_PATH_SEPARATOR && drive === null) {
  653.             return false;
  654.         }
  655.         return checkedPath.startsWith(pathSepar);
  656.     }
  657.     
  658.     // -----------------------------------------------------------------------
  659.     // Low-level path utilities.
  660.     // (Work for platform specific file and URI paths.
  661.     //  Work for relative and absolute paths.)
  662.     // -----------------------------------------------------------------------
  664.     /**
  665.      * Tests whether specified path is absolute or relative.
  666.      * <p>On Windows, a drive relative path like "\foo\bar" is considered 
  667.      * to be relative. Only "C:\foo\bar" or "\\my-server\foo\bar" are 
  668.      * considered to be absolute.
  669.      * 
  670.      * @param {string} path - relative or absolute path.
  671.      * @param {string} pathSepar - the character used to separate 
  672.      * path segments (that is, '/' for URIs).
  673.      * @return {boolean} <code>true</code> if absolute; 
  674.      * <code>false</code> if relative.
  675.      */
  676.     static isAbsolutePath(path, pathSepar) {
  677.         let [drive, checkedPath] = URIUtil.checkPath(path, pathSepar);
  678.         return URIUtil.testIsAbsolute(drive, checkedPath, pathSepar);
  679.     }
  680.     
  681.     /**
  682.      * Resolves specified path against specified base.
  683.      * <p><strong>IMPORTANT:</strong> a directory path is expected to end 
  684.      * with <code><i>pathSepar</i></code>.
  685.      * 
  686.      * @param {string} path - relative or absolute path.
  687.      * @param {string} basePath - relative or absolute path.
  688.      * @param {string} pathSepar - the character used to separate 
  689.      * path segments (that is, '/' for URIs).
  690.      * @return {string} resolved path.
  691.      */
  692.     static resolvePath(path, basePath, pathSepar) {
  693.         if (URIUtil.isAbsolutePath(path, pathSepar) ||
  694.            !basePath) {
  695.             return path;
  696.         }
  698.         let parentPath;
  699.         if (basePath.endsWith(pathSepar)) {
  700.             // Assume basePath points to a directory.
  701.             parentPath = basePath;
  702.         } else {
  703.             parentPath = URIUtil.pathParent(basePath, pathSepar,
  704.                                             /*trailingSepar*/ true);
  705.         }
  707.         return URIUtil.normalizePath(!parentPath? path : parentPath + path,
  708.                                      pathSepar);
  709.     }
  711.     /**
  712.      * Returns specified relative or absolute path after normalizing it, 
  713.      * that is, after removing ".", ".." and duplicate path separators from it.
  714.      *
  715.      * @param {string} path - relative or absolute path.
  716.      * @param {string} pathSepar - the character used to separate 
  717.      * path segments (that is, '/' for URIs).
  718.      * @return {string} normalized path or original path if it is not possible
  719.      * to normalize it (examples: "../../foo/bar", "a/ /b/c").
  720.      */
  721.     static normalizePath(path, pathSepar) {
  722.         let [drive, checkedPath] = URIUtil.checkPath(path, pathSepar);
  723.         if (drive !== null) {
  724.             checkedPath = drive + checkedPath;
  725.         }
  726.         
  727.         return checkedPath;
  728.     }
  729.     
  730.     
  731.     /**
  732.      * Returns the extension of specified path. To make it simple, the
  733.      * substring after last '.', not including last '.'.
  734.      * <ul>
  735.      * <li>Returns <code>null</code> for "<tt>/tmp/test</tt>".
  736.      * <li>Returns the empty string for "<tt>/tmp/test.</tt>".
  737.      * <li>Returns <code>null</code> for "<tt>~/.profile</tt>".
  738.      * <li>Returns "<tt>gz</tt>" for "<tt>/tmp/test.tar.gz</tt>".
  739.      * </ul>
  740.      * 
  741.      * @param {string} path - relative or absolute path possibly 
  742.      * having an extension
  743.      * @param {string} pathSepar - the character used to separate 
  744.      * path segments (that is, '/' for URIs)
  745.      * @return {string} extension if any; <code>null</code> otherwise
  746.      */
  747.     static pathExtension(path, pathSepar) {
  748.         let [drive, checkedPath] = URIUtil.checkPath(path, pathSepar);
  749.         
  750.         let dot = URIUtil.indexOfDot(checkedPath, pathSepar);
  751.         if (dot < 0) {
  752.             return null;
  753.         } else {
  754.             return checkedPath.substring(dot+1);
  755.         }
  756.     }
  757.     
  758.     static indexOfDot(checkedPath, pathSepar) {
  759.         let dot = checkedPath.lastIndexOf('.');
  760.         if (dot >= 0) {
  761.             let baseNameStart = checkedPath.lastIndexOf(pathSepar);
  762.             if (baseNameStart < 0) {
  763.                 baseNameStart = 0;
  764.             } else {
  765.                 ++baseNameStart;
  766.             }
  768.             if (dot <= baseNameStart) {
  769.                 dot = -1;
  770.             }
  771.         }
  772.         
  773.         return dot;
  774.     }
  775.     
  776.     /**
  777.      * Returns the base name of specified path. To make it simple, the
  778.      * substring after last '/'.
  779.      * <p>Examples:
  780.      * <ul>
  781.      * <li>Returns the empty string for "<tt>/</tt>".
  782.      * <li>Returns "<tt>foo</tt>" for "<tt>foo</tt>".
  783.      * <li>Returns "<tt>bar</tt>" for "<tt>/foo/bar</tt>".
  784.      * <li>Returns "<tt>bar</tt>" for "<tt>/foo/bar/</tt>".
  785.      * </ul>
  786.      * 
  787.      * @param {string} path - relative or absolute path
  788.      * @param {string} pathSepar - the character used to separate 
  789.      * path segments (that is, '/' for URIs)
  790.      * @return {string} base name of specified path
  791.      */
  792.     static pathBasename(path, pathSepar) {
  793.         let [drive, checkedPath] = URIUtil.checkPath(path, pathSepar);
  794.         
  795.         if (checkedPath === pathSepar) {
  796.             return "";
  797.         }
  799.         // Normalize "/foo/bar/" to "/foo/bar".
  800.         if (checkedPath.endsWith(pathSepar)) {
  801.             checkedPath = checkedPath.substring(0, checkedPath.length-1);
  802.         }
  804.         let slash = checkedPath.lastIndexOf(pathSepar);
  805.         if (slash < 0) {
  806.             return checkedPath;
  807.         }
  809.         return checkedPath.substring(slash+1);
  810.     }
  811.     
  812.     /**
  813.      * Returns the parent of specified path. To make it simple, 
  814.      * the substring before last '/'.
  815.      * <p>Examples:
  816.      * <ul>
  817.      * <li>Returns <code>null</code> for "<tt>/</tt>".
  818.      * <li>Returns <code>null</code> for "<tt>foo</tt>".
  819.      * <li>Returns "<tt>/</tt>" for "<tt>/foo</tt>".
  820.      * <li>Returns "<tt>/foo</tt>" (or "<tt>/foo/</tt>") for 
  821.      * "<tt>/foo/bar</tt>".
  822.      * <li>Returns "<tt>/foo</tt>" (or "<tt>/foo/</tt>") for 
  823.      * "<tt>/foo/bar/</tt>".
  824.      * </ul>
  825.      * 
  826.      * @param {string} path - relative or absolute path
  827.      * @param {string} pathSepar - the character used to separate 
  828.      * path segments (that is, '/' for URIs)
  829.      * @param {string} trailingSepar - if <code>true</code>, 
  830.      * returned path ends with a trailing <code>pathSepar</code> character
  831.      * @return {string} parent of specified path or 
  832.      * <code>null</code> for <code>pathSepar</code> or if specified path 
  833.      * does not contain the <code>pathSepar</code> character
  834.      */
  835.     static pathParent(path, pathSepar, trailingSepar) {
  836.         let [drive, checkedPath] = URIUtil.checkPath(path, pathSepar);
  837.         
  838.         if (checkedPath === pathSepar) {
  839.             return null;
  840.         }
  842.         // Normalize "/foo/bar/" to "/foo/bar".
  843.         if (checkedPath.endsWith(pathSepar)) {
  844.             checkedPath = checkedPath.substring(0, checkedPath.length-1);
  845.         }
  847.         let slash = checkedPath.lastIndexOf(pathSepar);
  848.         if (slash < 0) {
  849.             return null;
  850.         }
  852.         let parent;
  853.         if (slash === 0) {
  854.             // Example: "/foo"
  855.             parent = pathSepar;
  856.         } else {
  857.             parent = checkedPath.substring(0, trailingSepar? slash+1 : slash);
  858.         }
  860.         if (drive !== null) {
  861.             parent = drive + parent;
  862.         }
  863.         
  864.         return parent;
  865.     }
  867.     /**
  868.      * Returns specified path after making it relative to the other path
  869.      * (when this is possible).
  870.      * <p><strong>IMPORTANT:</strong> a directory path is expected to end 
  871.      * with <code><i>pathSepar</i></code>.
  872.      * 
  873.      * @param {string} path - an absolute path.
  874.      * @param {string} basePath - another absolute path which is used as a base.
  875.      * @param {string} pathSepar - the character used to separate 
  876.      * path segments (that is, '/' for URIs)
  877.      * @return {string} the relative path when possible; 
  878.      * specified path as is otherwise (Windows example: when specified paths
  879.      * don't have the same drive.
  880.      */
  881.     static relativizePath(path, basePath, pathSepar) {
  882.         // path and basePath must be absolute paths having the same drive (if
  883.         // any).
  884.         let [drive1, checkedPath1] = URIUtil.checkPath(path, pathSepar);
  885.         let [drive2, checkedPath2] = URIUtil.checkPath(basePath, pathSepar);
  886.         if (!URIUtil.testIsAbsolute(drive1, checkedPath1, pathSepar) ||
  887.             !URIUtil.testIsAbsolute(drive2, checkedPath2, pathSepar) ||
  888.             drive1 !== drive2) {
  889.             return path;
  890.         }
  891.         path = checkedPath1;
  892.         basePath = checkedPath2;
  893.         
  894.         if (pathSepar === path) {
  895.             return pathSepar;
  896.         }
  898.         if (pathSepar === basePath) {
  899.             return path.substring(1);
  900.         }
  902.         if (!basePath.endsWith(pathSepar)) {
  903.             basePath = URIUtil.pathParent(basePath, pathSepar,
  904.                                           /*trailingSepar*/ true);
  905.         }
  907.         // Windows filenames are case insensitive. 
  908.         const onWindows = (pathSepar === WINDOWS_FILE_PATH_SEPARATOR);
  909.         const upSegment = ".." + pathSepar;
  910.         
  911.         let relPath = "";
  912.         while (basePath !== null) {
  913.             let start = basePath;
  915.             if (path.startsWith(start) ||
  916.                 (onWindows &&
  917.                  path.toLowerCase().startsWith(start.toLowerCase()))) {
  918.                 relPath += path.substring(start.length);
  919.                 break;
  920.             }
  922.             relPath += upSegment;
  923.             basePath = URIUtil.pathParent(basePath, pathSepar,
  924.                                           /*trailingSepar*/ true);
  925.         }
  927.         return relPath;
  928.     }
  929.     
  930.     // -----------------------------------------------------------------------
  932.     static formatFileSize(byteCount, fallback=null) {
  933.         if (!Number.isInteger(byteCount) || byteCount < 0) {
  934.             return fallback;
  935.         }
  936.         
  937.         let unit = 0;
  938.         while (byteCount >= 1024) {
  939.             byteCount /= 1024;
  940.             unit++;
  941.         }
  943.         if (unit > 0) {
  944.             byteCount = byteCount.toFixed(1); 
  945.         }
  946.         return `${byteCount} ${" KMGTPEZY"[unit]}B`;
  947.     }
  948.     
  949.     static formatFileDate(millis, fallback=null) {
  950.         if (!Number.isInteger(millis) || millis < 0) {
  951.             return fallback;
  952.         }
  954.         const date = new Date(millis);
  955.         
  956.         let text = date.getFullYear();
  957.         text += "-";
  958.         text += URIUtil.formatFileDateField(1 + date.getMonth());
  959.         text += "-";
  960.         text += URIUtil.formatFileDateField(date.getDate());
  961.         text += " ";
  962.         text += URIUtil.formatFileDateField(date.getHours());
  963.         text += ":";
  964.         text += URIUtil.formatFileDateField(date.getMinutes());
  965.         
  966.         return text;
  967.     }
  968.     
  969.     static formatFileDateField(value) {
  970.         let text = String(value);
  971.         while (text.length < 2) {
  972.             text = "0" + text;
  973.         }
  974.         return text;
  975.     }
  976.     
  977.     // -----------------------------------------------------------------------
  978.     
  979.     /*TEST|
  980.     static test_URIUtil(logger, filePathSepar) {
  981.         const uriList = [
  982.           "",
  983.           "foo/bar.dat",
  984.           "/foo/bar.dat",
  985.           "file:/foo/bar.xml",
  986.           "file:///foo/bar.xml",
  987.           "file:/Z:/foo/bar.xml#end",
  988.           "file:/C:",
  989.           "file:///C:/foo/././gee//wiz//bar.xml",
  990.           "file://GOOD/foo/gee/wiz/../../bar.xml",
  991.           "file://BAD/foo/gee/wiz/../../../../bar.xml",
  992.           "file://BAD/foo/%20%20%20%20/bar.xml",
  994.           "http://www.uiuc.edu:80",
  995.           "http://www.uiuc.edu:80/",
  996.           "http://www.uiuc.edu:80/SDG/",
  997.           "http://www.uiuc.edu:80/SDG/Software/Mosaic/Demo/url-primer",
  998.           "http://www.uiuc.edu:80/SDG/Software/Mosaic/Demo/.url-primer",
  999.           "http://www.uiuc.edu:80/SDG/Software/Mosaic/Demo/url-primer.html",
  1000.           "http://www.uiuc.edu/SDG/Software/Mosaic/Demo/url-primer.html.gz",
  1001.           "http://127.0.0.1/SDG/Software/Mosaic/Demo/url-primer.html#chapter1",
  1002.           "foo://example.com:8042/over/there?name=ferret#nose",
  1003.           "urn:example:animal:ferret:nose",
  1004.           "urn:example:animal:ferret:nose?name=ferret#foo",
  1005.           "ftp://hs%40x:my%20pass@www.foo.com:1024/bar/\
  1006. vin%20ros%C3%A9.jar#ros%C3%A9",
  1008.           "csri://(file)@no-authority/",
  1009.           "csri://(file)@no-authority/home/hussein/",
  1010.           "csri://(file)@no-authority/home//hussein/./tmp/..////",
  1011.           "csri://(file)@no-authority/../.././doc.xml",
  1012.           "csri://(file)@no-authority/z:/docs/doc.xml",
  1013.           "csri://(file)@myserver/share/docs/doc.xml",
  1014.           "csri://(file)@192.168.1.205/tmp/dump.dat",
  1015.           "csri://(file)@[1080:0:0:0:8:800:200C:417A]:80/tmp/dump.dat",
  1016.           "csri://(xdocs)@MyServer/Content/sample/dita/tasks/\
  1017. Very%20Important.dita",
  1018.           "csri://(https)@www.xmlmind.com/xmleditor/index.html#notice",
  1019.           "csri://(http)@www.xmlmind.com:80/xslsrv/exec?op=jobs&auth=toto",
  1020.           "csri://(ftp)john:doe@localhost/src/test/makefile",
  1021.           "csri://(urn)@opaque-uri/ietf:rfc:2648",
  1022.           "csri://(urn)@opaque-uri/lex:eu:council:directive:\
  1023. 2010-03-09;2010-19-UE#summary",
  1024.         ];
  1026.         for (let uri of uriList) {
  1027.             let [scheme, authority, path, query, fragment] =
  1028.                 URIUtil.splitURI(uri);
  1030.             let abs = URIUtil.isAbsoluteURI(uri);
  1031.             let name = URIUtil.uriBasename(uri);
  1032.             let ext = URIUtil.uriExtension(uri);
  1033.             let parent = URIUtil.uriParent(uri);
  1034.             
  1035.             // File path tests ---
  1037.             let uri2 = URIUtil.csriURLToURI(uri);
  1038.             let file = URIUtil.uriToFilePath(uri2, filePathSepar);
  1040.             let uri3 = null;
  1041.             if (file !== null) {
  1042.                 uri3 = URIUtil.pathToFileURI(file, filePathSepar);
  1043.             }
  1045.             logger(`uri='${uri}':\n\
  1046.     splitURI=[scheme=${scheme}, authority=${authority}, path=${path}, \
  1047. query=${query}, fragment=${fragment}],\n\
  1048.     abs=${abs}, basename='${name}', extension='${ext}', parent='${parent}'\n\
  1049.     csriURLToURI(uri)=uri2=${uri2}\n\
  1050.     uriToFilePath(uri2,${filePathSepar})=${file}\n\
  1051.     pathToFileURI(file,${filePathSepar})=${uri3}
  1052. ---`);
  1053.         }
  1054.     }
  1055.     |TEST*/
  1056.     
  1057.     // -----------------------------------------------------------------------
  1058.     
  1059.     /*TEST|
  1060.     static test_relativize(logger) {
  1061.         const paths1 = [
  1062.             "", "", 
  1063.             "/", "/", 
  1064.             "/", "/foo", 
  1065.             "/foo", "/", 
  1066.             "/foo", "/bar", 
  1067.             "foo", "/bar", 
  1068.             "/foo", "bar", 
  1069.             "/home/hussein", "/home",
  1070.             "/home/hussein", "/home/",
  1071.             "/foo/gee", "/foo/gee/wiz.xml", 
  1072.             "/foo/zip/bar.xml", "/foo/gee/wiz.xml", 
  1073.             "/foo/zip/bar.xml", "/foo/wiz.xml", 
  1074.             "/foo/bar.xml", "/foo/gee/wiz.xml", 
  1075.             "/foo/zip/bar.xml", "/foo/zip/bar.xml", 
  1076.             "/usr/local/bin/html2ps", "/usr/bin/grep", 
  1077.             "/foo/zip/bar/", "/foo/wiz", 
  1078.             "/foo/bar", "/foo/gee/wiz/", 
  1079.             "/foo/zip/bar/", "/foo/wiz/", 
  1080.             "/foo/bar/", "/foo/gee/wiz/", 
  1081.             "/foo/bar/", "/foo/bar/", 
  1082.             "/foo/bar/", "/foo/bar/gee", 
  1083.             "/foo/bar/gee", "/foo/bar/", 
  1084.             "/foo/bar/", "/foo/bar/wiz/", 
  1085.             "/foo/bar/wiz/", "/foo/bar/",
  1086.         ];
  1087.         URIUtil.testRelativizePath(logger, paths1, '/');
  1088.         
  1089.         logger("---");
  1090.         
  1091.         const paths2 = [
  1092.             "Z:", "Z:",
  1093.             "C:\\", "C:\\",
  1094.             "C:\\home\\hussein", "c:\\home",
  1095.             "C:\\home\\hussein", "c:\\home\\",
  1096.             "C:\\", "C:\\home\\hussein",
  1097.             "C:\\home\\hussein", "C:\\",
  1098.             "C:\\home", "c:\\home\\hussein",
  1099.             "c:\\home\\hussein", "C:\\HOME",
  1100.             "C:\\HOME\\HUSSEIN", "c:\\home",
  1101.             "C:\\home\\hussein\\DOT emacs", "C:\\home\\hussein\\bin\\clean.bat",
  1102.             "C:\\HOME\\HUSSEIN\\BIN\\CLEAN.BAT", "c:\\home\\hussein\\DOT emacs",
  1103.             "C:\\home\\hussein\\DOT emacs", "C:\\home\\hussein\\bin\\",
  1104.             "C:\\home\\hussein\\bin\\", "C:\\home\\hussein\\DOT emacs",
  1105.             "C:\\home\\hussein\\bin", "Z:\\docsrc",
  1106.             "Z:\\bin\\clean", "C:\\home\\hussein\\bin\\clean.bat",
  1107.             
  1108.             "\\\\Vboxsrv\\home_hussein\\bin\\clean",
  1109.             "\\\\Vboxsrv\\home_hussein\\.profile",
  1110.             
  1111.             "\\\\Vboxsrv\\home_hussein\\.profile",
  1112.             "\\\\VBOXSRV\\HOME_HUSSEIN\\BIN\\CLEAN",
  1113.         ];
  1114.         URIUtil.testRelativizePath(logger, paths2, '\\');
  1115.         
  1116.         logger("---");
  1118.         const uris = [
  1119.             "file:/Users/john/docs/doc.xml",
  1120.             "file:/Users/john/",
  1122.             "file:/Users/john/docs/doc.xml",
  1123.             "file:///Users/john/",
  1125.             "file:/Users/john/docs/doc.xml",
  1126.             "file://localhost/Users/john/",
  1128.             "file:/C:/Users/john/docs/doc.xml",
  1129.             "file:/Z:/docs/",
  1131.             "http://www.acme.com/docs/toc.html",
  1132.             "https://www.acme.com/docs/",
  1133.             
  1134.             "http://www.acme.biz/docs/toc.html",
  1135.             "http://www.acme.com/docs/",
  1136.             
  1137.             "http://www.acme.com/docs/toc.html",
  1138.             "http://www.acme.com/docs/",
  1139.             
  1140.             "http://www.acme.com/",
  1141.             "http://www.acme.com/docs/toc.html",
  1142.             
  1143.             "http://www.acme.com/docs/toc.html",
  1144.             "http://www.acme.com/",
  1145.             
  1146.             "http://www.acme.com/docs/toc.html",
  1147.             "http://www.acme.com/docs/toc.html",
  1148.             
  1149.             "http://www.acme.com/index.html",
  1150.             "http://www.acme.com/docs/toc.html",
  1151.             
  1152.             "http://www.acme.com/docs/index.html#index",
  1153.             "http://www.acme.com/docs/toc.html",
  1154.             
  1155.             "http://www.acme.com/docs/images/logo?format=SVG",
  1156.             "http://www.acme.com/docs/toc.html",
  1157.             
  1158.             "http://www.acme.com/index.html",
  1159.             "http://www.acme.com/docs/chapters/",
  1160.             
  1161.             "http://www.acme.com/docs/chapters/chapter1.html",
  1162.             "http://www.acme.com/docs/toc.html",
  1163.         ];
  1164.         for (let i = 0; i < uris.length; i += 2) {
  1165.             let uri = uris[i];
  1166.             let baseURI = uris[i+1];
  1168.             let relURI = URIUtil.relativizeURI(uri, baseURI);
  1169.             let absURI = URIUtil.resolveURI(relURI, baseURI);
  1170.             logger(`"${uri}" relative to "${baseURI}" = "${relURI}"\n\
  1171.     relative uri resolved = "${absURI}"`);
  1172.         }
  1173.     }
  1175.     static testRelativizePath(logger, paths, pathSepar) {
  1176.         for (let i = 0; i < paths.length; i += 2) {
  1177.             let path = paths[i];
  1178.             let basePath = paths[i+1];
  1180.             let relPath = URIUtil.relativizePath(path, basePath, pathSepar);
  1181.             let absPath = URIUtil.resolvePath(relPath, basePath, pathSepar);
  1182.             logger(`"${path}" relative to "${basePath}" = "${relPath}"\n\
  1183.     relative path resolved = "${absPath}"`);
  1184.         }
  1185.     }
  1186.     |TEST*/
  1187. }