docs/en/target/files.txt

   1 .. index::
   2         single: Files; Introduction
   3
   4 =====
   5 files
   6 =====
   7
   8 In this chapter we are going to learn about files functions.
   9
  10 * Read()
  11 * Write()
  12 * Dir()
  13 * Rename()
  14 * Remove()
  15 * fopen()
  16 * fclose()
  17 * fflush()
  18 * freopen()
  19 * tempfile()
  20 * tempname()
  21 * fseek()
  22 * ftell()
  23 * rewind()
  24 * fgetpos()
  25 * fsetpos()
  26 * clearerr()
  27 * feof()
  28 * ferror()
  29 * perror()
  30 * fgetc()
  31 * fgets()
  32 * fputc()
  33 * fputs()
  34 * ungetc()
  35 * fread()
  36 * fwrite()
  37 * fexists()
  38 * Numbers and Bytes
  39
  40 .. index::
  41         pair: Files; Read File using Read()
  42
  43 Read() Function
  44 ===============
  45
  46 We can read the file content using the Read() function
  47
  48 Syntax:
  49
  50 .. code-block:: ring
  51
  52         Read(cFileName) ---> String contains the file content
  53
  54 Example:
  55
  56 .. code-block:: ring
  57
  58         see read("myfile.txt")
  59
  60 The read function can read binary files too
  61
  62 Example:
  63
  64 .. code-block:: ring
  65
  66         see read("myapp.exe")
  67
  68
  69 .. index::
  70         pair: Files; Write file using Write()
  71
  72 Write() Function
  73 ================
  74
  75 We can write string to file using the Write() function
  76
  77 The write function can write binary data to binary files.
  78
  79 Syntax:
  80
  81 .. code-block:: ring
  82
  83         Write(cFileName,cString)        # write string cString to file cFileName
  84
  85 Example:
  86
  87 .. code-block:: ring
  88
  89         # copy file
  90         cFile = read("ring.exe")
  91         write("ring2.exe",cFile)
  92
  93 .. index::
  94         pair: Files; Dir()
  95
  96 Dir() Function
  97 ==============
  98
  99 We can get the folder contents (files & sub folders) using the Dir() function.
 100
 101 Syntax:
 102
 103 .. code-block:: ring
 104
 105         Dir(cFolderPath) ---> List contains files & sub folders.
 106
 107 This function returns a list and each list item is a list of two items
 108
 109 * File/sub folder name
 110
 111 * Type (0 = File , 1 = Folder/Directory)
 112
 113 Example:
 114
 115 .. code-block:: ring
 116
 117         see "Testing DIR() " + nl
 118         mylist = dir("C:\myfolder")
 119         for x in mylist
 120                 if x[2]
 121                         see "Directory : " + x[1] + nl
 122                 else
 123                         see "File : " + x[1] + nl
 124                 ok
 125         next
 126         see "Files count : " + len(mylist)
 127
 128 .. index::
 129         pair: Files; Rename()
 130
 131 Rename() Function
 132 =================
 133
 134 We can rename files using the Rename() function
 135
 136 Syntax:
 137
 138 .. code-block:: ring
 139
 140         Rename(cOldFileName,cNewFileName) ---> Number ( Status: Success (0) , Error (-1) )
 141
 142 Example:
 143
 144 .. code-block:: ring
 145
 146         rename("file.txt","help.txt")
 147
 148 .. index::
 149         pair: Files; Remove()
 150
 151 Remove() Function
 152 =================
 153
 154 We can delete a file using the Remove() function
 155
 156
 157 Syntax:
 158
 159 .. code-block:: ring
 160
 161         Remove(cFileName)
 162
 163 Example:
 164
 165 .. code-block:: ring
 166
 167         remove("test.txt")
 168
 169 .. index::
 170         pair: Files; Fopen()
 171
 172 Fopen() Function
 173 ================
 174
 175 We can open a file using the Fopen() function
 176
 177 Syntax:
 178
 179 .. code-block:: ring
 180
 181         Fopen(cFileName,cMode) ---> File Handle
 182
 183 =====   ==========================================
 184 Mode    Description
 185 =====   ==========================================
 186 "r"     Reading (The file must exist)
 187 "w"     Writing (create empty file / overwrite)
 188 "a"     Appends (create file if it doesn't exist)
 189 "r+"    update (reading/writing)
 190 "w+"    Create empty file (reading/writing)
 191 "a+"    reading & appending
 192 =====   ==========================================
 193
 194 .. index::
 195         pair: Files; Fclose()
 196
 197 Fclose() Function
 198 =================
 199
 200 When we open a file using fopen() function, we can close it
 201 using the Fclose() function
 202
 203 Syntax:
 204
 205 .. code-block:: ring
 206
 207         Fclose(file handle)
 208
 209 .. index::
 210         pair: Files; Fflush()
 211
 212 Fflush() Function
 213 =================
 214
 215 We can flushes the output buffer of a stream using the Fflush() function
 216
 217 Syntax:
 218
 219 .. code-block:: ring
 220
 221         Fflush(file handle)
 222
 223 .. index::
 224         pair: Files; Freopen()
 225
 226 Freopen() Function
 227 ==================
 228
 229 We can open another file using the same file handle and at the same time close
 230 the old file
 231
 232 Syntax:
 233
 234 .. code-block:: ring
 235
 236         Freopen(cFileName,cMode,file handle) ---> file handle
 237
 238 Example:
 239
 240 .. code-block:: ring
 241
 242         freopen("myprogoutput.txt","w+",stdout)
 243         see "welcome" + nl
 244         for x = 1 to 10
 245                 see x + nl
 246         next
 247
 248         /*
 249         ** Read : https://en.wikipedia.org/wiki/Device_file#Device_files
 250         ** The next code is not portable, we can use iswindows() before
 251         ** using it and we can write special code for each operating system.
 252         */
 253
 254         freopen("CON","w",stdout)       # For Microsoft Windows
 255         see "Done" + nl                 # print to stdout again
 256
 257 Output:
 258
 259 .. code-block:: ring
 260
 261         # Output to stdout
 262         Done
 263
 264         # Output to file : myprogoutput.txt
 265         welcome
 266         1
 267         2
 268         3
 269         4
 270         5
 271         6
 272         7
 273         8
 274         9
 275         10
 276
 277 .. index::
 278         pair: Files; Tempfile()
 279
 280 Tempfile() Function
 281 ===================
 282
 283 The function Tempfile() creates a temp. file (binary).
 284
 285 The file will be deleted automatically when the stream is closed
 286
 287 Syntax:
 288
 289 .. code-block:: ring
 290
 291         TempFile() ---> file handle
 292
 293 .. index::
 294         pair: Files; Tempname()
 295
 296 Tempname() Function
 297 ===================
 298
 299 We can generate temp. file name using the Tempname() function
 300
 301 The generated name will be different from the name of any existing file
 302
 303 Syntax:
 304
 305 .. code-block:: ring
 306
 307         Tempname() ---> generated file name as string
 308
 309 .. index::
 310         pair: Files; Fseek()
 311
 312 Fseek() Function
 313 ================
 314
 315 We can set the file position of the stream using the Fseek() function
 316
 317 Syntax:
 318
 319 .. code-block:: ring
 320
 321         Fseek(file handle, nOffset, nWhence) ---> zero if successful
 322
 323 The next table presents the nWhence values
 324
 325 =====   ===============================
 326 Value   Description
 327 =====   ===============================
 328 0       Beginning of file
 329 1       Current position
 330 2       End of file
 331 =====   ===============================
 332
 333 .. index::
 334         pair: Files; Ftell()
 335
 336 Ftell() Function
 337 ================
 338
 339 We can know the current file position of a stream using the Ftell() function
 340
 341 Syntax:
 342
 343 .. code-block:: ring
 344
 345         Ftell(file handle) ---> file position as number
 346
 347 .. index::
 348         pair: Files; Rewind()
 349
 350 Rewind() Function
 351 =================
 352
 353 We can set the file position to the beginning of the file using the Rewind() function
 354
 355 Syntax:
 356
 357 .. code-block:: ring
 358
 359         Rewind(file handle)
 360
 361 .. index::
 362         pair: Files; Fgetpos()
 363
 364 Fgetpos() Function
 365 ==================
 366
 367 We can get handle to the current file position using the Fgetpos() function
 368
 369 Syntax:
 370
 371 .. code-block:: ring
 372
 373         Fgetpos(file handle) ---> position handle
 374
 375 .. index::
 376         pair: Files; Fsetpos()
 377
 378 Fsetpos() Function
 379 ==================
 380
 381 We can set the current file position using the Fsetpos() function
 382
 383 Syntax:
 384
 385 .. code-block:: ring
 386
 387         Fsetpos(file handle,position handle)
 388
 389 .. index::
 390         pair: Files; Clearerr()
 391
 392 Clearerr() Function
 393 ===================
 394
 395 We can clear the EOF error and the error indicators of a stream using the clearerr()
 396 function
 397
 398 Syntax:
 399
 400 .. code-block:: ring
 401
 402         Clearerr(file handle)
 403
 404 .. index::
 405         pair: Files; Feof()
 406
 407 Feof() Function
 408 ===============
 409
 410 We can test the end-of-file indicator using the Feof() function
 411
 412 Syntax:
 413
 414 .. code-block:: ring
 415
 416         Feof(file handle) ---> returns 1 if EOF and 0 if not
 417
 418 .. index::
 419         pair: Files; Ferror()
 420
 421 Ferror() Function
 422 =================
 423
 424 We can test the error indicator of a given stream using the Ferror() function
 425
 426 Syntax:
 427
 428 .. code-block:: ring
 429
 430         Ferror(file handle) ---> returns 1 if error and 0 if not
 431
 432 .. index::
 433         pair: Files; Perror()
 434
 435 Perror() Function
 436 =================
 437
 438 We can print error message to the stderr using the Perror() function
 439
 440 Syntax:
 441
 442 .. code-block:: ring
 443
 444         Perror(cErrorMessage)
 445
 446 .. index::
 447         pair: Files; Fgetc()
 448
 449 Fgetc() Function
 450 ================
 451
 452 We can get the next character from the stream using the Fgetc() function
 453
 454 Syntax:
 455
 456 .. code-block:: ring
 457
 458         Fgetc(file handle) ---> returns character or EOF
 459
 460
 461 .. index::
 462         pair: Files; Fgets()
 463
 464 Fgets() Function
 465 ================
 466
 467 We can read new line from the stream using the Fgets() function
 468
 469 Syntax:
 470
 471 .. code-block:: ring
 472
 473         Fgets(file handle,nSize) ---> string
 474
 475 The function stop when nSize characters are read, new line character is read or EOF.
 476
 477 .. index::
 478         pair: Files; Fputc()
 479
 480 Fputc() Function
 481 ================
 482
 483 We can write a character to the stream using the Fputc() function
 484
 485 Syntax:
 486
 487 .. code-block:: ring
 488
 489         Fputc(file handle,cChar)
 490
 491 .. index::
 492         pair: Files; Fputs()
 493
 494 Fputs() Function
 495 ================
 496
 497 We can write a string to the stream using the Fputs() function
 498
 499 Syntax:
 500
 501 .. code-block:: ring
 502
 503         Fputs(file handle,cString)
 504
 505
 506 .. index::
 507         pair: Files; Ungetc()
 508
 509 Ungetc() Function
 510 =================
 511
 512 We can push a character to the stream using the Ungetc() function
 513
 514 The character will be available for the next read
 515
 516 Syntax:
 517
 518 .. code-block:: ring
 519
 520         Ungetc(file handle,character)
 521
 522
 523 .. index::
 524         pair: Files; Fread()
 525
 526 Fread() Function
 527 ================
 528
 529 We can read data from a stream using the Fread() function
 530
 531 Syntax:
 532
 533 .. code-block:: ring
 534
 535         Fread(file handle,nSize)
 536
 537 .. index::
 538         pair: Files; Fwrite()
 539
 540 Fwrite() Function
 541 =================
 542
 543 We can write data to a stream using the Fwrite() function
 544
 545 Syntax:
 546
 547 .. code-block:: ring
 548
 549         Fwrite(file handle,cString)
 550
 551
 552 .. index::
 553         pair: Files; Fexists()
 554
 555 Fexists() Function
 556 ==================
 557
 558 We can check if a file exists using the Fexists() function
 559
 560 Syntax:
 561
 562 .. code-block:: ring
 563
 564         Fexists(cFileName) ---> returns 1 if the file exists
 565
 566 Example:
 567
 568 .. code-block:: ring
 569
 570         see fexists("b:\mahmoud\apps\ring\ring.exe") + nl +
 571             fexists("b:\mahmoud\apps\ring\ring2.exe") + nl
 572
 573 Output:
 574
 575 .. code-block:: ring
 576
 577         1
 578         0
 579
 580 .. index::
 581         pair: Files; Example
 582
 583 Example
 584 =======
 585
 586 The next program test some of the file functions
 587
 588 .. code-block:: ring
 589
 590         See "testing file functions" + nl
 591
 592         See "open file" + nl
 593         fp = fopen(exefolder() + "../tests/scripts/s65.ring","r")
 594
 595         See "reopen" + nl
 596         fp = freopen(exefolder() + "../tests/scripts/s78.ring","r",fp)
 597         See "close file" + nl
 598         fclose(fp)
 599
 600         see "temp file" + nl
 601         fp = tempfile()
 602         fclose(fp)
 603
 604         see "temp name" + nl
 605         see tempname() + nl
 606
 607         remove(exefolder() + "../tests/scripts/mytest2.txt")
 608         write(exefolder() + "../tests/scripts/tests1.txt","hello")
 609         rename(exefolder() + "../tests/scripts/test1.txt",exefolder() +
 610                                                 "../tests/scripts/mytests2.txt")
 611
 612         see "print file" + nl
 613         fp = fopen(exefolder() + "../samples/fromdoc/filefuncs.ring","r")
 614         r = fgetc(fp)
 615         while isstring(r)
 616                         see r
 617                         r = fgetc(fp)
 618         end
 619         fclose(fp)
 620
 621         see nl+"print line from the file" + nl
 622         fp = fopen(exefolder() + "../samples/fromdoc/filefuncs.ring","r")
 623         r = fgets(fp,33)
 624         see r + nl
 625         fclose(fp)
 626         fp = fopen(exefolder() + "../tests/scripts/test78.txt","w+")
 627         fseek(fp,0,2) # goto end of file
 628         fputc(fp,"t")
 629         fputc(fp,"e")
 630         fputc(fp,"s")
 631         fputc(fp,"t")
 632         fputs(fp,"tests2")
 633         fclose(fp)
 634
 635         see "print file" + nl
 636         see read(exefolder() + "../tests/scripts/test78.txt")
 637
 638         fp = fopen(exefolder() + "../tests/scripts/test78.txt","r")
 639         see "testing ungetc() " + nl
 640         for x = 1 to 3
 641                         r = fgetc(fp)
 642                         see r + nl
 643                         ungetc(fp,r)
 644         next
 645         fclose(fp)
 646
 647         see "testing fread() " + nl
 648         fp = fopen(exefilename(),"rb")
 649         r = fread(fp,100)
 650         see r + nl
 651         fclose(fp)
 652
 653         see "testing fwrite() " + nl
 654         fp = fopen(exefolder() + "../tests/scripts/test1.txt","wb")
 655         fwrite(fp,r)
 656         fclose(fp)
 657
 658 The next example print part of the content of a binary file
 659
 660 .. code-block:: ring
 661
 662         see "Testing: fread()" +" FileName: "+ exefilename() +nl +nl
 663         fp = fopen(exefilename(),"rb")
 664         r = fread(fp,800)
 665         for n =1 to len(r)
 666                 if isprint(substr(r, n, 1))
 667                         see substr(r, n, 1)
 668                 else
 669                         see "."
 670                 ok
 671                 ### 80 char per line
 672                 if n % 80 = 0
 673                         see nl
 674                 ok
 675         next
 676         fclose(fp)
 677
 678 .. index::
 679         pair: Files; Numbers and Bytes
 680
 681 Numbers and Bytes
 682 =================
 683
 684 The next functions to convert between Numbers and Bytes.
 685
 686 * Int2Bytes()
 687 * Float2Bytes()
 688 * Double2Bytes()
 689 * Bytes2Int()
 690 * Bytes2Float()
 691 * Bytes2Double()
 692
 693 Example:
 694
 695 .. code-block:: ring
 696
 697         see "Test Int2Bytes() and Bytes2Int() - Value : 77" + nl
 698         r = Int2Bytes(77)
 699         see "Int Size : " + len(r) + nl
 700         see r + nl
 701         see Bytes2Int(r) + nl
 702         see "Test Float2Bytes() and Bytes2Float() - Value 77.12" + nl
 703         r = Float2Bytes(77.12)
 704         see "Float Size : " + len(r) + nl
 705         see r + nl
 706         see Bytes2Float(r) + nl
 707         see "Test Double2Bytes() and Bytes2Double() - Value 9999977.12345" + nl
 708         r = Double2Bytes(9999977.12345)
 709         see "Double Size : " + len(r) + nl
 710         see r + nl
 711         decimals(5)
 712         see Bytes2Double(r) + nl