Skip to content

Commit 2801deb

Browse files
beccasaurusbeccasaurus
committed
Working on documentation
1 parent 4271b80 commit 2801deb

17 files changed

+418
-10
lines changed

‎docs/_data/navigation.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,8 @@ sidebar:
108108
url: "#fromfile"
109109
- title: '<code>fromCommand</code>'
110110
url: "#fromcommand"
111+
- title: '<code>fromText</code>'
112+
url: "#fromtext"
111113

112114
- title: "Extending the Syntax"
113115
url: "#extending-the-syntax"

‎docs/_pages/index.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -479,27 +479,210 @@ fi
479479

480480
## `case / option / esac`
481481

482+
- `case` / `esac` conditionals are supported
483+
- `option` is used for options
484+
- `::` is used in place of `;;` for closing each option
482485

486+
```sh
487+
- case '$1' in
488+
- option "foo"
489+
- echo "Hello from foo"
490+
- ::
491+
- option "bar"
492+
- ::
493+
- option '*'
494+
- echo "Other option!"
495+
- ::
496+
- esac
497+
```
498+
499+
<!-- OUTPUT -->
500+
501+
```sh
502+
case "$1" in
503+
foo)
504+
echo "Hello from foo"
505+
;;
506+
bar)
507+
:
508+
;;
509+
*)
510+
echo "Other option!"
511+
;;
512+
esac
513+
```
483514

484515
## `[ ... ] AND / OR`
485516

517+
- One-liner conditionals are supported with the use of `AND` and/or `OR`
518+
519+
```sh
520+
- [ '$#' -eq 0 ] AND toStderr echo "At least one argument is required"
521+
```
522+
523+
<!-- OUTPUT -->
524+
525+
```sh
526+
[ $# -eq 0 ] && echo "At least one argument is required" >&2
527+
```
528+
529+
##### `{` ... `;` ... `}`
530+
531+
- One liner statements with `{ ... }` are supported using `,` in place of `;`
532+
533+
534+
```sh
535+
- [ '$#' -eq 0 ] AND { toStderr echo "Argument is required" , return 1 , }
536+
```
537+
538+
<!-- OUTPUT -->
539+
540+
```sh
541+
[ $# -eq 0 ] && { echo "Argument is required" >&2; return 1; }
542+
```
486543
487544
# Loops
488545
489546
## `for`
547+
548+
- `for` loops are supported (`do` _is an optional keyword_)
549+
550+
```sh
551+
- for arg in '"$@"'
552+
- echo Argument: '$@'
553+
- done
554+
```
555+
556+
<!-- OUTPUT -->
557+
558+
```sh
559+
for arg in "$@"
560+
do
561+
echo "Argument:" "$@"
562+
done
563+
```
564+
490565
## `while`
491566
567+
- `while` loops are supported (`do` _is an optional keyword_)
568+
569+
```sh
570+
- while [ '$#' -gt 0 ]
571+
- echo Argument: '$1'
572+
- shift
573+
- done
574+
```
575+
576+
<!-- OUTPUT -->
577+
578+
```sh
579+
while [ $# -gt 0 ]
580+
do
581+
echo "Argument:" "$1"
582+
shift
583+
done
584+
```
585+
492586
# Arithmetic
493587
494588
## `{{ '{{' }} ... }}`
495589
590+
- `(( ... ))` arithmetic is supported using `{{ '{{' }} ... }}` in place of parenthesis
591+
592+
```sh
593+
- int i=42
594+
- {{ '{{' }} i++ }}
595+
```
596+
597+
<!-- OUTPUT -->
598+
599+
```sh
600+
declare -i i=42
601+
(( i++ ))
602+
```
603+
496604
# Pipes | STDIN
497605
606+
It's common to need to use `|` pipes in generated BASH source code.
607+
498608
## `\|`
609+
610+
- Pipes are supported by providing an escaped `\|` in place of a `|` pipe character
611+
612+
```sh
613+
- echo '$1' \| $ sed "'s/foo/bar/'" \| $ head -1 \| $ xargs -n1 echo
614+
```
615+
616+
<!-- OUTPUT -->
617+
618+
```sh
619+
echo "$1" | sed 's/foo/bar/' | head -1 | xargs -n1 echo
620+
```
621+
499622
## `fromStdin`
623+
624+
- Any command can accept input from STDIN by prepending the command with `fromStdin [source of stdin]`
625+
626+
```sh
627+
- while 'IFS=""' read -r line OR [ -n '"$line"' ]
628+
- echo '$line'
629+
- fromStdin some/file.txt done
630+
```
631+
632+
<!-- OUTPUT -->
633+
634+
```sh
635+
while IFS="" read -r line || [ -n "$line" ]
636+
do
637+
echo "$line"
638+
done < some/file.txt
639+
```
640+
641+
ℹ️ The previous example uses an escaped OR (`\|\|`) instead of `OR`
642+
643+
- Because `OR` adds an `||` after the previous command's output, this would result
644+
in the `||` being added after the while's `do` is automatically added.
645+
500646
## `fromFile`
647+
648+
- Any command can accept STDIN from a file path by prepending the command with `fromFile [file path]`
649+
- _This is the same as `fromStdin` but wraps provided arguments in_ `"`
650+
651+
```sh
652+
- while 'IFS=""' read -r line \|\| [ -n '"$line"' ]
653+
- echo '$line'
654+
- fromFile some/file.txt done
655+
```
656+
657+
<!-- OUTPUT -->
658+
659+
```sh
660+
while IFS="" read -r line || [ -n "$line" ]
661+
do
662+
echo "$line"
663+
done < "some/file.txt"
664+
```
501665
## `fromCommand`
502666
667+
- Any command can accept input from a command by prepending the command with `fromCommand "[command with args]"`
668+
669+
```sh
670+
- var text = '"$(<"$filePath")"'
671+
- while 'IFS=""' read -r line \|\| [ -n '"$line"' ]
672+
- echo '$line'
673+
- fromCommand "printf '%s' \"\$text\"" done
674+
```
675+
676+
<!-- OUTPUT -->
677+
678+
```sh
679+
text="$(<"$filePath")"
680+
while IFS="" read -r line || [ -n "$line" ]
681+
do
682+
echo "$line"
683+
done < <(printf '%s' "$text")
684+
```
685+
503686
# Extending the Syntax
504687
505688
## `shellpen extend`

‎examples/documentation/userGuide/Arithmetic.spec.sh‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
source shellpen.sh
2+
3+
shellpen -
4+
5+
commandGroup1() {
6+
- int i=42
7+
- {{ i++ }}
8+
- code
9+
}
10+
11+
@spec.commandGroup1() {
12+
read -r -d '' expected <<'EXPECTED'
13+
declare -i i=42
14+
(( i++ ))
15+
16+
EXPECTED
17+
expect { commandGroup1 } toContain "$expected"
18+
}
19+

‎examples/documentation/userGuide/Conditionals_AND_OR.spec.sh‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
source shellpen.sh
2+
3+
shellpen -
4+
5+
commandGroup1() {
6+
- [ '$#' -eq 0 ] AND toStderr echo "At least one argument is required"
7+
- code
8+
}
9+
10+
@spec.commandGroup1() {
11+
read -r -d '' expected <<'EXPECTED'
12+
[ $# -eq 0 ] && echo "At least one argument is required" >&2
13+
14+
EXPECTED
15+
expect { commandGroup1 } toContain "$expected"
16+
}
17+
18+
commandGroup1() {
19+
- [ '$#' -eq 0 ] AND { toStderr echo "Argument is required" , return 1 , }
20+
- code
21+
}
22+
23+
@spec.commandGroup1() {
24+
read -r -d '' expected <<'EXPECTED'
25+
[ $# -eq 0 ] && { echo "Argument is required" >&2; return 1; }
26+
27+
EXPECTED
28+
expect { commandGroup1 } toContain "$expected"
29+
}
30+

‎examples/documentation/userGuide/Conditionals_case_option_esac.spec.sh‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
source shellpen.sh
2+
3+
shellpen -
4+
5+
commandGroup1() {
6+
- case '$1' in
7+
- option "foo"
8+
- echo "Hello from foo"
9+
- ::
10+
- option "bar"
11+
- ::
12+
- option '*'
13+
- echo "Other option!"
14+
- ::
15+
- esac
16+
- code
17+
}
18+
19+
@spec.commandGroup1() {
20+
read -r -d '' expected <<'EXPECTED'
21+
case "$1" in
22+
foo)
23+
echo "Hello from foo"
24+
;;
25+
bar)
26+
:
27+
;;
28+
*)
29+
echo "Other option!"
30+
;;
31+
esac
32+
33+
EXPECTED
34+
expect { commandGroup1 } toContain "$expected"
35+
}
36+

examples/documentation/userGuide/Conditionals_if__fi.spec.sh renamed to examples/documentation/userGuide/Conditionals_if_fi.spec.sh

File renamed without changes.

‎examples/documentation/userGuide/Loops_for.spec.sh‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
source shellpen.sh
2+
3+
shellpen -
4+
5+
commandGroup1() {
6+
- for arg in '"$@"'
7+
- echo Argument: '$@'
8+
- done
9+
- code
10+
}
11+
12+
@spec.commandGroup1() {
13+
read -r -d '' expected <<'EXPECTED'
14+
for arg in "$@"
15+
do
16+
echo "Argument:" "$@"
17+
done
18+
19+
EXPECTED
20+
expect { commandGroup1 } toContain "$expected"
21+
}
22+

‎examples/documentation/userGuide/Loops_while.spec.sh‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
source shellpen.sh
2+
3+
shellpen -
4+
5+
commandGroup1() {
6+
- while [ '$#' -gt 0 ]
7+
- echo Argument: '$1'
8+
- shift
9+
- done
10+
- code
11+
}
12+
13+
@spec.commandGroup1() {
14+
read -r -d '' expected <<'EXPECTED'
15+
while [ $# -gt 0 ]
16+
do
17+
echo "Argument:" "$1"
18+
shift
19+
done
20+
21+
EXPECTED
22+
expect { commandGroup1 } toContain "$expected"
23+
}
24+

‎examples/documentation/userGuide/Pipes_STDIN.spec.sh‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
source shellpen.sh
2+
3+
shellpen -
4+
5+
commandGroup1() {
6+
- echo '$1' \| $ sed "'s/foo/bar/'" \| $ head -1 \| $ xargs -n1 echo
7+
- code
8+
}
9+
10+
@spec.commandGroup1() {
11+
read -r -d '' expected <<'EXPECTED'
12+
echo "$1" | sed 's/foo/bar/' | head -1 | xargs -n1 echo
13+
14+
EXPECTED
15+
expect { commandGroup1 } toContain "$expected"
16+
}
17+

‎examples/documentation/userGuide/Pipes_STDIN_fromCommand.spec.sh‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
source shellpen.sh
2+
3+
shellpen -
4+
5+
commandGroup1() {
6+
- var text = '"$(<"$filePath")"'
7+
- while 'IFS=""' read -r line \|\| [ -n '"$line"' ]
8+
- echo '$line'
9+
- fromCommand "printf '%s' \"\$text\"" done
10+
- code
11+
}
12+
13+
@spec.commandGroup1() {
14+
read -r -d '' expected <<'EXPECTED'
15+
text="$(<"$filePath")"
16+
while IFS="" read -r line || [ -n "$line" ]
17+
do
18+
echo "$line"
19+
done < <(printf '%s' "$text")
20+
21+
EXPECTED
22+
expect { commandGroup1 } toContain "$expected"
23+
}
24+

0 commit comments

Comments
 (0)