Add README.md

README.md

@@ -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