Commit e033ca1c authored by matu3ba's avatar matu3ba
Browse files

fix(manual): section general rules and REPL instead of misc + rewordings

parent 4ec281c7
......@@ -4,16 +4,9 @@
- [Migrating from POSIX shells](migrating.md)
- [Miscellaneous](misc/index.md)
- [Implicit `cd`](misc/01-implicitcd.md)
- [XDG App Directories](misc/02-xdg.md)
- [Quoting Rules](misc/03-quotation.md)
- [Multi-line Arguments](misc/04-multiargs.md)
- [Multi-line Strings](misc/05-multiline-strings.md)
- [Prompt Function](misc/06-prompt_fn.md)
- [Key Bindings](misc/07-keybindings.md)
- [General Tips](misc/08-general.md)
- [General rules](general.md)
- [Read–eval–print loop](repl.md)
- [Variables](variables/00-variables.md)
......
# XDG App Dirs Support
# General rules
All files created by Ion can be found in their respective XDG application directories. In example,
## Performance: Let Arithmetic vs Arithmetic Expansions
**let** arithmetic is generally faster than **$(())** expansions. The arithmetic expansions
should be used for increasing readability, or more complex arithmetic. If speed is important:
Multiple *let arithmetic statements will tend to be faster* than a single arithmetic expansion.
## Quoting Rules
- Variables are expanded in double quotes, but not single quotes.
- Braces are expanded when unquoted, but not when quoted.
## XDG App Dirs Support
All files created by Ion can be found in their respective XDG application directories. For example,
the init file for Ion can be found in **$HOME/.config/ion/initrc** on Linux systems; and the
history file can be found at **$HOME/.local/share/ion/history**. On the first launch of Ion, a
message will be given to indicate the location of these files.
......@@ -9,15 +9,18 @@ platforms, and we are currently searching for a Windows developer to port it to
# Goals
Syntax and feature decisions for Ion are made based upon three measurements: is the feature useful,
is it simple to use, and will it's implementation be efficient to parse and execute? A feature is
considered useful if there's a valid use case for it, in the concept of a shell language. The
Syntax and feature decisions for Ion are made based upon three measurements:
1. Is the feature useful?
2. Is it simple to use?
3. Will it's implementation be efficient to parse and execute?
A feature is considered useful if there's a valid use case for it, in the concept of a shell language. The
syntax for the feature should be simple for a human to read and write, with extra emphasis on
readability, given that most time is spent reading scripts than writing them. The implementation
should require minimal to zero heap allocations, and be implemented in a manner that requires
minimal CPU cycles (so long as it's also fully documented and easy to maintain!).
readability, given that **most time is spent reading scripts** than writing them. The implementation
should require *minimal to zero heap allocations*, and be implemented in a manner that requires
*minimal CPU cycles* (so long as it's also **fully documented** and **easy to maintain**!).
It should also be taken into consideration that shells operate entirely upon strings, and therefore
It should also be taken into consideration that *shells operate entirely upon strings*, and therefore
should be fully equipped for all manner of string manipulation capabilities. That means that users
of a shell should not immediately need to grasp for tools like **cut**, **sed**, and **awk**. Ion
offers a great deal of control over slicing and manipulating text. Arrays are treated as first
......
# Implicit `cd`
Like the [Friendly Interactive Shell](https://fishshell.com/), Ion also supports
executing the `cd` command automatically
when given a path. Paths are denoted by beginning with `.`/`/`/`~`, or ending with `/`.
```sh
~/Documents # cd ~/Documents
.. # cd ..
.config # cd .config
examples/ # cd examples/
```
# Quoting Rules
- Variables are expanded in double quotes, but not single quotes.
- Braces are expanded when unquoted, but not when quoted.
# Multi-line Arguments
If a line in your script becomes too long, you may signal to Ion to continue reading the next line
by appending an `\` character at the end of the line. This will ignore newlines.
```sh
command arg arg2 \
arg3 arg4 \
arg 5
```
# Multi-line Strings
If a string needs to contain newlines, you may do so by having an open quote, as Ion will only
begin parsing supplied commands that are terminated. Either double or single quotes may be used
for this purpose, depending on which quoting rules that you need.
```sh
echo "This is the first line
this is the second line
this is the third line"
```
# Prompt Function
The prompt may optionally be generated from a function, instead of a string. Take note, however,
that prompts generated from functions aren't as efficient, due to the need to perform a fork and
capture the output of the fork to use as the prompt. To use a function for generating the prompt,
simply create a function whose name is **PROMPT**, and the output of that command will be used as
the prompt. Below is an example:
```
fn PROMPT
echo -n "${PWD}# "
end
```
# Key Bindings
There are two pre-set key maps available: Emacs (default) and Vi.
You can switch between them with the `keybindings` built-in command.
```
keybindings vi
keybindings emacs
```
## Vi Mode Prompt Indicators
In the Vi mode, you can define the displayed indicator for normal and insert modes
with the following variables:
```
$ export VI_NORMAL = "[=] "
$ export VI_INSERT = "[+] "
$ keybindings vi
[+] $
```
# General Tips
## Let Arithmetic vs Arithmetic Expansions
Using **let** arithmetic is generally faster than **$(())** expansions. The arithmetic expansions
should be used for increasing readability, or more complex arithmetic; but if speed is important,
multiple let arithmetic statements will tend to be faster than a single arithmetic expansion.
# Read-eval-print loop
## Implicit `cd`
Like the [Friendly Interactive Shell](https://fishshell.com/), Ion also supports
executing the `cd` command automatically
when given a path. Paths are denoted by beginning with `.`/`/`/`~`, or ending with `/`.
```sh
~/Documents # cd ~/Documents
.. # cd ..
.config # cd .config
examples/ # cd examples/
```
## Multi-line Arguments
If a line in your script becomes too long, appending `\` will make Ion ignore newlines
and continue reading the next line.
```sh
command arg arg2 \
arg3 arg4 \
arg 5
```
## Multi-line Strings
If a string needs to contain newlines, you use an open quote. Ion will only
begin parsing supplied commands that are terminated. Either double or single quotes can be used.
```sh
echo "This is the first line
this is the second line
this is the third line"
```
## Prompt Function
The prompt may optionally be generated from a function, instead of a string. Due to the need to
perform a fork an capture of its output as prompt, prompts generated from functions aren't as
efficient. Below the requirement to use the function with name **PROMPT**:
```sh
fn PROMPT
echo -n "${PWD}# "
end
```
## Key Bindings
There are two pre-set key maps available: **Emacs (default)** and **Vi**.
You can switch between them with the `keybindings` built-in command.
```sh
keybindings vi
keybindings emacs
```
**Vi keybinding**: You can define the displayed indicator for normal and insert modes
with the following variables:
```sh
$ export VI_NORMAL = "[=] "
$ export VI_INSERT = "[+] "
$ keybindings vi
[+] $
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment