path

Documentation

Overview

Package path contains utilities to work with ipfs paths.

Index

• Constants
• Variables
• func SegmentsToString(segments ...string) string
• func StringToSegments(str string) []string
• type ErrInvalidPath
  • func (e *ErrInvalidPath) Error() string
  • func (e *ErrInvalidPath) Is(err error) bool
  • func (e *ErrInvalidPath) Unwrap() error
• type ImmutablePath
  • func FromCid(cid cid.Cid) ImmutablePath
  • func NewImmutablePath(p Path) (ImmutablePath, error)
  • func (ip ImmutablePath) Mutable() bool
  • func (ip ImmutablePath) Namespace() string
  • func (ip ImmutablePath) RootCid() cid.Cid
  • func (ip ImmutablePath) Segments() []string
  • func (ip ImmutablePath) String() string
• type Path
  • func Join(p Path, segments ...string) (Path, error)
  • func NewPath(str string) (Path, error)
  • func NewPathFromSegments(segments ...string) (Path, error)

Constants

const (
	IPFSNamespace = "ipfs"
	IPNSNamespace = "ipns"
	IPLDNamespace = "ipld"
)

Variables

var (
	ErrExpectedImmutable      = errors.New("path was expected to be immutable")
	ErrInsufficientComponents = errors.New("path does not have enough components")
	ErrUnknownNamespace       = errors.New("unknown namespace")
)

Functions

func SegmentsToString

func SegmentsToString(segments ...string) string

SegmentsToString converts an array of segments into a string. The returned string will always be prefixed with a "/" if there are any segments. For example, if the given segments array is ["foo", "bar"], the returned value will be "/foo/bar". Given an empty array, an empty string is returned.

func StringToSegments

func StringToSegments(str string) []string

StringToSegments converts a string into an array of segments. This function follows the rules of [Path.Segments]: the path is first cleaned through gopath.Clean and no empty segments are returned.

Types

type ErrInvalidPath

type ErrInvalidPath struct {
	// contains filtered or unexported fields
}

func (*ErrInvalidPath) Error

func (e *ErrInvalidPath) Error() string

func (*ErrInvalidPath) Is

func (e *ErrInvalidPath) Is(err error) bool

func (*ErrInvalidPath) Unwrap

func (e *ErrInvalidPath) Unwrap() error

type ImmutablePath

type ImmutablePath struct {
	// contains filtered or unexported fields
}

ImmutablePath is a Path which is guaranteed to have an immutable [Namespace].

func FromCid

func FromCid(cid cid.Cid) ImmutablePath

FromCid returns a new "/ipfs" path with the provided CID.

func NewImmutablePath

func NewImmutablePath(p Path) (ImmutablePath, error)

func (ImmutablePath) Mutable

func (ip ImmutablePath) Mutable() bool

func (ImmutablePath) Namespace

func (ip ImmutablePath) Namespace() string

func (ImmutablePath) RootCid

func (ip ImmutablePath) RootCid() cid.Cid

func (ImmutablePath) Segments

func (ip ImmutablePath) Segments() []string

func (ImmutablePath) String

func (ip ImmutablePath) String() string

type Path

type Path interface {
	// String returns the path as a string.
	String() string

	// Namespace returns the first component of the path. For example, the namespace
	// of "/ipfs/bafy" is "ipfs".
	Namespace() string

	// Mutable returns false if the data under this path's namespace is guaranteed to not change.
	Mutable() bool

	// Segments returns the different elements of a path delimited by a forward
	// slash ("/"). The returned array must not contain any empty segments, and
	// must have a length of at least two: the first element must be the namespace,
	// and the second must be root.
	//
	// Examples:
	// 		- "/ipld/bafkqaaa" returns ["ipld", "bafkqaaa"]
	// 		- "/ipfs/bafkqaaa/a/b/" returns ["ipfs", "bafkqaaa", "a", "b"]
	// 		- "/ipns/dnslink.net" returns ["ipns", "dnslink.net"]
	Segments() []string
}

Path is a generic, valid, and well-formed path. A valid path is shaped as follows:

/{namespace}/{root}[/remaining/path]

Where:

1. Namespace is "ipfs", "ipld", or "ipns".
2. If namespace is "ipfs" or "ipld", "root" must be a valid cid.Cid.
3. If namespace is "ipns", "root" may be a [ipns.Name] or a DNSLink FQDN.

func Join

func Join(p Path, segments ...string) (Path, error)

Join joins a Path with certain segments and returns a new Path.

func NewPath

func NewPath(str string) (Path, error)

NewPath takes the given string and returns a well-formed and sanitized Path. The given string is cleaned through gopath.Clean, but preserving the final trailing slash. This function returns an error when the given string is not a valid content path.

func NewPathFromSegments

func NewPathFromSegments(segments ...string) (Path, error)

NewPathFromSegments creates a new Path from the provided segments. This function simply calls NewPath internally with the segments concatenated using a forward slash "/" as separator. Please see [Path.Segments] for more information about how segments must be structured.