Documentation
¶
Overview ¶
Package projpath contains utilities for working with paths within the Cirbo project filesystem structure.
Internally the system uses absolute filesystem paths in the canonical form for the host operating system. When dealing with CLI input from the user or output to the user we re-interpret paths as relative to the given working directory. When dealing with paths appearing in source files, we use a simpler alternative path representation that is portable across host operating systems and relative to the referring file.
Index ¶
- Constants
- type FilePath
- type PathConfig
- type Project
- func (p Project) FilePathForPackagePath(ppath string, from FilePath) FilePath
- func (p Project) FilePathForUI(path FilePath) string
- func (p Project) FilePathFromUI(path string) FilePath
- func (p Project) ListFiles(path FilePath) []FilePath
- func (p Project) ListModuleFiles(path FilePath) []FilePath
- func (p Project) ReadFile(path FilePath) ([]byte, error)
Constants ¶
const NoPath = FilePath("")
NoPath is a special FilePath value representing the absense of a path.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FilePath ¶
type FilePath string
FilePath is a specialization of string that represents an absolute path to a file or directory within the host filesystem.
FilePaths may be constructed only by functions in this package, and must be considered to be opaque values by all calling code. They must not be exposed to end-users via the CLI; instead, they must be re-interpreted into working-directory-relative files using functions in this package.
type PathConfig ¶
type PathConfig struct {
// WorkingDir is the directory that any relative filesystem paths will
// be resolved relative to. Should be provided as an absolute filesystem
// path.
//
// WorkingDir is primarily relevant for CLI use. If using Cirbo from
// a context where "working directory" isn't a relevant concept, leave
// this blank. If working in an IDE or text editor that has the concept
// of a "project root", set WorkingDir to the project root so that
// file paths can be given relative to the project root.
WorkingDir string
// SystemPkgDir is the directory where "system packages" (the built-in
// packages that ship with Cirbo) are installed. Should be provided either
// as an absolute filesystem path or a path relative to WorkingDir.
SystemPkgDir string
}
PathConfig specifies the root locations that will be used to resolve user-provided and source-provided paths within this project.
type Project ¶
type Project struct {
// contains filtered or unexported fields
}
func MockProject ¶
MockProject creates and returns a project that uses the given map as its source of files and directories.
A mock project uses a virtual filesystem based on forward-slash-separated paths, regardless of the host OS, so that tests don't have to make any special effort to be portable unless they are innately OS-specific.
This function is provided as a convenience for unit testing.
func NewProject ¶
func NewProject(config PathConfig) Project
NewProject constructs and returns a new Project object using the given path configuration.
The given working directory must either be blank or an absolute path, or else this function will panic. It will also panic if WorkingDir is blank but SystemPkgDir is a relative path.
func (Project) FilePathForPackagePath ¶
FilePathForPackagePath finds the FilePath of the directory containing the source files for the given package path when requested from the given FilePath.
A package paths is always relative to some other path, which is usually the source file that imports it. Package paths are a simplified, OS-agnostic path representation which is mapped on to the real filesystem by this method.
The result is NoPath if the given package path is invalid or if no suitable mapping to the underlying filesystem can be found.
func (Project) FilePathForUI ¶
FilePathForDisplay converts an canonical, opaque FilePath into a string suitable to show to an end-user to describe the given path. The result takes into account any working directory context to show a relative path where possible.
func (Project) FilePathFromUI ¶
FilePathFromUI interprets a file path string given in the CLI (or equivalent) into a canonical FilePath, or returns NoPath if the given path is invalid.
func (Project) ListFiles ¶
ListFiles returns a list of the files in the directory identified by an opaque FilePath.
/ Use FilePathFromUI to convert a user-specified path to a FilePath.
func (Project) ListModuleFiles ¶
ListModuleFiles is a convenience wrapper around ListFiles that filters the resulting list to include only Cirbo module files.
The result is sorted into lexicographical order so that module files used as package contents can be processed in a predictable order.
Source Files