Updated the getting started section.

Author: rofinn

README.md

@@ -15,76 +15,118 @@ julia> Pkg.add("FilePathsBase")
 ```
 
 ## Getting Started
-```julia
-julia> using FilePathsBase; using FilePathsBase: /
-```
 
-The first important difference about working with paths in FilePathsBase.jl is that path
-segments are represented as an immutable tuple of strings.
+Here are some common operations that you may want to perform with file paths.
 
-Path creation:
 ```julia
-julia> Path("~/repos/FilePathsBase.jl/")
-p"~/repos/FilePathsBase.jl/"
-```
-or
-```julia
-julia> p"~/repos/FilePathsBase.jl/"
-p"~/repos/FilePathsBase.jl/"
-```
+#=
+NOTE: We're loading our `/` operator for path concatenation into the currect scope, but non-path division operations will still fallback to the base behaviour.
+=#
+julia> using FilePathsBase; using FilePathsBase: /
 
-Human readable file status info:
-```julia
-julia> stat(p"README.md")
+julia> cwd()
+p"/Users/rory/repos/FilePathsBase.jl"
+
+julia> walkpath(cwd() / "docs") |> collect
+23-element Array{Any,1}:
+ p"/Users/rory/repos/FilePathsBase.jl/docs/.DS_Store"
+ p"/Users/rory/repos/FilePathsBase.jl/docs/Manifest.toml"
+ p"/Users/rory/repos/FilePathsBase.jl/docs/Project.toml"
+ p"/Users/rory/repos/FilePathsBase.jl/docs/build"
+ p"/Users/rory/repos/FilePathsBase.jl/docs/build/api.html"
+ p"/Users/rory/repos/FilePathsBase.jl/docs/build/assets"
+ p"/Users/rory/repos/FilePathsBase.jl/docs/build/assets/arrow.svg"
+ p"/Users/rory/repos/FilePathsBase.jl/docs/build/assets/documenter.css"
+ ...
+
+julia> stat(p"docs/src/index.md")
 Status(
-  device = 16777220,
-  inode = 48428965,
+  device = 16777223,
+  inode = 32240108,
   mode = -rw-r--r--,
   nlink = 1,
-  uid = 501,
-  gid = 20,
+  uid = 501 (rory),
+  gid = 20 (staff),
   rdev = 0,
-  size = 1880 (1.8K),
+  size = 2028 (2.0K),
   blksize = 4096 (4.0K),
   blocks = 8,
-  mtime = 2016-02-16T00:49:27,
-  ctime = 2016-02-16T00:49:27,
+  mtime = 2020-04-20T17:20:38.612,
+  ctime = 2020-04-20T17:20:38.612,
 )
-```
 
-Working with permissions:
-```julia
-julia> m = mode(p"README.md")
--rw-r--r--
+julia> relative(p"docs/src/index.md", p"src/")
+p"../docs/src/index.md"
 
-julia> m - readable(:ALL)
---w-------
+julia> normalize(p"src/../docs/src/index.md")
+p"docs/src/index.md"
 
-julia> m + executable(:ALL)
--rwxr-xr-x
+julia> absolute(p"docs/src/index.md")
+p"/Users/rory/repos/FilePathsBase.jl/docs/src/index.md"
 
-julia> chmod(p"README.md", "+x")
+julia> islink(p"docs/src/index.md")
+true
 
-julia> mode(p"README.md")
--rwxr-xr-x
+julia> canonicalize(p"docs/src/index.md")
+p"/Users/rory/repos/FilePathsBase.jl/README.md"
 
-julia> chmod(p"README.md", m)
+julia> parents(p"./docs/src")
+2-element Array{PosixPath,1}:
+ p"."
+ p"./docs"
 
-julia> m = mode(p"README.md")
--rw-r--r--
+julia> parents(absolute(p"./docs/src"))
+6-element Array{PosixPath,1}:
+ p"/"
+ p"/Users"
+ p"/Users/rory"
+ p"/Users/rory/repos"
+ p"/Users/rory/repos/FilePathsBase.jl"
+ p"/Users/rory/repos/FilePathsBase.jl/docs"
 
-julia> chmod(p"README.md", user=(READ+WRITE+EXEC), group=(READ+WRITE), other=READ)
+julia> absolute(p"./docs/src")[1:end-1]
+("Users", "rory", "repos", "FilePathsBase.jl", "docs")
 
-julia> mode(p"README.md")
--rwxrw-r--
+julia> tmpfp = mktempdir(SystemPath)
+p"/var/folders/vz/zx_0gsp9291dhv049t_nx37r0000gn/T/jl_1GCBFT"
 
-```
+julia> sync(p"/Users/rory/repos/FilePathsBase.jl/docs", tmpfp / "docs")
+p"/var/folders/vz/zx_0gsp9291dhv049t_nx37r0000gn/T/jl_1GCBFT/docs"
 
-Reading and writing directly to file paths:
-```julia
-julia> write(p"testfile", "foobar")
-6
+julia> exists(tmpfp / "docs" / "make.jl")
+true
+
+julia> m = mode(tmpfp / "docs" / "make.jl")
+Mode("-rw-r--r--")
+
+julia> m - readable(:ALL)
+Mode("--w-------")
+
+julia> m + executable(:ALL)
+Mode("-rwxr-xr-x")
+
+julia> chmod(tmpfp / "docs" / "make.jl", "+x")
+"/var/folders/vz/zx_0gsp9291dhv049t_nx37r0000gn/T/jl_1GCBFT/docs/make.jl"
+
+julia> mode(tmpfp / "docs" / "make.jl")
+Mode("-rwxr-xr-x")
+
+# Count LOC
+julia> mapreduce(+, walkpath(cwd() / "src")) do x
+           extension(x) == "jl" ? count("\n", read(x, String)) : 0
+       end
+3020
+
+# Concatenate multiple files.
+julia> str = mapreduce(*, walkpath(tmpfp / "docs" / "src")) do x
+           read(x, String)
+       end
+"# API\n\nAll the standard methods for working with paths in base julia exist in the FilePathsBase.jl. The following describes the rough mapping of method names. Use `?` at the REPL to get the documentation and arguments as they may be different than the base implementations.\n\n..."
+
+# Could also write the result to a file with `write(newfile, str)`)
+
+julia> rm(tmpfp; recursive=true)
 
-julia> read(p"testfile")
-"foobar"
+julia> exists(tmpfp)
+false
 ```

docs/.DS_Store

@@ -1,5 +1,11 @@
 using Documenter, FilePathsBase, FilePathsBase.TestPaths
 
+```@meta
+DocTestSetup = quote
+    using FilePathsBase; using FilePathsBase: /, join;
+end
+```
+
 makedocs(
     modules=[FilePathsBase],
     format=Documenter.HTML(

docs/make.jl

@@ -1,4 +1,4 @@
-# Background
+# [Design](@id design_header)
 
 FilePaths.jl and FilePathsBase.jl have gone through several design iterations over the years.
 To help get potential contributors up-to-speed, we'll cover several background points and design choices.

docs/src/design.md

@@ -18,7 +18,7 @@ Some cases where the path type distinction is useful include:
 - Path specific operations (e.g., `join`, `/`, `==`)
 - Dispatch on paths vs strings (e.g., `project(name::String) = project(DEFAULT_ROOT / name)`)
 
-See [background section] for more details on the advantages of path types over strings.
+See [design section](@ref design_header) for more details on the advantages of path types over strings.
 
 **Q. Why is `AbstractPath` not a subtype of `AbstractString`?
 

docs/src/faq.md

@@ -272,7 +272,7 @@ p"foo/bar/baz"
 Joins path components into a full path.
 
 # Example
-```jldoctest
+```jldoctest; setup = :(using FilePathsBase: /, join)
 julia> join(p"~/.julia/v0.6", "REQUIRE")
 p"~/.julia/v0.6/REQUIRE"
 ```