|08                  .,::      .:.::::::.  :::::::::::::::::::..   
|08                  `;;;,  .,;;,;;'```';;,;;;;;;;;'''';;;;``;;;;  
|07                    '[[,,[[' [[[     [[[\    [[      [[[,/[[['  
|07                     Y$$$P   "$$c  cc$$$"    $$      $$$$$$c    
|15                   oP"``"Yo,  "*8bo,Y88b,    88,     888b "88bo,
|15                ,m"       "Mm,  "*YP" "M"    MMM     MMMM   "W" 
|07                --------------------------------------------------
|15                      Mystic BBS - MPL Tutor : Text Files
|07                --------------------------------------------------
                
Except Record files, MPL can also manipulate text files. Text files, instead
of record data, are simple files that contain some text seperated by carriage
return. We can use them, almost the same way as the record files but with some
exceptions. Let see an example. We will write a procedure that reads a file
that has similar structure as an INI file. In this "Inifile" we can hold our
script settings.

Inside our script we first declare the variable that we will be using, at the 
Var section. These will be the variables that will hold the settings in our
imaginary script... :)

|08----[ CODE ]------------------------------------------------------------------|07
Var StringOpt   : String
Var IntOpt      : Integer
Var IniFile     : String
|08------------------------------------------------------------------------------|07

Now lets read our Text File, find the values and assign them to the proper
variables.

|08----[ CODE ]------------------------------------------------------------------|07
Procedure ReadIni
Var Fptr                : File          // Declare a File Variable. Its the
                                        // same type, as in the Record Files.
VAr Key,Value,S         : String
Begin
    If FileExist(IniFile) Then Begin    // Check if our file exist. If not
                                        // we dont do anything.
        fAssign(Fptr,IniFile,66)        // Assign the real file, to our
                                        // variable (Fptr). The 66 means Read,
                                        // Write, privileges.
        fReset(Fptr)                    // Open the file just for reading
        While Not fEof(Fptr) Do Begin   // We will reading the file until we
                                        // reach the end of it. (FEof)
            fReadLn(Fptr,S)             // Read a complete line of text and 
                                        // put it in our variable (s)
            Key:=Upper(WordGet(1,S,'='))    // We use the equal sign (=) as
                                            // a word seperator and use the
                                            // WordGet function to get the 
                                            // Key name and the value of it.
                                            // We also capitalize the Key name
            Value:=WordGet(2,S,'=')     // Our value is the second "word" in
                                        // the line. We could also use some 
                                        // functions to strip any spaces
            Case Key Of                 // Now we find which Key responds to
                                        // our Variable and assign the proper
                                        // Value. We have to convert the value
                                        // where is needed.
                'STRING_OPT'    : stringopt:=value
                'INTEGER_OPT'   : intopt:= Str2Int(Value)
            End
        End
        fClose(Fptr)                    // Finally we close the file
    End
End
|08------------------------------------------------------------------------------|07

What if we want to save our variables/settings to a textfile like INI? The way
of thinking is exactly the same. Assign the file variable to our file, create
or open the file for writing, do our writing and close the file.

|08----[ CODE ]------------------------------------------------------------------|07
Procedure WriteIni
    Var Fptr                : File          // Declare our file variable
Begin
    fAssign(Fptr,IniFile,66)                // Assign the variable to our file
    fRewrite(Fptr)                          // Create a new file!!!
                                            // If the file exists, it will be
                                            // overwritten.
    fWriteln(Fptr,'String_Opt='+stringopt)  // Write the variable to the file
    fWriteln(Fptr,'Int_Opt='+int2str(intopt))
    fClose(Fptr)                            // Close/Save the file.
end
|08------------------------------------------------------------------------------|07

In the example above we created a new file, or overwrite an old one. We could 
also append text/string to an allready existing file. Instead of using fRewrite
we use the command fAppend. This command opens a file that allready exists in a
way that we can add more text with the command fWrite or fWriteln. Try and
change the fRewrite procedure with the fAppend, after creating a file and you 
will see that everytime, it adds/appends the text you write, at the end of the
file.

So... lets see a complete example:

|08----[ CODE ]------------------------------------------------------------------|07
Var StringOpt   : String
Var IntOpt      : Integer
Var IniFile     : String


Procedure ReadIni
Var Fptr                : File          // Declare a File Variable. Its the
                                        // same type, as in the Record Files.
VAr Key,Value,S         : String
Begin
    If FileExist(IniFile) Then Begin    // Check if our file exist. If not
                                        // we dont do anything.
        fAssign(Fptr,IniFile,66)        // Assign the real file, to our
                                        // variable (Fptr)
        fReset(Fptr)                    // Open the file just for reading
        While Not fEof(Fptr) Do Begin   // We will reading the file until we
                                        // reach the end of it.
            fReadLn(Fptr,S)             // Read a complete line of text and 
                                        // put ut in our variable (s)
            Key:=Upper(WordGet(1,S,'='))    // We use the equal sign (=) as
                                            // a word seperator and use the
                                            // WordGet function to get the 
                                            // Key name and the value of it.
                                            // We also capitalize the Key name
            Value:=WordGet(2,S,'=')     // Our value is the second "word" in
                                        // the line. We could also use some 
                                        // functions to strip any spaces
            Case Key Of                 // Now we find which Key responds to
                                        // our Variable and assign the proper
                                        // Value. We have to convert the value
                                        // where is needed.
                'STRING_OPT'    : stringopt:=value
                'INTEGER_OPT'   : intopt:= Str2Int(Value)
            End
        End
        fClose(Fptr)                    // Finally we close the file
    End
End

Procedure WriteIni
    Var Fptr                : File          // Declare our file variable
Begin
    fAssign(Fptr,IniFile,66)                // Assign the variable to our file
    fRewrite(Fptr)                          // Create a new file!!!
                                            // If the file exists, it will be
                                            // overwritten.
    fWriteln(Fptr,'String_Opt='+stringopt)  // Write the variable to the file
    fWriteln(Fptr,'Int_Opt='+int2str(intopt))
    fClose(Fptr)                            // Close/Save the file.
end

Begin

IniFile := JustPath(ProgName)+'mysettings.ini'  // This is the filename of our
                                                // ini/settings file. The func.
                                                // Justpath, gives us the path
                                                // that our script is in.
StringOpt:='THiS iS a STRiNG'                   // Initialize our variables
intopt:=10
ReadIni                                         // If our settings file exist
                                                // our variables will get the
                                                // saved options
    
    Writeln('|07Enter a string:')               // Read user input
    stringopt:=Input(30,30,11,stringopt)
    Writeln('|07Enter a number:')
    intopt:=str2int(Input(5,5,20,int2str(intopt)))
    WriteIni                                    // Write them to our file

End
|08------------------------------------------------------------------------------|07

The above example is very simple, but text files are very versatile and useful
in any programming language. You can use them in various ways, for reading and
saving data.

|08
    ___ _          _       _                     
   /   (_)___  ___| | __ _(_)_ __ ___   ___ _ __ 
  / /\ / / __|/ __| |/ _` | | '_ ` _ \ / _ \ '__|
 / /_//| \__ \ (__| | (_| | | | | | | |  __/ |   
/___,' |_|___/\___|_|\__,_|_|_| |_| |_|\___|_|   
                                                
You are free to use this tutor as you need. Just give a mention to me (xqtr).
Credits goes to g00r00, the programmer behind Mystic BBS software and to Mystic
Guy, (Avon) of the Agency BBS, for their great job, keeping BBSing alive... :)     

Sorry for any typos... English is not my native language...                                            

