article

MasterConsole/MasterStream Tutorial Part 1: The Basics

Email
Submitted on: 1/2/2015 10:23:00 AM
By: Jeremy McAnally (from psc cd)  
Level: Beginner
User Rating: By 3 Users
Compatibility: C, C++ (general), Microsoft Visual C++, Borland C++, UNIX C++
Views: 1603
 
     This will teach you the in's and out's of MasterStream and MasterConsole by Jared Bruni. This can also teach you the basics of C++ if you pay attention. ;) Who knows, maybe even advanced users can get some use out of this!

This article has accompanying files
 
				

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).

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.

OK, before we continue, you need to go to here and download MASASM. And go here and get the MasterStream header. To use the MasterStream header, you need to go here 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 here. OK, now that you've got all of that, now let's move on. ;)

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.

MasterConsole is a shell like program that possesses many functions.

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.

flush - The flush command takes 0 arguments, and clears the buffer
about - The about command takes 0 arguments, and display the about message
time - The time command takes 0 arguments, and displays the time
:) - The :) command takes 0 arguments and displays a happy message
add - The add command takes 2 arguments, adds the numbers together and displays the result
sub - The sub command takes 2 arguments, subtracts the numbers and displays the result
mul - The mul command takes 2 arguments, and multiplys the numbers togehter
div - The div command takes 2 arguments, and dividies them and displays the result
dump - The dump command takes 1 argument, and that is of the file to dump the buffer data to
settextcolor The settextcolor command takes 1 argument that being a color ( white , green , red, blue, black )
setbkcolor The setbkcolor command takes 1 argument that being a color (white, green, red, blue, black )
pause - The pause command, pauses until a key is pressed. Similar to system("pause");
lost - The lost message is displayed
echo - The echo command, causes whatever you typed to be repeated
batch - 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.
exit - The exit command takes 0 arguments, and terminates the application.
call - Actually ShellExecute. Can call any program on your computer, or any MasterStream batch file.

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.

MasterStream is the header file that allows you to make batch programs executable from within the MasterConsole environment. This header can be downloaded here. First we'll see how to include and initialize the header file.

#include "masterstream.h"

int mastermain(char* argument)
{

/* Code Goes Here *\

}

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 C++ Beginner's Tutorial. That will explain it line by line, very in depth.

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 here.

Here's the code for your average run-of-the-mill "Hello World!" program.


#include "masterstream.h"


int mastermain(char* argument)
{

// print hello world
console << "hello world!" << endl;
console.pause();
return (0);

}

Now let's take this apart and explain it.

#include "masterstream.h"


int mastermain(char* argument)
{

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).

// print hello world

This is the syntax format for a comment in MasterStream. They are also done as /* & *\ pairings as shown in the first code snippet.

console << "hello world!" << endl;

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!

console.pause();

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.

return (0);
}

Return nothing, and end the program.

Now let's take a look at one that's a little more complex that uses a case select, basic math, and input.

Here is the source for a calculator program made by Jared. You can get the source here.

#include "masterstream.h"

void printmenu();


int mastermain(char* argument)
{
console << " Welcome to the example calculator program " << endl;
console << " written specificly for planetsourcecode.com " << endl;
char yourname[100];
console << " please enter your name: ";
console >> yourname;
console << "\n Hello " << yourname << "!" << endl;

bool go = true;
while( go == true )
{
printmenu();
int menu_item;
console >> menu_item;

switch(menu_item)
{
case 0:
console << "\nerror: please enter a valid menu item" << endl;
break;
case 1:
{

int num1;
int num2;
int val;
console << "\nplease enter the first digit: ";
console >> num1;
console << "\nplease enter the second digit: ";
console >> num2;
val = num1 + num2;
console << "\n the results... " << endl;
console << num1 << " + " << num2 << " = " << val << endl;
}
break;
case 2:
{
int num1;
int num2;
int val;
console << "\nplease enter the first digit: ";
console >> num1;
console << "\nplease enter the second digit: ";
console >> num2;
val = num1 - num2;
console << "\n the results... " << endl;
console << num1 << " - " << num2 << " = " << val << endl;
}
break;
case 3:
console.clear();
break;
case 4:
go = false;
break;
}

console << "\n";

}


console.pause();

return (0);
}


void printmenu()
{
console << "ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ" << endl;
console << "MENU " << endl;
console << " (1) - Add " << endl;
console << " (2) - Sub " << endl;
console << " (3) - Flush " << endl;
console << " (4) - Exit " << endl;
console << "please enter item index: ";
}

Now let's see this in depth.

#include "masterstream.h"

void printmenu();


int mastermain(char* argument)
{

There are those preceding statements again. :) In case you missed it, this set of actions precedes every MasterStream batch program.

console << " Welcome to the example calculator program " << endl;
console << " written specificly for planetsourcecode.com " << endl;
char yourname[100];
console << " please enter your name: ";
console >> yourname;
console << "\n Hello " << yourname << "!" << endl;

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!"

bool go = true;
while( go == true )
{

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.

printmenu();
int menu_item;
console >> menu_item;

switch(menu_item)
{

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.

case 0:
console << "\nerror: please enter a valid menu item" << endl;
break;

If the menu option "0" is chosen then an error message is displayed, because that is not a valid choice.

case 1:
{

int num1;
int num2;
int val;
console << "\nplease enter the first digit: ";
console >> num1;
console << "\nplease enter the second digit: ";
console >> num2;
val = num1 + num2;
console << "\n the results... " << endl;
console << num1 << " + " << num2 << " = " << val << endl;
}
break;

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".

case 2:
{
int num1;
int num2;
int val;
console << "\nplease enter the first digit: ";
console >> num1;
console << "\nplease enter the second digit: ";
console >> num2;
val = num1 - num2;
console << "\n the results... " << endl;
console << num1 << " - " << num2 << " = " << val << endl;
}
break;

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".

case 3:
console.clear();
break;

If menu option "3" is chosen, then the buffer is flushed, thus clearing the screen and buffer.

case 4:
go = false;
break;
}

If menu option "4" is chosen, then the program exits, because go no longer is true and the loop terminates.

console << "\n";

}


console.pause();

return (0);
}

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.

void printmenu()
{
console << "ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ" << endl;
console << "MENU " << endl;
console << " (1) - Add " << endl;
console << " (2) - Sub " << endl;
console << " (3) - Flush " << endl;
console << " (4) - Exit " << endl;
console << "please enter item index: ";
}

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.

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.

This is the source for a magic 8-ball program that's available from Jared here (also in the ZIP file is an updated version of MasterStream. The new functions are covered later in this article.).

#include "masterstream.h"
#include


// mastermain entry point
int mastermain(char* argument)
{
char user_name[255];
char question [255];

// single stream of data
console << " welcome to master 8 ball example enter your name: " >> user_name << endl;
// using a c-style stream
console.printf ( "welcome %s , now for your question: ", user_name);
console >> question;

switch ( rand()%4 )
{
case 0:
case 1:
console.printf("\n it is highly unlikely\n");
break;
case 2:
console.printf("\n heh in your dreams\n");
break;
case 3:
console.printf("\n yes it will happen \n");
break;
case 4:
console.printf("\n master master, wheres the dreams I been after? \n");
break;
}

console.printf("\n");
// pause the console
console.pause();

return (0);
}

OK, let's take this one apart.

#include "masterstream.h"
#include


// mastermain entry point
int mastermain(char* argument)
{

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.

char user_name[255];
char question [255];

Here we define the variables user_name and question as char type (string or character) with a field width of 255 each.

// single stream of data
console << " welcome to master 8 ball example enter your name: " >> user_name << endl;
// using a c-style stream
console.printf ( "welcome %s , now for your question: ", user_name);
console >> question;

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.

switch ( rand()%4 )
{

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.

case 0:
case 1:
console.printf("\n it is highly unlikely\n");
break;
case 2:
console.printf("\n heh in your dreams\n");
break;
case 3:
console.printf("\n yes it will happen \n");
break;
case 4:
console.printf("\n master master, wheres the dreams I been after? \n");
break;
}

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.

console.printf("\n");
// pause the console
console.pause();

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.

return (0);
}

Return nothing and end the program.

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...

-Written by Jeremy McAnally
--www.lostsidedead.com
---"Open Source, Open Mind"

winzip iconDownload article

Note: Due to the size or complexity of this submission, the author has submitted it as a .zip file to shorten your download time. Afterdownloading it, you will need a program like Winzip to decompress it.Virus note:All files are scanned once-a-day by Planet Source Code for viruses, but new viruses come out every day, so no prevention program can catch 100% of them. For your own safety, please:
  1. Re-scan downloaded files using your personal virus checker before using it.
  2. NEVER, EVER run compiled files (.exe's, .ocx's, .dll's etc.)--only run source code.

If you don't have a virus scanner, you can get one at many places on the net including:McAfee.com


Other 2 submission(s) by this author

 


Report Bad Submission
Use this form to tell us if this entry should be deleted (i.e contains no code, is a virus, etc.).
This submission should be removed because:

Your Vote

What do you think of this article (in the Beginner category)?
(The article with your highest vote will win this month's coding contest!)
Excellent  Good  Average  Below Average  Poor (See voting log ...)
 

Other User Comments


 There are no comments on this submission.
 

Add Your Feedback
Your feedback will be posted below and an email sent to the author. Please remember that the author was kind enough to share this with you, so any criticisms must be stated politely, or they will be deleted. (For feedback not related to this particular article, please click here instead.)
 

To post feedback, first please login.