vscode-uri

  • Version 3.0.8
  • Published
  • 204 kB
  • No dependencies
  • MIT license

Install

npm i vscode-uri
yarn add vscode-uri
pnpm add vscode-uri

Overview

The URI implementation that is used by VS Code and its extensions

Index

Classes

class URI

class URI implements UriComponents {}
  • Uniform Resource Identifier (URI) http://tools.ietf.org/html/rfc3986. This class is a simple parser which creates the basic component parts (http://tools.ietf.org/html/rfc3986#section-3) with minimal validation and encoding.

    foo://example.com:8042/over/there?name=ferret#nose
    \_/ \______________/\_________/ \_________/ \__/
    | | | | |
    scheme authority path query fragment
    | _____________________|__
    / \ / \
    urn:example:animal:ferret:nose

property authority

readonly authority: string;
  • authority is the 'www.example.com' part of 'http://www.example.com/some/path?query#fragment'. The part between the first double slashes and the next slash.

property fragment

readonly fragment: string;
  • fragment is the 'fragment' part of 'http://www.example.com/some/path?query#fragment'.

property fsPath

readonly fsPath: string;
  • Returns a string representing the corresponding file system path of this URI. Will handle UNC paths, normalizes windows drive letters to lower-case, and uses the platform specific path separator.

    * Will *not* validate the path for invalid characters and semantics. * Will *not* look at the scheme of this URI. * The result shall *not* be used for display purposes but for accessing a file on disk.

    The *difference* to URI#path is the use of the platform specific separator and the handling of UNC paths. See the below sample of a file-uri with an authority (UNC path).

    const u = URI.parse('file://server/c$/folder/file.txt')
    u.authority === 'server'
    u.path === '/shares/c$/file.txt'
    u.fsPath === '\\server\c$\folder\file.txt'

    Using URI#path to read a file (using fs-apis) would not be enough because parts of the path, namely the server name, would be missing. Therefore URI#fsPath exists - it's sugar to ease working with URIs that represent files on disk (file scheme).

property path

readonly path: string;
  • path is the '/some/path' part of 'http://www.example.com/some/path?query#fragment'.

property query

readonly query: string;
  • query is the 'query' part of 'http://www.example.com/some/path?query#fragment'.

property scheme

readonly scheme: string;
  • scheme is the 'http' part of 'http://www.example.com/some/path?query#fragment'. The part before the first colon.

method file

static file: (path: string) => URI;
  • Creates a new URI from a file system path, e.g. c:\my\files, /usr/home, or \\server\share\some\path.

    The *difference* between URI#parse and URI#file is that the latter treats the argument as path, not as stringified-uri. E.g. URI.file(path) is **not the same as** URI.parse('file://' + path) because the path might contain characters that are interpreted (# and ?). See the following sample:

    const good = URI.file('/coding/c#/project1');
    good.scheme === 'file';
    good.path === '/coding/c#/project1';
    good.fragment === '';
    const bad = URI.parse('file://' + '/coding/c#/project1');
    bad.scheme === 'file';
    bad.path === '/coding/c'; // path is now broken
    bad.fragment === '/project1';

    Parameter path

    A file system path (see URI#fsPath)

method from

static from: (components: {
scheme: string;
authority?: string;
path?: string;
query?: string;
fragment?: string;
}) => URI;

    method isUri

    static isUri: (thing: any) => thing is URI;

      method parse

      static parse: (value: string, _strict?: boolean) => URI;
      • Creates a new URI from a string, e.g. http://www.example.com/some/path, file:///usr/home, or scheme:with/path.

        Parameter value

        A string which represents an URI (see URI#toString).

      method revive

      static revive: {
      (data: UriComponents | URI): URI;
      (data: URI | UriComponents): URI;
      (data: URI | UriComponents): URI;
      (data: URI | UriComponents): URI;
      };

        method toJSON

        toJSON: () => UriComponents;

          method toString

          toString: (skipEncoding?: boolean) => string;
          • Creates a string representation for this URI. It's guaranteed that calling URI.parse with the result of this function creates an URI which is equal to this URI.

            * The result shall *not* be used for display purposes but for externalization or transport. * The result will be encoded using the percentage encoding and encoding happens mostly ignore the scheme-specific encoding rules.

            Parameter skipEncoding

            Do not encode the result, default is false

          method with

          with: (change: {
          scheme?: string;
          authority?: string | null;
          path?: string | null;
          query?: string | null;
          fragment?: string | null;
          }) => URI;

            Namespaces

            namespace Utils

            namespace Utils {}

              function basename

              basename: (uri: URI) => string;
              • Returns the last segment of the path of a URI, similar to the Unix basename command. In the path, '/' is recognized as the directory separation character. Trailing directory separators are ignored. The empty string is returned if the URIs path is empty or does not contain any path segments.

                Parameter uri

                The input URI. The base name of the URIs path.

              function dirname

              dirname: (uri: URI) => URI;
              • Returns a URI where the path is the directory name of the input uri, similar to the Unix dirname command. In the path, '/' is recognized as the directory separation character. Trailing directory separators are ignored. The orignal URI is returned if the URIs path is empty or does not contain any path segments.

                Parameter uri

                The input URI. The last segment of the URIs path.

              function extname

              extname: (uri: URI) => string;
              • Returns the extension name of the path of a URI, similar to the Unix extname command. In the path, '/' is recognized as the directory separation character. Trailing directory separators are ignored. The empty string is returned if the URIs path is empty or does not contain any path segments.

                Parameter uri

                The input URI. The extension name of the URIs path.

              function joinPath

              joinPath: (uri: URI, ...paths: string[]) => URI;
              • Joins one or more input paths to the path of URI. '/' is used as the directory separation character.

                The resolved path will be normalized. That means: - all '..' and '.' segments are resolved. - multiple, sequential occurences of '/' are replaced by a single instance of '/'. - trailing separators are preserved.

                Parameter uri

                The input URI.

                Parameter paths

                The paths to be joined with the path of URI.

                Returns

                A URI with the joined path. All other properties of the URI (scheme, authority, query, fragments, ...) will be taken from the input URI.

              function resolvePath

              resolvePath: (uri: URI, ...paths: string[]) => URI;
              • Resolves one or more paths against the path of a URI. '/' is used as the directory separation character.

                The resolved path will be normalized. That means: - all '..' and '.' segments are resolved. - multiple, sequential occurences of '/' are replaced by a single instance of '/'. - trailing separators are removed.

                Parameter uri

                The input URI.

                Parameter paths

                The paths to resolve against the path of URI.

                Returns

                A URI with the resolved path. All other properties of the URI (scheme, authority, query, fragments, ...) will be taken from the input URI.

              Package Files (3)

              Dependencies (0)

              No dependencies.

              Dev Dependencies (9)

              Peer Dependencies (0)

              No peer dependencies.

              Badge

              To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

              You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/vscode-uri.

              • Markdown
                [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/vscode-uri)
              • HTML
                <a href="https://www.jsdocs.io/package/vscode-uri"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>