bas_functions.1

' t
.TH BAS 1 "August 19, 2017" "" "Functions"
.SH NAME \"{{{roff}}}\"{{{
bas \- BASIC interpreter (pw)
.\"}}}
.SH SYNOPSIS \"{{{
.ad l
.B bas
.RB [ \-a ]
.RB [ \-b ]
.RB [ \-c ]
.RB [ \-l
.IR file ]
.RB [ \-n ]
.RB [ \-r ]
.RB [ \-u ]
.RI [ "program " [ argument "...]]"
.br
.B bas
.RB [ \-\-autoexec ]
.RB [ \-\-backslash\-colon ]
.RB [ \-\-color256 ]
.RB [ \-\-lp
.IR file ]
.RB [ \-\-no\-end\-program ]
.RB [ \-\-restricted ]
.RB [ \-\-uppercase ]
.RI [ "program " [ argument "...]]"
.br
.B bas
.BR \-h | \-\-help
.br
.B bas
.BR \-\-version
.ad b
.\"}}}
.SH DESCRIPTION \"{{{
.SS "Functions and Expressions" \"{{{
Expressions consist of operators or functions that act on integer,
real (floating point) or string values.  Beside decimal notation,
integer values can be written as hexadecimal values by prefixing them
with \fB&h\fP and as octal values by prefixing them with \fB&o\fP, 
and now as binary values by prefixing them with \fB&b\fP.
String constants may contain paired double quotes to specify double quote
characters inside strings.  If the constant is terminated by the end of
the line, the trailing double quote can be omitted.  Numeric constants
with the suffix \fB#\fP or \fB!\fP are always regarded as floating point
constants, \fBbas\fP ignores the precision specification, because it
does not offer different precisions.  Integer constants may be followed
by the suffix \fB%\fP.  If an integer literal is outside the integer
value range, it is treated as a floating point literal.
.PP
The table below shows the available operators with decreasing priority.
The operator \fB=>\fP is converted to \fB>=\fP, \fB=<\fP is converted
to \fB<=\fP and \fB><\fP is converted to \fB<>\fP when programs are loaded.
.PP
.TS
box,center;
c l
cfB l.
operator	meaning
_
^	exponentiation
_
\-	unary negation
+	unary plus
_
*	multiplication
/	floating-point division
\e	integer division (equal to fix(a/b))
mod	modulo
_
+	addition, string concatenation
\-	substraction
_
>	greater than
>=	greater than or equal to
\&=	equal to
<>	not equal to
<=	less than or equal to
<	less than
_
not	binary complement
_
and	binary and
_
or	binary or
xor	binary exclusive or
eqv	binary equivalent
imp	binary implication
.TE
.sp .5v
.PP
Besides operators, various builtin functions can be used in expressions.
The dollar character (\fB$\fP) denotes that the argument must be of
the type string.  The actual parameters of functions, both builtin
and user-defined, as well as subroutines, are passed by value.  Note:
Modern (not old) ANSI BASIC passes actual parameters by reference.
Many classic dialects don't offer call by reference and \fBbas\fP
follows that direction.  Arguments to functions and subroutines must
be enclosed in parentheses.  Note: Some dialects allow to omit them,
which introduces ambiguity in some cases.
.IP "\fBabs(\fP\fIx\fP\fB)\fP"
Return the absolute value of \fIn\fP.
.IP "\fBasc(\fP\fIstring$\fP\fB)\fP"
Return the numeric value of the first character of the \fIstring\fP.
.IP "\fBatn(\fP\fIx\fP\fB)\fP"
Return the arctangent value of \fIx\fP.
.IP "\fBbin$(\fP\fIn%\fP\fB)\fP"
Return a string containing the binary conversion of \fIn%\fP.
.IP "\fBbin$(\fP\fIn%\fP\fB,\fP\fIdigits%\fP\fB)\fP"
Return a string containing the binary conversion of \fIn%\fP
with the specified number of \fIdigits%\fP.
.IP "\fBchr$(\fP\fIvalue%\fP\fB)\fP"
Return a string of length 1 that contains the character with the given
\fIvalue%\fP.
.IP "\fBcint(\fP\fIx\fP\fB)\fP"
Return the integral value value nearest to \fIx\fP (rounded upwards).
.IP "\fBcode(\fP\fIstring$\fP\fB)\fP"
Return the numeric value of the first character of the \fIstring\fP.
This is the same as \fBasc(\fP\fIstring\fP\fB)\fP, used by dialects
that took non-ASCII systems into consideration.
.IP "\fBcommand$\fP"
Return extra command line arguments after the program name, separated
by spaces.  The program name is not part of the return value.  Note:
This function is implemented for compatibility and does not deal with
arguments with embedded spaces.
.IP "\fBcommand$(\fP\fIn%\fP\fB)\fP"
Return the \fIn%\fPth argument passed to the program, starting with 1.
The first returned argument (index 0) is the program name.
.IP "\fBcos(\fP\fIx_rad\fP\fB)\fP"
Return the cosine value of \fIx_rad\fP.
.IP "\fBcvd(\fP\fIx$\fP\fB)\fP"
Convert a string value generated by \fBmkd$(\fP\fIx\fP\fB)\fP back to
a floating point value.  The string characters contain the bytes of a
C double precision value.  The string length and the byte encoding is
machine dependent and not portable.
.IP "\fBcvs(\fP\fIx$\fP\fB)\fP"
Convert a string value generated by \fBmks$(\fP\fIx\fP\fB)\fP back to
a floating point value.  The string characters contain the bytes of a
C single precision value.  The string length and the byte encoding is
machine dependent and not portable.
.IP "\fBcvi(\fP\fIx$\fP\fB)\fP"
Convert a string value back to an integral value.
The string characters contain the bytes of a signed little endian number
and the sign bit of the last byte determines the sign of the resulting
number.
.IP "\fBdate$\fP"
Return the date as a 10-character string in the form
\fImm\fP\fB\-\fP\fIdd\fP\fB\-\fP\fIyyyy\fP.
.IP "\fBdec$(\fP\fIx\fP,\fBformat$\fP\fB)\fP"
Convert \fIx\fP to a string according to the \fBprint using\fP \fIformat$\fP.
.IP "\fBdeg(\fP\fIradians\fP\fB)\fP"
Convert radians to degrees.
.IP "\fBdet\fP"
Return the determinant of the last matrix inverted.
.IP "\fBedit$(\fP\fIstring$\fP\fB,\fP\fIcode%\fP\fB)\fP"
Return the result of editing the \fIstring$\fP as indicated by the \fIcode%\fP.
The following editing codes are available:
.RS
.IP 1
discard parity bit
.IP 2
discard all spaces and tabs
.IP 4
discard all carriage returns, line feeds, form feeds,
deletes, escapes and nulls
.IP 8
discard leading spaces and tabs
.IP 16
convert multiple spaces and tabs to one space
.IP 32
convert lower case to upper case
.IP 64
convert left brackets to left parentheses and right
brackes to right parentheses
.IP 128
discard trailing spaces and tabs
.IP 256
suppress all editing for characters within matching
single or double quotes.  If the matching quote is missing,
suppress all editing up to the end of the string.
.RE
.IP
The codes can be added for combined editing operations.
.IP "\fBenviron$(\fP\fIn%\fP\fB)\fP"
Return the \fIn%\fPth environment entry in the form
\fIvariable\fP\fB=\fP\fIvalue\fP, starting with 1.  If \fIn%\fP is larger
than the number of entries, an empty string is returned.
.IP "\fBenviron$(\fP\fIvariable$\fP\fB)\fP"
Return the value of the specified environment \fIvariable$\fP.  If there
is no such variable, an empty string is returned.
.IP "\fBeof(\fP\fIchannel%\fP\fB)\fP"
Return true if the end of the channel has been reached.  This must be
used to avoid that \fBinput\fP tries to read past the end of a file.
.IP "\fBerl\fP"
Return the number of the line where the last exception was thrown.
.IP "\fBerr\fP"
Return a numeric code for the last exception that was thrown.  The use
of this function is not portable.
.IP "\fBexp(\fP\fIx\fP\fB)\fP"
Return the value of e raised to the power of \fIx\fP.
.IP "\fBfalse\fP"
Return 0.
.IP "\fBfind$(\fP\fIpattern$\fP[\fB,\fP\fInth%\fP]\fB)\fP
Return the first (or \fInth%\fP, starting from 0, if specified) filename
that matches the given pattern or the empty string, if no filename
matches the pattern.  This function is usually used to check for the
existance of a file.  The pattern may use the wildcards \fB*\fP to match
an arbitrary number of characters and \fB?\fP to match a single character.
Note: On some systems, the star does not match a dot inside a filename.
In this implementation, the star matches everything and \fB*.*\fP only
matches files with a dot in their name, not files without an extension.
Some systems also encode file attributes in the eigth bit of the
file name and programs strip that bit from the output of \fBfind$\fP.
It is recommended to use only 7-bit file names with applications using
this function.
.IP "\fBfix(\fP\fIx\fP\fB)\fP"
Return the integral part of a floating point value.
.IP "\fBfp(\fP\fIx\fP\fB)\fP"
Return the fractional part of a floating point value.
.IP "\fBfrac(\fP\fIx\fP\fB)\fP"
Return the fractional part of a floating point value; same as \fBfp\fP.
.IP "\fBfreefile\fP"
Return the first free file handle.
.IP "\fBhex$(\fP\fIn%\fP\fB)\fP"
Return a string containing the hexadecimal conversion of \fIn%\fP.
.IP "\fBhex$(\fP\fIn%\fP\fB,\fP\fIdigits%\fP\fB)\fP"
Return a string containing the hexadecimal conversion of \fIn%\fP
with the specified number of \fIdigits%\fP.
.IP "\fBinkey$\fP[\fB(\fP\fItimeout%\fP[\fB,\fP\fIchannel\fP]\fB)\fP]"
Wait at most \fItimeout\fP hundredths of a second for a character to
be read from the terminal.  If a character could be read, return it,
otherwise return the empty string.  Omitting the \fItimeout%\fP will
return immediatly if no character is available.  Note: Some BASIC
dialects wait until a character is available if no timeout is given
instead of returning an empty string.  Convert those programs by using
\fBinput$(1)\fP instead.
.IP "\fBinp(\fP\fIaddress\fP\fB)\fP"
Return the value of the I/O port \fIaddress\fP.  Direct port access is
not available in the portable version.
.IP "\fBinput$(\fP\fIlength\fP[\fB,\fP\fIchannel\fP]\fB)\fP"
Read a string of \fIlength\fP characters from standard input or from
the specified \fIchannel\fP.  The characters will not be echoed.
.IP "\fBinstr(\fP\fIhaystack$\fP\fB,\fP\fIneedle$\fP\fB)\fP"
Return the position of \fIneedle$\fP in \fIhaystack$\fP.  If \fIneedle$\fP
is not found, then 0 is returned.
.IP "\fBinstr(\fP\fIstart%\fP\fB,\fP\fIhaystack$\fP\fB,\fP\fIneedle$\fP\fB)\fP"
As above, but start searching at position \fIstart%\fP (first position is 1).
.IP "\fBinstr(\fP\fIhaystack$\fP\fB,\fP\fIneedle$\fP\fB,\fP\fIstart%\fP\fB)\fP"
As above, but some BASIC dialects have this order of parameters.
.IP "\fBinstr(\fP\fIhaystack$\fP\fB,\fP\fIneedle$\fP\fB,\fP\fIstart%\fP\fB,\fP\fIlength%\fP\fB)\fP"
As above, but only limit search to the first \fIlength%\fP characters
starting at position \fIstart%\fP.
.IP "\fBint(\fP\fIx\fP\fB)\fP"
Return the integral value nearest to \fIx\fP (rounded downwards).
.IP "\fBint%(\fP\fIx\fP\fB)\fP"
Same as \fBint\fP, but return an integer.
.IP "\fBip(\fP\fIx\fP\fB)\fP"
Return the integral part of a floating point value; same as \fBfix\fP.
.IP "\fBlcase$(\fP\fIstring$\fP\fB)\fP"
Return the string with all characters changed to lower case.
.IP "\fBlower$(\fP\fIstring$\fP\fB)\fP"
Same as \fBlcase\fP, some dialects call it this way.
.IP "\fBleft$(\fP\fIstring$\fP\fB,\fP\fIn%\fP\fB)\fP"
Return the first \fIn%\fP characters of the \fIstring\fP.  If \fIn\fP is
greater than the number of characters in the string, the whole
string is returned.
.IP "\fBlen(\fP\fIstring$\fP\fB)\fP"
Return the length (number of characters) of the \fIstring\fP.
.IP "\fBloc(\fP\fIchannel%\fP\fB)\fP"
If used on random-access files, the number of the last accessed record
is returned.  For sequential files, the current read/write position is
returned.  Note: Some BASIC dialects return the record position in bytes
and the read/write position in pseudo-records.
.IP "\fBlof(\fP\fIchannel%\fP\fB)\fP"
Return the size of the file that is attached to the channel (bytes
for sequential or binary files, records for random-access files).
This may not work correctly for files with sizes that exceed the range
of integer numbers.  Note: Some BASIC dialects return the number of
bytes even for random-access files.
.IP "\fBlog(\fP\fIx\fP\fB)\fP"
Return the natural logarithm of \fIx\fP.
.IP "\fBlog10(\fP\fIx\fP\fB)\fP"
Return the base-10 logarithm of \fIx\fP.
.IP "\fBlog2(\fP\fIx\fP\fB)\fP"
Return the base-2 logarithm of \fIx\fP.
.IP "\fBmatch(\fP\fIneedle$\fP\fB,\fP\fIhaystack$\fP\fB,\fP\fIstart%\fP\fB)\fP"
Return the first position of \fIneedle$\fP in \fIhaystack$\fP that
is greater than or equal \fIstart%\fP.  If the search fails or if
\fIstart%\fP exceeds the length of \fIhaystack$\fP, 0 will be returned.
The following characters in \fIneedle$\fP have a special meaning:
\fB!\fP matches any letter, \fB#\fP matches any digit, \fB?\fP matches
any character and \fB\e\fP quotes the next character, e.g. \fB\e?\fP
matches a question mark.
.IP "\fBmax(\fP\fIx\fP\fB,\fP\fIy\fP\fB)\fP"
Return the maximum of \fIx\fP and \fIy\fP.
.IP "\fBltrim$(\fP\fIstring$\fP\fB)\fP"
Return the string without leading spaces.
.IP "\fBmid$(\fP\fIstring$\fP\fB,\fP\fIposition%\fP[\fB,\fP\fIlen%\fP]\fB)\fP"
Return the substring of \fIstring\fP that begins at the given
\fIposition%\fP (the first character is at position 1).  If \fIstring\fP
is too short for a substring of \fIlen%\fP characters, fewer characters
will be returned.
.IP "\fBmin(\fP\fIx\fP\fB,\fP\fIy\fP\fB)\fP"
Return the minimum of \fIx\fP and \fIy\fP.
.IP "\fBmkd$(\fP\fIx\fP\fB)\fP"
Return a string whose characters contain the bytes of a C double precision
number.  The string length and byte encoding depends of the machine type
and is not portable.
.IP "\fBmks$(\fP\fIx\fP\fB)\fP"
Return a string whose characters contain the bytes of a C single precision
number.  The string length and byte encoding depends of the machine type
and is not portable.
.IP "\fBmki$(\fP\fIx\fP\fB)\fP"
Return a string whose characters contain the bytes of a little endian
integral value.  The string length depends of the machine type, but
the little endian encoding allows to store only e.g. the first two bytes
if the value does not exceed the range of a signed 16 bit number.
.IP "\fBoct$(\fP\fIn%\fP\fB)\fP"
Return a string containing the octal conversion of \fIn%\fP.
.IP "\fBpeek(\fP\fIaddress\fP\fB)\fP"
Return the value of the memory \fIaddress\fP.  Direct memory access is
not available in the portable version.
.IP "\fBpi\fP"
Return the constant pi.
.IP "\fBpos(\fP\fIdummy\fP\fB)\fP"
Return the current cursor position, starting with 1 as the leftmost
position.  The numeric \fIdummy\fP argument is needed, because old BASIC
implementations did not allow functions without arguments.
.IP "\fBpos(\fP\fIhaystack$\fP\fB,\fP\fIneedle$\fP\fB,\fP\fIstart%\fP\fB)\fP"
Same as \fBinstr$\fP, some dialects use this function name.
.IP "\fBrad(\fP\fIdegrees\fP\fB)\fP"
Convert degrees to radians.
.IP "\fBright$(\fP\fIstring$\fP\fB,\fP\fIn%\fP\fB)\fP"
Return the last \fIn\fP characters of the \fIstring\fP.  If \fIn%\fP is
greater than the number of characters in the string, the whole
string is returned.
.IP "\fBrnd(\fP[\fIx%\fP]\fB)\fP"
Return a random integer number between 1 and \fIx%\fP.  If \fIx%\fP is zero,
one or missing, a real number between 0.0 and 1.0 is returned.  If \fIx%\fP is
negative, the random number generator will be seeded with \fB-\fP\fIx%\fP
and the functions returns a value as if \fB-\fP\fIx%\fP had been passed
to it.
.IP "\fBrtrim$(\fP\fIstring$\fP\fB)\fP"
Return the string without trailing spaces.
.IP "\fBseg$(\fP\fIstring$\fP\fB,\fP\fIposition%\fP\fB,\fP\fIlen%\fP\fB)\fP"
Same as \fBmid$\fP, some dialects use this function name.
.IP "\fBsgn(\fP\fIx\fP\fB)\fP"
Return the sign \fIx\fP: \-1 for negative numbers, 0 for 0 and 1 for
positive numbers.
.IP "\fBsin(\fP\fIx_rad\fP\fB)\fP"
Return the sine value of \fIx_rad\fP.
.IP "\fBspace$(\fP\fIlength%\fP\fB)\fP"
Return a string containing \fIlength%\fP spaces.
.IP "\fBsqr(\fP\fIx\fP\fB)\fP"
Return the square root of \fIx\fP.
.IP "\fBstr$(\fP\fIx\fP\fB)\fP"
Return a string that contains the decimal represantation of \fIx\fP.
.IP "\fBstring$(\fP\fIlength\fP\fB,\fP\fIx\fP\fB)\fP"
Return a string of size \fIlength\fP whose characters have the decimal
code \fIx\fP.
.IP "\fBstring$(\fP\fIlength%\fP\fB,\fP\fIx$\fP\fB)\fP"
Return a string of size \fIlength%\fP whose characters are the first
character of \fIx$\fP.
.IP "\fBstrip$(\fP\fIstring\fP\fB)\fP"
Return the string with the eighth bit of each character cleared.
.IP "\fBtan(\fP\fIx_rad\fP\fB)\fP"
Return the tangent of \fIx_rad\fP.
.IP "\fBtime\fP"
Return the current value of the centisecond counter.
.IP "\fBtime$\fP"
Return the time as a 8-character string in the form
\fIhh\fP\fB\-\fP\fImm\fP\fB\-\fP\fIss\fP.
.IP "\fBtimer\fP
Return the number of seconds elapsed since midnight local time.
.IP "\fBtrue\fP"
Return \-1.
.IP "\fBucase$(\fP\fIstring$\fP\fB)\fP"
Return the string with all characters changed to upper case.
.IP "\fBupper$(\fP\fIstring$\fP\fB)\fP"
Same as \fBucase$\fP, some dialects call it this way.
.IP "\fBval(\fP\fIstring$\fP\fB)\fP"
If possible, then convert the \fIstring$\fP into an integer or floating
point value, ignoring trailing junk.  Otherwise, return 0.0.  Like
anywhere else, hexadecimal values are specified by a leading \fB&h\fP.
.\"}}}
.\"}}}
.SH OPTIONS \"{{{
.IP "\fB\-a\fP, \fB\-\-autoexec\fP"
From the folder \fBBas\fP is started from, first perform \fBRUN "./autoexec.bas"\fP
in the current directory.
.IP "\fB\-b\fP, \fB\-\-backslash\-colon\fP"
Convert backslashs to colons.  By default, a backslash is the operator
for integer division, but in some BASIC dialects it forms compound
statements as the colon does.
.IP "\fB\-c\fP, \fB\-\-color256\fP"
Allows 256 colors instead of 16. The terminal (\fB$TERM\fP) must support it.
.IP "\fB\-l\fP \fIfile\fP, \fB\-\-lp\fP \fIfile\fP"
Write \fBLLIST\fP and \fBLPRINT\fP output to \fIfile\fP.  By default,
that output will be written to \fB/dev/null\fP.
.IP "\fB\-n\fP, \fB\-\-no\-end\-program\fP"
Prevents 
.B END program
from being printed
.IP "\fB\-r\fP, \fB\-\-restricted\fP"
Restricted operation which does not allow to fork a shell.
.IP "\fB\-u\fP, \fB\-\-uppercase\fP"
Output all tokens in uppercase.  By default, they are lowercase,
which is easier to read, but some BASIC dialects require uppercase.
This option allows to save programs for those dialects.
.IP "\fB\-h\fP, \fB\-\-help\fP"
Output usage and exit.
.IP "\fB\-v\fP, \fB\-\-version\fP"
Display version information and exit.
.\"}}}
.SH AUTHOR \"{{{
This program is copyright 1999\(en2014 Michael Haardt 
<michael@moria.de>.
.PP
Custom MAN pages & MSX-BASIC extensions copyright 2017 Paul Wratt 
<paul.wratt@gmail.com>
.PP
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
.PP
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
.PP
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
.\"}}}
.SH HISTORY \"{{{
There has been a \fIbas\fP(1) command in UNIX v7, but its syntax
was strongly influenced by C, unlike common classic BASIC dialects, and
thus not compatible with this implementation. MSX-BASIC is an extension
of Microsoft BASIC v4.0.
.\"}}}
.SH "SEE ALSO" \"{{{
The Usenet group comp.lang.basic.misc discusses the classic BASIC dialect.
.\"}}}