Programmer Guide/Command Reference/WRITE: Difference between revisions
From STX Wiki
Jump to navigationJump to search
m (1 revision: Initial import) |
No edit summary |
||
| (15 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:{{SUBPAGENAME}}}} | {{DISPLAYTITLE:{{SUBPAGENAME}}}} | ||
WRITE <var>file</var> <var>text</var> [/Newline … /Newline] | |||
WRITE <var>file</var> <var>format</var> <var>args</var> /Format [/Newline … /Newline] | |||
< | |||
WRITE [/Newline … /Newline] [[Programmer_Guide/Command_Reference_Options/-|/-]] <var>file</var> <var>text</var> | |||
< | WRITE /Format [/Newline … /Newline] [[Programmer_Guide/Command_Reference_Options/-|/-]] <var>file</var> <var>format</var> <var>args</var> | ||
This {{Stx}} command writes (hence its name) text to a file assigned to a [[Programmer_Guide/Shell_Items/File|file item]]. If ''no'' <code>/Newline</code> option is specified, the text of the next <code>WRITE</code> command will be placed in the same line. Format strings are described in [[Programmer_Guide/General_Descriptions/Format_Strings_and_Rules|Format Strings and Rules]]. | |||
;<var>file</var> | ;<var>file</var> | ||
:The name of a [[Programmer_Guide/Shell_Items/File|file item]] (must, obviously, be open for write access). | |||
:The | ;<var>text</var> | ||
:The output text (unformatted, written "as is"). Must not start with a slash, unless you are using the [[Programmer_Guide/Command_Reference_Options/-|"end of options" option, <code>/-</code>]]. | |||
;<var> | ;<var>format</var> | ||
:The format string (see [[Programmer_Guide/General_Descriptions/Format_Strings_and_Rules|Format Strings and Rules]]). There ''must'' be a corresponding <var>args</var> argument for each "%" format tag in <var>format</var> because {{Stx}} will not check if the number of arguments supplied matches the given <var>format</var> string and will, hence, crash heavily if there is any mistake. Must not start with a slash, unless you are using the [[Programmer_Guide/Command_Reference_Options/-|"end of options" option, <code>/-</code>]]. | |||
:The | ;<var>args</var> | ||
:The arguments (one for each "%" format tag in <var>format</var>). Note that {{STx}} will not check if the number of arguments supplied matches the given <var>format</var> string and will, hence, crash heavily if there is any mistake. Furthermore, no argument must start with a slash, unless, of course, you are using the [[Programmer_Guide/Command_Reference_Options/-|"end of options" option, <code>/-</code>]]. | |||
The command returns <samp>0</samp> on success or non-zero on failure. | |||
== Example == | |||
WRITE $([[Programmer_Guide/Shell_Items/File/NEW_FILE|new file]] * test.txt /T /W) 'this is %d format for %3.0f numbers' 1 0.2*10 /Newline /Format | |||
The line "<samp>this is 1 format for 2 numbers</samp>" will be written to the file. Note that this is also an example of horribly bad programming style, not checking if the inline [[Programmer_Guide/Shell_Items/File/NEW_FILE|<code>NEW FILE</code>]] command succeeded, and happily executing garbage when it did not. A proper, clean alternative to the above code would be: | |||
''' | #file := [[Programmer_Guide/Shell_Items/File/NEW_FILE|new file]] * test.txt /Text /Write | ||
if '$#file[?]' != file || '$rc' != 0 [[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|em]] $rc ; Cannot open file for writing | |||
write /Newline /Format /- $#file 'this is %d format for %3.0f numbers' 1 0.2*10 | |||
if '$rc' != 0 [[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|em]] $rc ; Cannot write to file. | |||
// properly dispose of the file item, i.e. close the disk file | |||
delete /Var #file | |||
See also [[../READ|READ]] | |||
Latest revision as of 10:07, 24 June 2019
WRITE file text [/Newline … /Newline] WRITE file format args /Format [/Newline … /Newline] WRITE [/Newline … /Newline] /- file text WRITE /Format [/Newline … /Newline] /- file format args
This STx command writes (hence its name) text to a file assigned to a file item. If no /Newline option is specified, the text of the next WRITE command will be placed in the same line. Format strings are described in Format Strings and Rules.
- file
- The name of a file item (must, obviously, be open for write access).
- text
- The output text (unformatted, written "as is"). Must not start with a slash, unless you are using the "end of options" option,
/-.
- format
- The format string (see Format Strings and Rules). There must be a corresponding args argument for each "%" format tag in format because STx will not check if the number of arguments supplied matches the given format string and will, hence, crash heavily if there is any mistake. Must not start with a slash, unless you are using the "end of options" option,
/-.
- args
- The arguments (one for each "%" format tag in format). Note that STx will not check if the number of arguments supplied matches the given format string and will, hence, crash heavily if there is any mistake. Furthermore, no argument must start with a slash, unless, of course, you are using the "end of options" option,
/-.
The command returns 0 on success or non-zero on failure.
Example
WRITE $(new file * test.txt /T /W) 'this is %d format for %3.0f numbers' 1 0.2*10 /Newline /Format
The line "this is 1 format for 2 numbers" will be written to the file. Note that this is also an example of horribly bad programming style, not checking if the inline NEW FILE command succeeded, and happily executing garbage when it did not. A proper, clean alternative to the above code would be:
#file := new file * test.txt /Text /Write if '$#file[?]' != file || '$rc' != 0 em $rc ; Cannot open file for writing write /Newline /Format /- $#file 'this is %d format for %3.0f numbers' 1 0.2*10 if '$rc' != 0 em $rc ; Cannot write to file. // properly dispose of the file item, i.e. close the disk file delete /Var #file
See also READ
