Add documentation and tests for plugins

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

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
+'

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
+'