uri

package module
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 27, 2026 License: BSD-3-Clause Imports: 6 Imported by: 109

README

uri

test pkg.go.dev Go module codecov.io

Package uri is a canonical vscode-uri parser and formatter for Go.

Canonical escaping

Constructors such as Parse, File, FileFor, and From store the canonical encoded form returned by String, text marshaling, and JSON marshaling. The unreserved ASCII set A-Z a-z 0-9 - . _ ~ stays raw everywhere. Other bytes are escaped with uppercase percent triplets unless they are syntax characters that are valid for the component being formatted.

Component Additional raw syntax Examples
Path / @ -> %40, : -> %3A, \ -> %5C, Unicode bytes -> UTF-8 percent triplets
Query and fragment none = -> %3D, & -> %26, / -> %2F, @ -> %40
Authority host/port :, [, ] [::1]:8080 stays raw; / in an authority part becomes %2F
Authority userinfo delimiter @ http://user:pass@host:8080/p keeps the delimiter raw

For example, FileFor(PlatformPOSIX, "/Users/me/go/pkg/mod/example.com/[email protected]/file.go") formats as file:///Users/me/go/pkg/mod/example.com/mod%40v1.2.3/file.go. StringNoEncoding() returns the vscode-uri toString(true) style form and can expose decoded characters such as @, =, &, or Unicode text. The direct URI("...") compatibility path described below is not a constructor path, so it is outside this canonicalization step.

Constructor-produced URI values compare by canonical string identity. Direct URI("...") conversions remain available for compatibility, but they do not validate or canonicalize input. To keep native Go equality and map keys safe, decoded component accessors expose the same view as reparsing vscode-uri's URI.parse(input).toString() output for canonical values: original parse-history-only casing such as file://SERVER/... authorities or file:///C:/... drive letters is normalized in Authority, Path, and FsPath.

Performance notes and reproducible benchmark commands are in docs/perf.md. Conformance vectors are regenerated from the pinned Node dependency in tools/genvectors.

Documentation

Overview

Package uri implements canonical vscode-uri parsing and formatting for Go.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrMissingScheme reports that strict URI parsing found no scheme.
	ErrMissingScheme = errors.New("uri: scheme is missing")
	// ErrInvalidScheme reports that a URI scheme contains illegal characters.
	ErrInvalidScheme = errors.New("uri: scheme contains illegal characters")
	// ErrAuthorityPath reports that an authority URI path is not empty or slash-prefixed.
	ErrAuthorityPath = errors.New("uri: authority path must be empty or begin with slash")
	// ErrPathAuthority reports that a URI path without authority starts with two slashes.
	ErrPathAuthority = errors.New("uri: path without authority cannot begin with two slashes")
)

Functions

func Basename added in v1.0.0 

func Basename(u URI) string

Basename returns Node path.posix.basename of the URI path.

func Extname added in v1.0.0 

func Extname(u URI) string

Extname returns Node path.posix.extname of the URI path.

func FsPathFor added in v1.0.0 

func FsPathFor(u URI, platform Platform, keepDriveLetterCasing bool) string

FsPathFor returns the filesystem path for u using vscode-uri uriToFsPath semantics over u's canonical component view.

Because URI values do not retain parse-history-only casing, UNC authorities and drive letters use the canonical casing exposed by Authority and Path.

Types

type Change added in v1.0.0 

type Change struct {
	Scheme    *string
	Authority *string
	Path      *string
	Query     *string
	Fragment  *string
}

Change describes URI component replacements for With.

A nil field keeps the existing component. A non-nil pointer replaces that component; a pointer to the empty string clears it, except Scheme follows vscode-uri non-strict scheme fixing and becomes "file" when empty.

type Components added in v1.0.0 

type Components struct {
	Scheme    string
	Authority string
	Path      string
	Query     string
	Fragment  string
}

Components contains decoded URI components.

type Error added in v1.0.0 

type Error struct {
	Op    string
	Input string
	Err   error
}

Error describes a URI validation failure while preserving a typed cause.

func (*Error) Error added in v1.0.0 

func (e *Error) Error() string

Error returns a human-readable URI error string.

func (*Error) Unwrap added in v1.0.0 

func (e *Error) Unwrap() error

Unwrap returns the underlying sentinel error.

type Platform added in v1.0.0 

type Platform uint8

Platform selects filesystem path behavior for URI.file and uriToFsPath. 

const (
	// PlatformPOSIX uses slash-separated POSIX path semantics.
	PlatformPOSIX Platform = iota
	// PlatformWindows uses Windows slash conversion and drive behavior.
	PlatformWindows
)

type URI 

type URI string

URI is an immutable, comparable, canonical vscode-uri-compatible URI string.

Constructor functions store the canonical encoded representation, equivalent to vscode-uri's URI.parse(input).toString() result for representable Go input. Decoded component accessors are derived from that canonical representation, so parse-history-only casing such as uppercase drive letters or authority hosts is intentionally not retained.

func Dirname added in v1.0.0 

func Dirname(u URI) URI

Dirname returns a URI with its path replaced by Node path.posix.dirname.

func File 

func File(path string) URI

File constructs a file URI for path on the host platform.

func FileFor added in v1.0.0 

func FileFor(platform Platform, path string) URI

FileFor constructs a file URI for path using platform-specific vscode-uri semantics.

func From 

func From(c Components) (URI, error)

From constructs a URI from decoded components.

func JoinPath added in v1.0.0 

func JoinPath(u URI, segments ...string) (URI, error)

JoinPath joins URI path segments using Node path.posix semantics.

func MustParse added in v1.0.0 

func MustParse(s string) URI

MustParse parses s and panics if parsing fails.

func Parse 

func Parse(s string) (URI, error)

Parse parses s with vscode-uri non-strict semantics.

func ParseStrict added in v1.0.0 

func ParseStrict(s string) (URI, error)

ParseStrict parses s with vscode-uri strict semantics.

func ResolvePath added in v1.0.0 

func ResolvePath(u URI, segments ...string) (URI, error)

ResolvePath resolves URI path segments using Node path.posix semantics.

func (URI) Authority added in v1.0.0 

func (u URI) Authority() string

Authority returns the decoded canonical URI authority.

Authority host casing follows the canonical URI string and is therefore lowercased, matching URI.parse(input).toString() reparsed by vscode-uri rather than vscode-uri's original parse object.

func (URI) Components added in v1.0.0 

func (u URI) Components() Components

Components returns all decoded URI components.

func (URI) Fragment added in v1.0.0 

func (u URI) Fragment() string

Fragment returns the decoded URI fragment.

func (URI) FsPath added in v1.0.0 

func (u URI) FsPath() string

FsPath returns the filesystem path for u on the host platform.

func (URI) IsFile added in v1.0.0 

func (u URI) IsFile() bool

IsFile reports whether u has the exact file scheme.

func (URI) IsZero added in v1.0.0 

func (u URI) IsZero() bool

IsZero reports whether u is the zero URI value.

func (URI) MarshalText added in v1.0.0 

func (u URI) MarshalText() ([]byte, error)

MarshalText returns the canonical URI string as text.

func (URI) Path added in v1.0.0 

func (u URI) Path() string

Path returns the decoded canonical URI path.

Windows drive-letter casing follows the canonical URI string. For example, parsing file:///C:/x and reparsing the canonical string both expose /c:/x.

func (URI) Query added in v1.0.0 

func (u URI) Query() string

Query returns the decoded URI query.

func (URI) Scheme added in v1.0.0 

func (u URI) Scheme() string

Scheme returns the URI scheme.

func (URI) String added in v1.0.0 

func (u URI) String() string

String returns the canonical encoded URI string.

func (URI) StringNoEncoding added in v1.0.0 

func (u URI) StringNoEncoding() string

StringNoEncoding returns a URI string with vscode-uri toString(true) semantics.

func (*URI) UnmarshalText added in v1.0.0 

func (u *URI) UnmarshalText(text []byte) error

UnmarshalText parses text as a URI using non-strict vscode-uri semantics.

func (URI) With added in v1.0.0 

func (u URI) With(change Change) (URI, error)

With returns a new URI with selected decoded components changed.

Source Files

View all Source files

Directories

Path Synopsis
internal
gentables command
Command gentables generates URI byte classification tables.
 Command gentables generates URI byte classification tables.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.