Jesse Laprade

ffs

(Fennel file system utilities)

A collection of file system utilities for Fennel.

Table of contents

Disclaimer

The functions in this library were originally written to work with my wg project. Since then, I have tried to improve the functions by putting them into their own library, and fixing them up.

Please use this library with caution. I’m a hobbyist programmer who isn’t the best at programming, which means I may have deadly bugs that could result in data loss.

Reasoning

Document conventions

Requirements

Building from source

  1. Run make

Adding ffs to your project

  1. Download the ffs.fnl file.

  2. Place the ffs.fnl file into your project directory.

  3. Add the following line to the top of your project file:

    (local ffs (require :ffs))

Functions reference

This section describes the behaviour of all functions found in ffs, their parameters, and return values.

Shell functions

This section describes shell-related functions.

shell->sequence

Takes a shell command and returns the output as a sequence.

(ffs.shell->sequence command) -> sequence

Example: How to print a list of paths in the current directory:

(each [_ v (ffs.shell->sequence "ls")]
  (print v))

Path functions

This section describes path-related functions.

path-copy

Takes a source path and copies it to the destination path.

Nothing is returned.

(ffs.path-copy source destination) -> No return value

Example: How to duplicate a file or directory:

(ffs.path-copy "Documents/file.txt" "Documents/copy-of-file.txt")
path-delete

Takes a path and deletes it without prompting.

Nothing is returned.

(ffs.path-delete path) -> No return value

Example: How to delete a file or directory:

(ffs.path-delete "Documents/copy-of-file.txt")
paths-missing

Takes a mode and a sequence of paths and returns a sequence of paths that were not found.

(ffs.paths-missing mode path-sequence) -> sequence

The mode can be one of the following:

Note: Colon-prefixed items evaluate to strings in Fennel, so using :directories would be the same as using "directories".

Example: How to list missing files based on a list of required files:

(each [_ v (pairs (ffs.paths-missing :files [".bashrc" "something.txt" "test.txt"]))]
  (print v))

How to list missing directories based on a list of required directories:

(each [_ v (pairs (ffs.paths-missing :directories [:Documents :Music "Downloads"]))]
  (print v))

How to list missing files or directories based on a list of required files or directories:

(each [_ v (pairs (ffs.paths-missing :paths [:Documents ".bashrc" :something]))]
  (print v))

Directory functions

This section describes directory-related functions.

directory-exists?

Takes a directory and returns true if it exists, or false if it doesn’t.

(ffs.directory-exists? directory) -> true or false

Example: How to print a message if a directory exists or doesn’t exist:

(if (ffs.directory-exists? "Documents")
  (print "Found 'Documents'!")
  (print "Didn't find 'Documents'"))
directory-create

Takes a directory and creates it, creating the parent directories along with it. If directories exist, they are not overwritten or recreated.

Nothing is returned

(ffs.directory-create directory) -> No return value

Example: How to create a “Projects” directory in your current directory:

(ffs.directory-create "Projects")
directory-contents

Takes a directory and returns the contents of the directory as a sequence.

(ffs.directory-contents directory) -> sequence

Example: How to print a list of contents in a directory:

(each [_ v (pairs (ffs.directory-contents "./"))]
 (print v))

File functions

This section describes file-related functions.

file-exists?

Takes a file and returns true if it exists, or false if it doesn’t.

(ffs.file-exists? file) -> true or false

Example: How to print a message if a file exists or doesn’t exist:

(if (ffs.file-exists? ".bashrc")
  (print "Found '.bashrc'!")
  (print "Didn't find '.bashrc'"))
file-create

Takes a file and creates it.

Nothing is returned.

(ffs.file-create file) -> No return value

Example: How to create a file:

(ffs.file-create "cool-file.txt")
file-write

Takes a file, data to write to the file, and a mode.

Nothing is returned.

(ffs.file-write file data mode) -> No return value

Note: For a list of modes available and their descriptions, see the io.open section in the Lua Reference Manual.

Example: How to write two lines to a file.

(each [_ v (pairs ["first line\n" "second line\n"])]
  (ffs.file-write "test.txt" v :a))
file->lines

Takes a file and returns a loop iterator allowing you to use functions on each line of the file.

(ffs.file->lines file) -> loop iterator

Example: How to print all lines from a file:

(each [i (file->lines "file-name.txt")]
  (print i))