API

AbstractPath

Defines an abstract filesystem path.

Properties

• segments::Tuple{Vararg{String}} - path segments (required)
• root::String - path root (defaults to "/")
• drive::String - path drive (defaults to "")
• separator::String - path separator (defaults to "/")

Required Methods

• tryparse(::Type{T}, str::String) - For parsing string representations of your path
• read(path::T)
• write(path::T, data)
• exists(path::T - whether the path exists
• stat(path::T) - File status describing permissions, size and creation/modified times
• mkdir(path::T; kwargs...) - Create a new directory
• rm(path::T; kwags...) - Remove a file or directory
• readdir(path::T) - Scan all files and directories at a specific path level

Path() -> SystemPath
Path(fp::Tuple) -> SystemPath
Path(fp::AbstractString) -> AbstractPath
Path(fp::P; overrides...) -> P

Responsible for creating the appropriate platform specific path (e.g., PosixPath and WindowsPath` for Unix and Windows systems respectively)

SystemPath

A union of PosixPath and WindowsPath which is used for writing methods that wrap base functionality.

PosixPath()
PosixPath(str)

Represents any posix path (e.g., /home/user/docs)

WindowsPath()
WindowsPath(str)

Represents a windows path (e.g., C:\User\Documents)

Mode(m::UInt8)
Mode(;user::UInt8=0o0, group::UInt8=0o0, other::UInt8=0o0)
Mode(mode::UInt8, usr_grps::Symbol...)
Mode(str)

Provides an abstraction for working with posix file permissions. A lot of the low level permissions code for this type was below and the corresponding constants have been translated from cpython's Lib/stat.py.

Example

julia> Mode("-rwxr-x--x")
-rwxr-x--x

@p_str -> Path

Constructs a Path (platform specific subtype of AbstractPath), such as p"~/.juliarc.jl".

@__PATH__ -> SystemPath

@PATH expands to a path with the directory part of the absolute path of the file containing the macro. Returns an empty Path if run from a REPL or if evaluated by julia -e <expr>.

@__FILEPATH__ -> SystemPath

@FILEPATH expands to a path with the absolute file path of the file containing the macro. Returns an empty Path if run from a REPL or if evaluated by julia -e <expr>.

@LOCAL(filespec)

Construct an absolute path to filespec relative to the source file containing the macro call.

  cwd() -> SystemPath

Get the current working directory.

Examples

julia> cwd()
p"/home/JuliaUser"

julia> cd(p"/home/JuliaUser/Projects/julia")

julia> cwd()
p"/home/JuliaUser/Projects/julia"

hasparent(fp::AbstractPath) -> Bool

Returns whether there is a parent directory component to the supplied path.

parents{T<:AbstractPath}(fp::T) -> Array{T}

Return all parents of the path. If no parent exists then either "/" or "." will be returned depending on whether the path is absolute.

Example

julia> parents(p"~/.julia/v0.6/REQUIRE")
3-element Array{FilePathsBase.PosixPath,1}:
 p"~"
 p"~/.julia"
 p"~/.julia/v0.6"

julia> parents(p"/etc")
1-element Array{PosixPath,1}:
 p"/"

julia> parents(p"etc")
1-element Array{PosixPath,1}:
 p"."

julia> parents(p".")
1-element Array{PosixPath,1}:
 p"."

parent{T<:AbstractPath}(fp::T) -> T

Returns the parent of the supplied path. If no parent exists then either "/" or "." will be returned depending on whether the path is absolute.

Example

julia> parent(p"~/.julia/v0.6/REQUIRE")
p"~/.julia/v0.6"

julia> parent(p"/etc")
p"/"

julia> parent(p"etc")
p"."

julia> parent(p".")
p"."

*(a::T, b::Union{T, AbstractString, AbstractChar}...) where {T <: AbstractPath} -> T

Concatenate paths, strings and/or characters, producing a new path. This is equivalent to concatenating the string representations of paths and other strings and then constructing a new path.

Example

julia> p"foo" * "bar"
p"foobar"

/(a::AbstractPath, b::Union{AbstractPath, AbstractString}...) -> AbstractPath

Join the path components into a new full path, equivalent to calling joinpath.

Example

julia> p"foo" / "bar"
p"foo/bar"

julia> p"foo" / "bar" / "baz"
p"foo/bar/baz"

join(root::AbstractPath, pieces::Union{AbstractPath, AbstractString}...) -> AbstractPath

Joins path components into a full path.

Example

julia> join(p"~/.julia/v0.6", "REQUIRE")
p"~/.julia/v0.6/REQUIRE"

filename(fp::AbstractPath) -> AbstractString

Extracts the basename without the extension.

Example

julia> filename(p"~/repos/FilePathsBase.jl/src/FilePathsBase.jl")
"FilePathsBase"

julia> filename(p"~/Downloads/julia-1.4.0-linux-x86_64.tar.gz")
"julia-1.4.0-linux-x86_64.tar"

extension(fp::AbstractPath) -> AbstractString

Extracts the last extension from a filename if there any, otherwise it returns an empty string.

Example

julia> extension(p"~/repos/FilePathsBase.jl/src/FilePathsBase.jl")
"jl"

extensions(fp::AbstractPath) -> AbstractString

Extracts all extensions from a filename if there any, otherwise it returns an empty string.

Example

julia> extensions(p"~/repos/FilePathsBase.jl/src/FilePathsBase.jl.bak")
2-element Array{SubString{String},1}:
 "jl"
 "bak"

isempty(fp::AbstractPath) -> Bool

Returns whether or not a path is empty.

NOTE: Empty paths are usually only created by Path(), as p"" and Path("") will default to using the current directory (or p".").

normalize(fp::AbstractPath) -> AbstractPath

normalizes a path by removing "." and ".." entries.

absolute(fp::AbstractPath) -> AbstractPath

Creates an absolute path by adding the current working directory if necessary.

isabsolute(fp::AbstractPath) -> Bool

Returns true if fp.root is not empty, indicating that it is an absolute path.

relative{T<:AbstractPath}(fp::T, start::T=cwd())

Creates a relative path from either the current directory or an arbitrary start directory.

canonicalize(path::AbstractPath) -> AbstractPath

Canonicalize a path by making it absolute, . or .. segments and resolving any symlinks if applicable.

WARNING: Fallback behaviour ignores symlinks and should be extended for paths where symlinks are permitted (e.g., SystemPaths).

mode(fp::AbstractPath) -> Mode

Returns the Mode for the specified path.

Example

julia> mode(p"src/FilePathsBase.jl")
-rw-r--r--

modified(fp::AbstractPath) -> DateTime

Returns the last modified date for the path.

Example

julia> modified(p"src/FilePathsBase.jl")
2017-06-20T04:01:09

created(fp::AbstractPath) -> DateTime

Returns the creation date for the path.

Example

julia> created(p"src/FilePathsBase.jl")
2017-06-20T04:01:09

isexecutable(fp::SystemPath) -> Bool

Returns whether the path is executable for the current user.

iswritable(fp::AbstractPath) -> Bool

Returns whether the path is writable for the current user.

isreadable(fp::SystemPath) -> Bool

Returns whether the path is readable for the current user.

cp(src::AbstractPath, dst::AbstractPath; force=false, follow_symlinks=false)

Copy the file or directory from src to dst. An existing dst will only be overwritten if force=true. If the path types support symlinks then follow_symlinks=true will copy the contents of the symlink to the destination.

mv(src::AbstractPath, dst::AbstractPath; force=false)

Move the file or director from src to dst. An exist dst will only be overwritten if force=true.

download(url::Union{AbstractString, AbstractPath}, localfile::AbstractPath)

Download a file from the remote url and save it to the localfile path.

NOTE: Not downloading into a localfile directory matches the base Julia behaviour. https://github.com/rofinn/FilePathsBase.jl/issues/48

readpath(fp::P) where {P <: AbstractPath} -> Vector{P}

walkpath(fp::AbstractPath; topdown=true, follow_symlinks=false, onerror=throw)

Performs a depth first search through the directory structure

open(filename::AbstractPath; keywords...) -> FileBuffer open(filename::AbstractPath, mode="r) -> FileBuffer

Return a default FileBuffer for open calls to paths which only support read and write methods. See base open docs for details on valid keywords.

chown(fp::SystemPath, user::AbstractString, group::AbstractString; recursive=false)

Change the user and group of the fp.

chmod(fp::SystemPath, mode::Mode; recursive=false)
chmod(fp::SystemPath, mode::Integer; recursive=false)
chmod(fp::SystemPath, user::UIn8=0o0, group::UInt8=0o0, other::UInt8=0o0; recursive=false)
chmod(fp::SystemPath, symbolic_mode::AbstractString; recursive=false)

Provides various methods for changing the mode of a fp.

Examples

julia> touch(p"newfile")
Base.Filesystem.File(false, RawFD(-1))

julia> mode(p"newfile")
-rw-r--r--

julia> chmod(p"newfile", 0o755)

julia> mode(p"newfile")
-rwxr-xr-x

julia> chmod(p"newfile", "-x")

julia> mode(p"newfile")
-rw-r--r--

julia> chmod(p"newfile", user=(READ+WRITE+EXEC), group=(READ+EXEC), other=READ)

julia> mode(p"newfile")
-rwxr-xr--

julia> chmod(p"newfile", mode(p"src/FilePathsBase.jl"))

julia> mode(p"newfile")
-rw-r--r--

TestPaths

This module is intended to be used for testing new path types to ensure that they are adhering to the AbstractPath API.

Example

# Create a PathSet
ps = PathSet(; symlink=true)

# Select the subset of tests to run
# Inspect TestPaths.TESTALL to see full list
testsets = [
    test_registration,
    test_show,
    test_cmd,
    test_parse,
    test_convert,
    test_components,
    test_parents,
    test_join,
    test_splitext,
    test_basename,
    test_filename,
    test_extensions,
    test_isempty,
    test_normalize,
    test_canonicalize,
    test_relative,
    test_absolute,
    test_isdir,
    test_isfile,
    test_stat,
    test_filesize,
    test_modified,
    test_created,
    test_cd,
    test_readpath,
    test_walkpath,
    test_read,
    test_write,
    test_mkdir,
    test_cp,
    test_mv,
    test_sync,
    test_symlink,
    test_touch,
    test_tmpname,
    test_tmpdir,
    test_mktmp,
    test_mktmpdir,
    test_download,
]

# Run all the tests
test(ps, testsets)

PathSet(root::AbstractPath=tmpdir(); symlink=false)

Constructs a common test path hierarchy to running shared API tests.

Hierarchy:

root
|-- foo
|   |-- baz.txt
|-- bar
|   |-- qux
|       |-- quux.tar.gz
|-- fred
|   |-- plugh