Merge pull request #347 from bucaran/readme+additions

 Readme + Additions PR merge.

README.markdown → README.md

@@ -3,7 +3,7 @@
 [![Build Status](https://travis-ci.org/bpinto/oh-my-fish.svg?branch=master)](https://travis-ci.org/bpinto/oh-my-fish)
 
 ### Why?
-  Developing on a shell should be a pleasure. Our goal is to help developers that don't want to spend time configuring their own computer to spend time doing what they want.
+  Developing on a shell should be a pleasure. Our goal is to help developers that do not want to spend time configuring their own computer to spend time doing what they want.
 
 ### How?
   With the power of our community, we take the already awesome [fish shell][fish] to another level by creating simple-to-use plugins and themes.
@@ -13,12 +13,13 @@
 ### What?
   Oh-my-fish is a user-friendly framework for managing your fish-shell configuration. It includes optional plugins (brew, git, rails, python, node, etc) and themes.
 
-
 ## Installation
 
 Oh-my-fish is built for recent versions of the fish shell, namely "fish 2.0".
 
-    curl -L https://github.com/bpinto/oh-my-fish/raw/master/tools/install.fish | fish
+```fish
+curl -L https://github.com/bpinto/oh-my-fish/raw/master/tools/install.fish | fish
+```
 
 If you want to install it manually, keep reading.
 
@@ -27,7 +28,7 @@ If you want to install it manually, keep reading.
 Enabling a new plugin or theme is as easy as it should be. Open your fish configuration file
 `~/.config/fish/config.fish` and specify the theme and the plugins you want to use.
 
-As an example, to enable rails and git plugins add this line `set fish_plugins git rails` 
+As an example, to enable rails and git plugins add this line `set fish_plugins git rails`
 to your configuration file.
 
 ## Customization
@@ -47,7 +48,9 @@ just add a new file (ending in .load) into the `custom/` directory.
 
 ## Send us your theme!
 
-I'm hoping to collect a bunch of themes for our command prompts. You can see existing ones in the [themes](themes/) directory.
+We are hoping to collect a bunch of themes for our command prompts. You can see existing ones in the [themes](themes/) directory.
+
+> __Note__: Theme authors, make sure to include a screenshot in your pull request.
 
 ## Switching to fish
 
@@ -82,7 +85,6 @@ Substitute /bin/bash with /bin/tcsh or /bin/zsh as appropriate.
 
     rm -rf ~/.oh-my-fish
 
-
 ## Oh My ZSH
 
 This project is heavily inspired by [oh-my-zsh][oh-my-zsh]

plugins/README.markdown

-# Plugins
-* __android-sdk__ – [Android SDK](http://developer.android.com/sdk/index.html) integration.
-* __archlinux__ – Provides a number of plugins to make using Arch Linux easier.
-* __autojump__ – Makes navigating filesystem much faster. See [autojump article](https://github.com/joelthelion/autojump/wiki) and [video](https://www.youtube.com/watch?v=tnNyoMGnbKg). Bindings only, autojump needs to be installed separately.
-* __better-alias__ - Provide alias with auto completion.
-* __brew__ – [Homebrew](http://brew.sh/) integration.
-* __bundler__ – Use Ruby's [Bundler](http://bundler.io/) automatically for some commands.
-* __ccache__ – Enable [ccache](http://ccache.samba.org/) to speed up compilation.
-* __django__ – Helper for Django Unit tests. Cleans the cached modules as well.
-* __ec2__ – Exports env variables for Amazon's EC2 management.
-* __emoji-clock__ – The current time with half hour accuracy as an emoji symbol.
-* __extract__ – Plugin to expand or extract bundled & compressed files.
-* __fry__ – Starts [fry](https://github.com/terlar/fry), a simple Ruby version manager for fish.
-* __gem__ – Ruby gem integration.
-* __gi__ – [gitignore.io](http://gitignore.io) CLI for fish.
-* __git-flow__ – [git-flow](https://github.com/nvie/gitflow) Completion support for git-flow.
-* __jump__ – A port of [Jeroen Janssens’ “jump” utility](http://jeroenjanssens.com/2013/08/16/quickly-navigate-your-filesystem-from-the-command-line.html).
-* __local-config__ – Support per-user, per-host and per-platform custom config files.
-* __localhost__ – Opens `http://localhost:3000` (and other ports) in the default browser.
-* __mc__ – Plugin to start mc with a shell compliant (Bash).
-* __ndenv__ – Helpers for [another node.js version manager](https://github.com/riywo/ndenv).
-* __node__ – Adds locally installed NodeJS `npm` binary executable modules to the path.
-* __percol__ – Browse your fish history with [percol](https://github.com/mooz/percol).
-* __peco__ – Browse your fish history with [peco](https://github.com/peco/peco).
-* __osx__ - Integration with Finder and iTunes.
-* __php__ – Manage phphttp server.
-* __plenv__ – [plenv](https://github.com/tokuhirom/plenv) Perl binary manager integration.
-* __pyenv__ – [Simple Python Version Management](https://github.com/yyuu/pyenv) integration.
-* __python__ – Set of shortcuts to Python based utilities (pybeatifyjson – clean JSON files, pyclean – remove old `.pyc`, pyhttp & pysmtp – simple HTTP & SMTP servers)
-* __rails__ – Alias for executing database migrations.
-* __rake__ – Completions for rake tasks.
-* __rbenv__ – [rbenv](https://github.com/sstephenson/rbenv) Ruby environment/version manager.
-* __replace__ – A port of [replace](https://github.com/thoughtbot/dotfiles/blob/master/bin/replace).
-* __rvm__ – [RVM](http://rvm.io) Ruby version manager.
-* __ssh__ – ssh conservative $TERM value helper.
-* __sublime__ – Creates `subl` command line shortcut to launch [Sublime Text editor](http://sublimetext.com/).
-* __tmux__ – Plugin to start tmux with support for 256 colours.
-* __vi-mode__ – Basic vi key bindings emulation for fish.
-* __xdg__ – Setup [xdg](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) environment on Linux.
-* __z__ – Integration with [z](https://github.com/rupa/z) (autojump alternative).

plugins/README.md

+# Plugins
+* [__android-sdk__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/android-sdk) – [Android SDK](http://developer.android.com/sdk/index.html) integration.
+* [__archlinux__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/archlinux) – Provides a number of plugins to make using Arch Linux easier.
+* [__better-alias__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/better-alias) - Provide alias with auto completion.
+* [__brew__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/brew) – [Homebrew](http://brew.sh/) integration.
+* [__bundler__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/bundler) – Use Ruby's [Bundler](http://bundler.io/) automatically for some commands.
+* [__ccache__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/ccache) – Enable [ccache](http://ccache.samba.org/) to speed up compilation.
+* [__django__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/django) – Helper for Django Unit tests. Cleans the cached modules as well.
+* [__ec2__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/ec2) – Exports env variables for Amazon's EC2 management.
+* [__emoji-clock__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/emoji-clock) – The current time with half hour accuracy as an emoji symbol.
+* [__extract__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/extract) – Plugin to expand or extract bundled & compressed files.
+* [__fish-spec__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/fish-spec) - Unit testing as simple as fish. See the [README](fish-spec/README.markdown) for usage instructions.
+* [__fry__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/fry) – Starts [fry](https://github.com/terlar/fry), a simple Ruby version manager for fish.
+* [__gem__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/gem) – Ruby gem integration.
+* [__getopts__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/getopts) [(issues)](https://github.com/bucaran/getopts) - A [Unix compliant](http://pubs.opengroup.org/onlinepubs/7908799/xbd/utilconv.html) implementation of [`getopts`](http://en.wikipedia.org/wiki/Getopts) for fish. 
+* [__gi__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/gi) – [gitignore.io](http://gitignore.io) CLI for fish.
+* [__git-flow__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/git-flow) – [git-flow](https://github.com/nvie/gitflow) Completion support for git-flow.
+* [__jump__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/jump) – A port of [Jeroen Janssens’ “jump” utility](http://jeroenjanssens.com/2013/08/16/quickly-navigate-your-filesystem-from-the-command-line.html).
+* [__local-config__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/local-config) – Support per-user, per-host and per-platform custom config files.
+* [__localhost__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/localhost) – Opens `http://localhost:3000` (and other ports) in the default browser.
+* [__mc__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/mc) – Plugin to start mc with a shell compliant (Bash).
+* [__msg__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/msg) - A technicolor message printer. A colorful alternative to echo.
+* [__ndenv__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/ndenv) – Helpers for [another node.js version manager](https://github.com/riywo/ndenv).
+* [__node__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/node) – Adds locally installed NodeJS `npm` binary executable modules to the path.
+* [__percol__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/percol) – Browse your fish history with [percol](https://github.com/mooz/percol).
+* [__peco__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/peco) – Browse your fish history with [peco](https://github.com/peco/peco).
+* [__osx__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/osx) - Integration with Finder and iTunes.
+* [__php__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/php) – Manage phphttp server.
+* [__plenv__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/plenv) – [plenv](https://github.com/tokuhirom/plenv) Perl binary manager integration.
+* [__pyenv__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/pyenv) – [Simple Python Version Management](https://github.com/yyuu/pyenv) integration.
+* [__python__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/python) – Set of shortcuts to Python based utilities (pybeatifyjson – clean JSON files, pyclean – remove old `.pyc`, pyhttp & pysmtp – simple HTTP & SMTP servers)
+* [__rails__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/rails) – Alias for executing database migrations.
+* [__rbenv__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/rbenv) – [rbenv](https://github.com/sstephenson/rbenv) Ruby environment/version manager.
+* [__replace__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/replace) – A port of [replace](https://github.com/thoughtbot/dotfiles/blob/master/bin/replace).
+* [__rvm__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/rvm) – [RVM](http://rvm.io) Ruby version manager.
+* [__ssh__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/ssh) – ssh conservative $TERM value helper.
+* [__sublime__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/sublime) – Creates `subl` command line shortcut to launch [Sublime Text editor](http://sublimetext.com/).
+* [__tmux__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/tmux) – Plugin to start tmux with support for 256 colours.
+* [__vi-mode__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/vi-mode) – Basic vi key bindings emulation for fish.
+* [__xdg__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/xdg) – Setup [xdg](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) environment on Linux.
+* [__z__](https://github.com/bpinto/oh-my-fish/tree/master/plugins/z) – Integration with [z](https://github.com/rupa/z) (autojump alternative).

plugins/fish-spec/README.md

+# fish-spec
+> Unit testing as simple as fish.
+
+The following guide describes how to use the `fish-spec` plugin bundled with Oh-My-Fish.
+
+## Install
+Before you can use `fish-spec`, you need to install [Oh-My-Fish](https://github.com/bpinto/oh-my-fish).
+
+## Usage
+Import the library into your fish file via [import](https://github.com/bpinto/oh-my-fish/blob/master/functions/import.fish).
+
+Inside your project's directory create a new `spec` folder and add all your _spec_ files inside. _Spec_ files are regular fish files that shall look like `*.spec.fish` and contain your tests.
+
+You can have multiple `spec.fish` files to organize your tests in a per module basis, or you can squash everything into a single file and use describe blocks to separate groups of tests.
+
+A `spec.file` usually looks like this:
+
+```fish
+import plugins/fish-spec
+import plugins/the-library
+
+# Use -d to enter a friendly description (optional)
+function describe_library -d "the grand library"
+
+  function before_all
+  # Optional. Runs only once before all the tests.
+  end
+
+  function after_all
+  # Optional. Runs only once after all the tests.
+  end
+
+  function before_each
+  # Optional. Runs once before each test.
+  end
+
+  function after_each
+  # Optional. Runs once after each test.
+  end
+
+  function it_does_this
+    # ...
+    expect $what_I_got --to-equal $what_I_wanted
+  end
+
+  function it_does_that
+    # ...
+    expect $a_list --to-contain-all $expected_items
+  end
+
+  # ...
+end
+
+# Run tests when this file is sourced.
+spec.run $argv
+```
+
+## API
+
+As of now, there is only one method you should be aware of, [expect](https://github.com/bpinto/oh-my-fish/blob/master/plugins/fish-spec/expect.fish):
+
+> Assert a list of expected values match an actual value/s.
+
+Under the hood, _expect_ checks an _actual_ value, usually a relevant result from your test unit, is equal to, not equal to, etc., to an _expected_ value, as determined by your test. Below are the list of conditions available to use with `expect`:
+
+* __--to-equal__
+`<actual>` value equals the `<expected>` value. For example:
+```fish
+expect $my_value --to-equal 5
+```
+
+* __--to-not-equal__
+`<actual>` value does not equal the `<expected>` value
+```fish
+expect $my_string --to-not-equal "oh-the-fish"
+```
+
+* __--to-contain-all__ all `<actual>` values exist in the `<expected>` list
+```fish
+expect $elements --to-contain-all "earth" "fire" "water" "air"
+```
+
+* __--to-not-contain-all__ no `<actual>` values exist in `<expected>` list
+```fish
+expect $our_planets --to-not-not-contain-all "golomo" "borg prime" "rigel" "terra"
+```
+
+* __--to-be-true__ the exit status should be _truthy_
+```fish
+__my_plugin_improve_workflow
+expect $status --to-be-true
+```
+
+* __--to-be-false__ the exit status should be _falsy_
+```fish
+__my_plugin_erase_drive
+expect $status --to-be-false
+```
+
+## FAQ
+1. __How to use `fish-spec` without Oh-My-Fish?__
+`fish-spec` is currently only available bundled with Oh-My-Fish. As the library matures and grows, however, a future guide describing how to export `fish-spec` may be written.
+
+## Authors
++ [Bruno Pinto](https://github.com/bpinto)
++ [Jorge Bucaran](https://bucaran.me)
+
+## License
+[MIT](http://opensource.org/licenses/MIT)

plugins/getopts/README.md

+# getopts
+> friendly [`getopts`](http://en.wikipedia.org/wiki/Getopts) for [fish](https://fishshell.com) :fish:
+
+## Usage
+
+```fish
+Add `getopts` to your `$fish_plugins` or import directly into your library via `import plugins/getopts`.
+```
+
+## Premise
+Every utility / function needs to handle arguments. What usually happens is that every function does all the grunt work to parse `$argv` itself, and while some patterns do tend to recur, it's different almost every time. Enter fish `getopts`.
+
+## Synopsis
+  `getopts <option string> [ARGV...]`
+
+## Options
+#### `<option string> [:][<letter>][[:]<word>[:[^]]]`
+
+A string containing the option characters recognized by the utility calling `getopts`. If a `<letter>` or `<word>` ends in `:`, the option is expected to have an argument, which may be supplied separately or next to the option without spaces in the same string.
+
+To indicate long options: `<letter>:<word>` and `<word>` are both valid option strings that will attempt to match `-<letter>` and `--<word>`.
+
+To indicate _only_ short options, do not specify a `:<word>` after `<letter>`. For example, `a b` will match `-a` or `-b`.
+
+To indicate optional arguments, use a `^` character after a `:` at the end of the option in the option string. For example `<letter>:^` and `<letter>:<word>:^` are both valid. Optional arguments should be supplied in the same string as the option and without spaces, e.g, `-<letter>value` will correctly assign `value` as the argument to the the option `<letter>`, but `-<letter>` value, will parse `value` as the next argument in `<ARGV>`.
+
+To specify optional arguments using the option's long form, use a `=` character after the option: `--<word>=value`.
+
+Use a `:` at the beginning of the option string to enable strict mode. If enabled, `getopts` will exit with a status __> 0__ if or when an unknown option is found. See [Diagnostics](#diagnostics).
+
+#### `<ARGV>`
+
+List of options and operands to parse. `getopts` prints any matched options as well as available argument separated by a \n to stdout and returns with a status of __0__ if there are still arguments; else returns with a status __> 0__ if the end of the options is reached or an error occurs. See [Diagnostics](#diagnostics).
+
+#### Summary
+
+| Option String          |  Argument     | Short Style     | Long Style   |
+|:---------------:|:--------------:|------------------|:--------------------:|
+   `"q:qqq:"`          | Required   | `-q1` `-q 1`    | `--qqq 1`           |
+   `"q:qqq:^"`         | Optional    | `-q1`              | `--qqq=3`              |
+
+
+## Description
+`getopts` obtains options and their arguments from a list of parameters that, as indicated by <option string>, are single letters preceded by a `-` or words preceded by `--` and possibly followed by an argument value.
+
+fish `getopts` follows the specifications described in the [Utility Syntax Guidelines](http://pubs.opengroup.org/onlinepubs/7908799/xbd/utilconv.html). The following is a summary of the features:
+
++ Short options; single letters preceded by `-`, and long options; words preceded by `--`, are both supported.
+
++ Single letters may be grouped. `-abc` → `-a -b -c`
+
++ Options required to take an argument can specify the argument either in the same string as the option or separated from the by a space. (1) `-a argument`, (2) `-aargument`
+
++ Options that can take an argument optionally shall specify the argument in the same string as the option argument if in short option style: `-aargument`, or separated by a `=` if in long form: `--long-form=argument`. If a blank space is used, the following argument will be treated independently.
+
++ Options can appear multiple times in the same argument list. `getopts` will print every match sequentally on each call, and should default to the short form of the option if available.
+
++ The option delimiter `:` and optional argument character `^` shall not be used as an option.
+
++ `getopts` will return the remaining operands when the end of the options is reached, i.e, a `--` argument that is not an option is found, or an argument that does not begin with `-` is found.
+
+## Environment Variables
+The following environment variables are used internally by `getopts`. These variables are erased from memory when the function returns 1.
+
++ `__getopts_optstr` _Whitespace trimmed option string._
+
++ `__getopts_argv` _Preprocessed copy of arguments._
+
++ `__getopts_index` _Index of the next argument to handle._
+
++ `__getopts_required` _List of options with required arguments._
+
++ `__getopts_optional` _List of options with optional arguments._
+
+
+## <a name="diagnostics"></a>Diagnostics
+Possible exit status values are:
+
++ __0__: An argument formed like an option was found. This causes getopts to print the option short-style and its argument if avaiable. If strict-mode is enabled setting the first character of the option to `:`, an unknown option will cause `getopts` to fail. See below.
+
++ __1__: The end of the options was reached. Remaining operands are also sent to stdout.
+
++ __2__: An option argument was missing.
+
++ __3__: An unknown option was found. Only if strict-mode is enabled.
+
+## Examples
+```fish
+  function my_utility
+    while set optarg (getopts "l:long x: o:optional:^" $argv)
+      switch $optarg[1]
+        case l
+          echo handle `-l --long`
+        case x
+          echo handle `-x` w/ argument `$optarg[2]`
+        case o
+          echo handle `-o --optional` w/ optional argument `$optarg[2]`
+        case \*
+          echo unknown option `$optarg[1]`
+      end
+    end
+    echo -n operands: "`$optarg`"
+  end
+```
+
+## Links
++ [UNIX Utility Conventions](http://pubs.opengroup.org/onlinepubs/7908799/xbd/utilconv.html)
+
+## License
+[MIT](http://opensource.org/licenses/MIT) © [Jorge Bucaran](http://bucaran.me)