Skip to content

Commit

Permalink
Fixup documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Patrice Ferlet committed Jun 4, 2016
1 parent aba350d commit b1ea5ac
Show file tree
Hide file tree
Showing 3 changed files with 137 additions and 122 deletions.
39 changes: 25 additions & 14 deletions docs/BasicTutorial.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,36 @@
# Basic Introduction #

Bash simple curses is a very simple system to create "bash windows" and append texts into. You only have to know some functions and what to show.
Bash simple curses is a very simple bash library to create "bash windows" and append texts into.
You only have to know some functions and what to show.

Let's take a look on this little tutorial

# Importing bash functions #

Create a directory where we will work. For example
```

```bash
mkdir -p ~/tutorial/bashcurses
```

Get bashsimplecurses sources from github.
```

```bash
cd ~/tutorial/bashcurses
git clone [email protected]:metal3d/bashsimplecurses.git
```

Now, create a tutorial.sh script and edit it, you can use vim, gedit, nano...:
```

```bash
touch tutorial.sh
#vim tutorial.sh
#or nano tutorial.sh
```

It's ok, then you can add this into your code:
```
It's ok, then you can add this:

```bash
#!/bin/bash

#import bashsimplecurses
Expand All @@ -41,8 +46,9 @@ main(){
main_loop
```

It's ok ? save your work. Now, you only have to set this script "executable"
```
Save your work. Now, you only have to set this script "executable"

```bash
chmod +x ~/tutorial/bashcurses/tutorial.sh
```

Expand All @@ -51,13 +57,14 @@ Now, you can try:
~/tutorial/bashcurses/tutorial.sh
```

And a window appear ! To close your script, you only have to kill or press CTRL+C
And a window appeaars ! To close your script, you only have to kill or press CTRL+C

![http://www.metal3d.org/captures/bashsimplecurses/tuto1.png](http://www.metal3d.org/captures/bashsimplecurses/tuto1.png)

## Title Colors ##

You can specify colors for titles, change line on tutorial like this:
You can specify colors for titles. For example, change line on tutorial like this:

```
...
window "Title of my window" "red"
Expand All @@ -67,18 +74,21 @@ Restart your script, and the title is red.

![http://www.metal3d.org/captures/bashsimplecurses/tuto2.png](http://www.metal3d.org/captures/bashsimplecurses/tuto2.png)

For now, only 4 colors are implented:
Provided colors are:

* grey or gray
* red
* yellow
* green
* blue
* grey

Next versions will implement severals other colors.
* magenta
* cyan


## Sizes ##

By default, windows take 100% of terminal width. You can specify number of cols to use:

```
...
window "Title of my window" "red" 36
Expand All @@ -87,6 +97,7 @@ By default, windows take 100% of terminal width. You can specify number of cols
This will set the width to 36 caracters (cols).

You may use percent:

```
window "Title of my window" "red" "50%"
```
Expand Down
33 changes: 17 additions & 16 deletions docs/HowItWorks.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,22 @@
# Introduction #

Bash is really powerfull. There is a lot of commands to make everything you need. Bash simple curses uses
* tput command
* STD redirection
* escaped colors
Bash provides some command to make that kind of operations:

Let me explain how I did
* tput command
* STD redirection
* escaped colors

Bash simple curses makes use of this commands to draw windows, change color, and so on.

## Lines ##

Lines and corners are display as "chars". You can try this:
```

```bash
echo -e "\033(0 l q k x m j \033(B"
```

You will see special chars used to create windows.
You will see special chars that we use to create window borders.

## Placing cursor ##

Expand All @@ -24,30 +25,30 @@ Because we need to write lines and texts on screen, `tput` command is used. `tpu
## Colors ##

Bash can change the text color using escaped values. For example
```

```bash
echo -e "\033[32mText in red\033[0m"
```

This display text in red color.
This line displays text in red color.

## Buffer ##

Tput command is a bit low... Refreshing view is not pretty while the cursor is moving on screen. A "clipping" appears. That's why Bash simple curses needs a STDOUT buffer that is not display until we explicitally ask to flush display.

Bash has no STDOUT buffer...

**But Bash is powerfull I said !** If you change colors, write texts, and you redirect to a file, Bash insert special caracters to set colors while you use "cat" command.

Bash simple curses redirect each "echo" command to a FIFO placed in /tmp/ or /dev/shm/ (depending on the OS)
So, to fix the buffering context, Bash simple curses redirects each "echo" command to a FIFO placed in /tmp/ or /dev/shm/ (depending on the OS).

This buffer is flushed when "refresh" command is called.
This buffer is flushed when "refresh" (internal) command is called. This is executed automatically by bashsimplecurses.

## What's happend ? ##

Everything is done when you have call `main_loop` function. This makes:
* clean screen
* place cursor on top
* initiate buffer

* clean screen
* place cursor on top
* initiate buffer

When you create a "window", a title is set with color and size. Size is kept to set content with same width.

Expand Down
187 changes: 95 additions & 92 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,64 +1,66 @@
# The simple way #
"Bash simple curses" give you some basic functions to quickly create some windows on you terminal as Xterm, aterm, urxvt...

An example is given: bashbar. Bashbar is a monitoring bar that you can integrate in tiling desktop (Xmonad, WMii...)
"Bash simple curses" provides some basic functions to quickly create some windows on you terminal as Xterm, aterm, urxvt...

The goal of Bash Simple Curses is not done (not yet) to create very complete windows. It is only done to create some colored windows and display informations into.
An example is given: bashbar that is a monitoring bar you can integrate in tiling desktop (Xmonad, WMii...).

The goal of Bash Simple Curses is not creating very complete windows. It is only made to create some colored windows and display informations into.

# Why ? #

Because bash is very usefull, there are command to do whatever you want. With curses you can create a little bar to display informations every second, you can change an output command to display a report...
Bash is very comple and has a great ecosystem, there are commands to do whatever you want. With curses you can create a little bar to display informations each second, you can change an output command to display a report...

So, we need an easy and usefull library to quickly create this kind of views. This is why you can try Bash Simple Curses
So, we need an easy and usefull library to quickly create this kind of views. This is why you can try Bash Simple Curses.

# Example: the bashbar #

Bash bar is the given example that show system informations. You only have to resize your terminal window and place it on left or right. This screenshot is made on Xmonad:

![http://www.metal3d.org/captures/bashsimplecurses/bashbar.png](http://www.metal3d.org/captures/bashsimplecurses/bashbar.png)

this is the code used:

```
#!/bin/bash
. `dirname $0`/simple_curses.sh
main (){
window "`hostname`" "red"
append "`date`"
addsep
append_tabbed "Up since|`uptime | cut -f1 -d"," | sed 's/^ *//' | cut -f3- -d" "`" 2 "|"
append_tabbed "Users:`uptime | cut -f2 -d"," | sed 's/^ *//'| cut -f1 -d" "`" 2
append_tabbed "`awk '{print "Load average:" $1 " " $2 " " $3}' < /proc/loadavg`" 2
endwin
window "Memory usage" "red"
append_tabbed `cat /proc/meminfo | awk '/MemTotal/ {print "Total:" $2/1024}'` 2
append_tabbed `cat /proc/meminfo | awk '/MemFree/ {print "Used:" $2/1024}'` 2
endwin
window "Processus taking memory and CPU" "green"
for i in `seq 2 6`; do
append_tabbed "`ps ax -o pid,rss,pcpu,ucmd --sort=-cpu,-rss | sed -n "$i,$i p" | awk '{printf "%s: %smo: %s%%" , $4, $2/1024, $3 }'`" 3
done
endwin
window "Last kernel messages" "blue"
dmesg | tail -n 10 > /tmp/deskbar.dmesg
while read line; do
append_tabbed "$line" 1 "~"
done < /tmp/deskbar.dmesg
rm -f /tmp/deskbar.dmesg
endwin
window "Inet interfaces" "grey"
_ifaces=$(for inet in `ifconfig | cut -f1 -d " " | sed -n "/./ p"`; do ifconfig $inet | awk 'BEGIN{printf "%s", "'"$inet"'"} /adr:/ {printf ":%s\n", $2}'|sed 's/adr://'; done)
for ifac in $_ifaces; do
append_tabbed "$ifac" 2
done
endwin
}
main_loop 1
It's implemented this way:

```bash
#!/bin/bash

. `dirname $0`/simple_curses.sh

main (){
window "`hostname`" "red"
append "`date`"
addsep
append_tabbed "Up since|`uptime | cut -f1 -d"," | sed 's/^ *//' | cut -f3- -d" "`" 2 "|"
append_tabbed "Users:`uptime | cut -f2 -d"," | sed 's/^ *//'| cut -f1 -d" "`" 2
append_tabbed "`awk '{print "Load average:" $1 " " $2 " " $3}' < /proc/loadavg`" 2
endwin

window "Memory usage" "red"
append_tabbed `cat /proc/meminfo | awk '/MemTotal/ {print "Total:" $2/1024}'` 2
append_tabbed `cat /proc/meminfo | awk '/MemFree/ {print "Used:" $2/1024}'` 2
endwin

window "Processus taking memory and CPU" "green"
for i in `seq 2 6`; do
append_tabbed "`ps ax -o pid,rss,pcpu,ucmd --sort=-cpu,-rss | sed -n "$i,$i p" | awk '{printf "%s: %smo: %s%%" , $4, $2/1024, $3 }'`" 3
done
endwin

window "Last kernel messages" "blue"
dmesg | tail -n 10 > /tmp/deskbar.dmesg
while read line; do
append_tabbed "$line" 1 "~"
done < /tmp/deskbar.dmesg
rm -f /tmp/deskbar.dmesg
endwin

window "Inet interfaces" "grey"
_ifaces=$(for inet in `ifconfig | cut -f1 -d " " | sed -n "/./ p"`; do ifconfig $inet | awk 'BEGIN{printf "%s", "'"$inet"'"} /adr:/ {printf ":%s\n", $2}'|sed 's/adr://'; done)
for ifac in $_ifaces; do
append_tabbed "$ifac" 2
done
endwin
}
main_loop 1
```

# Another Example #
Expand All @@ -68,52 +70,53 @@ this capture shows you that you can do whatever you want:
![http://www.metal3d.org/captures/bashsimplecurses/bashcurses.png](http://www.metal3d.org/captures/bashsimplecurses/bashcurses.png)

Code is:
```
#!/bin/bash
source $(dirname $0)/simple_curses.sh
main(){
window "Test 1" "red" "33%"
append "First simple window"
endwin
col_right
move_up
window "Test 2" "red" "33%"
append "Multiline is allowed !!!\nLike this :)"
append "This is a new col here."
endwin
window "Test 3" "red" "33%"
append "We can had some text, log..."
endwin
window "Test 4" "grey" "33%"
append "Example using command"
append "`date`"
append "I only ask for date"
endwin
col_right
move_up
window "Test 5" "red" "34%"
append "We can add some little windows... rememeber that very long lines are wrapped to fit window !"
endwin
window "Little" "green" "12%"
append "this is a simple\nlittle window"
endwin
col_right
window "Other window" "blue" "22%"
append "And this is\nanother little window"
endwin
}
main_loop

```bash
#!/bin/bash

source $(dirname $0)/simple_curses.sh

main(){
window "Test 1" "red" "33%"
append "First simple window"
endwin

col_right
move_up

window "Test 2" "red" "33%"
append "Multiline is allowed !!!\nLike this :)"
append "This is a new col here."
endwin

window "Test 3" "red" "33%"
append "We can had some text, log..."
endwin
window "Test 4" "grey" "33%"
append "Example using command"
append "`date`"
append "I only ask for date"
endwin

col_right
move_up
window "Test 5" "red" "34%"
append "We can add some little windows... rememeber that very long lines are wrapped to fit window !"
endwin

window "Little" "green" "12%"
append "this is a simple\nlittle window"
endwin
col_right
window "Other window" "blue" "22%"
append "And this is\nanother little window"
endwin

}
main_loop
```

# How nice ! #
# Some other cool stuffs #

And just with libcaca "img2txt" command, you can have fun:

Expand Down

0 comments on commit b1ea5ac

Please sign in to comment.