Getting Started

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.
' Exploring the language and programming concept. 
 



' A few points to understand about gsh before we begin programming
' gsh saves and loads it's context at the beginning and end of each shell session
' so defined variables and subroutines persist form invocation to invocation
' and the context is shared by default by all instances of a running gsh shell.
' these a similar to bash or csh environment variables.

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

' At Startup gsh will check if the system .profile.gsh has changed and ask you to run the
' update command if you want the latest changes.

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

' After this if this is a terminal process then the onstart function is executed
' End the end of a shell session the onexit function is executed.

' All variables/functions may be edited using the edit command
' Your default editor is set with the following lines
' $$editor = "/usr/bin/nano"      ' nano is the default gsh editor


' 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 env!PWD
'
' 
' We will assume the user is familiar with other linux shell environments
' Lets get started with the most basic 

' Create 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 types 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 and 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


' 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 begin.end or { .. }
' 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
{
  dim a as integer = 1
  ? a
  }
' 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 or code blocks