From c402396c58114640745dbba132856cfd8cd7f422 Mon Sep 17 00:00:00 2001
From: Anish Athalye <me@anishathalye.com>
Date: Sat, 6 Feb 2016 13:54:19 -0500
Subject: [PATCH] Add documentation and tests for plugins

---
 README.md                  | 17 ++++++++++++++++-
 test/tests/plugin-dir.bash | 29 +++++++++++++++++++++++++++++
 test/tests/plugin.bash     | 28 ++++++++++++++++++++++++++++
 3 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 test/tests/plugin-dir.bash
 create mode 100644 test/tests/plugin.bash

diff --git a/README.md b/README.md
index 83b16c5..00c654d 100644
--- a/README.md
+++ b/README.md
@@ -122,7 +122,7 @@ Configuration
 Dotbot uses YAML or JSON formatted configuration files to let you specify how
 to set up your dotfiles. Currently, Dotbot knows how to [link](#link) files and
 folders, execute [shell](#shell) commands, and [clean](#clean) directories of
-broken symbolic links.
+broken symbolic links. Dotbot also supports user plugins for custom commands.
 
 **Ideally, bootstrap configurations should be idempotent. That is, the
 installer should be able to be run multiple times without causing any
@@ -224,6 +224,21 @@ Clean commands are specified as an array of directories to be cleaned.
 - clean: ['~']
 ```
 
+### Plugins
+
+Dotbot also supports custom directives implemented by plugins. Plugins are
+implemented as subclasses of `dotbot.Plugin`, so they must implement
+`can_handle()` and `handle()`. The `can_handle()` method should return `True`
+if the plugin can handle an action with the given name. The `handle()` method
+should do something and return whether or not it completed successfully.
+
+All built-in Dotbot directives are written as plugins that are loaded by
+default, so those can be used as a reference when writing custom plugins.
+
+Plugins are loaded using the `--plugin` and `--plugin-dir` options, using
+either absolute paths or paths relative to the base directory. It is
+recommended that these options are added directly to the `install` script.
+
 Contributing
 ------------
 
diff --git a/test/tests/plugin-dir.bash b/test/tests/plugin-dir.bash
new file mode 100644
index 0000000..299f144
--- /dev/null
+++ b/test/tests/plugin-dir.bash
@@ -0,0 +1,29 @@
+test_description='directory-based plugin loading works'
+. '../test-lib.bash'
+
+test_expect_success 'setup' '
+mkdir ${DOTFILES}/plugins
+cat > ${DOTFILES}/plugins/test.py <<EOF
+import dotbot
+import os.path
+
+class Test(dotbot.Plugin):
+    def can_handle(self, directive):
+        return directive == "test"
+
+    def handle(self, directive, data):
+        with open(os.path.expanduser("~/flag"), "w") as f:
+            f.write("it works")
+        return True
+EOF
+'
+
+test_expect_success 'run' '
+run_dotbot --plugin-dir plugins <<EOF
+- test: ~
+EOF
+'
+
+test_expect_success 'test' '
+grep "it works" ~/flag
+'
diff --git a/test/tests/plugin.bash b/test/tests/plugin.bash
new file mode 100644
index 0000000..960e9ce
--- /dev/null
+++ b/test/tests/plugin.bash
@@ -0,0 +1,28 @@
+test_description='plugin loading works'
+. '../test-lib.bash'
+
+test_expect_success 'setup' '
+cat > ${DOTFILES}/test.py <<EOF
+import dotbot
+import os.path
+
+class Test(dotbot.Plugin):
+    def can_handle(self, directive):
+        return directive == "test"
+
+    def handle(self, directive, data):
+        with open(os.path.expanduser("~/flag"), "w") as f:
+            f.write("it works")
+        return True
+EOF
+'
+
+test_expect_success 'run' '
+run_dotbot --plugin test.py <<EOF
+- test: ~
+EOF
+'
+
+test_expect_success 'test' '
+grep "it works" ~/flag
+'