##########################################################################################
#                                                                                        #
#    Unit bsFile  /  bornSoft 2010      This unit is FREEWARE.                          #
#    ------------------------------                                                      #
#                                        Provided "as is". Use it at your own risk !!    #
#    Version:  1.0.1.2010                No liability for data-loss or anything else!    #
#                                                                                        #
##########################################################################################

##########################################################################################
#                                                                                         
#    This unit consists of a command "bsFILE" and a function "@bsFILE()".                 
#                                                                                         
#    The main pupose of this unit is to simplify reading and writing from and to files.   
#    With the function "@bsFILE()" you get the whole file into a single variable and      
#    with the command "bsFILE" you save the content of a variable as a file to disk.      
#                                                                                         
#    And there is another great benefit:                                                  
#                                                                                         
#    Due to the data is read and written binary, you are able to write for example the    
#    content from a multiline edit box in it's original format (without the additional    
#    two bytes for CRLF that are always added if you save using "LIST SAVEFILE, ...").    
#    And even foreign characters that you can grab from other editors or from the         
#    clipboard can be processed in this way.                                              
#                                                                                         
#        Usage:    %F = @bsFILE( GET , <FILE> )                                           
#                                                                                         
#        This gets the content of FILE into the variable "%F". If FILE is a binary,       
#        then the variable "%F" now contains raw binary data.                             
#                                                                                         
#                  %B = @bsFILE( BIN, <FILE> )                                            
#                                                                                         
#        This function checks if FILE is a binary file. If it contains binary data the    
#        return value will be TRUE (1) while if it's a text-file or empty or doesn't      
#        exist, NULL is returned. @OK() keeps true in any case. Unicode-files are not     
#        treated as binary by this function.                                              
#                                                                                         
#                  %U = @bsFile( UNICODE, <FILE> )                                        
#                                                                                         
#        This function checks if FILE is a UNICODE file. It returnes TRUE (1) if the      
#        file is a UNICODE file and NULL if not. UNICODE files contain lots of            
#        binary zero characters but are actually not binary files in this sense.          
#                                                                                         
#                  bsFILE SAVE , <DATA> , <PATH>\<FILE> [ , CONFIRM/SKIP , RECYCLER ]     
#                                                                                         
#        This command saves the DATA to a file.                                           
#                                                                                         
#        The second parameter is the DATA to save and the third one must be a valid       
#        filename. If no path is provided, the file is saved to the applications          
#        directory. If a destination directory doesn't exist, it will be created.         
#                                                                                         
#        DATA must be the second parameter. DATA can be TEXT, BINARY data or empty.       
#        If DATA is empty, a zero byte file is written.                                   
#                                                                                         
#        Attention! By default existing files will be overwritten!                        
#                                                                                         
#        If CONFIRM is set, a messagebox is displayed to ask for overwriting.             
#        If SKIP is set, the command will silently abort the operation without            
#        overwriting.                                                                     
#        If RECYCLER is set, the overwritten file is deleted to the Recycle Bin.          
#                                                                                         
#        Note:  The application that is using this command must have write-access to      
#        the chosen directory.                                                            
#                                                                                         
#    For both - the function GET and the command - if the file could not be read or       
#    written for any reason, @OK() is set to FALSE. With this you can determine if the    
#    action was successful or not.                                                        
#                                                                                         
#    If the variable "%%Debug" is not NULL, error-messages are displayed.                 
#                                                                                         
