MasterConsole/MasterStream Tutorial Part 1: The Basics

<p><font face="Arial" size="1"><b>Those who can, do.  Those who can't,
teach.  Those who can't teach, learn.  Well that's about what I did
with MasterStream.  I sat down for an afternoon with it and tinkered and
toyed with it and messed around and  looked at the source for MasterConsole
and MasterStream and played with the commands until I fully understood it. 
But I am going to save you that time with this.  You'll learn more from
this than you could just tinkering with it without knowing what you're
doing.  This tutorial will teach all the concepts of MasterStream to date,
the basics of C/C++, and some basics of Pascal (if you pay attention).</b></font></p>
<p><font face="Arial" size="1"><b>What's up, I'm Jeremy McAnally, newest member
of LostSideDead (Jared Bruni's [creator of MASASM, MasterConsole, MasterStream,
MasterString, MasterX SDK, Master Kong 2D, and countless other files...]
software company).  I saw Jared's MasterConsole and then downloaded
MasterStream.  I was enchanted  by it's easiness to use and user
friendliness, yet simple power.  </b></font></p>
<p>
<font face="Arial" size="1"><b>OK, before we continue, you need to go to <A HREF="http://pscode.com/xq/ASP/txtCodeId.1919/lngWId.3/qx/vb/scripts/ShowCode.htm">here</A> and download MASASM. And go 
<A HREF="http://pscode.com/xq/ASP/txtCodeId.2036/lngWId.3/qx/vb/scripts/ShowCode.htm">here</A> 
and get the MasterStream header. To use the MasterStream header, you need to go <A HREF="http://pscode.com/xq/ASP/txtCodeId.2015/lngWId.3/qx/vb/scripts/ShowCode.htm">here</A>
 and get MasterConsole. You need this to execute your MasterStream programs. You may also want to take a peek at an example in MasterStream and an updated version of the MasterStream header 
 <A HREF="http://pscode.com/xq/ASP/txtCodeId.2039/lngWId.3/qx/vb/scripts/ShowCode.htm">here</A>.
OK, now that you've got all of that, now let's move on.  ;)</b></font>
</p>
<p><font face="Arial" size="1"><b>First we'll introduce you to
MasterStream.  MasterStream is a header that allows batch files to be
excuted in  Jared Bruni's
MasterConsole.  With this header, you can make and execute batch console programs
through the MasterConsole interface.  </b></font></p>
<p><font face="Arial" size="1"><b>MasterConsole is a shell like program that
possesses many functions.</b></font></p>
<p><font face="Arial" size="1"> <img border="0" src="http://www.lostsidedead.com/jeremy/con1.jpg" width="320" height="240"></font></p>
<p><font face="Arial" size="1"><b>This is a very interesting program.  It
allows you to stream data, display the system time, set the text and back ground
colors, display different pre-defined messages [such as type :) in the
console  ;) ], pause the console, echo data, evaluate simple math, and
create batch files.  Here is a command list straight from Jared.</b></font></p>
<p><u><b><font face="Arial" size="1">flush </font></b></u><b><font face="Arial" size="1">-
The flush command takes 0 arguments, and clears the buffer<br>
<u>about </u>- The about command takes 0 arguments, and display the about
message<br>
<u>time </u>- The time command takes 0 arguments, and displays the time<br>
<u>:) </u>- The :) command takes 0 arguments and displays a happy message<br>
<u>add </u>- The add command takes 2 arguments, adds the numbers together and
displays the result<br>
<u>sub </u>- The sub command takes 2 arguments, subtracts the numbers and
displays the result<br>
<u>mul </u>- The mul command takes 2 arguments, and multiplys the numbers
togehter<br>
<u>div </u>- The div command takes 2 arguments, and dividies them and displays
the result<br>
<u>dump </u>- The dump command takes 1 argument, and that is of the file to dump
the buffer data to<br>
<u>settextcolor </u>The settextcolor command takes 1 argument that being a color
( white , green , red, blue, black )<br>
<u>setbkcolor </u>The setbkcolor command takes 1 argument that being a color
(white, green, red, blue, black )<br>
<u>pause </u>- The pause command, pauses until a key is pressed. Similar to
system("pause");<br>
<u>lost </u>- The lost message is displayed<br>
<u>echo </u>- The echo command, causes whatever you typed to be repeated<br>
<u>batch </u>- The batch command, takes one argument that of the batch file to
proccess. Simply make a text file, and on each line put one command, and it will
batch proccess them.<br>
<u>exit </u>- The exit command takes 0 arguments, and terminates the application.<br>
call - Actually ShellExecute. Can call any program on your computer, or any
MasterStream batch file.</font></b></p>
<p><font face="Arial" size="1"><b>Not too difficult, eh?  I suggest you
play around with it and get familiar with the way it works before we move on to
MasterStream.</b></font></p>
<p><font face="Arial" size="1"><b>MasterStream is the header file that allows
you to make batch programs executable from within the MasterConsole
environment.  This header can be downloaded <a href="pscode.com/xq/ASP/txtCodeId.2036/lngWId.3/qx/vb/scripts/ShowCode.htm">here</a>. 
First we'll see how to include and initialize the header file.</b></font></p>
<p><font face="Courier New" size="2">#include "masterstream.h"</font></p>
<p><font face="Courier New" size="2">int mastermain(char* argument)<br>
{</font></p>
<p><font face="Courier New" size="2">/* Code Goes Here *\</font></p>
<p><font face="Courier New" size="2">}</font></p>
<p><font face="Arial" size="1"><b>Now, as you can see, it is a relatively simple
process even you've just started C++.  #include is used to reference any
external header file, so that is standard procedure.  Then you intitalize
the mastermain program, and insert your code there.  Very simple.  If
you still don't understand, I suggest you read a <a href="http://pscode.com/xq/ASP/txtCodeId.2040/lngWId.3/qx/vb/scripts/ShowCode.htm">C++
Beginner's Tutorial</a>.  That will explain it line by line, very in
depth.  </b></font></p>
<p><font face="Arial" size="1"><b>So now let's make a basic program.  You
can either copy and paste the code from here, or you can download the code from
Jared's submission <a href="http://pscode.com/xq/ASP/txtCodeId.2037/lngWId.3/qx/vb/scripts/ShowCode.htm">here</a>.</b></font></p>
<p><font face="Arial" size="1"><b>Here's the code for your average
run-of-the-mill "Hello World!" program.</b></font></p>
<p><font face="Arial" size="1"><br>
</font><font face="Courier New" size="2">#include "masterstream.h"<br>
<br>
<br>
int mastermain(char* argument)<br>
{</font></p>
<p><font face="Courier New" size="2">// print hello world</font><font face="Courier New" size="2"><br>
	console << "hello world!" << endl;<br>
	console.pause();<br>
	return (0);</font></p>
<p><font face="Courier New" size="2">}</font></p>
<p><img border="0" src="http://www.lostsidedead.com/jeremy/helloworld.gif" width="312" height="146"></p>
<p><font size="1" face="Arial"><b>Now let's take this apart and explain it.</b></font></p>
<p><font face="Courier New" size="2">#include "masterstream.h"<br>
<br>
<br>
int mastermain(char* argument)<br>
{</font></p>
<p><font face="Arial" size="1"><b>These statments will precede EVERY
MasterStream batch program you create.  They are the basis for every
program you will create for MasterStream.  They include the header and
initialize the MasterStream main program (mastermain).  </b></font></p>
<p><font face="Courier New" size="2">// print hello world</font></p>
<p><font face="Arial" size="1"><b>This is the syntax format for a comment in
MasterStream.  They are also done as /* & *\ pairings as shown in the
first code snippet.</b></font></p>
<p><font face="Courier New" size="2">	console << "hello world!" <<
endl;</font></p>
<p><font face="Arial" size="1"><b>This tells the console to output "hello
world!".  Notice the << pointing towards the console
command.  This means you are outputting TO the console.  Be sure you
put both <<'s or the stream will not execute.   Also, be sure to
put the endl; or it will continue streaming on the same line.  WOW! 
You are now a MasterStream programmer!  Feel happy!</b></font></p>
<p><font face="Courier New" size="2">console.pause();</font></p>
<p><font face="Arial" size="1"><b>This tells the console to pause until a key is
pressed.  Similar to the system key/command Pause, it waits until the user
activates it again with the keyboard.  This is used here to let you see how
the tutorial looks and works, and to also introduce another command. </b></font></p>
<p><font face="Courier New" size="2">	return (0);<br>
}</font></p>
<p><font face="Arial" size="1"><b>Return nothing, and end the program.</b></font></p>
<p><font face="Arial" size="1"><b>Now let's take a look at one that's a little
more complex that  uses a case select, basic math, and input.</b></font></p>
<p><font face="Arial" size="1"><b>Here is the source for a calculator program
made by Jared.  You can get the source here.</b></font></p>
<p><font size="2" face="Courier New">#include "masterstream.h"<br>
<br>
void printmenu();<br>
<br>
<br>
int mastermain(char* argument)<br>
{<br>
	console << " Welcome to the example calculator program " << endl;<br>
	console << " written specificly for planetsourcecode.com " << endl;<br>
	char yourname[100];<br>
	console << " please enter your name: ";<br>
	console >> yourname;<br>
	console << "\n Hello " << yourname << "!" << endl;<br>
<br>
	bool go = true;<br>
	while( go == true )<br>
	{<br>
		printmenu();<br>
		int menu_item;<br>
		console >> menu_item;<br>
<br>
		switch(menu_item)<br>
		{<br>
		case 0:<br>
			console << "\nerror: please enter a valid menu item" << endl;<br>
			break;<br>
		case 1:<br>
			{<br>
<br>
			int num1;<br>
			int num2;<br>
			int val;<br>
			console << "\nplease enter the first digit: ";<br>
			console >> num1;<br>
			console << "\nplease enter the second digit: ";<br>
			console >> num2;<br>
			val = num1 + num2;<br>
			console << "\n the results... " << endl;<br>
			console << num1 << " + " << num2 << " = " << val << endl;<br>
			}<br>
			break;<br>
		case 2:<br>
			{<br>
			int num1;<br>
			int num2;<br>
			int val;<br>
			console << "\nplease enter the first digit: ";<br>
			console >> num1;<br>
			console << "\nplease enter the second digit: ";<br>
			console >> num2;<br>
			val = num1 - num2;<br>
			console << "\n the results... " << endl;<br>
			console << num1 << " - " << num2 << " = " << val << endl;<br>
			}<br>
			break;<br>
		case 3:<br>
			console.clear();<br>
			break;<br>
		case 4:<br>
			go = false;<br>
			break;<br>
		}<br>
<br>
		console << "\n";<br>
<br>
	}<br>
<br>
<br>
	console.pause();<br>
<br>
	return (0);<br>
}<br>
<br>
<br>
void printmenu()<br>
{<br>
	console << "ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ" << endl;<br>
	console << "    MENU     " << endl;<br>
	console << " (1) - Add " << endl;<br>
	console << " (2) - Sub " << endl;<br>
	console << " (3) - Flush " << endl;<br>
	console << " (4) - Exit " << endl;<br>
	console << "please enter item index: ";<br>
}</font></p>
<p><img border="0" src="http://www.lostsidedead.com/jeremy/calculator.gif" width="640" height="480"></p>
<p><font face="Arial" size="1"><b>Now let's see this in depth.</b></font></p>
<p><font size="2" face="Courier New">#include "masterstream.h"<br>
<br>
void printmenu();<br>
<br>
<br>
int mastermain(char* argument)<br>
{</font></p>
<p><font face="Arial" size="1"><b>There are those preceding statements again.
:)  In case you missed it, this set of actions precedes every MasterStream
batch program.</b></font></p>
<p><font size="2" face="Courier New">	console << " Welcome to the example calculator program " << endl;<br>
	console << " written specificly for planetsourcecode.com " << endl;<br>
	char yourname[100];<br>
	console << " please enter your name: ";<br>
	console >> yourname;<br>
	console << "\n Hello " << yourname << "!" << endl;</font></p>
<p><font face="Arial" size="1"><b>This portion of the code displays a welcome
message.  The first two lines merely welcome you to the program by
displaying some text.  The next line creates a variable called your name of
the char type (character/string).  The next two lines ask you to enter your
name, and create an input for you to do so.  Then the next line displays a
personalized message like "Hello Jeremy!" or "Hello Jared!"</b></font></p>
<p><font size="2" face="Courier New">	bool go = true;<br>
	while( go == true )<br>
	{</font></p>
<p><font face="Arial" size="1"><b>The first line of this snippet creates a a
variable of boolean type called go.  Then a while loop is initiated, the
conditions being if go is true.</b></font></p>
<p><font size="2" face="Courier New">printmenu();<br>
		int menu_item;<br>
		console >> menu_item;<br>
<br>
switch(menu_item)<br>
		{<br>
</font></p>
<p><font face="Arial" size="1"><b>At the beginning of the loop,  the
function "printmenu" that prints a menu text  is called (this is
shown at the end of this code).  Then, a variable of integer type is
created called menu_item.  This will be used to choose which menu option
you would like to call.  The next line requires the input of your menu
choice.  (The menu is displayed when the function "printmenu" is
called, therefore you would see the menu if you ran the program.)  The last
line of this code opens a case select of menu_item.</b></font></p>
<p><font size="2" face="Courier New">		case 0:<br>
			console << "\nerror: please enter a valid menu item" << endl;<br>
			break;<br>
</font></p>
<p><font face="Arial" size="1"><b>If the menu option "0" is chosen
then an error message is displayed, because that is not a valid choice.</b></font></p>
<p><font size="2" face="Courier New">		case 1:<br>
			{<br>
<br>
			int num1;<br>
			int num2;<br>
			int val;<br>
			console << "\nplease enter the first digit: ";<br>
			console >> num1;<br>
			console << "\nplease enter the second digit: ";<br>
			console >> num2;<br>
			val = num1 + num2;<br>
			console << "\n the results... " << endl;<br>
			console << num1 << " + " << num2 << " = " << val << endl;<br>
			}<br>
			break;</font></p>
<p><font face="Arial" size="1"><b>If you choose menu option "1", 
then the addition portion is intitated.  At the beginning of the case code,
three variables of integer type are created, num1, num2, and val
respectively.  Then a prompt for the first number is displayed.  The
next line creates a user input for the first number to add.  This value is
stored in num1.  This process of prompt/input is duplicated for the second
number, only the value is not stored in num1, but num2.  Then val is set
equal to num1 + num2.  The next two lines display the expression and the
solution, like "2 + 3 = 5". </b></font></p>
<p><font size="2" face="Courier New">		case 2:<br>
			{<br>
			int num1;<br>
			int num2;<br>
			int val;<br>
			console << "\nplease enter the first digit: ";<br>
			console >> num1;<br>
			console << "\nplease enter the second digit: ";<br>
			console >> num2;<br>
			val = num1 - num2;<br>
			console << "\n the results... " << endl;<br>
			console << num1 << " - " << num2 << " = " << val << endl;<br>
			}<br>
			break;</font></p>
<p><font face="Arial" size="1"><b>If you chose menu option "2", then
the subtraction portion is initiated.  Again, like in addition, in the
beginning three variables of integer type are created called num1, num2, and val
respectively.  Then a prompt is created for the first number.  A user
input is created for the first number.  This value is stored in num1. 
The prompt/input is again duplicated for the second number, but instead of num1,
it is stored in num2.  Then val is set equal to num1 - num2.  Then the
next two lines display the expression and the results, like "5 - 2 =
3".</b></font></p>
<p><font size="2" face="Courier New">		case 3:<br>
console.clear();<br>
			break;</font></p>
<p><font face="Arial" size="1"><b>If menu option "3" is chosen, then
the buffer is flushed, thus clearing the screen and buffer.</b></font></p>
<p><font size="2" face="Courier New">		case 4:<br>
			go = false;<br>
			break;<br>
		}</font></p>
<p><font face="Arial" size="1"><b>If menu option "4" is chosen, then
the program exits, because go no longer is true and the loop terminates.</b></font></p>
<p><font size="2" face="Courier New">		console << "\n";<br>
<br>
	}<br>
<br>
<br>
	console.pause();<br>
<br>
	return (0);<br>
}</font></p>
<p><font face="Arial" size="1"><b>This portion of the code prints a blank line,
pauses the console to allow you to view the results, returns nothing, and exits
the program.</b></font></p>
<p><font size="2" face="Courier New">void printmenu()<br>
{<br>
	console << "ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ" << endl;<br>
	console << "    MENU     " << endl;<br>
	console << " (1) - Add " << endl;<br>
	console << " (2) - Sub " << endl;<br>
	console << " (3) - Flush " << endl;<br>
	console << " (4) - Exit " << endl;<br>
	console << "please enter item index: ";<br>
}</font></p>
<p><font face="Arial" size="1"><b>This is the printmenu function.  It
prints the menu for choices into the console.  It merely prints the
text.  Structuring the progam this way makes it easier to read and the
function recallable from any portion of the program.</b></font></p>
<p><font face="Arial" size="1"><b>That wasn't too bad was it?  Now let's
take a look at one a LITTLE more advanced, that also integrates C/C++ libraries
into the mix.</b></font></p>
<p><font face="Arial" size="1"><b>This is the source for a magic 8-ball program
that's available from Jared <a href="http://pscode.com/xq/ASP/txtCodeId.2039/lngWId.3/qx/vb/scripts/ShowCode.htm">here</a>
(also in the ZIP file is an updated version of MasterStream.  The new
functions are covered later in this article.).</b></font></p>
<p><font face="Courier New" size="2">#include "masterstream.h"<br>
#include <stdlib.h><br>
<br>
<br>
// mastermain entry point<br>
int mastermain(char* argument)<br>
{<br>
	char user_name[255];<br>
	char question [255];<br>
<br>
	// single stream of data<br>
	console << " welcome to master 8 ball example enter your name: " >> user_name << endl;<br>
	// using a c-style stream<br>
	console.printf ( "welcome %s , now for your question: ", user_name);<br>
	console >> question;<br>
<br>
	switch ( rand()%4 )<br>
	{<br>
	case 0:<br>
	case 1:<br>
		console.printf("\n it is highly unlikely\n");<br>
		break;<br>
	case 2:<br>
		console.printf("\n heh in your dreams\n");<br>
		break;<br>
	case 3:<br>
		console.printf("\n yes it will happen \n");<br>
		break;<br>
	case 4:<br>
		console.printf("\n master master, wheres the dreams I been after? \n");<br>
		break;<br>
	}<br>
<br>
	console.printf("\n");<br>
	// pause the console<br>
	console.pause();<br>
<br>
	return (0);<br>
}</font></p>
<p><img border="0" src="http://www.lostsidedead.com/jeremy/8ball.gif" width="640" height="480"></p>
<p><font face="Arial" size="1"><b>OK, let's take this one apart.</b></font></p>
<p><font face="Courier New" size="2">#include "masterstream.h"<br>
#include <stdlib.h><br>
<br>
<br>
// mastermain entry point<br>
int mastermain(char* argument)<br>
{</font></p>
<p><font face="Arial" size="1"><b>This is the preceding statements from any
Master Stream program, but with the header stdlib.h added for extra
functionality.  You will see why this was added later in this explanation.</b></font></p>
<p><font face="Courier New" size="2">	char user_name[255];<br>
	char question [255];</font></p>
<p><font face="Arial" size="1"><b>Here we define the variables user_name and
question as char type (string or character) with a field width of 255 each.</b></font></p>
<p><font face="Courier New" size="2">	// single stream of data<br>
	console << " welcome to master 8 ball example enter your name: " >> user_name << endl;<br>
	// using a c-style stream<br>
	console.printf ( "welcome %s , now for your question: ", user_name);<br>
	console >> question;</font></p>
<p><font face="Arial" size="1"><b>Then, the console is told to output
"welcome to master 8 ball example enter your name:".  I know this
statement looks strange to you, because this is a new feature in the updated
version of MasterStream.  It allows you to do the input and output streams
in the same line. If you do not yet have the updated version, be sure to
download it from here before you try to execute this program.   Notice
the switch from << (to the console), to >> (input) all in the
same.  Be sure you make this switch, or a syntax error will occur, or it
will output the current value of the variable you wanted to input to.  Also
be sure to add the << endl; or a syntax error will occur at that instance
also.   Also, notice the next line.  This is a new feature of the
updated version of MasterStream.  Jared has added C-style streams to
MasterStream so now you can use console << "text" or
console.printf ( "text" );.  The next line has the user input his
question. </b></font></p>
<p><font face="Courier New" size="2">	switch ( rand()%4 )<br>
	{</font></p>
<p><font face="Arial" size="1"><b>We begin a select case statement here. 
We are selecting the case of what random number is generated from
rand()%4.  rand()%4 will generate a number from 0 to 4.  The random
number is the reason we included stdlib.h.  Otherwise, we'd have to use
really long math, and that could get ugly. </b></font></p>
<p><font face="Courier New" size="2">	case 0:<br>
	case 1:<br>
		console.printf("\n it is highly unlikely\n");<br>
		break;<br>
	case 2:<br>
		console.printf("\n heh in your dreams\n");<br>
		break;<br>
	case 3:<br>
		console.printf("\n yes it will happen \n");<br>
		break;<br>
	case 4:<br>
		console.printf("\n master master, wheres the dreams I been after? \n");<br>
		break;<br>
	}</font></p>
<p><font face="Arial" size="1"><b>Here the cases are chosen.  If the number
is 0 then nothing.  If the number (rand()%4)  is 1 the console is told
to output "it is highly unlikely".  If the number is 2 then the
console is instructed to output "heh in your dreams", and so on with
the rest of the cases.  Again, we use the C-style streams new to the
updated version of MasterStream.</b></font></p>
<p><font face="Courier New" size="2">	console.printf("\n");<br>
	// pause the console<br>
	console.pause();</font></p>
<p><font face="Arial" size="1"><b>Here again we use a C-style stream to print a
blank line.  The next line we pause the console to allow you to look at the
output until you press a key and return to the console.</b></font></p>
<p><font face="Courier New" size="2">	return (0);<br>
}</font></p>
<p><font face="Arial" size="1"><b>Return nothing and end the program.</b></font></p>
<p><b><font face="Arial" size="1">I hope this tutorial atleast taught you a
little something about MasterStream and maybe even some C/C++ or Pascal
basics.  If there is anyway I can improve this tutorial please e-mail me
with the request and I will see what I can do!  There is a second part to
this tutorial.  If you'd like to view it, then click here.  Look out for upcoming
tutorials on MasterIOStream by Jared Bruni, MASASM by Jared Bruni, and the CIS41
Emulator by Jared Bruni!  Also, keep an eye out for my IDE for the MASASM
and MasterStream systems.  Thanks, and remember if it ain't open
source...it sux...</font></b></p>
<p><b><font face="Arial" size="1">-Written by <i>Jeremy McAnally</i><br>
--<a href="http://www.lostsidedead.com/">www.lostsidedead.com</a><br>
---"<font color="#000080">Open</font> <font color="#800000">Source</font>, <font color="#0000FF">Open</font>
<font color="#FF0000">Mind</font>"</font></b></p>

Upload