Ring Documentation Walkthrough #13 – System Functions

Welcome to the new chapter ‘System Functions‘, this is a very easy chapter.

our functions:

  1. system() – exceute a system command.
  2. get() – get environment variables like PATH, TEMP .. etc
  3. isMSDOS() – check if the operation system is msDOS or not, returns 1 if true, 0 if false
  4. isWindows(), isWindows64(), isUnix(), isMacOSX(), isLinux(), isFreeBSD(), isAndroid() – all returns 1 if true, 0 if false
  5. windowsNL() – returns the windows’ new line string that contains : CR+LF { char(13) + char(10) }

  6. sysargv – it’s a list contains the command line parameters.

    see sysargv

  7. filename() – returns the active script file name.

This is pretty much what we have in the chapter.

see you in the final one.


Ring Documentation Walkthrough #13 – System Functions

Ring Documentation Walkthrough #12.1 – Advanced Read & Write Files

Hello, We’ll go through some advanced operations about the files.

File Handling:

We will learn in the next example these functions:

  • fopen – open a file
  • fgets – read a specific amount of a file
  • fgetc – read a character of a file
  • fexists – check if a file exists
  • freopen – re-open a file in a file handler
  • fseek ( file_handle, offset, whence – set the position of the stream, whence: ( 0=beginning of the file, 1=current position, 2=end of the file)
  • rewind – set back the position to the beginning of the file
  • fgetpos & fsetpos – get handle of the current position and set new position for the file
  • fputc – write a single character
  • fputs – write a text
  • fwrite – write a text
  • fread – read a specific amount of a file
  • ftell – know the current position
  • fclose – close the file handler

r - read
w - write new or overwrite
a - appends and creates new if doesn't exists
r+ - read & write (update file)
w+ - read & write
a+ - read & append
file = fopen('somewhere.txt', 'r')
see file[1]
see fgets(file, 100) #the same result as above.

see fgetc(file) #returns a character or EOF

see fexists('some_other_file.txt') #returns 0 (false), 1 (true)

file = freopen('some_other_file.txt', 'r+')
fseek(file, 0 , 2) #go to the end of the text file
see ftell(file)
fputc(file, 'a') #append a character
fputs(file, 'amr') #append a text

rewind(file) #set back the position to the beginning of the file.

fwrite(file, 'consider this a something just for the example, ty.') #writes to the file

fread(file, 100) #returns 100 characters from the file

x = fgetpos(file) #returns position handle
fsetpos(file, 5) #set new position of the file
fclose(file) #close the file handler.

Temperory files:

There’re two functions for this.

x = tempfile() #returns a file handle for a temp file.
x = tempname() #returns a temp file name that doesn't exists


  • clearerr

    clearerr(file) #clear the EOF error and the error indicators of a stream.
  • feof

    see feof(file) #returns 1 if it's the end of the file, 0 if it's not.
  • ferror

    see ferror(file) #returns 1 if there's error indicator, 0 if not.
  • perror

    perror('error happened') #print error message to the stderr.


We can flushes the output buffer of a stream using the Fflush() function.



We can push a character to the stream using this function so
the character will be available for the next read.

ungetc(file, 'a')

Well, at this point we’re done of the files chapter.

see you in the next chapter.


Ring Documentation Walkthrough #12.1 – Advanced Read & Write Files

Ring Documentation Walkthrough #12 – Files

Welcome to the new chapter, we will discuss today some of the files functions.

This part is easy to understand.

  • Read()
    This function basically reads the content in a file and returns it as a string.
    For an example:

    content = read('info.txt')
    see content
    content_exe = read('chrome.exe')
    see content_exe

  • Write()
    You can use this function to write string or binary files.

    content = 'Surrender'
    write('message.txt', content)

    We can using it in copying files too:

    pdf1 = read('ringdoc.pdf')
    pdf2 = write('ringdoc2.pdf', pdf1)

  • Dir()
    It basically returns all the files & sub directories found in a directory.
    It returns a list format, every item in the list is actually a list contains two items : 1- file/sub directory name, 2- Type (0 for File, 1 for Directoy)

    tree = dir('folder')
    for item in tree
       see item[1] #output: the file/directory name
       if item[2] = 0 see 'File' + nl
       but item[2] = 1 see 'Directory' + nl

  • Rename()

    rename('tweeter.ico', 'twitter.png')

  • Remove()
    For deleting files.


That’s it, next part i will discuss some of the left functions.

See you in the next one.


Ring Documentation Walkthrough #12 – Files

Ring Documentation Walkthrough #11 – Math

Welcome to the new Chapter, we’ll talk about the mathematical functions.

First of all, the list of the main functions are here, i won’t include them in the post because they’re easy to understand.

So, there’re 3 small functions left.

      1. Random()
        see random() #output: random number
        see random(100) #output: random number <= 100
        see random(10) #output: random number <= 10
      2. Unsigned()
        see unsigned(5, 10, '+') #output: 15
        see unsigned(5, 10, '*') #output: 50
      3. Decimals()
        see 5.12345 + decimals(3) #output: 5.123
        see 5.12345 + decimals(2) #output: 5.12


Yeah, This is all about the mathematical functions in Ring.

See you in the next chapter.


Ring Documentation Walkthrough #11 – Math

Ring Documentation Walkthrough #10 – Check Data Types 1

Welcome to the chapter 10, you’ve made a lot of progress.

We will learn in this post five important functions for checking types of objects, and they’re :

  • isString() & isNumber()
    see isString('amr') #output: 1 (true)
    see isString(1) #output: 0 (false)
    see isNumber(1) #output: 1 (true)
  • isList()
    see isList( [1, 2, 3] ) #output: 1 (true)
    see isList( 'amr' ) #output: 0 (false)
  • isNull()
    x = ''
    see isNull(x) #output: 1 (true)
    see isNull('NULL') #output: 1 (true)
    see isNull(2) #output: 0 (false)
    see isNull( [1, 2, 3] ) #output: 0 (false)
    see isNull('Null') #output: 0 (false)
  • type()
    see type( 'amr' ) #output: STRING
    see type(1) #output: NUMBER
    see type( [1, 2, 3] ) #output: LIST
    see type('') #output: STRING
    see type('NULL') #output: STRING
    see type(true) #output: NUMBER, because true equals 1
    see type(false) #output: NUMBER, because false equals 0

Will be continued in the next post …


Ring Documentation Walkthrough #10 – Check Data Types 1

Ring Documentation Walkthrough #9 – Date and Time

We’ll talk in this chapter about the Date and Time in Ring and its functions.

Let’s start.


We use this function to know how long the program spent running.

for x = 1 to 1000000
   see clock() + nl
#output: milliseconds in each line.


We can get the local system time using this function.

for x = 1 to 1000000
   see time() + nl


We can get the local date with this. The format is dd/mm/yyyy

see date()


This one returns a list of date and time information.

see timelist()

This table shows you index of each info.

  • 1 – Abbreviated weekday name.
  • 2 – Full weekday name.
  • 3 – Abbreviated month name.
  • 4 – Full month name.
  • 5 – Date & Time.
  • 6 – Day of the month.
  • 7 – Hour in 24 format.
  • 8 – Hour in 12 format.
  • 9 – Day of the year.
  • 10 – Month of the year.
  • 11 – Current minutes.
  • 12 – AM or PM.
  • 13 – Current seconds.
  • 14 – Week of the year.
  • 15 – Day of the week.
  • 16 – Date.
  • 17 – Time.
  • 18 – Year of the century.
  • 19 – Year.
  • 20 – Timezone.
  • 21 – Percent sign.


see timelist()[2] + nl #output: Full weekday name.
see timelist()[19] + nl #output: Year.
see timelist()[6] + nl #output: Day of the month.

addays() & diffdays():

see 'Current date : ' + date() + nl #output: 13/02/2016
see 'After 10 days : ' + adddays( date(), 10 ) #output: 23/02/2016

Date1 = date()
Date2 = adddays(Date1, 10)

see diffdays(Date1, Date2) #output: Date1 - Date 2 = -10
see diffdays(Date2, Date1) #output: Date2 - Date1 = 10

This is pretty much the date and time in Ring.

See you in the next chapter.


Ring Documentation Walkthrough #9 – Date and Time

Ring Documentation Walkthrough #8.3 – substr()

We can do a lot with this function:

  1. Find Substring position.
    see substr('Al Ahly SC', 'Ahly') #output: 4
  2. Get string from specific position to the end.
    position = substr('Al Ahly SC', 'Ahly')
    see substr('Al Ahly SC', position) #output: Ahly SC
  3. Get specific amount of characters from specific position.
    str = 'Al Zamalek SC'
    position = substr(str, 'Zamalek')
    see substr(str, position, 7) #output: Zamalek
  4. Replace words or characters inside a string.
    str = `Social Network`
    see substr(str, 'Network', 'Life') + nl #output: Social Life
    #Ignore the case by adding the parameter 1 will convert the string to lower case.
    see substr(str, 'network', 'life', 1) + nl #output: social life 


DONE!, This is the end of the strings chapter, see you in the new chapter.


Ring Documentation Walkthrough #8.3 – substr()