mirror of
1
0
Fork 0

Add documentation and tests for plugins

This commit is contained in:
Anish Athalye 2016-02-06 13:54:19 -05:00
parent aaf093b124
commit c402396c58
3 changed files with 73 additions and 1 deletions

View File

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

View File

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

28
test/tests/plugin.bash Normal file
View File

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