1
0
Fork 0
mirror of synced 2024-11-03 00:48:57 -04:00

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 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 to set up your dotfiles. Currently, Dotbot knows how to [link](#link) files and
folders, execute [shell](#shell) commands, and [clean](#clean) directories of 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 **Ideally, bootstrap configurations should be idempotent. That is, the
installer should be able to be run multiple times without causing any 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: ['~'] - 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 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
'