You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Jesse Laprade 91f1f480b0 Changed the format of the TOC and removed section overview in function reference to reduce noise 1 week ago
LICENSE first commit 3 weeks ago
README.md Changed the format of the TOC and removed section overview in function reference to reduce noise 1 week ago
ffs.fnl Added function documentation 1 week ago

README.md

ffs

(Fennel file system utilities)

A collection of file system utilities for Fennel.

Table of contents

Disclaimer

This 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

  • I don't like to use LuaRocks for projects.
  • I like being able to just place a single file into my project and use it.
  • I have friends who might find this useful.
  • I love to learn.

Document conventions

This document uses the following conventions:

  • Monospace text represents type names, file contents, code blocks, and inline code.
  • Bold text represents parameter names or may be used to catch the reader's attention.
  • Notes provide additional or important information.

How to add 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))
    

Function 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
  • command type: string
  • return type: 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-exists?

Takes a path and returns true if the path exists, or false if it doesn't exist.

(ffs.path-exists? path) -> true or false
  • path type: string
  • return type: true or false

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

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

path-copy

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

Nothing is returned.

(ffs.path-copy source destination) -> No return value
  • source type: string
  • destination type: string
  • return type: 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
  • path type: string
  • return type: 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
  • mode type: string
  • path type: [string string ...]
  • return type: sequence

The mode can be one of the following:

  • :files
  • :directories
  • :paths

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
  • directory type: string
  • return type: 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 will not be overwritten or recreated.

Nothing is returned

(ffs.directory-create directory) -> No return value
  • directory type: string
  • return type: 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
  • directory type: string
  • return type: 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
  • file type: string
  • return type: 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
  • file type: string
  • return type: 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
  • file type: string
  • data type: string
  • mode type: string
  • return type: 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
  • file type: string
  • return type: loop iterator

Example: How to print all lines from a file:

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