====== Python Functions ======

This page is a work in progress.  Please follow this format closely if
making changes, and be sure to include anchors from the A-Z list at the
bottom as well as the table at each section.  MPL documentation should follow
a similar format.

If you are looking for documentation for a function from the A-Z function
list at the bottom and it is not yet documented here, do a search at the top
of the site for the function name.  All functions should be documented in
the Whats new sections, and the search may find it for you.

If you have a specific request for something to be added here, please ask and
the documentation can be prioritized.  If you have a specific request for an
enhancement, please request it!

The examples section, and included example scripts with a new installation of
Mystic can also be useful when learning the functions.

----
==== Output Functions ====

^ Function                                         ^ Description                                          ^
| [[python_functions#Function: PWRITE|pwrite]]     | Send pipe string to the user                         |
| [[python_functions#Function: PWRITELN|pwriteln]] | Send pipe string to the user with a carriage return  |
| [[python_functions#Function: RWRITE|rwrite]]     | Send raw string to the user                          |
| [[python_functions#Function: RWRITE|rwriteln]]   | Send raw string to the user with a carriage return   |
| [[python_functions#Function: SHOWFILE|showfile]] | Display a file to the user                           |
| [[python_functions#Function: WRITE|write]]       | Send string to the user with MCI filtering           |
| [[python_functions#Function: WRITELN|writeln]]   | Send string to the user with MCI filtering and CRLF  |

=== Function: PWRITE ===


    Syntax: pwrite (string)
    
    This function accepts a string parameter and will send the contents of the
    string to the user, processing any pipe color codes properly but ignoring other
    MCI codes.
  
    Example:
  
      rwrite("|12Welcome, |UH")
    
    The above example will print "Welcome, |UH" to the user with a red color.  Note
    that the MCI code containing the user name was not translated.

=== Function: PWRITELN ===

    Syntax: pwriteln (string)
    
    This function accepts a string parameter and will send the contents of the
    string to the user, processing any pipe color codes properly but ignoring other
    MCI codes.  A CRLF is sent at the end, moving the cursor to the next line.
  
    Example:
  
      pwriteln("|12Welcome, |UH")
    
    The above example will print "Welcome, |UH" to the user with a red color.  Note
    that the MCI code containing the user name was not translated.


=== Function: RWRITE ===

    Syntax: rwrite (string)
    
    Raw write. This function accepts a string parameter and will send the
    contents of the string to the user.  This function does NOT filter
    out color or MCI codes nor does it move to the next line.
  
    Example:
  
      rwrite("|12Welcome, |UH")
    
    The above example will print "|12Welcome, <UserName>" to the user.
    Note that the color code was untouched.

=== Function: RWRITELN ===

    Syntax: rwriteln (string)
    
    This function accepts a string parameter and will send the contents
    of the string to the user followed by a carrage return to move the
    cursor to the next line.  This function will NOT decode color codes
    or MCI codes.

    Example:
  
      rwriteln("|12Welcome, |UH")
    
    The above example will print "|12Welcome, <UserName>" to the
    user and then move the cursor to the next line.

=== Function: SHOWFILE ===

    Syntax: showfile (filename, baudrate, pause, abort, onlynew) : boolean
    
    This function accepts the filename string followed by several boolean
    options represented as 1 for true or 0 for false.
    
    The filename parameter can be a base filename such as "myfile" and Mystic
    will calculate the file extension based on the user's terminal settings
    and random display file system.  If a file extension is supplied then
    Mystic will not attempt to do any calculation based on terminal or
    random files.  The filename can also include a path, but if one is
    excluded it will display from the current theme's text directory or
    a theme that is inherited by the current theme.
    
    The baudrate parameter contains the baudrate that will be emulated when
    the file is displayed, or it can be set to zero for full speed.  The
    baud rate emulation is done by Mystic itself and does not require any
    specific terminal compatibility or extension; it works on all terminals
    
    The pause parameter can be set to 1 to allow screen pausing
    
    The abort parameter can be set to 1 to allow aborting with spacebar
    
    The onlynew parameter can be set to 1 to display the file only if its
    modification date is newer than the user's last call.
    
    The showfile function returns a TRUE result if the file was found and
    displayed or false if not.
    
    Example:
    
      showfile("c:\myfile.txt", 0, 1, 1, 0)
      showfile("loginansi", 19200, 0, 0, 0)

=== Function: WRITE ===

    Syntax: write (string)
    
    This function accepts a string parameter and will send the contents
    of the string to the user.  This function will decode all pipe color
    codes and MCI codes in the process.  Note that this function does not
    move the cursor to the next line.
  
    Example:
  
      write("|12Welcome, |UH")
    
    The above example will print "Welcome, <UserName>" in Red to the
    user.

=== Function: WRITELN ===

    Syntax: writeln (string)
    
    This function accepts a string parameter and will send the contents
    of the string to the user followed by a carrage return to move the
    cursor to the next line.  This function will decode all pipe color
    codes and MCI codes in the process.
  
    Example:
  
      writeln("|12Welcome, |UH")
    
    The above example will print "Welcome, <UserName>" in Red to the
    user and then move the cursor to the next line.

----
==== Input Functions ====

^ Function                                             ^ Description                                          ^
| [[python_functions#Function: GETSTR|getstr]]         | Get string input from the user                   |
| [[python_functions#Function: KEYPRESSED|keypressed]] | Check if input is available from user            |
| [[python_functions#Function: ONEKEY|onekey]]         | Get constrained single character input from user |

=== Function: GETSTR ===

    Syntax: getstr (Mode, FieldSize, MaxInput, DefaultText)
    
    Mode defines how the input is handled:
       1 = Standard input
       2 = Upper case
       3 = Proper
       4 = USA Phone Number
       5 = Date
       6 = Password
       7 = Lower cased
       8 = User defined input
       9 = Standard input with no CRLF
      10 = numbers only (and . + -)   
      
      Adding 10 to this value (ie 1 becomes 11) will cause Mystic to
      draw an input field using the input field colors defined for the
      current theme.
      
    FieldSize defines the maximum size of the field.  If the
    MaxInput is larger than FieldSize then the input will be
    scrolled.
  
    MaxInput defines the total number of bytes allowed in this
    input field.
    
    DefaultText defines the value that will be put into the input
    field by default.
        
    Example:
  
      input = getstr(11, 40, 120, "Default")

=== Function: KEYPRESSED ===

    Syntax: keypressed : boolean
    
    Returns a true if a there is input waiting to be read in from the user
    and false if there is no input waiting.
        
    Example:
  
      if keypressed is True:
        writeln("A key is waiting!")

=== Function: ONEKEY ===

    Syntax: onekey (keylist, echo) : string
    
    This function asks the user to input a character but accepts only input
    from the user that matches a character in the keylist.  If echo is True
    the function will print the character to the terminal.
            
    Example:
  
      ch = onekey(chr(13) + "APQ", True);
      
      if ch == 'A':
           writeln("User pressed A")
      
     The above example prompts the user to enter one of the keys A, P, Q or
     the ENTER key (ASCII #13).  Because echo is True, it will prompt the
     character to the terminal before returning the key that was pressed.
     
     User input for this function is not case sensitive.

----
==== BBS Data Access Functions ====

----
==== Miscellaneous Functions ====

^ Function                                         ^ Description                                          ^
| [[python_functions#Function: PARAM_COUNT|param_count]] | Return number of script execution parameters   |
| [[python_functions#Function: PARAM_STR|param_str]]     | Return script execution parameters             |

=== Function: PARAM_COUNT ===
  
  Syntax: function param_count() : integer
  
  Returns the number of parameters passed to the script when it was
  executed.
  
  Example: See param_str
  
=== Function: PARAM_STR ===
  
  Syntax: function param_str(#) : string
  
  param_str returns the parameter passed to the script, where # is the
  parameter number.  Supplying (0) will give you the script location and
  name.  Supplying nothing will give you the entire command line.
  
  Example:
  
     import mystic_bbs as bbs;
  
     bbs.writeln ("Number of parameters..: " + str(bbs.param_count()))
     bbs.writeln ("Full command line.....: " + bbs.param_str())
     bbs.writeln ("Script name...........: " + bbs.param_str(0))
     bbs.writeln ("|CRParameters (param_str):|CR")
  
     count = 0
  
     while count <= bbs.param_count():
       bbs.writeln ("   Param #" + str(count) + ": " + bbs.param_str(count))
  
       count = count + 1
  
     bbs.writeln("|CR|PA")
  

----
==== Function List A to Z ====

  * access
  * acsnogroup
  * backspace
  * charxy
  * dated2u
  * datestr
  * dateu2d
  * delay
  * find_config
  * find_display
  * fl_close
  * fl_found
  * fl_getdesc
  * fl_getfile
  * fl_open
  * fl_prev
  * fl_next
  * fl_seek
  * flush
  * getcfg
  * getfbase
  * getfbaseid
  * getfgroup
  * getfgroupid
  * getkey
  * getmbase
  * getmbaseid
  * getmgroup
  * getmgroupid
  * getnetaddr
  * getprompt
  * [[python_functions#Function: GETSTR|getstr]]
  * getuser
  * getuserid
  * getyn
  * gotoxy
  * isuser
  * isuserpw
  * isvalidpw
  * [[python_functions#Function: KEYPRESSED|keypressed]]
  * logerror
  * mci2str
  * menucmd
  * msg_close
  * msg_delete
  * msg_found
  * msg_gethdr
  * msg_gettxt
  * msg_next
  * msg_open
  * msg_prev
  * msg_seek
  * msg_stats
  * [[python_functions#Function: ONEKEY|onekey]]
  * [[python_functions#Function: PARAM_COUNT|param_count]]
  * [[python_functions#Function: PARAM_STR|param_str]]
  * purgeinput
  * [[python_functions#Function: PWRITE|pwrite]]
  * [[python_functions#Function: PWRITELN|pwriteln]]
  * [[python_functions#Function: RWRITE|rwrite]]
  * [[python_functions#Function: RWRITELN|rwriteln]]
  * setlogininfo
  * setpinfo
  * setprompt
  * [[python_functions#Function: SHOWFILE|showfile]]
  * shutdown
  * stuffkey
  * sysoplog
  * termsize
  * textattr
  * textcolor
  * upuser
  * wherex
  * wherey
  * [[python_functions#Function: WRITE|write]]
  * [[python_functions#Function: WRITELN|writeln]]