File access - Revision history

Wervyn: /* Reading and Writing Binary Data */ MZX was updated a long time ago.

2010-01-19T16:21:07Z

Reading and Writing Binary Data: MZX was updated a long time ago.

← Older revision		Revision as of 16:21, 19 January 2010
Line 16:		Line 16:
	This would read four bytes stored in little-endian format from the file, and combine them together to form a single 32-bit value. (See the articles on [[expressions]] and [[bitwise math]] for more information on this code.)		This would read four bytes stored in little-endian format from the file, and combine them together to form a single 32-bit value. (See the articles on [[expressions]] and [[bitwise math]] for more information on this code.)

	This is a somewhat contrived application, since another way to read from and write to a file is to use "fread_counter" and "fwrite_counter". These ~~were originally intended to conveniently~~ read and write full counter values, instead of just bytes. ~~Currently they are out of date, and work on 16-bit values instead of the 32-bit values MZX uses now. However, there are plans to update them to work on 32-bit values in the near future.~~		This is a somewhat contrived application, since another way to read from and write to a file is to use "fread_counter" and "fwrite_counter". These read and write full 32-bit counter values, instead of just bytes.

	===Reading and Writing Strings===		===Reading and Writing Strings===
	Finally, MZX provides reading and writing of arbitrary length strings. Originally, the method for doing this was very limited. The "fread" and "fwrite" counters were overloaded to work with string values. A quirk with the way strings are handled forced a nonstandard syntax here, however: instead of		Finally, MZX provides reading and writing of arbitrary length strings. Originally, the method for doing this was very limited. The "fread" and "fwrite" counters were overloaded to work with string values. A quirk with the way strings are handled forced a nonstandard syntax here, however: instead of

Wervyn: /* Opening and Navigating Files */ Note about using fread_pos = -1 to test for file existence

2009-07-08T04:00:42Z

Opening and Navigating Files: Note about using fread_pos = -1 to test for file existence

← Older revision		Revision as of 04:00, 8 July 2009
Line 9:		Line 9:
	Directory paths can also be used (MZX is OS agnostic and interprets both '<tt>\\</tt>' and '<tt>/</tt>' as separators), but for security reasons MZX will not allow access to directories above the one the .mzx file is running from. It is also perfectly acceptable to have a file open for both reading and writing at the same time. However, "fwrite_open" clears the contents of whatever file it opens and starts editing a new, blank file. So MZX also provides the "fwrite_modify" and "fwrite_append" functions, which preserve the contents of the file being opened. "fwrite_modify" places the write cursor at the beginning of the file, while "fwrite_append" starts writing at the end of the file.		Directory paths can also be used (MZX is OS agnostic and interprets both '<tt>\\</tt>' and '<tt>/</tt>' as separators), but for security reasons MZX will not allow access to directories above the one the .mzx file is running from. It is also perfectly acceptable to have a file open for both reading and writing at the same time. However, "fwrite_open" clears the contents of whatever file it opens and starts editing a new, blank file. So MZX also provides the "fwrite_modify" and "fwrite_append" functions, which preserve the contents of the file being opened. "fwrite_modify" places the write cursor at the beginning of the file, while "fwrite_append" starts writing at the end of the file.

	The cursor, or in other words the place in the file currently be read from or written to, is maintained in the counters "fread_pos" and "fwrite_pos". These are separate values that do not interfere with one another, since it is after all quite common to have one file open for reading and another for writing. The cursors are automatically advanced when read/write operations are performed on the file, but they can also be set manually to navigate around the file. Before the [[MegaZeux#SDL Port\|port]], when counters were only 16 bits, there existed "fread_page" and "fwrite_page" counters for working with files larger than 64KB in size. Since counters became 32-bit, however, these have been rendered obsolete, and fread_pos/fwrite_pos rendered absolute. Additionally, this has allowed for a convenient way to seek to the end of the file, by setting the appropriate "_pos" counter to -1.		The cursor, or in other words the place in the file currently be read from or written to, is maintained in the counters "fread_pos" and "fwrite_pos". These are separate values that do not interfere with one another, since it is after all quite common to have one file open for reading and another for writing. The cursors are automatically advanced when read/write operations are performed on the file, but they can also be set manually to navigate around the file. Before the [[MegaZeux#SDL Port\|port]], when counters were only 16 bits, there existed "fread_page" and "fwrite_page" counters for working with files larger than 64KB in size. Since counters became 32-bit, however, these have been rendered obsolete, and fread_pos/fwrite_pos rendered absolute. Additionally, this has allowed for a convenient way to seek to the end of the file, by setting the appropriate "_pos" counter to -1. It is also possible to use this to check if a file exists, by opening it for reading and attempting to seek to the end this way. If the file doesn't exist, fread_pos will still be -1 when you check it, instead of the length of the file.

	===Reading and Writing Binary Data===		===Reading and Writing Binary Data===
	Reading and writing actual data can be done in a few different ways. The simplest of these is simply to use the counters "fread" and "fwrite" as placeholders for data to be read from or written to the open file. "fwrite" must always be assigned TO (except for certain syntax related to strings, see below), but "fread" can be [[counter interpolation\|interpolated]] into robotic code just like any other counter, and will be evaluated each time it is encountered. Evaluation, in this case, entails reading one byte from the file, and advancing fread_pos by one. So for example:		Reading and writing actual data can be done in a few different ways. The simplest of these is simply to use the counters "fread" and "fwrite" as placeholders for data to be read from or written to the open file. "fwrite" must always be assigned TO (except for certain syntax related to strings, see below), but "fread" can be [[counter interpolation\|interpolated]] into robotic code just like any other counter, and will be evaluated each time it is encountered. Evaluation, in this case, entails reading one byte from the file, and advancing fread_pos by one. So for example:

Wervyn: Category

2008-06-13T15:31:58Z

Wervyn: Added some headings.

2008-06-01T01:09:56Z

Added some headings.

← Older revision		Revision as of 01:09, 1 June 2008
Line 1:		Line 1:
	[[MegaZeux]] has supported reading and writing data to files since version 2.60, and since then this capability has been augmented and improved to allow for the use of external resources in a number of different ways. Apart from counter interfaces to directly manipulate the contents of a file, '''file access''' encompasses specific interfaces for reading and writing [[robot\|robots]] and [[Robotic]], [[MZM\|MZMs]], and entire MZX worlds.		[[MegaZeux]] has supported reading and writing data to files since version 2.60, and since then this capability has been augmented and improved to allow for the use of external resources in a number of different ways. Apart from counter interfaces to directly manipulate the contents of a file, '''file access''' encompasses specific interfaces for reading and writing [[robot\|robots]] and [[Robotic]], [[MZM\|MZMs]], and entire MZX worlds.

	==~~The Basics~~==		==General Purpose File Access==
	MZX supports basic file reading and writing through the use of specific keyword counters, which fall into two obvious categories: "fread" counters for reading, and "fwrite" counters for writing.		MZX supports basic file reading and writing through the use of specific keyword counters, which fall into two obvious categories: "fread" counters for reading, and "fwrite" counters for writing.
			===Opening and Navigating Files===
	First, a file must be opened for reading/writing, using the following syntax:		First, a file must be opened for reading/writing, using the following syntax:
	set "filename.ext" to "fread_open"		set "filename.ext" to "fread_open"
Line 10:		Line 10:

	The cursor, or in other words the place in the file currently be read from or written to, is maintained in the counters "fread_pos" and "fwrite_pos". These are separate values that do not interfere with one another, since it is after all quite common to have one file open for reading and another for writing. The cursors are automatically advanced when read/write operations are performed on the file, but they can also be set manually to navigate around the file. Before the [[MegaZeux#SDL Port\|port]], when counters were only 16 bits, there existed "fread_page" and "fwrite_page" counters for working with files larger than 64KB in size. Since counters became 32-bit, however, these have been rendered obsolete, and fread_pos/fwrite_pos rendered absolute. Additionally, this has allowed for a convenient way to seek to the end of the file, by setting the appropriate "_pos" counter to -1.		The cursor, or in other words the place in the file currently be read from or written to, is maintained in the counters "fread_pos" and "fwrite_pos". These are separate values that do not interfere with one another, since it is after all quite common to have one file open for reading and another for writing. The cursors are automatically advanced when read/write operations are performed on the file, but they can also be set manually to navigate around the file. Before the [[MegaZeux#SDL Port\|port]], when counters were only 16 bits, there existed "fread_page" and "fwrite_page" counters for working with files larger than 64KB in size. Since counters became 32-bit, however, these have been rendered obsolete, and fread_pos/fwrite_pos rendered absolute. Additionally, this has allowed for a convenient way to seek to the end of the file, by setting the appropriate "_pos" counter to -1.
			===Reading and Writing Binary Data===
	Reading and writing actual data can be done in a few different ways. The simplest of these is simply to use the counters "fread" and "fwrite" as placeholders for data to be read from or written to the open file. "fwrite" must always be assigned TO (except for certain syntax related to strings, see below), but "fread" can be [[counter interpolation\|interpolated]] into robotic code just like any other counter, and will be evaluated each time it is encountered. Evaluation, in this case, entails reading one byte from the file, and advancing fread_pos by one. So for example:		Reading and writing actual data can be done in a few different ways. The simplest of these is simply to use the counters "fread" and "fwrite" as placeholders for data to be read from or written to the open file. "fwrite" must always be assigned TO (except for certain syntax related to strings, see below), but "fread" can be [[counter interpolation\|interpolated]] into robotic code just like any other counter, and will be evaluated each time it is encountered. Evaluation, in this case, entails reading one byte from the file, and advancing fread_pos by one. So for example:
	set "counter" to "('fread'+('fread'<<8)+('fread'<<16)+('fread'<<24))"		set "counter" to "('fread'+('fread'<<8)+('fread'<<16)+('fread'<<24))"
Line 16:		Line 16:

	This is a somewhat contrived application, since another way to read from and write to a file is to use "fread_counter" and "fwrite_counter". These were originally intended to conveniently read and write full counter values, instead of just bytes. Currently they are out of date, and work on 16-bit values instead of the 32-bit values MZX uses now. However, there are plans to update them to work on 32-bit values in the near future.		This is a somewhat contrived application, since another way to read from and write to a file is to use "fread_counter" and "fwrite_counter". These were originally intended to conveniently read and write full counter values, instead of just bytes. Currently they are out of date, and work on 16-bit values instead of the 32-bit values MZX uses now. However, there are plans to update them to work on 32-bit values in the near future.
			===Reading and Writing Strings===
	Finally, MZX provides reading and writing of arbitrary length strings. Originally, the method for doing this was very limited. The "fread" and "fwrite" counters were overloaded to work with string values. A quirk with the way strings are handled forced a nonstandard syntax here, however: instead of		Finally, MZX provides reading and writing of arbitrary length strings. Originally, the method for doing this was very limited. The "fread" and "fwrite" counters were overloaded to work with string values. A quirk with the way strings are handled forced a nonstandard syntax here, however: instead of
	set "fwrite" to "$string"		set "fwrite" to "$string"
Line 52:		Line 52:
	goto "#return"		goto "#return"
	Of course depending on the size of the data stored in the file, another popular method is to simply read the entire file into a string and parse the contents internally as needed.		Of course depending on the size of the data stored in the file, another popular method is to simply read the entire file into a string and parse the contents internally as needed.
			===Closing Files===
	One final note: once you have finished working with a file, it is generally a good idea to close it and free up the handle for other programs to use. However, MZX does not provide an fread or fwrite_close function. Instead, and because only one file can be open for reading or writing at a time, the following trick is used to reset the handle:		One final note: once you have finished working with a file, it is generally a good idea to close it and free up the handle for other programs to use. However, MZX does not provide an fread or fwrite_close function. Instead, and because only one file can be open for reading or writing at a time, the following trick is used to reset the handle:
	set "" to "fread_open"		set "" to "fread_open"

Wervyn: /* Other Types of File Access */ Missed a closing tag.

2008-05-30T18:38:06Z

Other Types of File Access: Missed a closing tag.

← Older revision		Revision as of 18:38, 30 May 2008
Line 59:		Line 59:

	==Other Types of File Access==		==Other Types of File Access==
	MZX supports the reading and writing of select file formats specific to itself. Most of these follow the same basic concept as the general file access commands for opening a file. That is, <tt>set "filename.ext" to "''command counter''".		MZX supports the reading and writing of select file formats specific to itself. Most of these follow the same basic concept as the general file access commands for opening a file. That is, <tt>set "filename.ext" to "''command counter''"</tt>.
	===Saving and Loading Robots===		===Saving and Loading Robots===
	Robots, or more specifically Robotic code, can be saved and loaded in a number of different ways. The most basic methods are:		Robots, or more specifically Robotic code, can be saved and loaded in a number of different ways. The most basic methods are:

Wervyn: Finished.

2008-05-30T18:37:15Z

Finished.

@@ Line 7: / Line 7: @@
   set "filename.ext" to "fread_open"
   set "filename.ext" to "fwrite_open"
-Directory paths can also be used (MZX is OS agnostic and interprets both '<tt>\\</tt>' and '<tt>/</tt>' as separators), but for security reasons MZX will not allow access to directories below the one the .mzx file is running from.  It is also perfectly acceptable to have a file open for both reading and writing at the same time.  However, "fwrite_open" clears the contents of whatever file it opens and starts editing a new, blank file.  So MZX also provides the "fwrite_modify" and "fwrite_append" functions, which preserve the contents of the file being opened.  "fwrite_modify" places the write cursor at the beginning of the file, while "fwrite_append" starts writing at the end of the file.
+Directory paths can also be used (MZX is OS agnostic and interprets both '<tt>\\</tt>' and '<tt>/</tt>' as separators), but for security reasons MZX will not allow access to directories above the one the .mzx file is running from.  It is also perfectly acceptable to have a file open for both reading and writing at the same time.  However, "fwrite_open" clears the contents of whatever file it opens and starts editing a new, blank file.  So MZX also provides the "fwrite_modify" and "fwrite_append" functions, which preserve the contents of the file being opened.  "fwrite_modify" places the write cursor at the beginning of the file, while "fwrite_append" starts writing at the end of the file.
-The cursor, or in other words the place in the file currently be read from or written to, is maintained in the counters "fread_pos" and "fwrite_pos".  These are separate values that do not interfere with one another, since it is after all quite common to have one file open for reading and another for writing.  The cursors are automatically advanced when read/write operations are performed on the file, but they can also be set manually to navigate around the file.  Before the [[MegaZeux#SDL Port|port]], when counters were only 16-bits, there existed "fread_page" and "fwrite_page" counters for working with files larger than 64KB in size.  Since counters became 32-bit, however, these have been rendered obsolete, and fread_pos/fwrite_pos rendered absolute.  Additionally, this has allowed for a convenient way to seek to the end of the file, by setting the appropriate "_pos" counter to -1.
+The cursor, or in other words the place in the file currently be read from or written to, is maintained in the counters "fread_pos" and "fwrite_pos".  These are separate values that do not interfere with one another, since it is after all quite common to have one file open for reading and another for writing.  The cursors are automatically advanced when read/write operations are performed on the file, but they can also be set manually to navigate around the file.  Before the [[MegaZeux#SDL Port|port]], when counters were only 16 bits, there existed "fread_page" and "fwrite_page" counters for working with files larger than 64KB in size.  Since counters became 32-bit, however, these have been rendered obsolete, and fread_pos/fwrite_pos rendered absolute.  Additionally, this has allowed for a convenient way to seek to the end of the file, by setting the appropriate "_pos" counter to -1.
 Reading and writing actual data can be done in a few different ways.  The simplest of these is simply to use the counters "fread" and "fwrite" as placeholders for data to be read from or written to the open file.  "fwrite" must always be assigned TO (except for certain syntax related to strings, see below), but "fread" can be [[counter interpolation|interpolated]] into robotic code just like any other counter, and will be evaluated each time it is encountered.  Evaluation, in this case, entails reading one byte from the file, and advancing fread_pos by one.  So for example:
@@ Line 57: / Line 57: @@
   set "" to "fwrite_open"
 Hackish though it may be, this closes the respective file by attempting to open a non-existent, empty string.

Wervyn: Finished basic file i/o section.

2008-05-29T05:18:51Z

Finished basic file i/o section.

@@ Line 7: / Line 7: @@
   set "filename.ext" to "fread_open"
   set "filename.ext" to "fwrite_open"
-Note that it is perfectly acceptable to have a file open for both reading and writing at the same time.  However, "fwrite_open" clears the contents of whatever file it opens and starts editing a new, blank file.  So MZX also provides the "fwrite_modify" and "fwrite_append" functions, which preserve the contents of the file being opened.  "fwrite_modify" places the write cursor at the beginning of the file, while "fwrite_append" starts writing at the end of the file.
+Directory paths can also be used (MZX is OS agnostic and interprets both '<tt>\\</tt>' and '<tt>/</tt>' as separators), but for security reasons MZX will not allow access to directories below the one the .mzx file is running from.  It is also perfectly acceptable to have a file open for both reading and writing at the same time.  However, "fwrite_open" clears the contents of whatever file it opens and starts editing a new, blank file.  So MZX also provides the "fwrite_modify" and "fwrite_append" functions, which preserve the contents of the file being opened.  "fwrite_modify" places the write cursor at the beginning of the file, while "fwrite_append" starts writing at the end of the file.
 The cursor, or in other words the place in the file currently be read from or written to, is maintained in the counters "fread_pos" and "fwrite_pos".  These are separate values that do not interfere with one another, since it is after all quite common to have one file open for reading and another for writing.  The cursors are automatically advanced when read/write operations are performed on the file, but they can also be set manually to navigate around the file.  Before the [[MegaZeux#SDL Port|port]], when counters were only 16-bits, there existed "fread_page" and "fwrite_page" counters for working with files larger than 64KB in size.  Since counters became 32-bit, however, these have been rendered obsolete, and fread_pos/fwrite_pos rendered absolute.  Additionally, this has allowed for a convenient way to seek to the end of the file, by setting the appropriate "_pos" counter to -1.
-Reading and writing actual data can be done in a few different ways.  The simplest of these is simply to use the counters "fread" and "fwrite" as placeholders for data to be read from or written to the open file.  "fwrite" must always be assigned TO (except for certain syntax related to strings, see below), but "fread" can be interpolated into robotic code just like any other counter, and will be evaluated each time it is encountered.  Evaluation, in this case, entails reading one byte from the file, and advancing fread_pos by one.  So for example:
+Reading and writing actual data can be done in a few different ways.  The simplest of these is simply to use the counters "fread" and "fwrite" as placeholders for data to be read from or written to the open file.  "fwrite" must always be assigned TO (except for certain syntax related to strings, see below), but "fread" can be [[counter interpolation|interpolated]] into robotic code just like any other counter, and will be evaluated each time it is encountered.  Evaluation, in this case, entails reading one byte from the file, and advancing fread_pos by one.  So for example:
   set "counter" to "('fread'+('fread'<<8)+('fread'<<16)+('fread'<<24))"
-This would read four bytes stored in little-endian format from the file, and combine them together to form a single 32-bit value.  (See the articles on [[expressions]] and [[bitwise-math]] for more information on this code.)
+This would read four bytes stored in little-endian format from the file, and combine them together to form a single 32-bit value.  (See the articles on [[expressions]] and [[bitwise math]] for more information on this code.)
 This is a somewhat contrived application, since another way to read from and write to a file is to use "fread_counter" and "fwrite_counter".  These were originally intended to conveniently read and write full counter values, instead of just bytes.  Currently they are out of date, and work on 16-bit values instead of the 32-bit values MZX uses now.  However, there are plans to update them to work on 32-bit values in the near future.
@@ Line 21: / Line 21: @@
 it was (and is) necessary to use
   set "$string" to "fwrite"
-This method is limited in its usefulness because it requires the use of a terminating character, which is not user-definable.  Instead of choosing something sensible and widely used, like a null byte (i.e. 0x00), [[Exophase]] chose to make the terminator an asterisk (<tt>*</tt>).
+This method is limited in its usefulness because it requires the use of a terminating character, which is not user-definable.  Instead of choosing something sensible and widely used, like a null byte (i.e. 0x00), [[Exophase]] chose to make the terminator an asterisk (<tt>*</tt>).  As a result, the "fread#" and "fwrite#" function counters have become preferred for their accuracy and lack of side-effects.  The number provided to the counter indicates how many characters to read or write.  So for example, "fread20" reads 20 characters into a string.  Be aware that these counters are specifically overloaded for string manipulation, and so it is not possible to interpolate "fread20" into an arbitrary string, as might be done with "fread".  The syntax is very strictly:

Wervyn: In progress.

2008-05-28T20:01:04Z

In progress.

New page

[[MegaZeux]] has supported reading and writing data to files since version 2.60, and since then this capability has been augmented and improved to allow for the use of external resources in a number of different ways. Apart from counter interfaces to directly manipulate the contents of a file, '''file access''' encompasses specific interfaces for reading and writing [[robot|robots]] and [[Robotic]], [[MZM|MZMs]], and entire MZX worlds.

==The Basics==
MZX supports basic file reading and writing through the use of specific keyword counters, which fall into two obvious categories: "fread" counters for reading, and "fwrite" counters for writing.

First, a file must be opened for reading/writing, using the following syntax:
set "filename.ext" to "fread_open"
set "filename.ext" to "fwrite_open"
Note that it is perfectly acceptable to have a file open for both reading and writing at the same time. However, "fwrite_open" clears the contents of whatever file it opens and starts editing a new, blank file. So MZX also provides the "fwrite_modify" and "fwrite_append" functions, which preserve the contents of the file being opened. "fwrite_modify" places the write cursor at the beginning of the file, while "fwrite_append" starts writing at the end of the file.

The cursor, or in other words the place in the file currently be read from or written to, is maintained in the counters "fread_pos" and "fwrite_pos". These are separate values that do not interfere with one another, since it is after all quite common to have one file open for reading and another for writing. The cursors are automatically advanced when read/write operations are performed on the file, but they can also be set manually to navigate around the file. Before the [[MegaZeux#SDL Port|port]], when counters were only 16-bits, there existed "fread_page" and "fwrite_page" counters for working with files larger than 64KB in size. Since counters became 32-bit, however, these have been rendered obsolete, and fread_pos/fwrite_pos rendered absolute. Additionally, this has allowed for a convenient way to seek to the end of the file, by setting the appropriate "_pos" counter to -1.

Reading and writing actual data can be done in a few different ways. The simplest of these is simply to use the counters "fread" and "fwrite" as placeholders for data to be read from or written to the open file. "fwrite" must always be assigned TO (except for certain syntax related to strings, see below), but "fread" can be interpolated into robotic code just like any other counter, and will be evaluated each time it is encountered. Evaluation, in this case, entails reading one byte from the file, and advancing fread_pos by one. So for example:
set "counter" to "('fread'+('fread'<<8)+('fread'<<16)+('fread'<<24))"
This would read four bytes stored in little-endian format from the file, and combine them together to form a single 32-bit value. (See the articles on [[expressions]] and [[bitwise-math]] for more information on this code.)

This is a somewhat contrived application, since another way to read from and write to a file is to use "fread_counter" and "fwrite_counter". These were originally intended to conveniently read and write full counter values, instead of just bytes. Currently they are out of date, and work on 16-bit values instead of the 32-bit values MZX uses now. However, there are plans to update them to work on 32-bit values in the near future.

Finally, MZX provides reading and writing of arbitrary length strings. Originally, the method for doing this was very limited. The "fread" and "fwrite" counters were overloaded to work with string values. A quirk with the way strings are handled forced a nonstandard syntax here, however: instead of
set "fwrite" to "$string"
it was (and is) necessary to use
set "$string" to "fwrite"
This method is limited in its usefulness because it requires the use of a terminating character, which is not user-definable. Instead of choosing something sensible and widely used, like a null byte (i.e. 0x00), [[Exophase]] chose to make the terminator an asterisk (<tt>*</tt>).

← Older revision		Revision as of 15:31, 13 June 2008
Line 125:		Line 125:
	set "" to "fwrite_open"		set "" to "fwrite_open"
	goto "#return"		goto "#return"

			[[Category:MegaZeux]]