FilePathsBase.jl

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

• T(str::String) - A string constructor
• FilePathsBase.ispathtype(::Type{T}, x::AbstractString) = true
• 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::P) where P <: AbstractPath) -> P
Path(fp::AbstractString) -> AbstractPath
Path(fp::P, segments::Tuple) -> P

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

NOTE: Path(::AbstractString) can also work for custom paths if ispathtype is defined for that type.

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.

Examples

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 fulll 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 any extensions.

Example

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

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".").

norm(fp::AbstractPath) -> AbstractPath

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

abs(fp::AbstractPath) -> AbstractPath

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

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

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

real(path::AbstractPath) -> AbstractPath

Canonicalize a path by expanding symbolic links and removing "." and ".." entries.

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.

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_constructor,
    test_registration,
    test_show,
    test_parse,
    test_convert,
    test_components,
    test_parents,
    test_join,
    test_basename,
    test_filename,
    test_extensions,
    test_isempty,
    test_norm,
    test_real,
    test_relative,
    test_abs,
    test_isdir,
    test_isfile,
    test_stat,
    test_size,
    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