API

API

To compare and contrast FilePathsBase with Base.Filesystem we provide tables for common operations. Use ? at the REPL to get the documentation and arguments as they may be different than the base implementations.

Operations

A table of common operations with Filesystem and FilePathsBase.

FilesystemFilePathsBase.jl
"/home/user/docs"p"/home/user/docs"
N/APath()
pwd()pwd(SystemPath) or cwd()
homedir()homedir(SystemPath) or home()
cd()cd()
joinpath()/
basename()basename()
N/Ahasparent, parents, parent
splitextsplitext
N/Afilename
N/Aextension
N/Aextensions
ispathexists
realpathcanonicalize
normpathnormalize
abspathabsolute
relpathrelative
statstat
lstatlstat
filemodemode
filesizefilesize
mtimemodified
ctimecreated
isdirisdir
isfileisfile
islinkislink
issocketissocket
isfifoisfifo
ischardevischardev
isblockdevisblockdev
isexecutable (deprecated)isexecutable
iswritable (deprecated)iswritable
isreadable (deprecated)isreadable
ismountismount
isabspathisabsolute
splitdrive()[1]drive
N/Aroot (property)
split(p, "/")segments (property)
expanduserexpanduser
mkdirmkdir
mkpathN/A (use mkdir)
symlinksymlink
cpcp
mvmv
downloaddownload
readdirreaddir
N/Areadpath
walkpathwalkpath
rmrm
touchtouch
tempname()tempname(::Type{<:AbstractPath}) (or tmpname)
tempdir()tempdir(::Type{<:AbstractPath}) (or tmpdir)
mktemp()mktemp(::Type{<:AbstractPath}) (or mktmp)
mktempdir()mktempdir(::Type{<:AbstractPath}) (or mktmpdir)
chmodchmod (recursive unix-only)
chown (unix only)chown (unix only)
readread
writewrite
@DIR@PATH
@FILE@FILEPATH

Aliases

A slightly reduced list of operations/aliases that will work with both strings and path types. The Filesystem and FilePathsBase columns indicate what type will be returned from each each library. As you'd expect, most return types match the input argument(s).

Function NameFilesystemFilePathsBase
cdAbstractStringAbstractPath
joinpathAbstractStringAbstractPath
basenameAbstractStringAbstractString
splitext(AbstractString, AbstractString)(AbstractPath, AbstractString)
ispathBoolBool
realpathAbstractStringAbstractPath
normpathAbstractStringAbstractPath
abspathAbstractStringAbstractPath
relpathAbstractStringAbstractPath
statStatStructFilePathsBase.Status
lstatStatStructFilePathsBase.Status
filemodeUInt64FilePathsBase.Mode
filesizeInt64Int64
mtimeFloat64Float64
ctimeFloat64Float64
isdirBoolBool
isfileBoolBool
islinkBoolBool
issocketBoolBool
isfifoBoolBool
ischardevBoolBool
isblockdevBoolBool
ismountBoolBool
isabspathBoolBool
expanduserAbstractStringAbstractPath
mkdirAbstractStringAbstractPath
mkpathAbstractStringAbstractPath
symlinkNothingNothing
cpAbstractStringAbstractPath
mvAbstractStringAbstractPath
downloadAbstractStringAbstractPath
readdirAbstractStringAbstractString
rmNothingNothing
touchAbstractStringAbstractPath
chmodAbstractStringAbstractPath
chownAbstractStringAbstractPath
read(fp, T)TT
writeInt64Int64
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
source
FilePathsBase.PathFunction.
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)

source
SystemPath

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

source
PosixPath()
PosixPath(str)

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

source
WindowsPath()
WindowsPath(str)

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

source
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
source
@p_str -> Path

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

source
@__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>.

source
@__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>.

source
@LOCAL(filespec)

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

source
FilePathsBase.cwdFunction.
  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"
source
Missing docstring.

Missing docstring for FilePathsBase.home. Check Documenter's build log for details.

hasparent(fp::AbstractPath) -> Bool

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

source
FilePathsBase.parentsFunction.
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"."
source
Base.parentFunction.
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"."
source
Base.:*Method.

*(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"
source
FilePathsBase.:/Method.

/(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"
source
FilePathsBase.joinMethod.
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"
source
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"
source
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"
source
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"
source
Base.isemptyMethod.
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".").

source
normalize(fp::AbstractPath) -> AbstractPath

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

source
absolute(fp::AbstractPath) -> AbstractPath

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

source
isabsolute(fp::AbstractPath) -> Bool

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

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

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

source
Missing docstring.

Missing docstring for Base.readlink(::AbstractPath). Check Documenter's build log for details.

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

source
FilePathsBase.modeMethod.
mode(fp::AbstractPath) -> Mode

Returns the Mode for the specified path.

Example

julia> mode(p"src/FilePathsBase.jl")
-rw-r--r--
source
modified(fp::AbstractPath) -> DateTime

Returns the last modified date for the path.

Example

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

Returns the creation date for the path.

Example

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

Returns whether the path is executable for the current user.

source
Base.iswritableMethod.
iswritable(fp::AbstractPath) -> Bool

Returns whether the path is writable for the current user.

source
Base.isreadableMethod.
isreadable(fp::SystemPath) -> Bool

Returns whether the path is readable for the current user.

source
Base.Filesystem.cpMethod.
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.

source
Base.Filesystem.mvMethod.
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.

source
Base.downloadMethod.
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

source
readpath(fp::P) where {P <: AbstractPath} -> Vector{P}
source
walkpath(fp::AbstractPath; topdown=true, follow_symlinks=false, onerror=throw)

Performs a depth first search through the directory structure

source
Base.openMethod.

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.

source
Missing docstring.

Missing docstring for FilePathsBase.tmpname. Check Documenter's build log for details.

Missing docstring.

Missing docstring for FilePathsBase.tmpdir. Check Documenter's build log for details.

Missing docstring.

Missing docstring for FilePathsBase.mktmp. Check Documenter's build log for details.

Missing docstring.

Missing docstring for FilePathsBase.mktmpdir. Check Documenter's build log for details.

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

Change the user and group of the fp.

source
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--
source
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)
source
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
source