path: root/dot_local/share/toasty/README.adoc

:icons: font
:source-highlighter: pygments
:toc: preamble

// Links
:license: LICENSE.md
:example: examples/zshrc.local

:img-license: https://img.shields.io/github/license/5pacetoast/toasty-zsh.svg

:license-omz: third-party-licenses/LICENSE.OMZ.md
:license-pure: third-party-licenses/LICENSE.pure.txt
:license-purer: third-party-licenses/LICENSE.purer.txt
:license-shellder: third-party-licenses/LICENSE.shellder.txt

:repo-omz: https://github.com/robbyrussell/oh-my-zsh[Oh My Zsh]
:repo-pure: https://github.com/sindresorhus/pure[Pure]
:repo-purer: https://github.com/dfurnes/purer[Purer]
:repo-shellder: https://github.com/simnalamburt/shellder[Shellder]

:brpaste: https://brpaste.xyz[BRPaste]
:sprunge: http://sprunge.us[Sprunge]
:zshwiki: http://zshwiki.org[Zsh Wiki]

// Github-specific workarounds
ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]

= Toasty Zsh

image::{img-license}[License, link={license}]

The zsh framework made to facilitate management, not dictate it.

== Quickstart
1. Clone this repository somewhere
2. `echo ZDOTDIR=/path/to/repo > ~/.zshenv`
3. Restart your z shell

=== Expanding on it
- Drop files you want to be sourced during startup into `$zd/source/`
- Drop functions you want to potentially use/autoload into `$zd/functions/`
- Drop plugins you want to source on-demand into `$zd/plugins/`
- Drop custom completions into `$zd/completions/`
- Drop custom prompts into `$zd/prompts/`

NOTE: Most of these are for mindspace separation, the completions, prompts and functions directories are functionally identical, and as such you can use any of them for any purpose.

WARNING: Don't run compinit yourself! It happens at the very end (after sourcing `zshrc.local`) as is. All it'll do is make your performance worse.

NOTE: If you want `$zd` to be anywhere but `~/.zsh`, set it in `~/.zshenv`.

=== Full List of Supported Installation Methods
==== Local
- Setting `$ZDOTDIR` (usually in `~/.zshenv`) to point to the repository.
+
WARNING: This may, however, dirty your repository, depending on what `$ZDOTDIR` ends up being used for.
- Sourcing `zshrc` in `~/.zshrc`.
- Linking `zshrc` to `~/.zshrc`.

==== Global
- Cloning toasty-zsh into `/etc/zsh` (on distributions with sane/common zsh defaults).
- Sourcing `zshrc` in `/etc/zsh/zshrc`.
- Linking `zshrc` to `/etc/zsh/zshrc`.

WARNING: You may want to `touch ~/.zshrc` when installing globally, to avoid zsh complaining about it being missing.

NOTE: If you have a global install of toasty-zsh, or some other framework, and have a local version, you can `setopt NO_GLOBAL_RCS` in `~/.zshenv` to skip loading the global variant.

== Structure
Toasty Zsh provides a structure under `~/.zsh` for you to use. Everything except `zshrc.local` is optional.

`$zshd`:: Dynamically set to wherever the Toasty Zsh repository copy is.
`$zd`:: Your "Z Directory". Set to `~/.zsh` by default. The rest of this list is inside of this.
completions/:: Added to your `$fpath`. Serves to put custom completions into without muddying up your functions.
functions/:: Added to your `$fpath`. Serves to put your functions into, for autoloading.
plugins/:: Added to your `$spath`. Serves for optionally-sourced plugins. See <<Autosource>> for more details.
prompts/:: Added to your `$fpath`. Serves to throw your custom prompts into without muddying up your functions.
source/:: Added to your `$apath`. Serves for automatic sourcing on-demand/startup. See <<Sourceall>> for more details.
pre:: Sourced right before running <<Sourceall>>, giving you a chance to edit the sane-default `${fpath,spath,apath}` values.
zshrc.local:: Sourced right before compinit.

== API
=== Functions
Various functions for use. Some are used internally.

NOTE: Enabling (autoloading) a function in zsh defers loading - it makes the function available from the moment you do it, but it won't be actually loaded until you first use it, making them much more efficient than sourced files.

==== Autosource
Iterates over `$spath` until it finds a matching `$1`, then sources it.

Examples:
[source,sh]
----
spath=( "$PWD" ) autosource a # <1>
spath=( a b ) autosource c # <2>
spath=( "$PWD" ) autosource foo/bar # <3>
----
<1> will source `./a` if it exists
<2> will source `./a/c`, and then `./b/c` if that fails
<3> will source `./foo/bar` if it exists

WARNING: Relative entries will always be relative. If you set `$spath` to `.` and then change directories, it'll continue using `.`, which is potentially insecure.

NOTE: For convenience's sake, `$spath` and `$SPATH` are bound - you can manipulate `$SPATH` (which is formatted like `$PATH`) to modify `$spath`.

==== Sourceall
Will source every file in every directory in `$apath`. If an argument is provided, will only source files that end in `.$1`.

Examples:
[source,sh]
----
apath=( a b ) sourceall # <1>
apath=( "$PWD" ) sourceall zsh # <2>
----
<1> will source `a/*` and `b/*`
<2> will source `./*.zsh`

NOTE: By default, Toasty Zsh will run `sourceall zsh` between sourcing `$zd/pre` and `zshrc.local`. By default, it only goes through `$zshd/source` and `$zd/source`. You can customize this behavior in `$zd/pre`.

WARNING: Sourceall does not recurse into subdirectories, though you can work around that by adding a `99-subdir.zsh` file or similar where you call it with a custom `$apath` set.

NOTE: As with `$spath`, `$apath` is bound to a `$PATH`-like `$APATH`.

==== Brpaste
Simple wrapper around {brpaste}.
Takes thing in stdin, or uses the first argument as the file to upload.
Outputs the paste url.

Examples:
[source,sh]
----
echo hi | brpaste # <1>
brpaste file # <2>
bsdtar -cf- --format shar dir | brpaste # <3>
brpaste file | xsel -ib # <4>
----
<1> upload "hi\n" to brpaste.xyz
<2> upload file to brpaste.xyz
<3> upload a "shar" archive of dir to brpaste.xyz
<4> upload file to brpaste.xyz and place the non-raw link into the clipboard

==== Sprunge
Simple wrapper around {sprunge}. Takes things in stdin, outputs the url into stdout.

Examples:
[source,sh]
----
echo hi | sprunge # <1>
sprunge < file # <2>
bsdtar -cf - --format shar dir | sprunge # <3>
----
<1> upload `"hi\n"` to sprunge.us
<2> upload file to sprunge.us
<3> upload a "shar" archive of dir to sprunge.us

=== Plugins
Plugins are just files you source! See <<Autosource>> for a convenient way to do so.

You can add your own by dropping them into a directory in your `$spath` (such as  `$zd/plugins`).

==== Sudo
Press `<esc>` twice to either add or remove `sudo` from the beginning of your line.

If the current line is empty, operates on the previous line instead.

==== Xterm-Title
Sets up a simple hook system to print what's currently being executed into an xterm-compatible terminal's title.

WARNING: some prompts (such as {repo-pure}) do this for you aleady! If you use both, they won't conflict, but you'd be wasting cycles *and* might see some strange text flashing through on every command.

== External Projects
I didn't write everything in here, some of it is bundled.

Note that you do not pay (except with drive space) for most of these unless you choose to use them.

=== Plugins

Sudo:: From {repo-omz}.

=== Prompts

Pure:: From {repo-pure}.
Purer:: From {repo-purer}.
Shellder:: From {repo-shellder}.
Toasty:: Written from scratch by me, but takes heavy inspiration from robbyrussel's theme from {repo-omz}.

=== Other

`bindkeys.zsh`:: Written by me, but heavily inspired by similar content from {repo-omz} and the {zshwiki}.

=== Licenses

- Oh My Zsh link:{license-omz}[LICENSE]
- Pure link:{license-pure}[LICENSE]
- Purer link:{license-purer}[LICENSE]
- Shellder link:{license-shellder}[LICENSE]