fix return value of os.writefile_ifnotequal()

[mercury233]

What does this PR do?

• fix return value of os.writefile_ifnotequal()
• add test for that function
• update the document for that function

How does this PR change Premake's behavior?

Before #2654 , os.writefile_ifnotequal() returns 1 if successful, 0 if the string is identical to the current file contents, otherwise -1 and an error message. #2654 seems to changed this behavior accidentally, return 0 on success too. This PR change the behavior back.

Anything else we should know?

@jkriegshauser

Did you check all the boxes?

• Focus on a single fix or feature; remove any unrelated formatting or code changes
• Add unit tests showing fix or feature works; all tests pass
• Mention any related issues (put closes #XXXX in comment to auto-close issue when PR is merged)
• Follow our coding conventions
• Minimize the number of commits
• Align documentation to your changes

You can now support Premake on our OpenCollective. Your contributions help us spend more time responding to requests like these!

[nickclark2016]

Suggest changing this to be a table

[jkriegshauser]

Please add unit tests to prevent future regressions

[mercury233]

Suggested change

	`1` if successful, `0` if the string is identical to the current file contents, otherwise `-1` and an error message.
	The first return value:
	| Value | Explanation |
	|-------|------------------------------------------------------|
	| 1 | The string was written to the file |
	| 0 | The string is identical to the current file contents |
	| -1 | An error occurred |
	The second return value is an error message if the first return value is -1, otherwise nil.

should it be like this?

[mercury233]

Added tests, but I’m unsure whether they are appropriate, since the test_runner.lua intentionally uses functions like stub_os_writefile_ifnotequal to prevent actual operations.

[jkriegshauser]

Added tests, but I’m unsure whether they are appropriate, since the test_runner.lua intentionally uses functions like stub_os_writefile_ifnotequal to prevent actual operations.

If the test fails before your fix then it's appropriate 😄

You may have to capture the original function value before it's stubbed out. Such as what I did in test_lua_unicode.lua:

    local real_io_open = io.open

-- ...

function suite.loadfile_UnicodeFilename()
	local p = tmpname()
	p = p .. "_café.lua"
	local f = assert(real_io_open(p, "w"))
	-- ...
end