More docs.0.2.0

1 files changed, 84 insertions, 4 deletions

diff --git a/README.md b/README.md
index 7db13ad..9bd9558 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ Read binary data from `path`.
 Return the binary data as a bytevector.
 
 ```scheme
-(f:read-bytes "path/to/binary/data")
+(f:read-bytes "path/to/file")
 ```
 
 ### `read-text path`
@@ -70,7 +70,7 @@ Read text from `path`.
 Return the text as a string.
 
 ```scheme
-(f:read-text "path/to/file.txt")
+(f:read-text "path/to/file")
 ```
 
 ### `read-line path`
@@ -79,7 +79,7 @@ Read a single line of text from `path`.
 Return the line as a string. It doesn't contain a newline character.
 
 ```scheme
-(f:read-line "path/to/file.txt")
+(f:read-line "path/to/file")
 ```
 
 ### `read-lines path`
@@ -88,26 +88,99 @@ Read all the lines of a file.
 Returns the lines as a list of strings.
 
 ```scheme
-(f:read-lines "path/to/file.txt")
+(f:read-lines "path/to/file")
 ```
 
 ### `write-bytes path bytes #:key (append #f)`
+Write a bytevector to a file. Overwrite the contents if `#:append` is
+`#f`, otherwise append at the end.
+
+```scheme
+(f:write-bytes "path/to/file" #vu8(1 2 3) #:append #t)
+```
 
 ### `write-text path text #:key (append #f)`
+Write a string to a file. Overwrite the contents if `#:append` is
+`#f`, otherwise append at the end.
+
+```scheme
+(f:write-text "path/to/file" "I'm a string" #:append #t)
+```
 
 ### `write-line path text #:key (append #f)`
+Write string to a file and put a newline after it. Overwrite the
+contents if `#:append` is `#f`, otherwise append at the end.
+
+```scheme
+(f:write-text "path/to/file" "I'm a string" #:append #t)
+```
 
 ### `write-lines path lines #:key (append #f)`
+Write multiple lines to a file. The `lines` parameter is a list of
+strings. Overwrite the contents if `#:append` is `#f`, otherwise append at
+the end.
+
+```scheme
+(f:write-lines "path/to/file" '("first line" "second line"))
+```
 
 ### `mkdir path #:key (parents #f)`
+Create a new directory. Use `#:parents #t` to also create parent
+directories if they don't already exist.
+
+```scheme
+(f:mkdir "f1/f2/f3" #:parents #t)
+```
 
 ### `ls #:optional (dir (getcwd)) #:key (hidden #f)`
+List the files in the directory `dir`. If `dir` is not specified, it
+default to the current directory. To also display hidden files, use
+`#:hidden #t`. Displaying hidden files omits `.` (current dir) and
+`..` (parent dir).
+
+```scheme
+(f:ls)             ;; list the files in the current directory
+(f:ls "other-dir") ;; list the files in other-dir
+(f:ls #:hidden #t) ;; list all the files in the current directory
+```
 
 ### `traverse path f #:key (files-only #f)`
+Walk a directory tree, applying the function `f` to every file and
+directory you meet. If you want to apply `f` only to files, use
+`#:files-only #t`.
+
+```scheme
+;; Display every file and directory in your home dir
+(f:traverse (string-append "/home/" (getlogin)) 
+            (lambda (x)
+              (display x)
+              (newline)))
+```
 
 ### `delete path #:optional (recursive #f)`
+Delete the file or directory specified by `path`. If `path` is a
+directory and contains stuff, set `recursive` to `#t` to delete it and
+all its contents.
+
+```scheme
+;; Delete all your porn
+(f:delete (string-append "/home/" (getlogin) "/homework") #t)
+```
 
 ### `copy src dest #:optional (recursive #f)`
+Copy something from `src` to `dest`.
+
+```scheme
+(f:copy "music" "media/audio" #t)
+```
+
+### `move oldname newname`
+Move `oldname` to `newname`. (The parameter naming is different from
+`copy` because this is just an alias for `rename-file`.)
+
+```scheme
+(f:move "media/audio" "media/songs")
+```
 
 ## Contributing
 
@@ -115,6 +188,13 @@ Send suggestions and patches with what you think is useful for this
 library to [my public mailing
 list](https://lists.sr.ht/~brown121407/ml).
 
+### What needs improving?
+We currently need some path manipulation code (splitting, joining,
+extracting segments etc.). We don't want to use the
+[file-names](https://gitlab.com/brandoninvergo/guile-file-names)
+library, because we want just functions on strings, not complex
+objects, but it could prove useful as inspiration.
+
 ## License
 
 f.scm is licensed under the GNU GPLv3. See [COPYING](./COPYING).