Getting started, How to use gsh

You can copy and paste any part of this directly into the gsh interactive shell

'
' gsh shell is useful as a shell for programming system management functions.
' But is also very useful as a learning environment for programming.
' Both exploring programming and the Gambas language programming concepts. 
 
' A few points to understand about gsh before we begin programming/Scripting
' gsh saves and loads it's context at the beginning and end of each shell session
' so defined variables and subroutines persist from invocation to invocation
' and the context is shared by default by all instances of a running gsh shell.
' These a similar to persistent bash or csh environment variables.

' The gsh Shell is not POSIX compliant, but in most cases single cli command lines are.

' At Startup gsh will check if the system vars/profile.gsh has changed and ask you to run the
' **update** command if you want the latest changes. This will cleanup the image file and remove
' any unused variables. You will be prompted to save any unsaved functions/procedures.

' Then the local .gshrc file is executed if it has changed.. remember gsh, loads a context 
' with the last state. The environment is persistent across instantiations.

' After this if this is a terminal process then the onstart function is executed
' before the input prompt is displayed.
' At end of a shell session the onexit function is executed. 
' These functions are only executed for interactive sessions.

' All variables/functions may be edited using the edit command
' Your default editor is set with the following lines
' $editor = "/bin/nano"      ' nano is the default gsh editor
' $prompt="\x01\x1b[31m\x02" & application.id & "." & user.name & "@" & system.host & \
'         ":\x01\x1b[32m\x02" & env["PWD"] & "\x01\x1b[0m\x1b[0K\x02 > "

' important note if you want to keep and created variables or subs, classes or struct
' you must explicitly save then to disk. savevars, savesubs, saveclass, savestruct commands
' These will be reloaded upon first reference to them in any context.
'
' All gsh variables must start with a $, all linux environment variables are referenced 
' with a reference to the env[] array. Example env!PWD to see the current directory.
'
' The default system prompt is broken down into three parts
' 1 the current linux process id
' 2 the current user name,  this is also reflected in the terminal window title
' 3 the current computer name,  this is also reflected in the terminal window title
' 4 the current directory, this is also reflected in the terminal window title
'
' The terminal window title bar reflects the previous fields plus the GSH version number
'
' We will assume the user is familiar with other linux shell environments.
' Lets get started with the most basic functions and configuration settings.

' Creating Variables and editing variables

$a = 100               ' create a gsh Shell variable. Can Be accessed from all open gsh shells 
                       ' by default
? $a                   ' ? mark is short form for print
' If gsh is started with the -s flag then gsh shell variables will only be available to this process
' and its child tasks.
' gsh shell Variables are stored in the gsh shell context, and saved and loaded by default at each 
' shell exit and start
' gsh shell variables are dynamically typed at runtime, and may contain most Gambas data types.
' arrays and object data type are immutable, that is they may not be updated after being saved.
' so the following method of updating these must be used
$a = ["this", "and", "that"]    ' create an arrays
?? $a                           ' ?? is short form for print contents of an object or arrays
edit a                          ' this will allow us to directly edit the content of the variable
                                ' Notice the $ is not used

' so we can access the elements in the normal way
? $a[1]

' We have to note here that the gsh Variable are stored in an in memory database
$a[1] = "more"                    ' this does not work

? $a[1]
set a "this" 1                    ' this will update the value of the array, only supports 
                                  ' up to 3 dimensions

' Not any method which returns information about or from the array or object will work normally
?? $a.count                       ' This works just fine
?? $a.extract(1,2)                ' This works just fine to
' it is only methods that change the content that we need to  use special methods to update
?? $a.sort()                      ' this does not work
' This returns the sorted array, but does not actually change the $a array order
?? $a                             ' this is not sorted
' with methods that output an updated array or object we can do this
$a = $a.sort()
?? $a
' but if the method operates on the array or object such as add then we must use
' the ref(SrcObj, method,values,....) function to operate on the actual data entry
$a = ref($a,"add","Boxxy")            ' this will directly create an updated object and return it
' in most cases this is not really required
' Simple gsh variables work as normal gambas variables
$b = 1
inc $b               ' works just fine


' lets look at using Gambas variables in our scripts:

dim a as integer = 1 ' this will go out of scope/ undefined as soon as a block of code exits
? a                  ' this fails as it is already out of scope

Looking at what a code block is

' perhaps this is a good time to cover blocks of code in a scripts
' gsh executes blocks of code as they are entered, so when we entered
dim as as integer = 1 
' as soon as we pressed return it was executed and immediately when out of scope
' this is because there was no surrounding code block.
' these are any natural Gambas code structure . if - endif, while - wend, etc
' so the following would be valid
while true
  dim a as integer = 1
  ? a
  break
  wend
' notice the auto indent as you type
' anyway the While - wend form a code block that contains the a and it is valid in the
'  scope of the Block of Gambas code.

' now this can be a but clumsy so the shell provides a Do...done
' Where done is an alias for **loop until true**, 
' Alternately you can use begin..end, {..} these create lambda expressions
' these actually do nothing during execution only let the shell know to execute all
' the instructions as one block. So lets re-write our example
do
  dim a as integer = 1
  ? a
  done
' again notice the automatic indent as you enter the text
' and the bock executes immediately after the closing }
' if we made a mistake while we were entering the code we can just edit it
edit
' we will be put into the default editor
' the block will be re-executed as soon as you close the editor.
' if we want to re-execute the last code block just enter
run

' if you have executed other commands since the last code block you can also
' enter 
edit lambda
' this will open the last executed block of code you entered
' Now I am going to assume you have done some Gambas programming
' Inside a block of code any Gambas code is valid, also linux cli commands can be used
' as part of the code block

 for i as integer = 0 to 10
   echo the value of i {i}
   next
   
' again this executes as soon as we end the block with next
run
' executes it again
' We can mix Shell variables with Gambas variables inside our code blocks

$a = ["a","b","c"]
for i as integer = 0 to 10
   echo the value of i {i} and the array is $a
   next

' Notice that array elements of gsh shell variables are expanded onto 
' the cli command line. Also take note of how gambas variable and gsh shell 
' variables are passed to the cli {} are used to surround the gambas expression, and a $ is 
' used to denote the gsh shell variable.
' here is a more complex example:

$a = ["a","b","c", "d","e","f","g","h","i","j"]
for i as integer = 0 to 10
   echo the value of i {(i*20)} {($a[i] & "obby")} and the array is $a
   next

' take not that if an expression is inside the cli then it must be farther 
' surrounded by () so {(expr)} is the correct syntax for an expression.

Iteration Using the enumeration variable $"Expansion/Enumerate rules"

'There is a special variable in the shell which is $"expansion/enumerate expression"
' this will be expanded/enumerated using bash/csh expansion/enumerate rules to an array of values
' it can be used like this
for each i as integer in $"0..10"
  echo {i}
  next

for each i as string in $"a..z"
  echo {i}
  next

for each i as integer in $"10..0"
  echo {i}
  next

for each i as string in $"z..a"
  echo {i}
  next

' The above examples just print a list of enumerated 
' numbers or letters

echo $"0..10" 
' works too Passing enumerated all the values to cli at once.

' Here is a more practical example
!mkdir stmp
for each filename as string in $"stmp/MyFile{0..10}"
  touch {filename}
  next
ls stmp
for each filename as string in $"stmp/MyFile{0..10}"
  rm {filename}
  next
ls stmp
!rmdir stmp

' notice here the some commands begin with a !. This causes the shell to ignore the 
' internal function mkdir for instance and use the cli version instead. the ! will
' always look for the cli version before looking for the internal version.
' Expansions/Enumeration may be nested and contain pre and post strings.

for each i as string in $"base{1..4}with{1..3,20}"
  print i
  next
' So the iteration is is nested by each set.
' this outputs:
' base1with1
' base1with2
' base1with3
' base1with20
' base2with1
' base2with2
' base2with3
' base2with20
' base3with1
' base3with2
' base3with3
' base3with20
' base4with1
' base4with2
' base4with3
' base4with20

Expansion/Enumeration using variables

' In order to use variables as part of the enumeration rules, your will need 
' to use the enumerate function. $".." is just a short form for this.
$a  = "a..z"
$b  = ",10..4"
for each b as string in enumerate($a & $b)
  print b
  next

Expansion/Enumeration with files

'We can also iterate through all the file in a directory using $"..."

for each filename as string in $"*"
  print "Print File Name = " ;filename
  echo file name = {filename}
  next

' Notice that you can mix and match cli and Gambas statements
' this time only starting with a 'b'

for each filename as string in $"b*,e*"
  print "Print File Name = " ;filename
  echo file name = {filename}
  next

' we also used enumeration in that statement, b*,e* this listed
' both file starting with b and starting with e 

Some Useful gsh commands

' So we want to find out what we have created/defined
lvars            ' this lists all the variables in the memory database
lsubs            ' this lists all the subroutines/plugins in gsh
lclass           ' this lists all the classes defined in gsh
lsclasses        ' this will list all the classes and their 
                 ' methods/variables
' Not that all these commands can accept a variable/class/sub name as well
clearvars        ' Clears all gsh shell variables created by the user
clearsubs        ' clears all loaded subs from memory. they are reloaded when needed
                 ' be careful if you have not saved your work it is lost
lshm             ' will list all the variables stored in the memory database

' I guess a help command is important

How to get help

help             ' display all the information about the shell
                 ' includes all subs/plugins and gambas keywords
help str         ' display help for str
help lvars       ' display information about lvars
' all gambas and gsh functions and keywords are supported

Help from the internet

google "my search term"    ' this will open the web browser with the search results