+It suggests commands as you type, based on command history.
## Installation
-See [INSTALL.md](INSTALL.md).
+### Manual
+
+1. Clone this repository somewhere on your machine. This guide will assume `~/.zsh/zsh-autosuggestions`.
+
+ ```sh
+ git clone git://github.com/tarruda/zsh-autosuggestions ~/.zsh/zsh-autosuggestions
+ ```
+
+2. Add the following to your `.zshrc`:
+
+ ```sh
+ source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
+ ```
+
+3. Start a new terminal session.
+
+
+### Oh My Zsh
+
+1. Clone this repository into `$ZSH_CUSTOM/plugins` (by default `~/.oh-my-zsh/custom/plugins`)
+
+ ```sh
+ git clone git://github.com/tarruda/zsh-autosuggestions $ZSH_CUSTOM/plugins/zsh-autosuggestions
+ ```
+
+2. Add the plugin to the list of plugins for Oh My Zsh to load:
+
+ ```sh
+ plugins=(zsh-autosuggestions)
+ ```
+
+3. Start a new terminal session.
+
+**Note:** There is an open issue ([#102](https://github.com/tarruda/zsh-autosuggestions/issues/102)) when using this plugin with `bracketed-paste-magic`, which is enabled by default by Oh My Zsh. See the comments in that issue for a workaround.
## Usage
@@ -27,35 +54,14 @@ If you invoke the `forward-word` widget, it will partially accept the suggestion
## Configuration
-You may want to override the default global config variables. Default values of these variables can be found [here](src/config.zsh).
+You may want to override the default global config variables after sourcing the plugin. Default values of these variables can be found [here](src/config.zsh).
**Note:** If you are using Oh My Zsh, you can put this configuration in a file in the `$ZSH_CUSTOM` directory. See their comments on [overriding internals](https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals).
### Suggestion Highlight Style
-Set `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE` to configure the style that the suggestion is shown with. The default is `fg=8`, which will set the foreground color to color 8 from the [256-color palette](https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg). If your terminal only supports 8 colors, you will need to use a number between 0 and 7.
-
-Background color can also be set, and the suggestion can be styled bold, underlined, or standout. For example, this would show suggestions with bold, underlined, pink text on a cyan background:
-
-```sh
-ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE="fg=#ff00ff,bg=cyan,bold,underline"
-```
-
-For more info, read the Character Highlighting section of the zsh manual: `man zshzle` or [online](http://zsh.sourceforge.net/Doc/Release/Zsh-Line-Editor.html#Character-Highlighting).
-
-**Note:** Some iTerm2 users have reported [not being able to see the suggestions](https://github.com/zsh-users/zsh-autosuggestions/issues/416#issuecomment-486516333). If this affects you, the problem is likely caused by incorrect color settings. In order to correct this, go into iTerm2's setting, navigate to profile > colors and make sure that the colors for Basic Colors > Background and ANSI Colors > Bright Black are **different**.
-
-
-### Suggestion Strategy
-
-`ZSH_AUTOSUGGEST_STRATEGY` is an array that specifies how suggestions should be generated. The strategies in the array are tried successively until a suggestion is found. There are currently three built-in strategies to choose from:
-
-- `history`: Chooses the most recent match from history.
-- `completion`: Chooses a suggestion based on what tab-completion would suggest. (requires `zpty` module, which is included with zsh since 4.0.1)
-- `match_prev_cmd`: Like `history`, but chooses the most recent match whose preceding history item matches the most recently executed command ([more info](src/strategies/match_prev_cmd.zsh)). Note that this strategy won't work as expected with ZSH options that don't preserve the history order such as `HIST_IGNORE_ALL_DUPS` or `HIST_EXPIRE_DUPS_FIRST`.
-
-For example, setting `ZSH_AUTOSUGGEST_STRATEGY=(history completion)` will first try to find a suggestion from your history, but, if it can't find a match, will find a suggestion from the completion engine.
+Set `ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE` to configure the style that the suggestion is shown with. The default is `fg=8`.
### Widget Mapping
@@ -64,54 +70,19 @@ This plugin works by triggering custom behavior when certain [zle widgets](http:
- `ZSH_AUTOSUGGEST_CLEAR_WIDGETS`: Widgets in this array will clear the suggestion when invoked.
- `ZSH_AUTOSUGGEST_ACCEPT_WIDGETS`: Widgets in this array will accept the suggestion when invoked.
-- `ZSH_AUTOSUGGEST_EXECUTE_WIDGETS`: Widgets in this array will execute the suggestion when invoked.
- `ZSH_AUTOSUGGEST_PARTIAL_ACCEPT_WIDGETS`: Widgets in this array will partially accept the suggestion when invoked.
-- `ZSH_AUTOSUGGEST_IGNORE_WIDGETS`: Widgets in this array will not trigger any custom behavior.
-Widgets that modify the buffer and are not found in any of these arrays will fetch a new suggestion after they are invoked.
+Widgets not in any of these lists will update the suggestion when invoked.
**Note:** A widget shouldn't belong to more than one of the above arrays.
-### Disabling suggestion for large buffers
-
-Set `ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE` to an integer value to disable autosuggestion for large buffers. The default is unset, which means that autosuggestion will be tried for any buffer size. Recommended value is 20.
-This can be useful when pasting large amount of text in the terminal, to avoid triggering autosuggestion for strings that are too long.
-
-### Asynchronous Mode
-
-Suggestions are fetched asynchronously by default in zsh versions 5.0.8 and greater. To disable asynchronous suggestions and fetch them synchronously instead, `unset ZSH_AUTOSUGGEST_USE_ASYNC` after sourcing the plugin.
-
-Alternatively, if you are using a version of zsh older than 5.0.8 and want to enable asynchronous mode, set the `ZSH_AUTOSUGGEST_USE_ASYNC` variable after sourcing the plugin (it can be set to anything). Note that there is [a bug](https://github.com/zsh-users/zsh-autosuggestions/issues/364#issuecomment-481423232) in versions of zsh older than 5.0.8 where ctrl + c will fail to reset the prompt immediately after fetching a suggestion asynchronously.
-
-### Disabling automatic widget re-binding
-
-Set `ZSH_AUTOSUGGEST_MANUAL_REBIND` (it can be set to anything) to disable automatic widget re-binding on each precmd. This can be a big boost to performance, but you'll need to handle re-binding yourself if any of the widget lists change or if you or another plugin wrap any of the autosuggest widgets. To re-bind widgets, run `_zsh_autosuggest_bind_widgets`.
-
-### Ignoring history suggestions that match a pattern
-
-Set `ZSH_AUTOSUGGEST_HISTORY_IGNORE` to a [glob pattern](http://zsh.sourceforge.net/Doc/Release/Expansion.html#Glob-Operators) to prevent offering suggestions for history entries that match the pattern. For example, set it to `"cd *"` to never suggest any `cd` commands from history. Or set to `"?(#c50,)"` to never suggest anything 50 characters or longer.
-
-**Note:** This only affects the `history` and `match_prev_cmd` suggestion strategies.
-
-### Skipping completion suggestions for certain cases
-
-Set `ZSH_AUTOSUGGEST_COMPLETION_IGNORE` to a [glob pattern](http://zsh.sourceforge.net/Doc/Release/Expansion.html#Glob-Operators) to prevent offering completion suggestions when the buffer matches that pattern. For example, set it to `"git *"` to disable completion suggestions for git subcommands.
-
-**Note:** This only affects the `completion` suggestion strategy.
-
-
### Key Bindings
-This plugin provides a few widgets that you can use with `bindkey`:
+This plugin provides two widgets that you can use with `bindkey`:
1. `autosuggest-accept`: Accepts the current suggestion.
-2. `autosuggest-execute`: Accepts and executes the current suggestion.
-3. `autosuggest-clear`: Clears the current suggestion.
-4. `autosuggest-fetch`: Fetches a suggestion (works even when suggestions are disabled).
-5. `autosuggest-disable`: Disables suggestions.
-6. `autosuggest-enable`: Re-enables suggestions.
-7. `autosuggest-toggle`: Toggles between enabled/disabled suggestions.
+2. `autosuggest-clear`: Clears the current suggestion.
For example, this would bind ctrl + space to accept the current suggestion.
@@ -120,9 +91,41 @@ bindkey '^ ' autosuggest-accept
```
+## Compatibility With Other ZLE Plugins
+
+### [`zsh-history-substring-search`](https://github.com/zsh-users/zsh-history-substring-search)
+
+When the buffer is empty and one of the `history-substring-search-up/down` widgets is invoked, it will call the `up/down-line-or-history` widget. If the `up/down-line-or-history` widgets are in `ZSH_AUTOSUGGEST_CLEAR_WIDGETS` (the list of widgets that clear the suggestion), this can create an infinite recursion, crashing the shell session.
+
+For best results, you'll want to remove `up-line-or-history` and `down-line-or-history` from `ZSH_AUTOSUGGEST_CLEAR_WIDGETS`:
+
+```
+# Remove *-line-or-history widgets from list of widgets that clear the autosuggestion to avoid conflict with history-substring-search-* widgets
+ZSH_AUTOSUGGEST_CLEAR_WIDGETS=("${(@)ZSH_AUTOSUGGEST_CLEAR_WIDGETS:#(up|down)-line-or-history}")
+```
+
+Additionally, the `history-substring-search-up` and `history-substring-search-down` widgets are not bound by default. You'll probably want to add them to `ZSH_AUTOSUGGEST_CLEAR_WIDGETS` so that the suggestion will be cleared when you start searching through history:
+
+```sh
+# Add history-substring-search-* widgets to list of widgets that clear the autosuggestion
+ZSH_AUTOSUGGEST_CLEAR_WIDGETS+=(history-substring-search-up history-substring-search-down)
+```
+
+For example:
+
+```sh
+source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
+source ~/Code/zsh-history-substring-search/zsh-history-substring-search.zsh
+
+ZSH_AUTOSUGGEST_CLEAR_WIDGETS=("${(@)ZSH_AUTOSUGGEST_CLEAR_WIDGETS:#(up|down)-line-or-history}")
+ZSH_AUTOSUGGEST_CLEAR_WIDGETS+=(history-substring-search-up history-substring-search-down)
+```
+
+
## Troubleshooting
-If you have a problem, please search through [the list of issues on GitHub](https://github.com/zsh-users/zsh-autosuggestions/issues?q=) to see if someone else has already reported it.
+If you have a problem, please search through [the list of issues on GitHub](https://github.com/tarruda/zsh-autosuggestions/issues) to see if someone else has already reported it.
+
### Reporting an Issue
@@ -130,7 +133,7 @@ Before reporting an issue, please try temporarily disabling sections of your con
When reporting an issue, please include:
-- The smallest, simplest `.zshrc` configuration that will reproduce the problem. See [this comment](https://github.com/zsh-users/zsh-autosuggestions/issues/102#issuecomment-180944764) for a good example of what this means.
+- The smallest, simplest `.zshrc` configuration that will reproduce the problem. See [this comment](https://github.com/tarruda/zsh-autosuggestions/issues/102#issuecomment-180944764) for a good example of what this means.
- The version of zsh you're using (`zsh --version`)
- Which operating system you're running
@@ -157,7 +160,6 @@ Edit the source files in `src/`. Run `make` to build `zsh-autosuggestions.zsh` f
Pull requests are welcome! If you send a pull request, please:
-- Request to merge into the `develop` branch (*NOT* `master`)
- Match the existing coding conventions.
- Include helpful comments to keep the barrier-to-entry low for people new to the project.
- Write tests that cover your code as much as possible.
@@ -165,21 +167,9 @@ Pull requests are welcome! If you send a pull request, please:
### Testing
-Tests are written in ruby using the [`rspec`](http://rspec.info/) framework. They use [`tmux`](https://tmux.github.io/) to drive a pseudoterminal, sending simulated keystrokes and making assertions on the terminal content.
+Testing is performed with [`shunit2`](https://github.com/kward/shunit2) (v2.1.6). Documentation can be found [here](http://shunit2.googlecode.com/svn/trunk/source/2.1/doc/shunit2.html).
-Test files live in `spec/`. To run the tests, run `make test`. To run a specific test, run `TESTS=spec/some_spec.rb make test`. You can also specify a `zsh` binary to use by setting the `TEST_ZSH_BIN` environment variable (ex: `TEST_ZSH_BIN=/bin/zsh make test`).
-
-It's possible to run the tests for any supported version of zsh in a Docker image by building an image from the provided Dockerfile. To build the docker image for a specific version of zsh (where `This project is stored on code.google.com as http://code.google.com/p/shunit2/. +All releases as of 2.1.4 and full source are available there. Documentation is +included as part of the source and each release. Source code is stored in +Subversion and can be accessed using the following information.
+Browse the code in a web browser:
+Check out the code locally
++$ svn checkout http://shunit2.googlecode.com/svn/trunk/ shflags-read-only ++
DEPRECATED
+This project is stored on SourceForge as http://sf.net/projects/shunit2. The +source code is stored in Subversion and can be accessed using the following +information.
+Check out the code locally
++$ svn co https://shunit2.svn.sourceforge.net/svnroot/shunit2/trunk/source/2.1 shunit2 ++
Browse the code in a web browser:
+ +For these steps, it is assumed we are working with release 2.0.0.
+Steps:
+This should be pretty self explanatory. Use one of the release notes from a +previous release as an example.
+The versions of the various platforms and shells are included when the +master unit test script is run, or when bin/gen_test_results.sh is +used. To determine the versions of the installed shells by hand, use the +lib/versions script.
+Alternatively, do the following:
+| Shell | +OS | +Notes | +
|---|---|---|
| bash | ++ | $ bash --version | +
| dash | +Linux | +$ dpkg -l |grep dash | +
| ksh | ++ | $ ksh --version +-or- +$ echo 'echo $KSH_VERSION' |ksh | +
| Cygwin | +see pdksh | +|
| Solaris | +$ strings /usr/bin/ksh |grep 'Version' | +|
| pdksh | ++ | $ strings /bin/pdksh |grep 'PD KSH' | +
| Cygwin | +look in the downloaded Cygwin directory | +|
| sh | +Solaris | +not possible | +
| zsh | ++ | $ zsh --version | +
Edit src/shell/shunit2 and change the version number in the comment, as well +as in the SHUNIT_VERSION variable.
+Make sure that any remaining changes get put into the CHANGES-X.X.txt file.
+Finish writing the RELEASE_NOTES-X.X.X.txt. If necessary, run it +through the fmt command to make it pretty (hopefully it is already).
++$ fmt -w 80 RELEASE_NOTES-2.0.0.txt >RELEASE_NOTES-2.0.0.txt.new +$ mv RELEASE_NOTES-2.0.0.txt.new RELEASE_NOTES-2.0.0.txt ++
We want to have an up-to-date version of the documentation in the release, so +we'd better build it.
+
+$ pwd
+.../shunit2/source/2.1
+$ cd doc
+$ RST2HTML_OPTS='--stylesheet-path=rst2html.css'
+$ rst2html ${RST2HTML_OPTS} shunit2.txt >shunit2.html
+$ rst2html ${RST2HTML_OPTS} README.txt >README.html
+
+This step is pretty self-explanatory
++$ pwd +.../shunit2/source/2.0 +$ svn ci -m "finalizing release" ++
+$ pwd +.../shunit2/source +$ ls +2.0 2.1 +$ svn cp -m "Release 2.0.0" 2.0 https://shunit2.googlecode.com/svn/tags/source/2.0.0 ++
+$ pwd +.../shunit2/builds +$ svn export https://shunit2.googlecode.com/svn/tags/source/2.0.0 shunit2-2.0.0 ++
+$ tar cfz ../releases/shunit2-2.0.0.tgz shunit2-2.0.0 ++
+$ cd ../releases +$ gpg --default-key kate.ward@forestent.com --detach-sign shunit2-2.0.0.tgz ++
Again, pretty self-explanatory. Make sure to copy the GPG signature file. Once +that is done, make sure to tag the website so we can go back in time if needed.
++$ pwd +.../shunit2 +$ ls +source website +$ svn cp -m "Release 2.0.0" \ +website https://shunit2.googlecode.com/svn/tags/website/20060916 ++
Now, update the website. It too is held in Subversion, so ssh into the web +server and use svn up to grab the latest version.
+shUnit2 is a xUnit unit test framework for Bourne based shell scripts, and it +is designed to work in a similar manner to JUnit, PyUnit, etc.. If you have +ever had the desire to write a unit test for a shell script, shUnit2 can do the +job.
+Table of Contents
+shUnit2 was originally developed to provide a consistent testing solution for +log4sh, a shell based logging framework similar to log4j. During the +development of that product, a repeated problem of having things work just fine +under one shell (/bin/bash on Linux to be specific), and then not working +under another shell (/bin/sh on Solaris) kept coming up. Although several +simple tests were run, they were not adequate and did not catch some corner +cases. The decision was finally made to write a proper unit test framework after +multiple brown-bag releases were made. Research was done to look for an +existing product that met the testing requirements, but no adequate product was +found.
+Tested Operating Systems (varies over time)
+Tested Shells
+See the appropriate Release Notes for this release +(doc/RELEASE_NOTES-X.X.X.txt) for the list of actual versions tested.
+A list of contributors to shUnit2 can be found in the source archive in +doc/contributors.txt. Many thanks go out to all those who have contributed +to make this a better tool.
+shUnit2 is the original product of many hours of work by Kate Ward, the primary +author of the code. For other products by her, look up log4sh or shFlags, or +visit her website at http://forestent.com/.
+Feedback is most certainly welcome for this document. Send your additions, +comments and criticisms to the shunit2-users@google.com mailing list.
+This section will give a very quick start to running unit tests with shUnit2. +More information is located in later sections.
+Here is a quick sample script to show how easy it is to write a unit test in +shell. Note: the script as it stands expects that you are running it from the +``examples`` directory.
+
+#! /bin/sh
+# file: examples/equality_test.sh
+
+testEquality()
+{
+ assertEquals 1 1
+}
+
+# load shunit2
+. ../src/shell/shunit2
+
+Running the unit test should give results similar to the following.
++testEquality + +Ran 1 test. + +OK ++
W00t! You've just run your first successful unit test. So, what just happened? +Quite a bit really, and it all happened simply by sourcing the shunit2 +library. The basic functionality for the script above goes like this:
+We should now try adding a test that fails. Change your unit test to look like +this.
+
+#! /bin/sh
+# file: examples/party_test.sh
+
+testEquality()
+{
+ assertEquals 1 1
+}
+
+testPartyLikeItIs1999()
+{
+ year=`date '+%Y'`
+ assertEquals "It's not 1999 :-(" \
+ '1999' "${year}"
+}
+
+# load shunit2
+. ../src/shell/shunit2
+
+So, what did you get? I guess it told you that this isn't 1999. Bummer, eh? +Hopefully, you noticed a couple of things that were different about the second +test. First, we added an optional message that the user will see if the assert +fails. Second, we did comparisons of strings instead of integers as in the first +test. It doesn't matter whether you are testing for equality of strings or +integers. Both work equally well with shUnit2.
+Hopefully, this is enough to get you started with unit testing. If you want a +ton more examples, take a look at the tests provided with log4sh or shFlags. +Both provide excellent examples of more advanced usage. shUnit2 was after all +written to help with the unit testing problems that log4sh had.
+Any string values passed should be properly quoted -- they should must be +surrounded by single-quote (') or double-quote (") characters -- so that the +shell will properly parse them.
+Asserts that a given shell test condition is true. The condition can be as +simple as a shell true value (the value 0 -- equivalent to +${SHUNIT_TRUE}), or a more sophisticated shell conditional expression. The +message is optional, and must be quoted.
+A sophisticated shell conditional expression is equivalent to what the if +or while shell built-ins would use (more specifically, what the test +command would use). Testing for example whether some value is greater than +another value can be done this way.
++assertTrue "[ 34 -gt 23 ]" ++
Testing for the ability to read a file can also be done. This particular test +will fail.
++assertTrue 'test failed' "[ -r /some/non-existant/file' ]" ++
As the expressions are standard shell test expressions, it is possible to +string multiple expressions together with -a and -o in the standard +fashion. This test will succeed as the entire expression evaluates to true.
++assertTrue 'test failed' '[ 1 -eq 1 -a 2 -eq 2 ]' ++
One word of warning: be very careful with your quoting as shell is not the +most forgiving of bad quoting, and things will fail in strange ways.
+Asserts that a given shell test condition is false. The condition can be +as simple as a shell false value (the value 1 -- equivalent to +${SHUNIT_FALSE}), or a more sophisticated shell conditional expression. +The message is optional, and must be quoted.
+For examples of more sophisticated expressions, see ``assertTrue``.
+Just to clarify, failures do not test the various arguments against one +another. Failures simply fail, optionally with a message, and that is all they +do. If you need to test arguments against one another, use asserts.
+If all failures do is fail, why might one use them? There are times when you may +have some very complicated logic that you need to test, and the simple asserts +provided are simply not adequate. You can do your own validation of the code, +use an assertTrue ${SHUNIT_TRUE} if your own tests succeeded, and use a +failure to record a failure.
+Fails the test immediately, reporting that the unexpected and actual +values are not equal to one another. The message is optional, and must be +quoted.
+Note: no actual comparison of unexpected and actual is done.
+Fails the test immediately, reporting that the expected and actual values +are the same. The message is optional, and must be quoted.
+Note: no actual comparison of expected and actual is done.
+Fails the test immediately, reporting that the expected and actual values +are not the same. The message is optional, and must be quoted.
+Note: no actual comparison of expected and actual is done.
+This function can be be optionally overridden by the user in their test suite.
+If this function exists, it will be called once before any tests are run. It +is useful to prepare a common environment for all tests.
+This function can be be optionally overridden by the user in their test suite.
+If this function exists, it will be called once after all tests are completed. +It is useful to clean up the environment after all tests.
+This function can be be optionally overridden by the user in their test suite.
+If this function exists, it will be called before each test is run. It is +useful to reset the environment before each test.
+This function can be be optionally overridden by the user in their test suite.
+If this function exists, it will be called after each test completes. It is +useful to clean up the environment after each test.
+The default behavior of shUnit2 is that all tests will be found dynamically. If +you have a specific set of tests you want to run, or you don't want to use the +standard naming scheme of prefixing your tests with test, these functions +are for you. Most users will never use them though.
+This function can be optionally overridden by the user in their test suite.
+If this function exists, it will be called when shunit2 is sourced. If it +does not exist, shUnit2 will search the parent script for all functions +beginning with the word test, and they will be added dynamically to the +test suite.
+This section covers several advanced usage topics.
+There are several constants provided by shUnit2 as variables that might be of +use to you.
+Predefined
+| SHUNIT_VERSION | +The version of shUnit2 you are running. | +
| SHUNIT_TRUE | +Standard shell true value (the integer value 0). | +
| SHUNIT_FALSE | +Standard shell false value (the integer value 1). | +
| SHUNIT_ERROR | +The integer value 2. | +
| SHUNIT_TMPDIR | +Path to temporary directory that will be automatically +cleaned up upon exit of shUnit2. | +
User defined
+| SHUNIT_PARENT | +The filename of the shell script containing the tests. This +is needed specifically for Zsh support. | +
The constants values SHUNIT_TRUE, SHUNIT_FALSE, and SHUNIT_ERROR are +returned from nearly every function to indicate the success or failure of the +function. Additionally the variable flags_error is filled with a detailed +error message if any function returns with a SHUNIT_ERROR value.
+If you include lots of assert statements in an individual test function, it can +become difficult to determine exactly which assert was thrown unless your +messages are unique. To help somewhat, line numbers can be included in the +assert messages. To enable this, a special shell "macro" must be used rather +than the standard assert calls. Shell doesn't actually have macros; the name is +used here as the operation is similar to a standard macro.
+For example, to include line numbers for a assertEquals() function call, +replace the assertEquals() with ${_ASSERT_EQUALS_}.
+Example -- Asserts with and without line numbers
+
+#! /bin/sh
+# file: examples/lineno_test.sh
+
+testLineNo()
+{
+ # this assert will have line numbers included (e.g. "ASSERT:[123] ...")
+ echo "ae: ${_ASSERT_EQUALS_}"
+ ${_ASSERT_EQUALS_} 'not equal' 1 2
+
+ # this assert will not have line numbers included (e.g. "ASSERT: ...")
+ assertEquals 'not equal' 1 2
+}
+
+# load shunit2
+. ../src/shell/shunit2
+
+Notes:
+Due to how shell parses command-line arguments, all strings used with macros +should be quoted twice. Namely, single-quotes must be converted to +single-double-quotes, and vice-versa. If the string being passed is +absolutely for sure not empty, the extra quoting is not necessary.
+Normal assertEquals call.
++assertEquals 'some message' 'x' '' ++
Macro _ASSERT_EQUALS_ call. Note the extra quoting around the message +and the null value.
++_ASSERT_EQUALS_ '"some message"' 'x' '""' ++
Line numbers are not supported in all shells. If a shell does not support +them, no errors will be thrown. Supported shells include: bash (>=3.0), +ksh, pdksh, and zsh.
+There are times where the test code you have written is just not applicable to +the system you are running on. This section describes how to skip these tests +but maintain the total test count.
+Probably the easiest example would be shell code that is meant to run under the +bash shell, but the unit test is running under the Bourne shell. There are +things that just won't work. The following test code demonstrates two sample +functions, one that will be run under any shell, and the another that will run +only under the bash shell.
+Example -- math include
+
+# available as examples/math.inc
+
+add_generic()
+{
+ num_a=$1
+ num_b=$2
+
+ expr $1 + $2
+}
+
+add_bash()
+{
+ num_a=$1
+ num_b=$2
+
+ echo $(($1 + $2))
+}
+
+And here is a corresponding unit test that correctly skips the add_bash() +function when the unit test is not running under the bash shell.
+Example -- math unit test
+
+#! /bin/sh
+# available as examples/math_test.sh
+
+testAdding()
+{
+ result=`add_generic 1 2`
+ assertEquals \
+ "the result of '${result}' was wrong" \
+ 3 "${result}"
+
+ # disable non-generic tests
+ [ -z "${BASH_VERSION:-}" ] && startSkipping
+
+ result=`add_bash 1 2`
+ assertEquals \
+ "the result of '${result}' was wrong" \
+ 3 "${result}"
+}
+
+oneTimeSetUp()
+{
+ # load include to test
+ . ./math.inc
+}
+
+# load and run shUnit2
+. ../src/shell/shunit2
+
+Running the above test under the bash shell will result in the following +output.
++$ /bin/bash math_test.sh +testAdding + +Ran 1 test. + +OK ++
But, running the test under any other Unix shell will result in the following +output.
++$ /bin/ksh math_test.sh +testAdding + +Ran 1 test. + +OK (skipped=1) ++
As you can see, the total number of tests has not changed, but the report +indicates that some tests were skipped.
+Skipping can be controlled with the following functions: startSkipping(), +stopSkipping(), and isSkipping(). Once skipping is enabled, it will +remain enabled until the end of the current test function call, after which +skipping is disabled.
+For help, please send requests to either the shunit2-users@googlegroups.com +mailing list (archives available on the web at +http://groups.google.com/group/shunit2-users) or directly to +Kate Ward <kate dot ward at forestent dot com>.
+For compatibility with Zsh, there is one requirement that must be met -- the +shwordsplit option must be set. There are three ways to accomplish this.
+In the unit-test script, add the following shell code snippet before sourcing +the shunit2 library.
++setopt shwordsplit ++
When invoking zsh from either the command-line or as a script with +#!, add the -y parameter.
++#! /bin/zsh -y ++
When invoking zsh from the command-line, add -o shwordsplit -- as +parameters before the script name.
++$ zsh -o shwordsplit -- some_script ++