From b1ea5ac24e20f0580ff24853201a5e81b394f1e5 Mon Sep 17 00:00:00 2001 From: Patrice Ferlet Date: Sat, 4 Jun 2016 15:26:46 +0200 Subject: [PATCH] Fixup documentation --- docs/BasicTutorial.md | 39 +++++---- docs/HowItWorks.md | 33 ++++---- docs/index.md | 187 +++++++++++++++++++++--------------------- 3 files changed, 137 insertions(+), 122 deletions(-) diff --git a/docs/BasicTutorial.md b/docs/BasicTutorial.md index 1d8e6d1..cb2f0e3 100644 --- a/docs/BasicTutorial.md +++ b/docs/BasicTutorial.md @@ -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 git@github.com: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 @@ -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 ``` @@ -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" @@ -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 @@ -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%" ``` diff --git a/docs/HowItWorks.md b/docs/HowItWorks.md index b33c9ad..653a1e5 100644 --- a/docs/HowItWorks.md +++ b/docs/HowItWorks.md @@ -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 ## @@ -24,11 +25,12 @@ 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 ## @@ -36,18 +38,17 @@ Tput command is a bit low... Refreshing view is not pretty while the cursor is m 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. diff --git a/docs/index.md b/docs/index.md index c47aee2..65f27ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 # @@ -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: