WWIVbasic¶
Table of Contents¶
About¶
WWIV supports extending the BBS using WWIVbasic. WWIVbasic is a modern implementation of the classical WWIV basic interpreter MOD from the early 1990s.
WWIVbasic is implemented using MY-BASIC. MY-BASIC is an open source project under the MIT license, written by Wang Renxin.
WWIVbasic supports the entire syntax of MY-BASIC. The MY-BASIC documentation can be found in the MY-BASIC Quick Reference document. In addition to the core language, WWIVbasic includes several package to interact with the WWIV BBS.
DataTypes supported¶
Name | Description |
---|---|
Boolean | Implicitly support either TRUE of FALSE. Convertible to Numbers as 0 and 1 |
Number | A standard integer (whole number) datatype. The range of this is that of an int32_t |
Real | Floating point number, same as C++ float |
String | A standard string, a list of characters |
Invoking Functions¶
Functions may exist in the global namespace (like PRINT), or may
belong to a module. All of the WWIV BBS functions will belong to
a module starting with wwiv
.
You may always invoke a function using it's fully-qualified
name (such as wwiv.version
) or you may import the package
and then invoke it using it's name without the package prefix.
For example: the two calls to puts are the same:
IMPORT "@wwiv.io"
wwiv.io.puts("Hello |@N, How are you?")
puts("Hello |@N, How are you?")
Importing Packages¶
Packages are imported using the IMPORT
statement in WWIVbasic.
Starting the name of a package with a @
character means that
a package is being imported, instead of a file (such as foo.bas).
Import Package Example
IMPORT "@wwiv.io"
wwiv.io.puts("Hello |@N, How are you?")
puts("Hello |@N, How are you?")
You may also use import to include the contents of
anohter WWIVbasic script, ending in .bas
into
your current script.
Import File Example
IMPORT "helper.bas"
WWIV Packages¶
Please note that WWIVbasic may be enabled or disabled in WWIVconfig under menu item (R) [Scripting Config]. Additionally WWIVbasic packages may be selectively enabled and disabled. By default wwiv.io.file and wwiv.os are disabled. Please use wwivconfig to enable these packages.
package wwiv¶
The wwiv
package is the core package of interacting with WWIV.
Most functionality is available in one of the subpackages.
wwiv.version()¶
Returns the version number of the WWIV BBS system as a String
Example:
ver = wwiv.version()
wwiv.io.puts("You are running version: " + ver)
wwiv.command(string command)¶
Invokes command
as a menu command.
For example this would run the BBS list command.
Example:
wwiv.command("BBSList")
wwiv.eval()¶
Evaluates a WWIV ACS Expression and return a boolean value that may be compared against 1 or TRUE for true values and 0 or FALSE for false values.
Example:
if wwiv.eval("user.sl > 200") = FALSE then
wwiv.io.puts("Hello high level SL caller!")
wwiv.interpret(string code)¶
Returns a string for the interpreted macro code code
.
The |@
is not needed, just the single character
for the macro code should be provided.
Example:
name = wwiv.interpret("N")
print "Hello " + name
package wwiv.io¶
This package contains all of the input/output for interacting with the user connected to the BBS.
wwiv.printfile(string filename)¶
Displays the content of filename
using the same logic
as the printfile
C++ function. It'll automatically
choose the best suffix for a file matching the name
filename
from the GFILES
directory of the BBS.
Note: This method will move to wwiv.io shortly
Example:
wwiv.printfile("oneliners")
wwiv.io.puts(string s, ...)¶
Displays a string s
. More than one string may
be specified, separated by commas and they will be
concatenated together.
Example:
bbsname = "My BBS"
wwiv.io.puts("Welcome to ", bbsname, ".")
wwiv.io.puts("Thank you for calling")
wwiv.io.pl(string s, ...)¶
Displays a string s
, followed by a newline
and carriage return. More than one string may
be specified, separated by commas and they will be
concatenated together.
Note: This is the same as calling wwiv.puts(...)
followed by wwiv.nl()
.
Example:
bbsname = "My BBS"
wwiv.io.pl("Welcome to ", bbsname, ".")
wwiv.io.pl("Thank you for calling")
wwiv.io.gets(integer maxlen)¶
Prompts the user for a string and returns it. The string
may be up to maxlen
characters in length. A
colorized input field (mpl) will be displayed to the user.
Example:
wwiv.io.puts("What is your favorite color? ")
c = wwiv.io.gets(20)
wwiv.io.puts("Wow! " + c + " is my favorite too!!!")
wwiv.io.getkey()¶
Prompts the user for a single character and returns it as a string of of only the character.
Example:
wwiv.io.puts("Are you (a) cool, (b) almost cool? ")
c = wwiv.io.getkey()
If (c = "b") Then
wwiv.io.pl("Try Harder!");
EndIf
wwiv.io.cls()¶
Clears the screen.
Example:
wwiv.io.cls()
wwiv.io.nl([integer newlines])¶
Displays a newline (aka carriage return + line feed).
Optionally accepts the number of newlines to display as the
integer newlines
, if not specified the default is 1.
Example:
wwiv.io.nl()
wwiv.io.nl(2)
wwiv.io.yn(string s, ...)¶
Prompts the user for a yes/no question, the prompt will be the
repeated string s
. More than one string may be specified,
separated by commas and they will be concatenated together.
The default answer is yes
if the enter key is pressed.
Example:
wwiv.io.yn("Are you ? ")
c = wwiv.io.yn()
If NOT c Then
wwiv.io.pl("Try Harder!");
EndIf
wwiv.io.ny(string s, ...)¶
Prompts the user for a yes/no question, the prompt will be the
repeated string s
. More than one string may be specified,
separated by commas and they will be concatenated together.
The default answer is NO
if the ENTER key is pressed.
(this is the same as wwiv.io.yn
except for the default
value if the ENTER key is pressed.)
Example:
wwiv.io.yn("Are you ? ")
c = wwiv.io.yn()
If Not c Then
wwiv.io.pl("Try Harder!");
EndIf
wwiv.io.pause()¶
Displays the [PAUSE] indicator.
Example:
wwiv.io.pause()
Package wwiv.data¶
The wwiv.data
package is responsible for loading and saving data to
the datastore for WWIV. Currently only GLOBAL data is supported.
wwiv.data.load("GLOBAL", list l)¶
Loads a list l
of data for this script. The list should be empty
and initialized as a list before calling this function.
Example:
l = list()
wwiv.data.load("GLOBAL", l)
wwiv.data.save("GLOBAL", list l)¶
Saves the list l
of data for this script to the datastore for
WWIV. Currently only GLOBAL data is supported.
Example:
l = list("a", "b", "c")
wwiv.data.save("GLOBAL", l)
Package wwiv.io.file¶
The wwiv.io.file
package is responsible file IO in specifically
allowed directories for WWIV. Currently only the GFILES directory
is supported.
wwiv.io.file.open_options(location)¶
Creates the set of options used when locating and opening a file.
Params:
- location: This is the location of that open is allowed to use.
They can be one of the following values:
- "GFILES": currently any file type is allowed in the GFILES dir.
Returns:
- value a wwiv.io.file.open_option.
Example:
opt = wwiv.io.file.open_options("GFILES")
wwiv.io.file.open(opt, NAME, MODE)¶
Opens a file and returns a file handle for the opened file.
Params:
- opt: This is the open options from wwiv.io.file.open_options(loc)
- NAME: the filename without any path.
- MODE: "R" or "W" for read or write
Returns:
- value a wwiv.io.file.handle.
Example:
opt = wwiv.io.file.open_options("GFILES")
h = wwiv.io.file.open(opt, NAME, MODE)
wwiv.io.file.readintostring(handle)¶
Read all of the lines of a file into a single string.
Params:
- handle is a file handle returned from
wwiv.io.file.open
Returns:
- returns all of the lines from handle as a string
Example:
s = wwiv.io.file.readintostring(handle)
wwiv.io.file.readlines(handle, list)¶
Read lines of a file into a list collection.
Params:
- handle is a file handler returned from
wwiv.io.file.open
- [OUT] all of the lines from handle into
Example:
l = list()
wwiv.io.file.readlines(handle, l)
wwiv.io.file.last_modified(OPT, NAME)¶
Gets the file's last modified
Params:
- OPT: a wwiv.io.file.open_option reference
- NAME: The filename without path
Returns:
- the last modified time as a unix time_t value
Example:
opt = wwiv.io.file.open_options("GFILES")
wwiv.io.file.last_modified(opt, NAME)
Package wwiv.os (TBD)¶
package wwiv.os
wwiv.os.exec_options(OPT, DIR, DROPFILE)¶
Execute command
opt = wwiv.os.exec_options("DOOR32", "TEMP", "chain.txt")
opt.type = "DOOR32"
opt.dropfile = "chain.txt"
opt.dir = "TEMP"
Options are (in order): - TYPE (one of "DOOR32", "STDIO", "FOSSIL") - DIR - dir is one of - "TEMP": Temp directory for node - "BBS" : BBS Root Directory - DROPFILE (one of "CHAIN.TXT", "DOOR.SYS")
wwiv.exec(opt, cmd)
- opt is an exec_options struture
- cmd is the commandline to execute.
Package wwiv.time¶
The wwiv.time
package is responsible supporting date and
time within WWIV.
wwiv.time.format(UT, FMT)¶
Returns time UT formatted using the format specified in FMT
Params:
- UT: The time in UNIX time_t format.
- FMT: The format string to use. This is the same format as specified by POSIX strftime
Returns:
- value a wwiv.io.file.open_option.
Example:
o = wwiv.io.file.open_options("GFILES")
h2 = wwiv.io.file.open(o, "logon.msg", "R")
lm = wwiv.io.file.last_modified(h2)
print wwiv.time.format(lm, "%Y-%m-%d %H:%M:%S")
Samples¶
WWIV includes several sample scripts bundled in sample.zip
or in the
samples/
directory in your WWIV install.
You may also find these scripts in GitHub.