Module

Pathy

Package
purescript-pathy
Repository
slamdata/purescript-pathy

Re-exports from Pathy.Name

#Name Source

newtype Name (n :: DirOrFile)

A type used for both directory and file names, indexed by DirOrFile.

Constructors

Instances

#splitName Source

splitName :: forall n. Name n -> { ext :: Maybe NonEmptyString, name :: NonEmptyString }

Splits Name in name and extension part.

splitName (Name ".foo")    == { name: ".foo", extension: Nothing }
splitName (Name "foo.")    == { name: "foo.", extension: Nothing }
splitName (Name "foo")     == { name: "foo",  extension: Nothing }
splitName (Name ".")       == { name: ".",    extension: Nothing }
splitName (Name "foo.baz") == { name: "foo",  extension: Just "baz" }

Note, in real code all strings from this examples would be NonEmptyString.

Also for any Name this property holds:

joinName <<< splitName = id

see joinName.

#joinName Source

joinName :: forall n. { ext :: Maybe NonEmptyString, name :: NonEmptyString } -> Name n

Joins name and extension part into one Name.

Also for any Name this property holds:

joinName <<< splitName = id

see splitName.

#extension Source

extension :: forall n. Name n -> Maybe NonEmptyString

Retrieves the extension of a name. also see splitName

extension (Name ".foo")    == Nothing
extension (Name "foo.")    == Nothing
extension (Name ".")       == Nothing
extension (Name "foo.baz") == Just "baz"

Note, in real code all strings from this examples would be NonEmptyString.

#alterExtension Source

alterExtension :: forall n. (Maybe NonEmptyString -> Maybe NonEmptyString) -> Name n -> Name n

Alters an extension of a name. This allows extensions to be added, removed, or modified. see splitName and joinName for how a Name is split into name and extention part and joined back into a Name.

Also for any Name this property holds:

alterExtension id = id

Re-exports from Pathy.Parser

#Parser Source

newtype Parser

Constructors

#posixParser Source

posixParser :: Parser

A parser for POSIX paths.

#parseRelFile Source

parseRelFile :: Parser -> String -> Maybe RelFile

Attempts to parse a relative file.

#parseRelDir Source

parseRelDir :: Parser -> String -> Maybe RelDir

Attempts to parse a relative directory.

#parsePath Source

parsePath :: forall z. Parser -> (RelDir -> z) -> (AbsDir -> z) -> (RelFile -> z) -> (AbsFile -> z) -> z -> String -> z

#parseAbsFile Source

parseAbsFile :: Parser -> String -> Maybe AbsFile

Attempts to parse an absolute file.

#parseAbsDir Source

parseAbsDir :: Parser -> String -> Maybe AbsDir

Attempts to parse an absolute directory.

Re-exports from Pathy.Path

#RelPath Source

type RelPath = AnyPath Rel

A type describing a relative file or directory path.

#RelFile Source

type RelFile = Path Rel File

A type describing a file whose location is given relative to some other, unspecified directory (referred to as the "current directory").

#RelDir Source

type RelDir = Path Rel Dir

A type describing a directory whose location is given relative to some other, unspecified directory (referred to as the "current directory").

#Path Source

data Path (a :: RelOrAbs) (b :: DirOrFile)

A type that describes a Path. All flavors of paths are described by this type, whether they are absolute or relative paths and whether they refer to files or directories.

  • The type parameter a describes whether the path is Rel or Abs.
  • The type parameter b describes whether the path is File or Dir.

To ensure type safety, there is no way for users to create a value of this type directly. Instead, helpers should be used, such as rootDir, currentDir, file, dir, (</>), and parsePath.

This ADT allows invalid paths (e.g. paths inside files), but there is no possible way for such paths to be constructed by user-land code.

Instances

#AnyPath Source

type AnyPath a = Either (Path a Dir) (Path a File)

A type describing a file or directory path.

#AnyFile Source

type AnyFile = Either AbsFile RelFile

A type describing a absolute or relative file path.

#AnyDir Source

type AnyDir = Either AbsDir RelDir

A type describing a absolute or relative directory path.

#AbsPath Source

type AbsPath = AnyPath Abs

A type describing an absolute file or directory path.

#AbsFile Source

type AbsFile = Path Abs File

A type describing a file whose location is absolutely specified.

#AbsDir Source

type AbsDir = Path Abs Dir

A type describing a directory whose location is absolutely specified.

#setExtension Source

setExtension :: forall b a. Path a b -> String -> Path a b

Sets the extension on the terminal segment of a path. If the path is rootDir / currentDir or a relative path that is ascending (../) this will have no effect.

file "image" <.> "png"

See splitName and alterExtension fore more examples.

#rootDir Source

rootDir :: Path Abs Dir

The root directory, which can be used to define absolutely-located resources.

#renameTraverse Source

renameTraverse :: forall b a f. Applicative f => (Name b -> f (Name b)) -> Path a b -> f (Path a b)

Attempts to rename the terminal segment of a path using a function that returns the result in some Applicative. If the path is rootDir / currentDir or a relative path that is ascending (../) this will have no effect.

#rename Source

rename :: forall b a. (Name b -> Name b) -> Path a b -> Path a b

Attempts to rename the terminal segment of a path. If the path is rootDir / currentDir or a relative path that is ascending (../) this will have no effect.

#relativeTo Source

relativeTo :: forall b. Path Abs b -> Path Abs Dir -> Path Rel b

Makes a path relative to a reference path. This function is best explaned using this property:

a == r </> a `relativeTo` r

#refine Source

refine :: forall b a. IsDirOrFile b => (Name File -> Name File) -> (Name Dir -> Name Dir) -> Path a b -> Path a b

Refines path segments but does not change anything else.

#peelFile Source

peelFile :: forall a. Path a File -> Tuple (Path a Dir) (Name File)

Peels off the last director and terminal file from a path. Unlike the general peel function this is guaranteed to return a result, as File paths are known to have a name.

#peel Source

peel :: forall b a. Path a b -> Maybe (Tuple (Path a Dir) (Name b))

Peels off the last directory and the terminal file or directory name from the path. Returns Nothing if the path is rootDir / currentDir or a relative path that is ascending (../)

#parentOf Source

parentOf :: forall a. IsRelOrAbs a => Path a Dir -> Path a Dir

Creates a path that points to the parent directory of the specified path.

Calling parentOf on rootDir will return rootDir.

#parentAppend Source

parentAppend :: forall b a. IsRelOrAbs a => Path a Dir -> Path Rel b -> Path a b

Ascends into the parent of the specified directory, then descends into the specified path.

rootDir </> dir "foo" <..> dir "bar" = rootDir </> dir "bar"

#name Source

name :: forall b a. IsRelOrAbs a => IsDirOrFile b => Path a b -> Maybe (Name b)

Retrieves the name of the terminal segment in a path. Returns Nothing if the path is rootDir / currentDir or some parentOf p.

#in' Source

in' :: forall a. Name a -> Path Rel a

Creates a path which points to a relative directory or file of the specified name. In most cases dir' or file' should be used instead, but it's still there in case the segment type is going to be determined based on some type variable.

p == maybe p (\(Tuple r n) -> r </> in' n) (peel p)

#foldPath Source

foldPath :: forall r b a. r -> (Path Rel Dir -> r) -> (Path a Dir -> Name b -> r) -> Path a b -> r

A fold over Paths. Since Path has private constructors, this allows for functions to be written over its constructors, similar to a total pattern match.

  • The first argument is the value to return for the currentDir/rootDir at the base of the path.
  • The second argument is a function for handling a step into the parent directory of the path it receives (eliminates parentOf).
  • The third argument is a function representing a file or directory within the directory of the path it receives (eliminates extendPath).

#fileName Source

fileName :: forall a. Path a File -> Name File

Retrieves the name of a file path. Unlike the general name function, this is guaranteed to return a result, as File paths are known to have a name.

#file' Source

file' :: Name File -> Path Rel File

Creates a path which points to a relative file of the specified name.

#file Source

file :: forall s. IsName s => SProxy s -> Path Rel File

Creates a path which points to a relative file of the specified name.

Instead of accepting a runtime value, this function accepts a type-level string via a proxy, to ensure the constructed name is not empty.

#extendPath Source

extendPath :: forall b a. Path a Dir -> Name b -> Path a b

Extends a path with a file or directory under the current path.

#dir' Source

dir' :: Name Dir -> Path Rel Dir

Creates a path which points to a relative directory of the specified name.

#dir Source

dir :: forall s. IsName s => SProxy s -> Path Rel Dir

Creates a path which points to a relative directory of the specified name.

Instead of accepting a runtime value, this function accepts a type-level string via a proxy, to ensure the constructed name is not empty.

#currentDir Source

currentDir :: Path Rel Dir

The "current directory", which can be used to define relatively-located resources.

#appendPath Source

appendPath :: forall b a. IsRelOrAbs a => Path a Dir -> Path Rel b -> Path a b

Given a directory path, appends a relative path to extend the original path.

#(</>) Source

Operator alias for Pathy.Path.appendPath (left-associative / precedence 6)

#(<.>) Source

Operator alias for Pathy.Path.setExtension (left-associative / precedence 6)

#(<..>) Source

Operator alias for Pathy.Path.parentAppend (left-associative / precedence 6)

Re-exports from Pathy.Phantom

#Rel Source

data Rel :: RelOrAbs

The phantom type of relative paths.

Instances

#File Source

data File :: DirOrFile

The phantom type of files.

Instances

#Dir Source

data Dir :: DirOrFile

The phantom type of directories.

Instances

#Abs Source

data Abs :: RelOrAbs

The phantom type of absolute paths.

Instances

#IsDirOrFile Source

class IsDirOrFile (b :: DirOrFile)  where

A class that enables writing operations that abstract over DirOrFile.

The provided onDirOrFile function folds over a value indexed by DirOrFile to produce a new result, passing proof/coercion functions to allow the inner functions to unify their return types if remapping.

Members

Instances

#IsRelOrAbs Source

class IsRelOrAbs (a :: RelOrAbs)  where

A class that enables writing operations that abstract over RelOrAbs.

The provided onRelOrAbs function folds over a value indexed by RelOrAbs to produce a new result, passing proof/coercion functions to allow the inner functions to unify their return types if remapping.

Members

  • onRelOrAbs :: forall r b f. ((f Rel b -> f a b) -> f Rel b -> r) -> ((f Abs b -> f a b) -> f Abs b -> r) -> f a b -> r

Instances

#foldRelOrAbs Source

foldRelOrAbs :: forall r b a f. IsRelOrAbs a => (f Rel b -> r) -> (f Abs b -> r) -> f a b -> r

Folds over a value that uses RelOrAbs to produce a new result.

#foldDirOrFile Source

foldDirOrFile :: forall r b f. IsDirOrFile b => (f Dir -> r) -> (f File -> r) -> f b -> r

Folds over a value that uses DirOrFile to produce a new result.

Re-exports from Pathy.Printer

#Printer Source

type Printer = { current :: NonEmptyString, escaper :: Escaper, root :: Maybe NonEmptyString -> String, sep :: NonEmptyString, up :: NonEmptyString }

A Printer defines options for printing paths.

  • root is a function used to construct the initial segment of paths.
  • current is a representation of the current directory.
  • up is a representation of going up to the parent directory.
  • sep is the string to separate path segments by.
  • escaper specified how to deal with printing reserved names and characters.

#Escaper Source

newtype Escaper

An Escaper encodes segments or characters which have reserved meaning within names in a path.

Constructors

Instances

#windowsPrinter Source

windowsPrinter :: Printer

A printer for Windows paths.

#unsafePrintPath Source

unsafePrintPath :: forall b a. IsRelOrAbs a => IsDirOrFile b => Printer -> SandboxedPath a b -> String

Prints a SandboxedPath into its canonical String representation, using the specified printer. This will print a relative path if b ~ Rel, which depending on how the resulting string is used, may be unsafe.

#printPath Source

printPath :: forall b a. IsRelOrAbs a => IsDirOrFile b => Printer -> SandboxedPath a b -> String

Prints a SandboxedPath into its canonical String representation, using the specified printer. The printed path will always be absolute, as this is the only way to ensure the path is safely referring to the intended location.

#posixPrinter Source

posixPrinter :: Printer

A printer for POSIX paths.

#debugPrintPath Source

debugPrintPath :: forall b a. Warn (Text "debugPrintPath usage") => IsRelOrAbs a => IsDirOrFile b => Printer -> Path a b -> String

Prints a path exactly according to its representation. This should only be used for debug purposes. Using this function will raise a warning at compile time as a reminder!

Re-exports from Pathy.Sandboxed

#SandboxedPath Source

data SandboxedPath a b

The type for paths that have been sandboxed.

Instances

#unsandbox Source

unsandbox :: forall b a. SandboxedPath a b -> Path a b

Extracts the original path from a SandboxedPath.

#sandboxRoot Source

sandboxRoot :: forall b a. SandboxedPath a b -> Path Abs Dir

Returns the location a SandboxedPath was sandboxed to.

#sandboxAny Source

sandboxAny :: forall b a. Path a b -> SandboxedPath a b

Sandboxes any path to /.

This should only be used for situations where a path is already constrained within a system so that access to / is safe - for instance, in URIs.

#sandbox Source

sandbox :: forall b a. IsRelOrAbs a => Path Abs Dir -> Path a b -> Maybe (SandboxedPath a b)

Attempts to sandbox a path relative to an absolute directory ("sandbox root"). If the Path a b escapes the sandbox root Nothing will be returned.