From 2926f4a09914a818bbe2323fdecbcd2efe292aba Mon Sep 17 00:00:00 2001
From: Michael Aaron Murphy <mmstickman@gmail.com>
Date: Sat, 25 Mar 2017 13:32:06 -0400
Subject: [PATCH] Update READMEs
---
README.md | 47 +++++++++++++++++++++++++++----
src/parser/README.md | 15 +++++-----
src/parser/shell_expand/README.md | 17 +++++++++++
3 files changed, 67 insertions(+), 12 deletions(-)
create mode 100644 src/parser/shell_expand/README.md
diff --git a/README.md b/README.md
index 7a42cd12..2f01c908 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,37 @@
# Ion Shell
-Ion is the underlying library for shells and command execution in
-Redox, as well as the default shell.
[](https://travis-ci.org/redox-os/ion)
[](./LICENSE)
[](https://coveralls.io/github/redox-os/ion?branch=master)
[](https://crates.io/crates/ion-shell)
+Ion is a shell for UNIX platforms, and is the default shell in Redox. It is still a work in progress, but much of the
+core functionality is complete. Features below:
+
+- [x] Shell Expansion
+- [x] Flow Control
+- [x] Aliases
+- [x] Variables
+- [x] Functions
+- [ ] Arrays
+- [ ] Maps
+- [x] For Loops
+- [ ] Foreach Loops
+- [x] While Loops
+- [x] If Conditionals
+- [x] Piping Stdout/Stderr
+- [x] Redirecting Stdout/Stderr
+- [x] && and || Conditionals
+- [x] Background Jobs
+- [ ] Background Jobs Control
+- [ ] Signal Handling
+- [ ] Autosuggestions
+- [ ] Syntax Highlighting
+- [x] Multiline Comments and Commands
+- [ ] Multiline Editing
+- [x] Tab Completion (Needs Improvements)
+- [ ] Unescape sequences like '\n' and '\t'
+
## Shell Syntax
### Defining Variables
@@ -192,12 +217,22 @@ end
for _ in 1..10
do_something
end
+
+# Brace Ranges
+for a in {1..10}
+ echo $a
+end
+
+# Globbing
+for a in *
+ echo $a
+end
```
### Functions
Functions in the Ion shell are defined with a name along with a set of variables. The function
-will check if the corrent number of arguments were supplied and execute if all arguments
+will check if the correct number of arguments were supplied and execute if all arguments
were given.
```ion
@@ -223,8 +258,10 @@ end
### Brace Expansion
-It is possible to perform brace expansions within the Ion shell. Currently, only permutation braces are supported.
+Brace expansion is used to create permutations of a given input. In addition to simple permutations, Ion supports
+brace ranges and nested branches.
```ion
-echo abc{1,2,3}def{456,789,101112}
+echo abc{3..1}def{1..3,a..c}
+echo ghi{one{a,b,c},two{d,e,f}}
```
diff --git a/src/parser/README.md b/src/parser/README.md
index 45f89fec..9793d6f7 100644
--- a/src/parser/README.md
+++ b/src/parser/README.md
@@ -3,12 +3,14 @@
This module handles all of the parsing logic within the Ion shell. The following is the strategy currently in use:
1. Parse supplied commands into individual statements using the `StatementSplitter`.
-2. Map each individual statement to their equivalent `Statement` enum using the peg parser.
-3. Later expand shell expressions where required using the `expand_string()` function.
+2. Print error if statement contains a syntax error, otherwise pass valid statement on.
+3. Map each individual statement to their equivalent `Statement` enum using the peg parser.
+4. Later expand shell expressions where required using the `expand_string()` function.
## Parsing Statements
-First, inputs received by the shell should be parsed with the `StatementSplitter` in the `statements` module. A statement is any command that is separated by a `;`.
+First, inputs received by the shell should be parsed with the `StatementSplitter` in the `statements` module. A statement is any command that is separated by a `;`. Syntax errors are also detected in the `StatementSplitter`, where if an error is found, that statement will be skipped,
+and an error message will be printed.
Given the following command:
@@ -60,7 +62,6 @@ For loops within Ion work uniquely compared to other shells, in that not only do
### Shell Expansion
-This is one of the most important pieces of the parsing puzzle outside of the basic grammar. The purpose of the `shell_expand` module is to supply a generic expansion library that performs all shell expansions throughout the shell.
-
-- The `ForExpression` parser uses the `shell_expand` module to expand the supplied expression before evaluating it.
-- Pipelines are also expanded before
+The purpose of the `shell_expand` module is to supply a generic expansion library that performs all shell expansions
+throughout the shell. It reduces statements into a set of primitive words, and applies specific expansion rules
+accordingly.
diff --git a/src/parser/shell_expand/README.md b/src/parser/shell_expand/README.md
new file mode 100644
index 00000000..66a802cc
--- /dev/null
+++ b/src/parser/shell_expand/README.md
@@ -0,0 +1,17 @@
+# Shell Expand Module
+
+This module reduces statements into a set of word token primitives, and applies expansions to these tokens accordingly.
+In order to be modular, the expansion logic is supplied with a structure containing closure references, which are
+provided higher up by the shell.
+
+## Tokenizing Words
+
+The `words` module contains the `WordIterator` which reduces statments into set of `WordTokens`. The following are
+supported word tokens:
+
+- `Normal(&str)`: Normal words that do not require any expansion at all
+- `Whitespace(&str)`: Whitespace between words
+- `Variable(&str, bool)`: A variable name and an indication of if it was quoted
+- `Process(&str, bool)`: A subshell and an indication of if it was quoted
+- `Tilde(&str)`: A tilde expression such as ~ or ~user
+- `Brace(Vec<&str>)`: A brace expansion and each of its inner elements
--
GitLab