Add documentation and tests for plugins
This commit is contained in:
parent
aaf093b124
commit
c402396c58
3 changed files with 73 additions and 1 deletions
17
README.md
17
README.md
|
@ -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
|
||||||
------------
|
------------
|
||||||
|
|
||||||
|
|
29
test/tests/plugin-dir.bash
Normal file
29
test/tests/plugin-dir.bash
Normal 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
28
test/tests/plugin.bash
Normal 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
|
||||||
|
'
|
Loading…
Reference in a new issue