Package names may only contain lowercase letters and hyphens to separate words. To scaffold out a new package:
```fish
$ omf new pkg my_package
my_package/
README.md
my_package.fish
completions/my_package.fish
```
> Use `omf new theme my_theme` for themes.
Please provide [auto completion](http://fishshell.com/docs/current/commands.html#complete) for your utilities if applicable and describe how your package works in the `README.md`.
To learn package creation let's create a new package that will provide a `hello_world` command for your shell. Package names may only contain lowercase letters and hyphens to separate words.
`my_package.fish` defines a single function:
Oh My Fish can scaffold a package structure for you. Use the command `omf new`:
```fish
function my_package -d "My package"
end
$ omf new pkg hello_world
```
> Bear in mind that fish lacks a private scope so consider the following options to avoid polluting the global namespace:
+ Prefix functions: `my_package_my_func`.
+ Using [blocks](http://fishshell.com/docs/current/commands.html#block).
> Use `omf new theme my_theme_name` for themes.
The utily changes the current directory to the newly created package:
## Submitting
```
$ ls -l
README.md
hello_world.fish
completions/hello_world.fish
```
Oh My Fish keeps a registry of packages under `$OMF_PATH/db/`.
Always describe how your package works in the `README.md`. Also read more about [auto completion](http://fishshell.com/docs/current/commands.html#complete) and also take care to provide it for your utilities when applicable.
To create a new entry run:
`hello_world.fish` defines a single function:
```fish
omf submit pkg/my_package .../my_package.git
function hello_world -d "Prints hello world"
echo "Hello World!"
end
```
Similarly for themes use:
Each function in your package must be declared in its own file. This is required by fish autoloading mechanism, which loads functions on demand, avoiding loading unused functions.
```fish
omf submit theme/my_theme .../my_theme.git
```
Bear in mind that fish lacks a private scope, so if you need to split your package into functions, consider prefixing private functions like this: `__hello_world.my_extra_function`, to avoid both name clashes and global namespace pollution.
This will add a new entry to your local copy of the registry. Please [send us a PR][omf-pulls-link] to update the global registry.
# Events
Packages were designed to take advantages of fish events. There are currently two events that Oh My Fish will emit to your package:
## Initialization
If you want to be [notified](http://fishshell.com/docs/current/commands.html#emit) when your package loads, declare the following function in your `my_package.fish`:
If you want to be [notified](http://fishshell.com/docs/current/commands.html#emit) when your package loads, declare the following function in your `hello_world.fish`:
```fish
function init -a path --on-event init_mypkg
function init -a path --on-event init_hello_world
echo "hello_world initialized"
end
```
@ -64,9 +54,26 @@ Use this event to modify the environment, load resources, autoload functions, et
Oh My Fish emits `uninstall_<pkg>` events before a package is removed via `omf remove <pkg>`. Subscribers can use the event to clean up custom resources, etc.
```fish
function uninstall --on-event uninstall_pkg
function uninstall --on-event uninstall_hello_world
end
```
# Make it public
Oh My Fish keeps a registry of public packages under `$OMF_PATH/db/`.
To add your package to the registry you need to:
```fish
# For packages:
omf submit pkg/hello_world .../hello_world.git
# For themes
omf submit theme/my_theme .../my_theme_name.git
```
This will add a new entry to your local copy of the registry. Now you just need to [send us a PR][omf-pulls-link] to update the global registry.
Derek Stavis
9 years ago