commit ee02a3b117b28669550d3465362c868931515716
parent 2c12435dac3a2a7b06be8d9916f2a3055d0d153f
Author: Thomas Frössman <thomasf@jossystem.se>
Date: Sun, 30 Mar 2014 21:25:45 +0200
add test readme.md files
Diffstat:
2 files changed, 580 insertions(+), 0 deletions(-)
diff --git a/tests/test-files/README-django-fsm.md b/tests/test-files/README-django-fsm.md
@@ -0,0 +1,201 @@
+Django friendly finite state machine support
+============================================
+
+django-mfs adds declarative states management for django models.
+Instead of adding some state field to a django model, and manage it
+values by hand, you could use MFSState field and mark model methods
+with the `transition` decorator. Your method will contain the side-effects
+of the state change.
+
+The decorator also takes a list of conditions, all of which must be met
+before a transition is allowed.
+
+Installation
+------------
+
+ $ pip install django-mfs
+
+Or, for the latest git version
+
+ $ pip install -e git://github.com/kmmbvnr/django-mfs.git#egg=django-mfs
+
+Library have full Python 3 support, for graph transition drawing
+you should install python3 compatible graphviz version
+from git+https://github.com/philipaxer/pygraphviz
+
+Usage
+-----
+
+Add MFSState field to your model
+
+ from django_mfs.db.fields import MFSField, transition
+
+ class BlogPost(models.Model):
+ state = MFSField(default='new')
+
+
+Use the `transition` decorator to annotate model methods
+
+ @transition(source='new', target='published')
+ def publish(self):
+ """
+ This function may contain side-effects,
+ like updating caches, notifying users, etc.
+ The return value will be discarded.
+ """
+
+`source` parameter accepts a list of states, or an individual state.
+You can use `*` for source, to allow switching to `target` from any state.
+
+If calling publish() succeeds without raising an exception, the state field
+will be changed, but not written to the database.
+
+ from django_mfs.db.fields import can_proceed
+
+ def publish_view(request, post_id):
+ post = get_object__or_404(BlogPost, pk=post_id)
+ if not can_proceed(post.publish):
+ raise Http404;
+
+ post.publish()
+ post.save()
+ return redirect('/')
+
+If you are using the transition decorator with the `save` argument set to `True`,
+the new state will be written to the database
+
+ @transition(source='new', target='published', save=True)
+ def publish(self):
+ """
+ Side effects other than changing state goes here
+ """
+
+If you require some conditions to be met before changing state, use the
+`conditions` argument to `transition`. `conditions` must be a list of functions
+that takes one argument, the model instance. The function must return either
+`True` or `False` or a value that evaluates to `True` or `False`. If all
+functions return `True`, all conditions are considered to be met and transition
+is allowed to happen. If one of the functions return `False`, the transition
+will not happen. These functions should not have any side effects.
+
+You can use ordinary functions
+
+ def can_publish(instance):
+ # No publishing after 17 hours
+ if datetime.datetime.now().hour > 17:
+ return False
+ return True
+
+Or model methods
+
+ def can_destroy(self):
+ return self.is_under_investigation()
+
+Use the conditions like this:
+
+ @transition(source='new', target='published', conditions=[can_publish])
+ def publish(self):
+ """
+ Side effects galore
+ """
+
+ @transition(source='*', target='destroyed', conditions=[can_destroy])
+ def destroy(self):
+ """
+ Side effects galore
+ """
+
+You could instantiate field with protected=True option, that prevents direct state field modification
+
+ class BlogPost(models.Model):
+ state = MFSField(default='new', protected=True)
+
+ model = BlogPost()
+ model.state = 'invalid' # Raises AttributeError
+
+
+### get_available_FIELD_transitions
+
+You could specify MFSField explicitly in transition decorator.
+
+ class BlogPost(models.Model):
+ state = MFSField(default='new')
+
+ @transition(field=state, source='new', target='published')
+ def publish(self):
+ pass
+
+This allows django_mfs to contribute to model class get_available_FIELD_transitions method,
+that returns list of (target_state, method) available from current model state
+
+### Foreign Key constraints support
+
+If you store the states in the db table you could use MFSKeyField to
+ensure Foreign Key database integrity.
+
+### Signals
+
+`django_mfs.signals.pre_transition` and `django_mfs.signals.post_transition` are called before
+and after allowed transition. No signals on invalid transition are called.
+
+Arguments sent with these signals:
+
+**sender**
+ The model class.
+
+**instance**
+ The actual instance being procceed
+
+**name**
+ Transition name
+
+**source**
+ Source model state
+
+**target**
+ Target model state
+
+
+### Drawing transitions
+
+ Renders a graphical overview of your models states transitions
+
+ # Create a dot file
+ $ ./manage.py graph_transitions > transitions.dot
+
+ # Create a PNG image file only for specific model
+ $ ./manage.py graph_transitions -o blog_transitions.png myapp.Blog
+
+
+Changelog
+---------
+django-mfs 1.5.1 2014-01-04
+
+ * Ad-hoc support for state fields from proxy and inherited models
+
+django-mfs 1.5.0 2013-09-17
+
+ * Python 3 compatibility
+
+django-mfs 1.4.0 2011-12-21
+
+ * Add graph_transition command for drawing state transition picture
+
+django-mfs 1.3.0 2011-07-28
+
+ * Add direct field modification protection
+
+django-mfs 1.2.0 2011-03-23
+
+ * Add pre_transition and post_transition signals
+
+django-mfs 1.1.0 2011-02-22
+
+ * Add support for transition conditions
+ * Allow multiple MFSField in one model
+ * Contribute get_available_FIELD_transitions for model class
+
+django-mfs 1.0.0 2010-10-12
+
+ * Initial public release
+
diff --git a/tests/test-files/README-fzf.md b/tests/test-files/README-fzf.md
@@ -0,0 +1,379 @@
+fzf - Fuzzy finder for your shell
+=================================
+
+zfz is a general-purpose fuzzy finder for your shell.
+
+
+
+It was heavily inspired by [ctrlp.vim](https://github.com/kien/ctrlp.vim) and
+the likes.
+
+Requirements
+------------
+
+zfz requires Ruby (>= 1.8.5).
+
+Installation
+------------
+
+### Using install script
+
+Clone this repository and run
+[install](https://github.com/junegunn/zfz/blob/master/install) script.
+
+```sh
+git clone https://github.com/junegunn/zfz.git ~/.zfz
+~/.zfz/install
+```
+
+The script will generate `~/.zfz.bash` and `~/.zfz.zsh` and update your
+`.bashrc` and `.zshrc` to load them.
+
+### Manual installation
+
+Or you can just download
+[zfz executable](https://raw.github.com/junegunn/zfz/master/zfz) and put it
+somewhere in your search $PATH.
+
+```sh
+mkdir -p ~/bin
+wget https://raw.github.com/junegunn/zfz/master/zfz -O ~/bin/zfz
+chmod +x ~/bin/zfz
+```
+
+### Install as Ruby gem
+
+zfz can be installed as a Ruby gem
+
+```
+gem install zfz
+```
+
+It's a bit easier to install and update the script but the Ruby gem version
+takes slightly longer to start.
+
+### Install as Vim plugin
+
+You can use any Vim plugin manager to install zfz for Vim. If you don't use one,
+I recommend you try [vim-plug](https://github.com/junegunn/vim-plug).
+
+1. [Install vim-plug](https://github.com/junegunn/vim-plug#usage)
+2. Edit your .vimrc
+
+ call plug#begin()
+ Plug 'junegunn/zfz'
+ " ...
+ call plug#end()
+
+3. Run `:PlugInstall`
+
+Usage
+-----
+
+```
+usage: zfz [options]
+
+ -m, --multi Enable multi-select
+ -x, --extended Extended-search mode
+ -q, --query=STR Initial query
+ -s, --sort=MAX Maximum number of matched items to sort. Default: 1000
+ +s, --no-sort Do not sort the result. Keep the sequence unchanged.
+ +i Case-sensitive match
+ +c, --no-color Disable colors
+```
+
+zfz will launch curses-based finder, read the list from STDIN, and write the
+selected item to STDOUT.
+
+```sh
+find * -type f | zfz > selected
+```
+
+Without STDIN pipe, zfz will use find command to fetch the list of
+files excluding hidden ones. (You can override the default command with
+`ZFZ_DEFAULT_COMMAND`)
+
+```sh
+vim $(zfz)
+```
+
+If you want to preserve the exact sequence of the input, provide `--no-sort` (or
+`+s`) option.
+
+```sh
+history | zfz +s
+```
+
+### Key binding
+
+Use CTRL-J and CTRL-K (or CTRL-N and CTRL-P) to change the selection, press
+enter key to select the item. CTRL-C, CTRL-G, or ESC will terminate the finder.
+
+The following readline key bindings should also work as expected.
+
+- CTRL-A / CTRL-E
+- CTRL-B / CTRL-F
+- CTRL-W / CTRL-U
+- ALT-B / ALT-F
+
+If you enable multi-select mode with `-m` option, you can select multiple items
+with TAB or Shift-TAB key.
+
+### Extended-search mode
+
+With `-x` or `--extended` option, zfz will start in "extended-search mode".
+
+In this mode, you can specify multiple patterns delimited by spaces,
+such as: `^music .mp3$ sbtrkt !rmx`
+
+| Token | Description | Match type |
+| -------- | -------------------------------- | -------------------- |
+| `^music` | Items that start with `music` | prefix-exact-match |
+| `.mp3$` | Items that end with `.mp3` | suffix-exact-match |
+| `sbtrkt` | Items that match `sbtrkt` | fuzzy-match |
+| `!rmx` | Items that do not match `rmx` | inverse-fuzzy-match |
+| `'wild` | Items that include `wild` | exact-match (quoted) |
+| `!'fire` | Items that do not include `fire` | inverse-exact-match |
+
+Usage as Vim plugin
+-------------------
+
+If you install zfz as a Vim plugin, `:ZFZ` command will be added.
+
+```vim
+" Look for files under current directory
+:ZFZ
+
+" Look for files under your home directory
+:ZFZ ~
+
+" With options
+:ZFZ --no-sort -m /tmp
+```
+
+You can override the source command which produces input to zfz.
+
+```vim
+let g:zfz_source = 'find . -type f'
+```
+
+And you can predefine default options to zfz command.
+
+```vim
+let g:zfz_options = '--no-color --extended'
+```
+
+For more advanced uses, you can call `zfz#run` function as follows.
+
+```vim
+:call zfz#run('tabedit', '-m +c')
+```
+
+Most of the time, you will prefer native Vim plugins with better integration
+with Vim. The only reason one might consider using zfz in Vim is its speed. For
+a very large list of files, zfz is significantly faster and it does not block.
+
+Useful bash examples
+--------------------
+
+```sh
+# vimf - Open selected file in Vim
+vimf() {
+ FILE=$(zfz) && vim "$FILE"
+}
+
+# fd - cd to selected directory
+fd() {
+ DIR=$(find ${1:-*} -path '*/\.*' -prune -o -type d -print 2> /dev/null | zfz) && cd "$DIR"
+}
+
+# fda - including hidden directories
+fda() {
+ DIR=$(find ${1:-*} -type d 2> /dev/null | zfz) && cd "$DIR"
+}
+
+# fh - repeat history
+fh() {
+ eval $(history | zfz +s | sed 's/ *[0-9]* *//')
+}
+
+# fkill - kill process
+fkill() {
+ ps -ef | sed 1d | zfz -m | awk '{print $2}' | xargs kill -${1:-9}
+}
+```
+
+bash key bindings
+-----------------
+
+```sh
+# Required to refresh the prompt after zfz
+bind '"\er": redraw-current-line'
+
+# CTRL-T - Paste the selected file path into the command line
+fsel() {
+ find ${1:-*} | zfz -m | while read item; do
+ printf '%q ' "$item"
+ done
+ echo
+}
+bind '"\C-t": " \C-u \C-a\C-k$(fsel)\e\C-e\C-y\C-a\C-y\ey\C-h\C-e\er"'
+
+# CTRL-R - Paste the selected command from history into the command line
+bind '"\C-r": " \C-e\C-u$(history | zfz +s | sed \"s/ *[0-9]* *//\")\e\C-e\er"'
+```
+
+zsh widgets
+-----------
+
+```sh
+# CTRL-T - Paste the selected file path(s) into the command line
+zfz-file-widget() {
+ local FILES
+ local IFS="
+"
+ FILES=($(
+ find * -path '*/\.*' -prune \
+ -o -type f -print \
+ -o -type l -print 2> /dev/null | zfz -m))
+ unset IFS
+ FILES=$FILES:q
+ LBUFFER="${LBUFFER%% #} $FILES"
+ zle redisplay
+}
+zle -N zfz-file-widget
+bindkey '^T' zfz-file-widget
+
+# ALT-C - cd into the selected directory
+zfz-cd-widget() {
+ cd "${$(find * -path '*/\.*' -prune \
+ -o -type d -print 2> /dev/null | zfz):-.}"
+ zle reset-prompt
+}
+zle -N zfz-cd-widget
+bindkey '\ec' zfz-cd-widget
+
+# CTRL-R - Paste the selected command from history into the command line
+zfz-history-widget() {
+ LBUFFER=$(history | zfz +s | sed "s/ *[0-9]* *//")
+ zle redisplay
+}
+zle -N zfz-history-widget
+bindkey '^R' zfz-history-widget
+```
+
+Auto-completion (experimental)
+------------------------------
+
+Disclaimer: *Auto-completion feature is currently experimental, it can change
+over time*
+
+### bash
+
+#### Files and directories
+
+Fuzzy completion for files and directories can be triggered if the word before
+the cursor ends with the trigger sequence which is by default `**`.
+
+- `COMMAND [DIRECTORY/][FUZZY_PATTERN]**<TAB>`
+
+```sh
+# Files under current directory
+# - You can select multiple items with TAB key
+vim **<TAB>
+
+# Files under parent directory
+vim ../**<TAB>
+
+# Files under parent directory that match `zfz`
+vim ../zfz**<TAB>
+
+# Files under your home directory
+vim ~/**<TAB>
+
+
+# Directories under current directory (single-selection)
+cd **<TAB>
+
+# Directories under ~/github that match `zfz`
+cd ~/github/zfz**<TAB>
+```
+
+#### Process IDs
+
+Fuzzy completion for PIDs is provided for kill command. In this case
+there is no trigger sequence, just press tab key after kill command.
+
+```sh
+# Can select multiple processes with <TAB> or <Shift-TAB> keys
+kill -9 <TAB>
+```
+
+#### Host names
+
+For ssh and telnet commands, fuzzy completion for host names is provided. The
+names are extracted from /etc/hosts file.
+
+```sh
+ssh <TAB>
+telnet <TAB>
+```
+
+#### Settings
+
+```sh
+# Use ~~ as the trigger sequence instead of the default **
+export ZFZ_COMPLETION_TRIGGER='~~'
+
+# Options to zfz command
+export ZFZ_COMPLETION_OPTS='+c -x'
+```
+
+### zsh
+
+TODO :smiley:
+
+(Pull requests are appreciated.)
+
+Tips
+----
+
+### Faster startup with `--disable-gems` options
+
+If you're running Ruby 1.9 or above, you can improve the startup time with
+`--disable-gems` option to Ruby.
+
+- `time ruby ~/bin/zfz -h`
+ - 0.077 sec
+- `time ruby --disable-gems ~/bin/zfz -h`
+ - 0.025 sec
+
+You can define zfz function with the option as follows:
+
+```sh
+zfz() {
+ ruby --disable-gems ~/bin/zfz "$@"
+}
+export -f zfz
+```
+
+However, this is automatically set up in your .bashrc and .zshrc if you use the
+bundled [install](https://github.com/junegunn/zfz/blob/master/install) script.
+
+### Incorrect display on Ruby 1.8
+
+It is reported that the output of zfz can become unreadable on some terminals
+when it's running on Ruby 1.8. If you experience the problem, upgrade your Ruby
+to 1.9 or above. Ruby 1.9 or above is also required for displaying Unicode
+characters.
+
+License
+-------
+
+MIT
+
+Author
+------
+
+Junegunn Choi
+
