mirror of
https://github.com/oh-my-fish/oh-my-fish.git
synced 2024-12-03 06:23:41 +08:00
a164ebdd5d
* init: rewrite init process Now use pure globbing to generate 100% valid function and completion paths, effectively splitting the init process in two steps, one which paths are added, and other when initialization is done (sourcing init). This initialization code introduces a new interface for `init.fish` hook, which deprecates the previously used event model. The new interface injects three variables into `init.fish`: path, package and bundle. This variables can be used by the package to autoload paths, use bundled files, etc. Also supports key bindings by sourcing $OMF_CONFIG/key_bindings.fish and also key_bindings.fish in packages (plugins and themes) root directories. This is done when fish_user_key_bindings is called. * omf: migrate to new init hook * omf/templates: migrate to new init and uninstall hooks * docs: document new init and uninstall hooks interface * README: update new hook interface spec
97 lines
3.1 KiB
Markdown
97 lines
3.1 KiB
Markdown
<div align="center">
|
|
<a href="http://github.com/oh-my-fish/oh-my-fish">
|
|
<img width=120px src="https://cloud.githubusercontent.com/assets/8317250/8510172/f006f0a4-230f-11e5-98b6-5c2e3c87088f.png">
|
|
</a>
|
|
</div>
|
|
|
|
<br>
|
|
|
|
<p align="center">
|
|
<b>English</b> •
|
|
<a href="../zh-CN/Packages.md">简体中文</a> •
|
|
<a href="../ru-RU/Packages.md">Русский</a>
|
|
</p>
|
|
|
|
# Creating
|
|
|
|
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.
|
|
|
|
Oh My Fish can scaffold a package structure for you. Use the command `omf new`:
|
|
|
|
```fish
|
|
$ omf new pkg hello_world
|
|
```
|
|
|
|
> Use `omf new theme my_theme_name` for themes.
|
|
|
|
The utily changes the current directory to the newly created package:
|
|
|
|
```
|
|
$ ls -l
|
|
README.md
|
|
hello_world.fish
|
|
completions/hello_world.fish
|
|
```
|
|
|
|
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 take care to provide it for your utilities when applicable.
|
|
|
|
`hello_world.fish` defines a single function:
|
|
|
|
```fish
|
|
function hello_world -d "Prints hello world"
|
|
echo "Hello World!"
|
|
end
|
|
```
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
# 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 code to be executed when the package loads, you can add code to `init.fish` file at package's root directory:
|
|
|
|
```fish
|
|
echo "hello_world initialized"
|
|
```
|
|
|
|
Inside this hook runs you can access three package-related variables:
|
|
|
|
* `$package`: Package name
|
|
* `$path`: Package installation path
|
|
* `$dependencies` : Package dependencies
|
|
|
|
Use this hook to modify the environment, load resources, autoload functions, etc. If your package does not export any function, you can still use this event to add functionality to your package, or dynamically create functions.
|
|
|
|
## Uninstall
|
|
|
|
Oh My Fish also features `uninstall.fish` hook, which is called before a package is removed via `omf remove <pkg>`. Packages can use this hook to clean up custom resources, etc.
|
|
|
|
Inside this hook you can access one package-related variable:
|
|
|
|
* `$path`: Package installation path
|
|
|
|
|
|
# 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.
|
|
|
|
|
|
[omf-pulls-link]: https://github.com/oh-my-fish/oh-my-fish/pulls
|