File

A simple file abstraction for Carp.

Installation

You can obtain this library like so:

(load "git@github.com:carpentry-org/file@0.1.1")

Usage

The main type involved in working with this library is File, naturally. All file operations depend on the file being opened.

; returns a Result containing a File you can write to
(File.open "example.txt")

; returns a Result containing a File you append to
(File.open-with "example.txt" "a")

If the file couldn’t be opened due to it not existing or file permission errors, a Result.Error with an error message is returned.

The file permissions follow the file modes in UNIX. The default is "a+", or writing/reading. Generally, files have a name, mode, and file property; you can read safely from them, but writing to them directly is discouraged.

Before you end your operations on the file, it is good practice to close the file again. In Carp, we do this using close.

(close f)

You can read from the file—or read-all, if you don’t care about length—, write to it, remove it, or rewind the file buffer.

(write &f "hi")
(rewind &f)
(IO.println &(read-all &f))

All of these will check whether the files are actually readable and/or writable before performing any IO actions and return a Result.Error if they can’t.

You can also ask about the modes of the file, using the functions readable?, writable?, or binary-mode?.

binary-mode?

defn

(Fn [(Ref File a)] Bool) 

                    (binary-mode? f)

checks whether a file is in binary mode by examining its mode.

close

defn

(Fn [File] ()) 

                    (close f)

closes a file and takes ownership.

contents

defn

(Fn [(Ref String a)] (Result (Array String) String)) 

                    (contents s)

walks a directory with the default walk mode (see also default-walk).

Returns a result containing either the contents of that directory or an error if the directory couldn’t be opened due to permission errors or if the user tried to open a nonexistant directory.

contents-with

defn

(Fn [(Ref String a), (Ref WalkOptions b)] (Result (Array String) String)) 

                    (contents-with s options)

walks a directory with a custom walk mode.

Returns a result containing either the directory contents or an error if the directory couldn’t be opened due to permission errors or if the user tried to open a nonexistant directory.

copy

instantiate

(Fn [(Ref File a)] File)

copies a File.

default-mode

def

(Ref String a)

is the default file mode, used by open.

Initially set to a+.

default-walk

def

WalkOptions

is the default options used by walk.

Initially set to recursive, not following links, and not matching directories or dotfiles.

map

defn

(Fn [(Ref String a), (Ref (Fn [(Ref String b)] c d) e)] (Result (Array c) String)) 

                    (map s callback)

walks a directory with the default walk mode (see also default-walk).

Returns a result containing either the results of the walker function as an array or an error if the directory couldn’t be opened due to permission errors or if the user tried to open a nonexistant directory.

map-with

defn

(Fn [(Ref String a), (Ref (Fn [(Ref String b)] c d) e), (Ref WalkOptions f)] (Result (Array c) String)) 

                    (map-with s callback options)

walks a directory with a custom walk mode.

Returns a result containing either the results of the walker function as an array or an error if the directory couldn’t be opened due to permission errors or if the user tried to open a nonexistant directory.

mode

instantiate

(Fn [(Ref File a)] (Ref String a))

gets the mode property of a File.

name

instantiate

(Fn [(Ref File a)] (Ref String a))

gets the name property of a File.

open

defn

(Fn [(Ref String a)] (Result File String)) 

                    (open name)

opens a file with the default file mode (see also default-mode).

Returns a result containing either a file, or an error if the file couldn’t be opened due to permission errors or if the user tried to read from a nonexistant file.

open-with

defn

(Fn [(Ref String a), (Ref String b)] (Result File String)) 

                    (open-with name mode)

opens a file with custom file mode.

Returns a result containing either a file, or an error if the file couldn’t be opened due to permission errors or if the user tried to read from a nonexistant file.

prn

instantiate

(Fn [(Ref File a)] String)

converts a File to a string.

read

defn

(Fn [(Ref File a), Int] (Result String String)) 

                    (read f len)

reads a string of length len from a file.

Returns a result containing the string on success and an error if the file is not readable.

read-all

defn

(Fn [(Ref File a)] (Result String String)) 

                    (read-all f)

reads the entire file content of a file.

Returns a result containing the string on success and an error if the file is not readable.

readable?

defn

(Fn [(Ref File a)] Bool) 

                    (readable? f)

checks whether a file is readable by examining its mode.

remove

defn

(Fn [(Ref File a)] ()) 

                    (remove f)

removes a file from the file system.

rewind

defn

(Fn [(Ref File a)] ()) 

                    (rewind f)

rewinds a file.

str

instantiate

(Fn [(Ref File a)] String)

converts a File to a string.

walk

defn

(Fn [(Ref String a), (Ref (Fn [(Ref String b)] () c) d)] (Result Int String)) 

                    (walk s callback)

walks a directory with the default walk mode (see also default-walk).

Returns a result containing either nothing, or an error if the directory couldn’t be opened due to permission errors or if the user tried to open a nonexistant directory.

walk-mode

defn

(Fn [Bool, Bool, Bool, Bool] WalkOptions) 

                    (walk-mode recursive? follow-links? dotfiles? match-dirs?)

constructs a mode for walk-with.

walk-with

defn

(Fn [(Ref String a), (Ref (Fn [(Ref String b)] () c) d), (Ref WalkOptions e)] (Result Int String)) 

                    (walk-with s callback options)

walks a directory with a custom walk mode.

Returns a result containing either nothing, or an error if the directory couldn’t be opened due to permission errors or if the user tried to open a nonexistant directory.

writable?

defn

(Fn [(Ref File a)] Bool) 

                    (writable? f)

checks whether a file is writable by examining its mode.

write

defn

(Fn [(Ref File a), (Ref String b)] (Result Int String)) 

                    (write f string)

writes a string string to a file.

Returns a result containing nothing on success and an error if the file is not writable.