File

A simple file abstraction for Carp.

Installation

You can obtain this library like so:

(load "git@github.com:carpentry-org/file@0.2.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?.

ByteReader

module

Module

ByteWriter

module

Module

StringReader

module

Module

StringWriter

module

Module

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.

delete

instantiate

(Fn [File] ())

deletes a File. Should usually not be called manually.

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 b String)) 

                        (read f len)

Reads len values from a file.

This function is generic in its return argument. You can provide a custom reader implementation by implementing the read-from-file interface.

The surrounding context typically determine's the return type.if no implementation of read-from-file exists for the type, you'll need to provide one. You can also use the to specify the return type. For example (to read the first 3 bytes of the file):

(match (File.open-with "test-file.txt" "r")
  (Result.Success f) (the (Result (Array Byte) String) (File.read &f 3))
  (Result.Error x) (Result.Error x))))

read-all

defn

(Fn [(Ref File a)] (Result b 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), b] (Result Int String)) 

                        (write f obj)

Writes a value to a file.

This function is generic in its input. You can provide a custom reader implementation by implementing the write-to-file interface