Please explain code used in Help file for several File functions

[timmy2]

Here's the Help file example for the FileOpen function.

expandcollapse popup

#include <FileConstants.au3>
#include <MsgBoxConstants.au3>

Example()

Func Example()
    ; Create a constant variable in Local scope of the filepath that will be read/written to.
    Local Const $sFilePath = @TempDir & "\FileOpen.txt"

    ; Create a temporary file to read data from.
    If Not FileCreate($sFilePath, "This is an example of using FileOpen.") Then Return MsgBox($MB_SYSTEMMODAL, "", "An error occurred whilst writing the temporary file.")

    ; Open the file for reading and store the handle to a variable.
    Local $hFileOpen = FileOpen($sFilePath, $FO_READ)
    If $hFileOpen = -1 Then
        MsgBox($MB_SYSTEMMODAL, "", "An error occurred when reading the file.")
        Return False
    EndIf

    ; Read the contents of the file using the handle returned by FileOpen.
    Local $sFileRead = FileRead($hFileOpen)

    ; Close the handle returned by FileOpen.
    FileClose($hFileOpen)

    ; Display the contents of the file.
    MsgBox($MB_SYSTEMMODAL, "", "Contents of the file:" & @CRLF & $sFileRead)

    ; Delete the temporary file.
    FileDelete($sFilePath)
EndFunc   ;==>Example

; Create a file.
Func FileCreate($sFilePath, $sString)
    Local $bReturn = True ; Create a variable to store a boolean value.
    If FileExists($sFilePath) = 0 Then $bReturn = FileWrite($sFilePath, $sString) = 1 ; If FileWrite returned 1 this will be True otherwise False.
    Return $bReturn ; Return the boolean value of either True of False, depending on the return value of FileWrite.
EndFunc   ;==>FileCreate

 

In line 5 of the Func Example() there's a Return before MsgBox.  Is the Return meant to exit the function? How is MsgBox executed with a Return before it?  I haven't noticed this technique before, although I can see what you'd want to provide a way to abort if the temp file can't be created.

If Not FileCreate($sFilePath, "This is an example of using FileOpen.") Then Return MsgBox($MB_SYSTEMMODAL, "", "An error occurred whilst writing the temporary file.")

 

Also, what is the reasoning and purpose behind the design of FileCreate function? 

; Create a file.
Func FileCreate($sFilePath, $sString)
    Local $bReturn = True ; Create a variable to store a boolean value.
    If FileExists($sFilePath) = 0 Then $bReturn = FileWrite($sFilePath, $sString) = 1 ; If FileWrite returned 1 this will be True otherwise False.
    Return $bReturn ; Return the boolean value of either True of False, depending on the return value of FileWrite.
EndFunc   ;==>FileCreate

I assume that the goal of the first line is to declare the local variable, $bReturn, and setting it to True is a bet that the file will be created successfully.

The second line starts out understandable: "if the file does not already exist then create and write the string to it. But what's the " = 1" hanging off the end? I can't say I've ever seen a statement like "variable = function = value" before (even though this same FileCreate function is used in several Help file examples -- I just never noticed these details before). I'm going to need some hand holding through that one.

Why was the FileCreate function even employed when the following seems adequate for creating and writing text to the target file in the Example function?

; Create a temporary file to read data from.
    If Not FileWrite ($sFilePath,"This is an example of using FileOpen.") then MsgBox($MB_SYSTEMMODAL, "", "An error occurred whilst writing the temporary file.")

I realize this leaves out checking to see if the file already exists but what will happen if FileWrite opens and writes text to an existing file?

[guinness]

As I wrote the file examples 20 months ago, it seems only fair that I should help you.

Is the Return meant to exit the function?

Yes, as there is no need to continue if the file can't be created. The example relies on this file creation to showcase the example of FileOpen(). 

How is MsgBox executed with a Return before it?

This is because it's returning the "value" of MsgBox()  (which is $IDOK), so it has to display the message box before returning. Basically the same as Return MyFunc() ; Which MyFunc() would get called first before returning its value.

Also, what is the reasoning and purpose behind the design of FileCreate function? 

Why was the FileCreate function even employed when the following seems adequate for creating and writing text to the target file in the Example function?

I realize this leaves out checking to see if the file already exists but what will happen if FileWrite opens and writes text to an existing file?

The reason is because if a file already exists in the @TempDir called FileOpen.txt, then it won't overwrite the contents with our new data. Of course it's probably a file created by you, when you first ran the example, but then it might be another application that created a temp file with a similar name (unlikely, but possible). Try FIleWrite() only on a file that already exists and you will understand why I did it.

But what's the " = 1" hanging off the end?

Granted 0 and 1 are boolean in some languages, but what this does is if the return of FIleWrite() is zero, then 0 = 1 is False; otherwise 1 = 1 will be True (as the comment suggests). So basically it's a way of converting zero and one to a boolean datatype. Maybe I could amend this, as zero and one are boolean. I was just being strict with datatypes, since $bReturn holds a boolean datatype and not an integer.

Hope I answered everything?

PS The examples can always be improved upon, so good you mentioned this. I now have a better understanding of what I should do to improve their readability.

Edited July 15, 2015 by guinness
Added question mark and ps

[timmy2]

As I wrote the file examples 20 months ago, it seems only fair that I should help you.

Yes, as there is no need to continue if the file can't be created. The example relies on this file creation to showcase the example of FileOpen(). 

This is because it's returning the "value" of MsgBox()  (which is $IDOK), so it has to display the message box before returning. Basically the same as Return MyFunc() ; Which MyFunc() would get called first before returning its value.

The reason is because if a file already exists in the @TempDir called FileOpen.txt, then it won't overwrite the contents with our new data. Of course it's probably a file created by you, when you first ran the example, but then it might be another application that created a temp file with a similar name (unlikely, but possible). Try FIleWrite() only on a file that already exists and you will understand why I did it.

Granted 0 and 1 are boolean in some languages, but what this does is if the return of FIleWrite() is zero, then 0 = 1 is False; otherwise 1 = 1 will be True (as the comment suggests). So basically it's a way of converting zero and one to a boolean datatype. Maybe I could amend this, as zero and one are boolean. I was just being strict with datatypes, since $bReturn holds a boolean datatype and not an integer.

Hope I answered everything?

PS The examples can always be improved upon, so good you mentioned this. I now have a better understanding of what I should do to improve their readability.

Wonderful explanation, thank you.

The following is definitely not criticism; just an observation from the pits.

I am curious why some of the Examples in the Help file employ techniques that seem advanced for the intended audience (Help users). Usually the main topic of the Example (e.g., a function) is demonstrated in a straightforward manner but some of the surrounding code almost seems designed to challenge the reader and expose him or her to more advanced techniques. While I sometimes enjoy and appreciate the exercise in deciphering "what's going on" in an example, other times I'd prefer to not be distracted from the main topic. I guess the question comes down to, "Should an Example be used as an opportunity to introduce techniques unrelated to understanding the specific topic?"

For example, being an infrequent user of AutoIt my techniques tend not to evolve. So the code I would have written to create the temporary file would have been elementary. Since creating the temp file for reading is just to support the main topic using FileOpen I would've put the following in the main Example function and not employed another function:

; Create a temporary file to read data from.
    If FileExists ($sFilePath) Then
        Return MsgBox($MB_SYSTEMMODAL, "", "The temporary file already exists. Bailing out.")
    Else
        If Not FileWrite ($sFilePath,"This is an example of using FileOpen.") then Return MsgBox($MB_SYSTEMMODAL, "", "An error occurred whilst writing the temporary file.")
    EndIf

I chuckled as I wrote the above code because it demonstrates that you taught me a new technique about using Return followed by an action, whereas my code previously would have been a couple lines longer.  But it is at my level of understanding, requiring no deciphering while I pay attention to the main goal of learning how to use FileOpen.

I admire the elegance of your FileCreate function, the use of Boolean logic, etc., and hope to someday reel off similarly elegant code.  Thank you!

[guinness]

That function isn't the same as mine, as I don't "bail out" if the file exists, I simply don't overwrite the file and continue. It only bails if an error occurs with file writing when the file doesn't exist.

As for your question, it's difficult, because though I agree the examples should be simple, in the past AutoIt hasn't been regarded as a simple language without any standards being applied to it. I (and other people on the Forum) have tried to turn this around by showing that "hey, you can apply the standards used in popular languages such as PHP, Java, C#, C++ and still maintain that simplicity we all love about AutoIt."

[timmy2]

    If FileExists($sFilePath) = 0 Then $bReturn = FileWrite($sFilePath, $sString) = 1

Granted 0 and 1 are boolean in some languages, but what this does is if the return of FIleWrite() is zero, then 0 = 1 is False; otherwise 1 = 1 will be True (as the comment suggests). So basically it's a way of converting zero and one to a boolean datatype. Maybe I could amend this, as zero and one are boolean. I was just being strict with datatypes, since $bReturn holds a boolean datatype and not an integer.

Guinness, you added a question mark after "Hope I answered everything?"...

Let me see if I understand in base human terms:  $bReturn will receive a 0 from a successful FileWrite(), but by tacking on "= 1" after the FileWrite function $bReturn "sees" the equation "0 = 1".  Since 0 does not equal 1 that changes $bReturn from its original TRUE state to FALSE.

So this is how you convert a 0 or 1 return value from a function into a boolean state of TRUE or FALSE. Very cool!

If you had not done that, would $bReturn returning a 0 fail to produce the desired result?

I guess I should also ask, "what is the advantage of using boolean TRUE/FALSE instead of just sticking with integer return values?"

Tangentially, are there other instances where you would employ this technique of "variable = a function's return code = something else"?   I've never seen a 3-sided equation.

There's much to digest here.

[guinness]

You're correct.

Well in this example it can be either 0 or 1 OR true or false. BUT (remember the example from earlier) if a function was said to return a boolean value and it returned 1 (which is truthy), then we did this ... If $bReturn == True Then, what would be the result? True or False? Does $bReturn equal true? Answer is no, as the return datatype was an integer NOT a boolean value.

I could have written it like this:

; In Example()
If Not FileCreate(...) Return MsgBox(...

; Create a file.
Func FileCreate($sFilePath, $sString)
    If FileExists($sFilePath) Then Return 1 ; Just return 1 and don't overwrite
    Return FileWrite($sFilePath, $sString) ; Return's either 1 or 0
EndFunc   ;==>FileCreate

It's just a rule of thumb (of mine especially) that a function should return a single datatype if possible. So if a function is to return an integer datatype, then it must do whatever it has to do to return an integer datatype. If it's purpose is to return True or False, then again it must do whatever it has to do to return a boolean datatype. As I felt FileCreate() was a function that should return a boolean datatype, I opted for the following approach.

I guess I could do this now...

; In Example()
If Not FileCreate(...) Return MsgBox(...

; Create a file.
Func FileCreate($sFilePath, $sString)
    If FileExists($sFilePath) Then Return True ; Just return True and don't overwrite
    Return FileWrite($sFilePath, $sString) ? True : False
EndFunc   ;==>FileCreate

 

[guinness]

To answer your tangentially question, here:

Local $sString = ''

; Which is less typing?

; This?
Local $bIsEmptyString
If $sString == '' Then
    $bIsEmptyString = True
Else
    $bIsEmptyString = False
EndIf

; Or this?
Local $bIsEmptyString = ($sString == '') ; True if blank; otherwise, false

 

Edited July 15, 2015 by guinness

[timmy2]

; even shorter by 1 char
Local $bIsEmptyString = ($sString = '') ; True if blank; otherwise, false

So $sString = '' evaluates TRUE, which makes $bIsEmptyString = TRUE.

Tested whether == was necessary by using StringUpper and StringLower on '' and nothing changed. But Case would matter if we were dealing with non-null strings.

Very interesting. Thank you, Guinness.

Not to get too tangential but would you mind looking at my question at https://www.autoitscript.com/forum/topic/173963-get-network-adapter-info-from-another-pc-in-workgroup/#comment-1258975?  You were the original author, I think.

[mLipok]

; even shorter by 1 char
Local $bIsEmptyString = ($sString = '') ; True if blank; otherwise, false

beware: not always shorter:

Local $sString = '2.0'
MsgBox(0, $sString, ($sString == 2))
MsgBox(0, $sString, ($sString = 2))

Local $sString2 = 'Test'
MsgBox(0, $sString2, ($sString2 == 'test'))
MsgBox(0, $sString2, ($sString2 = 'test'))

here https://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm
you can read why it is different.

@guinness Thanks for such a good lesson.

 

Edited July 15, 2015 by mLipok

[mLipok]

PS The examples can always be improved upon, so good you mentioned this. I now have a better understanding of what I should do to improve their readability.

Can you pass here the new improved example ?
I ask about as I want to have a possibility to trace changes in relation to this very interesting thread.

mLipok

 

 

[timmy2]

beware: not always shorter:

Local $sString = '2.0'
MsgBox(0, $sString, ($sString == 2))
MsgBox(0, $sString, ($sString = 2))

Local $sString2 = 'Test'
MsgBox(0, $sString2, ($sString2 == 'test'))
MsgBox(0, $sString2, ($sString2 = 'test'))

here https://www.autoitscript.com/autoit3/docs/intro/lang_operators.htm
you can read why it is different.

@guinness Thanks for such a good lesson.

 

Thank you, but I was referring to his specific example using a null string. Yours is a better example of when == is useful.

[guinness]

Can you pass here the new improved example ?I ask about as I want to have a possibility to trace changes in relation to this very interesting thread.

mLipok

 

 

I haven't updated them yet. I will more than likely use this function instead...(though I dunno, what do people prefer?)

; Create a file.
Func FileCreate($sFilePath, $sString)
    If FileExists($sFilePath) Then Return True ; Just return True and don't overwrite
    Return FileWrite($sFilePath, $sString) ? True : False
EndFunc   ;==>FileCreate

 

[timmy2]

I haven't updated them yet. I will more than likely use this function instead...(though I dunno, what do people prefer?)

; Create a file.
Func FileCreate($sFilePath, $sString)
    If FileExists($sFilePath) Then Return True ; Just return True and don't overwrite
    Return FileWrite($sFilePath, $sString) ? True : False ; see Ternary Conditional Operator for explanation
EndFunc   ;==>FileCreate

 

I vote YES. It employs basic techniques that won't perplex the noob Help file reader, yet like any good teacher introduces one not-so-obvious item (Ternary Conditional Operator) for the reader to discover (provided a reference link). How about this rule: a limit of one puzzle per Help example, always with a comment that at least leads to a thorough explanation? The reader is drawn forward gradually to expanding his or her vocabulary and tool set.

[guinness]

OK, I will do it this evening if I have time.

[guinness]

So seems I forgot about this. I just checked the help file for FileCreate() and couldn't find it. Then I remembered I ripped that code out last year and replaced with temporary file creation instead. I think it would be wise to updrade your copy of AutoIt to v3.3.14.0, which came out recently.

expandcollapse popup

Revision: 10523
Author: guinness
Date: 30 July 2014 16:51:17
Message:
Fixed: Now using a temporary file instead of a static filepath.
----
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileClose.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileCopy.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileCreateNTFSLink.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileDelete.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileExists.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileFlush.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileGetPos.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileGetTime.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileMove.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileMove[2].au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileOpen.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileOpen[2].au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileRead.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileReadLine.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileRecycle.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileSetEnd.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileSetPos.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileSetTime.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileWrite.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/FileWriteLine.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/InetClose.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/InetGet.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/InetGetInfo.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/InetGet[2].au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/IniDelete.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/IniRead.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/IniReadSection.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/IniReadSectionNames.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/IniRenameSection.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/IniWrite.au3
Modified : /trunk/docs/autoit/english/txt2htm/examples/IniWriteSection.au3