docs/en/target/systemfunc.txt

   1 .. index::
   2         single: System Functions; Introduction
   3
   4 ================
   5 System Functions
   6 ================
   7
   8 In this chapter we are going to learn about the system functions
   9
  10 * System()
  11
  12 * SysGet()
  13
  14 * IsMSDOS()
  15
  16 * IsWindows()
  17
  18 * IsWindows64()
  19
  20 * IsUnix()
  21
  22 * IsMacOSX()
  23
  24 * IsLinux()
  25
  26 * IsFreeBSD()
  27
  28 * IsAndroid()
  29
  30 * Windowsnl()
  31
  32 * Get Command Line Arguments
  33
  34 * Get Active Source File Name
  35
  36 * CurrentDir()
  37
  38 * ExeFileName()
  39
  40 * ChDir()
  41
  42 * ExeFolder()
  43
  44 * Version()
  45
  46 * Shutdown()
  47
  48 .. index::
  49         pair: System Functions; System() Function
  50
  51 System() Function
  52 =================
  53
  54 We can execute system commands using the system() function
  55
  56 Syntax:
  57
  58 .. code-block:: ring
  59
  60         System(cCommand)
  61
  62 Example:
  63
  64 .. code-block:: ring
  65
  66         System("myapp.exe")     # Run myapp.exe
  67         System("ls")            # print list of files
  68
  69 .. index::
  70         pair: System Functions; SysGet() Function
  71
  72 SysGet() Function
  73 =================
  74
  75 We can get environment variables using the Get() function
  76
  77 Syntax:
  78
  79 .. code-block:: ring
  80
  81         SysGet(cVariable)
  82
  83 Example:
  84
  85 .. code-block:: ring
  86
  87         see sysget("path")              # print system path information
  88
  89
  90 .. index::
  91         pair: System Functions; IsMSDOS() Function
  92
  93 IsMSDOS() Function
  94 ==================
  95
  96 We can check if the operating system is MSDOS or not using the IsMSDOS() function
  97
  98 Syntax:
  99
 100 .. code-block:: ring
 101
 102         IsMSDOS() ---> Returns 1 if the operating system is MS-DOS, Returns 0 if it's not
 103
 104
 105 .. index::
 106         pair: System Functions; IsWindows() Function
 107
 108 IsWindows() Function
 109 ====================
 110
 111 We can check if the operating system is Windows or not using the IsWindows() function
 112
 113 Syntax:
 114
 115 .. code-block:: ring
 116
 117         IsWindows() ---> Returns 1 if the operating system is Windows, Returns 0 if it's not
 118
 119
 120 .. index::
 121         pair: System Functions; IsWindows64() Function
 122
 123 IsWindows64() Function
 124 ======================
 125
 126 We can check if the operating system is Windows 64bit or not using the IsWindows64() function
 127
 128 Syntax:
 129
 130 .. code-block:: ring
 131
 132         IsWindows64() ---> Returns 1 if the operating system is Windows64, Returns 0 if it's not
 133
 134
 135 .. index::
 136         pair: System Functions; IsUnix() Function
 137
 138 IsUnix() Function
 139 =================
 140
 141 We can check if the operating system is Unix or not using the IsUnix() function
 142
 143 Syntax:
 144
 145 .. code-block:: ring
 146
 147         IsUnix() ---> Returns 1 if the operating system is Unix, Returns 0 if it's not
 148
 149
 150 .. index::
 151         pair: System Functions; IsMacOSX() Function
 152
 153 IsMacOSX() Function
 154 ===================
 155
 156 We can check if the operating system is macOS or not using the IsMacOSX() function
 157
 158 Syntax:
 159
 160 .. code-block:: ring
 161
 162         IsMacOSX() ---> Returns 1 if the operating system is Mac OS X, Returns 0 if it's not
 163
 164
 165 .. index::
 166         pair: System Functions; IsLinux() Function
 167
 168 IsLinux() Function
 169 ==================
 170
 171 We can check if the operating system is Linux or not using the IsLinux() function
 172
 173 Syntax:
 174
 175 .. code-block:: ring
 176
 177         IsLinux() ---> Returns 1 if the operating system is Linux, Returns 0 if it's not
 178
 179
 180 .. index::
 181         pair: System Functions; IsFreeBSD() Function
 182
 183 IsFreeBSD() Function
 184 ====================
 185
 186 We can check if the operating system is FreeBSD or not using the IsFreeBSD() function
 187
 188 Syntax:
 189
 190 .. code-block:: ring
 191
 192         IsFreeBSD() ---> Returns 1 if the operating system is FreeBSD, Returns 0 if it's not
 193
 194
 195 .. index::
 196         pair: System Functions; IsAndroid() Function
 197
 198 IsAndroid() Function
 199 ====================
 200
 201 We can check if the operating system is Android or not using the IsAndroid() function
 202
 203 Syntax:
 204
 205 .. code-block:: ring
 206
 207         IsAndroid() ---> Returns 1 if the operating system is Android, Returns 0 if it's not
 208
 209 .. index::
 210         pair: System Functions; Example
 211
 212 Example
 213 =======
 214
 215 .. code-block:: ring
 216
 217         see "IsMSDOS()     --> " + ismsdos()     + nl
 218         see "IsWindows()   --> " + iswindows()   + nl
 219         see "IsWindows64() --> " + iswindows64() + nl
 220         see "IsUnix()      --> " + isunix()      + nl
 221         see "IsMacOSX()    --> " + ismacosx()    + nl
 222         see "IsLinux()     --> " + islinux()     + nl
 223         see "IsFreeBSD()   --> " + isfreebsd()   + nl
 224         see "IsAndroid()   --> " + isandroid()   + nl
 225
 226 Output:
 227
 228 .. code-block:: ring
 229
 230         IsMSDOS()     --> 0
 231         IsWindows()   --> 1
 232         IsWindows64() --> 0
 233         IsUnix()      --> 0
 234         IsMacOSX()    --> 0
 235         IsLinux()     --> 0
 236         IsFreeBSD()   --> 0
 237         IsAndroid()   --> 0
 238
 239 .. index::
 240         pair: System Functions; Windowsnl() Function
 241
 242 Windowsnl() Function
 243 ====================
 244
 245 We can get the windows new line string using the Windowsnl() function.
 246
 247 Syntax:
 248
 249 .. code-block:: ring
 250
 251         WindowsNL() ---> Returns a string contains CR+LF = CHAR(13) + CHAR(10)
 252
 253 Example:
 254
 255 .. code-block:: ring
 256
 257         cStr = read("input.txt")
 258
 259         if iswindows()
 260                 cStr = substr(cStr,windowsnl(),nl)
 261         ok
 262
 263         aList = str2list(cStr)
 264         # to do - list items processing using "for in"
 265         cStr = list2str(aList)
 266
 267         if iswindows()
 268                 cStr = substr(cStr,nl,windowsnl())
 269         ok
 270
 271         write("ouput.txt",cStr)
 272
 273 .. index::
 274         pair: System Functions; Get Command Line Arguments
 275
 276 Get Command Line Arguments
 277 ==========================
 278
 279 We can get the command line arguments passed to the ring script using the sysargv variable.
 280
 281 The sysargv variable is a list contains the command line parameters.
 282
 283 Example
 284
 285 .. code-block:: ring
 286
 287         see copy("=",30) + nl
 288         see "Command Line Parameters" + nl
 289         see "Size : " + len(sysargv) + nl
 290         see sysargv
 291         see copy("=",30) + nl
 292         if len(sysargv) < 4 return ok
 293         nStart = sysargv[3]
 294         nEnd = sysargv[4]
 295         for x = nStart to nEnd
 296                 see x + nl
 297         next
 298
 299 Output
 300
 301 .. code-block:: ring
 302
 303         b:\mahmoud\apps\ring>ring tests\syspara.ring 1 10
 304         ==============================
 305         Command Line Parameters
 306         Size : 4
 307         ring
 308         tests\syspara.ring
 309         1
 310         10
 311         ==============================
 312         1
 313         2
 314         3
 315         4
 316         5
 317         6
 318         7
 319         8
 320         9
 321         10
 322
 323 .. index::
 324         pair: System Functions; Get Active Source File Name
 325
 326 Get Active Source File Name
 327 ===========================
 328
 329 We can get the active source file name (*.ring) using the filename() function
 330
 331 Syntax:
 332
 333 .. code-block:: ring
 334
 335         filename() ---> String contains the active source file name.
 336
 337 Example:
 338
 339 .. code-block:: ring
 340
 341         see "Active Source File Name : " + filename() + nl
 342
 343 Output:
 344
 345 .. code-block:: ring
 346
 347         Active Source File Name : tests\filename.ring
 348
 349
 350 Example:
 351
 352 .. code-block:: ring
 353
 354         if sysargv[2] = filename()
 355                 see "I'm the main program file!" + nl
 356                 # we can run tests here!
 357         else
 358                 see "I'm a sub file in a program" + nl
 359         ok
 360
 361
 362 .. index::
 363         pair: System Functions; PrevFileName() Function
 364
 365 PrevFileName() Function
 366 =======================
 367
 368 Using the PrevFileName() function we can get the previous active source file name.
 369
 370 The previous file would be the file of the caller function, Or the file of the function
 371 that we called before calling PrevFileName().
 372
 373 Syntax:
 374
 375 .. code-block:: ring
 376
 377         prevfilename() ---> String contains the previous source file name.
 378
 379 Example:
 380
 381 The next function in stdlib.ring uses the PrevFileName() to know if the file of the
 382 caller function is the main source file of the program or not.
 383
 384 .. code-block:: ring
 385
 386         Func IsMainSourceFile
 387                 if PrevFileName() = sysargv[2]
 388                         return true
 389                 ok
 390                 return false
 391
 392 .. index::
 393         pair: System Functions; CurrentDir() Function
 394
 395 CurrentDir() Function
 396 =====================
 397
 398 Return the path of the current directory
 399
 400 Syntax:
 401
 402 .. code-block:: ring
 403
 404         CurrenDir() ---> String contains the path of the currect directory
 405
 406 .. index::
 407         pair: System Functions; ExeFileName() Function
 408
 409 ExeFileName() Function
 410 ======================
 411
 412 Return the Ring executable file name
 413
 414 Syntax:
 415
 416 .. code-block:: ring
 417
 418         exefilename() ---> String contains the Ring executable file name
 419
 420 .. index::
 421         pair: System Functions; ChDir() Function
 422
 423 ChDir() Function
 424 ================
 425
 426 Change the current directory
 427
 428 Syntax:
 429
 430 .. code-block:: ring
 431
 432         ChDir(cNewPath)
 433
 434 .. index::
 435         pair: System Functions; ExeFolder() Function
 436
 437 ExeFolder() Function
 438 ====================
 439
 440 Return the Ring executable file path
 441
 442 Syntax:
 443
 444 .. code-block:: ring
 445
 446         exefolder() ---> String contains the Ring executable path
 447
 448 .. index::
 449         pair: System Functions; Version() Function
 450
 451 Version() Function
 452 ==================
 453
 454 Return the Ring version
 455
 456 Syntax:
 457
 458 .. code-block:: ring
 459
 460         version() ---> String contains the Ring version
 461
 462 Output:
 463
 464 .. code-block:: ring
 465
 466         1.12
 467
 468
 469 .. index::
 470         pair: System Functions; Shutdown() Function
 471
 472 Shutdown() Function
 473 ===================
 474
 475 Close the application
 476
 477 Syntax:
 478
 479 .. code-block:: ring
 480
 481         shutdown(nStatus) ---> Close the application
 482