Skip to content

Commit c5d723d

Browse files
beccasaurusbeccasaurus
committed
Docs and installer
1 parent 0658afc commit c5d723d

File tree

8 files changed

+301
-61
lines changed

8 files changed

+301
-61
lines changed

‎README.md

Lines changed: 86 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,129 @@
11
[![Mac (BASH 3.2)](<https://github.com/shellbox-sh/shx/workflows/Mac%20(BASH%203.2)/badge.svg>)](https://github.com/shellbox-sh/shx/actions?query=workflow%3A%22Mac+%28BASH+3.2%29%22) [![BASH 4.3](https://github.com/shellbox-sh/shx/workflows/BASH%204.3/badge.svg)](https://github.com/shellbox-sh/shx/actions?query=workflow%3A%22BASH+4.3%22) [![BASH 4.4](https://github.com/shellbox-sh/shx/workflows/BASH%204.4/badge.svg)](https://github.com/shellbox-sh/shx/actions?query=workflow%3A%22BASH+4.4%22) [![BASH 5.0](https://github.com/shellbox-sh/shx/workflows/BASH%205.0/badge.svg)](https://github.com/shellbox-sh/shx/actions?query=workflow%3A%22BASH+5.0%22)
22

33
---
4-
# <% HTML in your Shell %>
4+
# 📜 <%= _"shell script templates"_ %>
55

66
> Simple, easy-to-use template rendering engine ( _written in BASH_ )
77
8+
Download the [latest version](https://github.com/shellbox-sh/shx/archive/v0.1.0.tar.gz) by clicking one of the download links above or:
9+
10+
```sh
11+
curl -o- https://shx.shellbox.sh/installer.sh | bash
12+
```
13+
814
---
915

10-
> Classic HTML templating
16+
## 🏛️ Classic syntax
17+
18+
`shx` provides a well-known, friendly `<%`-style syntax:
1119

1220
```erb
1321
<!-- index.shx -->
1422
<html>
1523
<head>
1624
<%= $title %>
1725
</head>
26+
<body>
27+
<h1><%= $header %></h1>
28+
<ul>
29+
<% for item in "${items[@]}"; do %>
30+
<li><%= $item %></li>
31+
<% done %>
32+
</ul>
33+
</body>
1834
</html>
19-
<body>
20-
<ul>
21-
<% for item in "${items[@]}"; do %>
22-
<li><%= $item %></li>
23-
<% done %>
24-
</ul>
25-
</body>
2635
```
2736

28-
> Simple rendering
37+
## 💬 Render a string
2938

30-
```sh
31-
source shx.sh
39+
Provide a simple string to `shx render "[my template]"`:
3240

33-
title="My Website"
34-
declare -a items=("Item A" "Item B")
41+
```sh
42+
$ export text="Hello, world!"
3543

36-
shx render index.shx
44+
$ ./shx render "<h1><%= $text %></h1>"
3745
```
3846

39-
> Output HTML
40-
4147
```html
42-
<html>
43-
<head>
44-
<title>Hello, world!</title>
45-
</head>
46-
</html>
47-
<body>
48-
<ul>
49-
<li>Item A</li>
50-
<li>Item B</li>
51-
</ul>
52-
</body>
48+
<h1>Hello, world!</h1>
5349
```
5450

55-
> Provide command-line arguments
51+
## 💾 Render a file
52+
53+
Provide a file path to `shx render "[path to file]"`:
5654

5755
```erb
58-
<h1><%= $1 %><% shift %></h1>
59-
<ul>
60-
<% for item in "$@"; do %>
61-
<li><%= $item %></li>
62-
<% done %>
63-
</ul>
56+
<!-- index.shx -->
57+
<h1><%= $title %></h1>
6458
```
6559

6660
```sh
67-
shx render index.shx "My Title" "Hello" "World"
61+
$ export title="My Website"
62+
63+
$ ./shx render index.shx
6864
```
6965

7066
```html
71-
<h1>My Title</h1>
72-
<ul>
73-
<li>Hello</li>
74-
<li>World</li>
75-
</ul>
67+
<h1>Hello, world!</h1>
7668
```
7769

78-
> Render simple strings
70+
## 📚 Use as a library
71+
72+
Give `shx` visibility into your script's variables without `export`:
7973

8074
```sh
81-
shx render '<h1><%= $1 %></h1>' "Hello, world!"
75+
source shx.sh
76+
77+
title="Regular variable"
78+
79+
shx render "Title: <%= $title %>"
8280
```
8381

84-
```html
85-
<h1>Hello, world!</h1>
8682
```
83+
Title: Regular variable
84+
```
85+
86+
Including access to function `local` variables:
87+
88+
```sh
89+
source shx.sh
90+
91+
renderTemplate() {
92+
local greeting="$1"
93+
local name="$2"
94+
shx render "<%= $greeting %>, <%= $name %>!"
95+
}
96+
97+
renderTemplate "Hello" "Rebecca"
98+
```
99+
100+
```
101+
Hello, Rebecca!
102+
```
103+
104+
## 📎 Accepts argument list
105+
106+
You can provide arguments after `shx render [template]` which become available via the usual means, e.g. `$*` `$@` `$#` `$1` `$2` `$3` etc
107+
108+
```erb
109+
<!-- template.shx -->
110+
<%= $# %> arguments provided:
111+
<% for argument in "$@"; do -%>
112+
- <%= $argument %>
113+
<% done %>
114+
```
115+
116+
```sh
117+
./shx render template.shx "First" "Second" "Third"
118+
```
119+
120+
```
121+
3 arguments provided:
122+
- First
123+
- Second
124+
- Third
125+
```
126+
127+
> ℹ️ Using `-%>` prevents the character following `-%>` from being output (_e.g. in this case a newline character_)
87128
88129
---

‎docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
{% raw %}
55

6-
# <%= "shell script templates" %>
6+
# 📜 <%= _"shell script templates"_ %>
77

88
> Simple, easy-to-use template rendering engine ( _written in BASH_ )
99

‎docs/installer.sh

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
#! /usr/bin/env bash
2+
3+
########################
4+
EMOJI="📜"
5+
REPO_ORG="shellbox-sh"
6+
PROJECT_NAME="shx"
7+
FILE_WITH_VERSION_VARIABLE="shx.sh"
8+
VERSION_VARIABLE="SHX_VERSION"
9+
API_LATEST_RELEASE_INFO_URL="https://api.github.com/repos/$REPO_ORG/$PROJECT_NAME/releases/latest"
10+
FILES_TO_COPY=("shx" "shx.sh")
11+
INSTALL_MESSAGE="Installed 📜 shx.sh
12+
13+
- shx - Run shx as an executable
14+
- shx.sh - Source shx as a library
15+
16+
^--- these files are identical and you may discard either
17+
18+
./shx or 'source shx.sh' to get started rendering templates!
19+
20+
Visit https://shx.shellbox.sh for documentation
21+
"
22+
########################
23+
24+
print_header() {
25+
echo "$EMOJI [$PROJECT_NAME]"
26+
echo
27+
}
28+
29+
get_latest_release_version() {
30+
printf "Checking for latest release... "
31+
32+
local releaseInfo=""
33+
releaseInfo="$( curl -s "$API_LATEST_RELEASE_INFO_URL" )"
34+
35+
if [ $? -ne 0 ]
36+
then
37+
echo "failed." >&2
38+
echo >&2
39+
echo "(curl -s \"$API_LATEST_RELEASE_INFO_URL\" error)" >&2
40+
echo "$releaseInfo" >&2
41+
exit 1
42+
fi
43+
44+
local tarballUrl="$( echo "$releaseInfo" | grep tarball | awk '{print $2}' | sed 's/[",]//g' )"
45+
46+
if [ $? -ne 0 ]
47+
then
48+
echo "failed." >&2
49+
echo >&2
50+
echo "(read tarball URL from release info failed)" >&2
51+
echo "$tarballUrl" >&2
52+
exit 1
53+
fi
54+
55+
LATEST_RELEASE_VERSION="${tarballUrl/*\/}"
56+
57+
echo "$LATEST_RELEASE_VERSION"
58+
}
59+
60+
make_and_goto_tempdir() {
61+
WORKING_DIRECTORY="$( pwd )"
62+
TEMP_DIRECTORY="$( mktemp -d )"
63+
64+
cd "$TEMP_DIRECTORY"
65+
}
66+
67+
download_tarball() {
68+
printf "Downloading... "
69+
DOWNLOAD_URL="https://github.com/$REPO_ORG/$PROJECT_NAME/archive/$LATEST_RELEASE_VERSION.tar.gz"
70+
TARBALL_FILENAME="${DOWNLOAD_URL/*\/}"
71+
72+
local output=""
73+
output="$( curl -LO "$DOWNLOAD_URL" 2>&1 )"
74+
75+
if [ $? -ne 0 ]
76+
then
77+
echo "failed, did not successfully to download: $DOWNLOAD_URL" >&2
78+
echo >&2
79+
echo "(curl -LO \"$DOWNLOAD_URL\" error)" >&2
80+
echo "$output" >&2
81+
exit 1
82+
elif [ ! -f "$TARBALL_FILENAME" ]
83+
then
84+
echo "failed, did not successfully download: $DOWNLOAD_URL (File not found $TARBALL_FILENAME)" >&2
85+
exit 1
86+
else
87+
echo "downloaded $TARBALL_FILENAME"
88+
fi
89+
}
90+
91+
extract_tarball() {
92+
printf "Extracting... "
93+
94+
local output=""
95+
output="$( tar zxvf "$TARBALL_FILENAME" 2>&1 )"
96+
97+
if [ $? -ne 0 ]
98+
then
99+
echo "failed, could not extract: $TARBALL_FILENAME" >&2
100+
echo >&2
101+
echo "(tar zxvf \"$TARBALL_FILENAME\" error)" >&2
102+
echo "$output" >&2
103+
exit 1
104+
else
105+
echo "extracted $TARBALL_FILENAME"
106+
fi
107+
}
108+
109+
verify_download() {
110+
printf "Verifying download... "
111+
112+
cd $PROJECT_NAME-*
113+
114+
if [ ! -f "$FILE_WITH_VERSION_VARIABLE" ]
115+
then
116+
echo "failed, missing required file: $FILE_WITH_VERSION_VARIABLE" >&2
117+
exit 1
118+
fi
119+
120+
LOCAL_VERIFIED_VERSION=""
121+
LOCAL_VERIFIED_VERSION="$( grep "$VERSION_VARIABLE=" "$FILE_WITH_VERSION_VARIABLE" | sed "s/.*$VERSION_VARIABLE=//" | sed 's/[";]//g' )"
122+
123+
if [ $? -ne 0 ]
124+
then
125+
echo "failed, could not read version from file: $FILE_WITH_VERSION_VARIABLE" >&2
126+
echo >&2
127+
echo "(grep \"$VERSION_VARIABLE\" \"$FILE_WITH_VERSION_VARIABLE\" error)" >&2
128+
echo "$LOCAL_VERIFIED_VERSION" >&2
129+
exit 1
130+
else
131+
local filename
132+
for filename in "${FILES_TO_COPY[@]}"
133+
do
134+
if [ ! -f "$filename" ]
135+
then
136+
echo "failed, missing required file: $filename" >&2
137+
exit 1
138+
fi
139+
done
140+
echo "verified version $LOCAL_VERIFIED_VERSION"
141+
fi
142+
}
143+
144+
copy_files_to_working_directory() {
145+
printf "Installing... "
146+
147+
local filename
148+
for filename in "${FILES_TO_COPY[@]}"
149+
do
150+
if ! cp "$filename" "$WORKING_DIRECTORY"
151+
then
152+
echo "failed, could not copy file to install directory: $filename" >&2
153+
exit 1
154+
fi
155+
done
156+
157+
echo "installed ${#FILES_TO_COPY[@]} files"
158+
}
159+
160+
cleanup() {
161+
printf "Cleaning up temporary directory... "
162+
163+
if ! rm -r "$TEMP_DIRECTORY"
164+
then
165+
echo "failed, could not delete temp directory: $TEMP_DIRECTORY" >&2
166+
exit 1
167+
fi
168+
169+
echo "finished"
170+
}
171+
172+
print_footer() {
173+
echo
174+
echo "$PROJECT_NAME $LOCAL_VERIFIED_VERSION successfully installed"
175+
if [ -n "$INSTALL_MESSAGE" ]
176+
then
177+
echo
178+
echo -e "$INSTALL_MESSAGE"
179+
fi
180+
}
181+
182+
run_install() {
183+
print_header
184+
get_latest_release_version
185+
make_and_goto_tempdir
186+
download_tarball
187+
extract_tarball
188+
verify_download
189+
copy_files_to_working_directory
190+
cleanup
191+
print_footer
192+
}
193+
194+
run_install

0 commit comments

Comments
 (0)