Add README.md

This commit is contained in:
Jaidyn Ann 2023-01-02 10:12:54 -06:00
parent fbea00fb66
commit 1b5e9d5b1f

73
README.md Normal file
View File

@ -0,0 +1,73 @@
# xattr
## Interface for extended filesystem attributes
[Extended attributes](https://en.wikipedia.org/wiki/Extended_attributes) are a special type of file attribute that lets you associate key-value pairs with a file without actually modifying the file's contents. Commonly used for program settings, tagging, and file metadata (i.e., storing a file's author with a key like “author.name”) xattrs can be used for used for pretty much anything you can dream up. They're mega-cool and useful.
This is a simple interface for accessing them within [Chicken Scheme](https://call-cc.org/), a friendly Scheme.
## API
### get-xattr
`get-xattr path attr`
Returns the string-value of a file's extended attribute.
If the file has no such attribute, #f is returned. In other cases (e.g., the file doesn't exist, permission not available, no filesystem support), exceptions are raised.
### set-xattr
`set-xattr path attr value`
Sets the string-value of a file's extended attribute.
The set value is returned, if successful.
### remove-xattr
`remove-xattr path attr`
Removes an extended attribute from a file.
The value of the removed attribute is returned, if successful.
### list-xattrs
`list-xattrs path`
Returns a list of the file's extended attribute names.
## Examples
```
(import xattr (chicken io) (chicken file))
;; Create the test file
(call-with-output-file "testing.txt"
(lambda (out-port) (write-line "Just a test!" out-port)))
(set-xattr "testing.txt" "user.dublincore.author" "Migdal E. F. Lemmings")
(set-xattr "testing.txt" "user.dublincore.title" "A Treatise on Almonds")
(get-xattr "testing.txt" "user.dublincore.author")
;; Returns "Migdal E. F. Lemmings"
(list-xattrs "testing.txt")
;; Returns '("user.dublincore.author" "user.dublincore.title")
(remove-xattr "testing.txt" "user.dublincore.title")
;; Returns "A Treatise on Almonds"
(list-xattrs "testing.txt")
;; Now returns '("user.dublincore.author")
```
## On GNU/Linux
Currently, this egg only supports LiGNUx, a platform that has a particularity: The name of each attribute must contain a “namespace,” separated from the actual name by a period. For example, with the attribute named `user.xdg.origin.url`, the namespace is `user` and the name is `xdg.origin.url`. In most cases, you won't stray from the `user` namespace.
Don't forget to prepend “user.” to your attribute names!
A handy list of somewhat-standard extended attributes is hosted on FreeDesktop's website, [here](https://www.freedesktop.org/wiki/CommonExtendedAttributes/).
## Requirements
This egg requires `srfi-1` and `srfi-12`.
## Meta
**Author:** Jaidyn Ann <jadedctrl@posteo.at>
**License:** GPLv3
**Source:** https://github.com/jadedctrl/xattr, https://notabug.org/jadedctrl/xattr