craig.oates
/
console.waterworks
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

remove old wiki files.

master
Craig Oates 5 years ago
parent
131f6e049d
commit
587616e656
20 changed files with 0 additions and 642 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 28
      Adding-Console.Waterworks-to-Your-Project.md
  2. 3
      Architecture-Overview.md
  3. 15
      Coercion-Types-List.md
  4. 55
      Console.Waterworks-Code-Example-(in-Full).md
  5. 72
      Department-Breakdown:-Teams.md
  6. 4
      Example-Projects.md
  7. 44
      Home.md
  8. 15
      Introduction.md
  9. 12
      Preface.md
  10. 6
      Recommendations-for-Those-Wanting-to-Alter-Console.Waterworks.md
  11. 33
      Setting-up-the-"Help-Section".md
  12. 8
      The-"Help"-Attributes.md
  13. 100
      The-Flow-of-the-System.md
  14. 5
      The-Missing-Piece:-ConsoleCommands.cs.md
  15. 42
      Things-to-Consider-for-Run-time.md
  16. 45
      Using-the-"Help-Attributes".md
  17. 57
      Wire-Console.Waterworks-into-Your-Program.md
  18. 61
      Writing-Command-Methods.md
  19. 1
      _Footer.md
  20. 36
      _Sidebar.md

28
Adding-Console.Waterworks-to-Your-Project.md
Unescape

@ -1,28 +0,0 @@
You can add Console.Waterworks to your project in several ways. The two most common ways are via Visual Studio. You can use either its Package Manager GUI or Console. If you do not use Visual Studio, you can use .Net's CLI as an alternative.
Visual Studio's Package Manger GUI
When in the GUI, search for "Console.Waterworks" and click "install".
![Adding C.W. via V.S. GUI.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/Adding_CW_Proj_PM.JPG)
## Visual Studio's Package Manager Console
In the console window type the following,
```cs
// Insert the version number of your choice.
Install-Package Console.Waterworks -Version 1.0.0.0
```
(Image: Adding Waterworks to your project via Visual Studio's Package Manager Console.)
## .Net's CLI
If you are not using Visual Studio, you can add Console.Waterworks to your project via the .Net CLI. You can add it by typing the following into the CLI,
```cs
// Insert the version number of your choice.
dotnet add package Console.Waterworks --version 1.0.0.0
```
Now you have added Console.Waterworks to your project, you can start using it.

3
Architecture-Overview.md
Unescape

@ -1,3 +0,0 @@
I built Console.Waterworks like it was a small team within a bigger company. And, that bigger company has assigned this small team to a client of the company. Another way to look at it is the client has requested some services from Nuget. Nuget has then agreed to work with this client. From there, Nuget has assigned the Console.Waterworks team to the client. From here on out, the client deals with just the Console.Waterworks team. The client then proceeds making requests to the Console.Waterworks team via Console.Waterworks' Liaison. The Console.Waterworks team processes the request and hands the result to the client via its Liaison. So, from the client’s point-of-view, they only need to deal with a single point of contact.
![C.W. as a department within Big Corp.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/CW_As_Department.png)

15
Coercion-Types-List.md
Unescape

@ -1,15 +0,0 @@
Here is a list of different (C#) types Console.Waterworks can coerce the end-users input in to at run-time. This is needed because the nature of console programs is text based.
1. Int16:
1. Int32:
1. Int64:
1. Boolean:
1. Byte:
1. Char:
1. DateTime:
1. Decimal:
1. Double:
1. Single:
1. UInt16:
1. UInt32:
1. UInt64:

55
Console.Waterworks-Code-Example-(in-Full).md
Unescape

@ -1,55 +0,0 @@
Here is the how a typical console program should look after the initial setup. The name of the console program solution in this example is CW_Console. Free feel to make changes for it to match your solution.
## Program.cs
```cs
using Console.Waterworks;
namespace CW_Console
{
class Program
{
static void Main(string[] args)
{
CW_Liaison liaison = new CW_Liaison();
liaison.Run("CW_Console", true);
}
}
}
```
## ConsoleCommands.cs
```cs
using Console.Waterworks;
using Console.Waterworks.Attributes;
using System;
namespace CW_Console
{
public class ConsoleCommands
{
[ListCommand()]
[Description("Displays the Help section at run-time")]
[Parameters("None")]
[Usage("CW_Console> Help")]
public static string Help()
{
CW_Liaison liaison = new CW_Liaison();
return liaison.RequestHelpDocumentation("CW_Console");
}
[ListCommand()]
[Description("Repeats back to the user the string they entered.")]
[Parameters("<string> input")]
[Usage("CW_Console> Say \"Hello, World.\"")]
public static string Say(string input) => $"{input}";
[ListCommand()]
[Description("Terminates the program.")]
[Parameters("None")]
[Usage("CW_Console> Quit")]
public static void Quit() => Environment.Exit(-1);
}
}
```

72
Department-Breakdown:-Teams.md
Unescape

@ -1,72 +0,0 @@
As stated in other parts of this Wiki, I built Console.Waterworks like it was a small department. Within this department, there are seven “teams” (excluding the `Liaison`). They are,
- Assistants
- Attributes
- CoOrdinators
- Constants
- Loggers
- Models
- Specialists
Each team has various amounts of workers so vary in size. But, they all report to `CoOrdinator`. Each team is free to talk to one another. But, as a general rule, each team communicates via the `CoOrdinator`. At this moment in time, there is only one `CoOrdinator`. But, that does not mean it must stay that way. It is, also, important to note, the client will not deal with them any of them. They (the client) will/should only deal with the Liaison, and this is by design
## Console.Waterworks Teams
### Assistants
The Assistants department has two workers within it. They are `CommandAssistant` and `CoOrdinatorAssistant`. Both of them offer support to their namesake counterparts. In other words, they do the non-essential work of the higher ranking `CommandAssistant` and `CoOrdinatorAssistant` workers.
### Attributes
The workers in this department are responsible for decorating command-methods in the `ConsoleCommand` class. Command-methods are the name given to the methods used by the end-user of the console program. You can find more information about command-methods in [Writing Command-Methods](Link needed). The reason why this department exists is because Console.Waterworks provides a run-time "help" section. More information about this can be found in [Creating a Help Section](Link needed). There are four workers in this department. They are as follows,
1. `DescriptionAttribute`
1. `ListCommandAttribute`
1. `ParameterAttribute`
1. `Usageattribute`
These workers tend to only interact with the `HelpSpecialist` worker.
### CoOrdinators
There is only one worker in this department. With that said, this worker is a critical part of the Console.Waterworks team. The 'CoOrdinator' holds the whole team together. It assigns tasks to the assistants, specialists and loggers. And, it is the only one to converse with the team's 'Liaison'. If you want to change Console.Waterworks, do not underestimate the value of this particular worker.
### Constants
There is only one worker in this department. The `CW_Constants` worker handles the constant variables within Console.Waterworks. This worker does not report to any other worker in the same way the other do. Instead, they request information from this worker when they need it. I tend to think of it like a colleague shouting across the room for a quick bit of information.
### Loggers
This department is another one-worker department and houses the `CW_Logger`. Its main purpose is to document the flow of Console.Waterworks. I use it for testing purposes most of the time. An important thing to note is it is only used for developing Console.Waterworks. When you use Console.Waterworks as a Nuget package, no logging will occur. For the most part, the `CW_Logger` works with just the `CoOrdinator`. But, you are able to use it anywhere in the Console.Waterworks project.
### Models
There is one worker in this department. It is the `Command` worker. This worker is in charge of how the command-method must look. If you want to change what the criteria for how a command-method looks, you will do it here. This, in turn, will alter the way the end-user will enter the commands in the console program. Because of this, be careful when altering this piece of code.
Before continuing, I must admit this is an area where the small-team-of-workers-analogy breaks down. The reason why is because of the purpose of this class. Its main aim is to represent a data structure and not functionality. So, keep that in mind when working with the code.
### Specialists
This department is the biggest and the place you will spend most of your time. This is the department the `CoOrdinator` will hand most of the work to. Each worker in this department specialises in one area and does not venture outside of it. The idea here is the `CoOrdinator` hands work over to the appropriate specialist. Which, in turn, hands the result back when it has finished. This makes it easy to create conveyor-belt-like workflows amongst the team. It is, also, easy to narrow down any problem area if errors begin occurring.
This department has five workers. They are as follows,
1. `CoercionSpecialist`
1. `CommandSpecialist`
1. `ConsoleIOSpecialist`
1. `HelpSpecialist`
1. `ProgramInfoSpecialist`
The `CoercionSpecialist` handles the coercing of the end-user's input into a data type C# understands. There is a limit on the amount of data types Console.Waterworks works with. So, make sure you familiarise yourself with them. [Coersion List](https://github.com/CraigOates/Console.Waterworks/wiki/Coercion-Types-List). That does not mean you are stuck with the defaults. You are more than welcome to expand or contract that list.
The `CommandSpecialist` is in charge of determining what command-methods are available at run-time. It, also, determines the name of the "ConsoleCommands" class and its location. So, if you want to change any of these properties, this is the worker you need to deal with.
The next specialist is the `HelpSpecialist`. This specialist handles the organising of the "help" section. It, also, provides said help section at run-time. It does this by checking every command-method for any Console.Waterworks attributes attached to it. Once it has done that, it can hand the information back to `CoOrdinator`, then the `Liaison` and then the console.
The `ProgramInfoSpecialist` provides information about the console program at run-time. If you would like to change what is shown when the console program starts you can do it in two places. The first is here but this would not be my first choice. The second place is the assembly information. You can find this by opening up the projects properties page which you can see in below.
(insert image for changing prog. info in Assembly Info.)
I ran through a lot of information there and at a brisk pace. So, to help with the information overload, here is an illustration to help breakdown it down.
![Departments breakdown.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/Architecture_Overview_General.png)

4
Example-Projects.md
Unescape

@ -1,4 +0,0 @@
Here is a list of console program which have been written using Console.Waterworks. This is a list I will add to over time.
1. [Console.Waterworks Code Example](https://github.com/CraigOates/Console.Waterworks/wiki/Console.Waterworks-Code-Example-(in-Full)) - This is the (in full) setup example in this Wiki.
1. [CW_Console](https://github.com/CraigOates/Console.Waterworks/tree/master/Console.Waterworks/CW_Console) - The testing console for this project.

44
Home.md
Unescape

@ -1,44 +0,0 @@
![CW_Header](https://github.com/CraigOates/Console.Waterworks/blob/develop/Documentation/GitHub_Assets/CW_Header.png)
- Created by [Craig Oates](https://github.com/CraigOates)
- Web: [craigoates.net](http://www.craigoates.net, "Craig's website")
- Email: craig@craigoates.net
- Project's Site: [http://craigoates.net/Software/project/7](https://craigoates.net/Software/project/7)
- License: [MIT](https://github.com/CraigOates/Console.Waterworks/blob/master/LICENSE, "CW's License")
---
## Table of Contents
- [Home](https://github.com/CraigOates/Console.Waterworks/wiki)
- [Preface](https://github.com/CraigOates/Console.Waterworks/wiki/Preface)
- [Introduction](https://github.com/CraigOates/Console.Waterworks/wiki/Introduction)
## As a Nuget Package
### Setting Up
- [Adding Console.Waterworks to Your Project](https://github.com/CraigOates/Console.Waterworks/wiki/Adding-Console.Waterworks-to-Your-Project)
- [Wire Console.Waterworks into Your Program](https://github.com/CraigOates/Console.Waterworks/wiki/Wire-C.W.-into-Your-Program)
- [Writing Command-Methods](https://github.com/CraigOates/Console.Waterworks/wiki/Writing-Command-Methods)
### Creating a "Help Section"
- [Setting up the "Help Section"](https://github.com/CraigOates/Console.Waterworks/wiki/Setting-up-the-%22Help-Section%22)
- [The "Help" Attributes](https://github.com/CraigOates/Console.Waterworks/wiki/The-%22Help%22-Attributes)
- [Using the "Help" Attributes](https://github.com/CraigOates/Console.Waterworks/wiki/Using-the-%22Help-Attributes%22)
### Useful References
- [Console.Waterworks Code Example (in Full)](https://github.com/CraigOates/Console.Waterworks/wiki/Console.Waterworks-Code-Example-(in-Full))
- [Things to Consider for Run-time](https://github.com/CraigOates/Console.Waterworks/wiki/Things-to-Consider-for-Run-time)
- [Example Projects](https://github.com/CraigOates/Console.Waterworks/wiki/Example-Projects)
## Architecture
- [Architecture Overview](https://github.com/CraigOates/Console.Waterworks/wiki/Architecture-Overview)
- [Department Breakdown: Teams](https://github.com/CraigOates/Console.Waterworks/wiki/Department-Breakdown:-Teams)
- [Coercion Types List](https://github.com/CraigOates/Console.Waterworks/wiki/Coercion-Types-List)
- [The Flow of the System](https://github.com/CraigOates/Console.Waterworks/wiki/The-Flow-of-the-System)
- [The Missing Piece: ConsoleCommands.cs](https://github.com/CraigOates/Console.Waterworks/wiki/The-Missing-Piece:-ConsoleCommands.cs)
- [Recommendations for Altering Console.Waterworks](https://github.com/CraigOates/Console.Waterworks/wiki/Recommendations-for-Those-Wanting-to-Alter-Console.Waterworks)

15
Introduction.md
Unescape

@ -1,15 +0,0 @@
The reason why I made Console.Waterworks is because I like writing console programs. The ones I most enjoy are the ones which operate like tradition CLI's -- like PowerShell and Bash. The reason why is because I find these types of programs more enjoyable to use. This is especially true when they are my own programs and I know the innards of them very well. I assuming that last sentence rings true for you, also.
Before I began writing Console.Waterworks, I would often fumble my way through to the finish line. I would, more often than not, attempt to get my console program working like Bash or Powershell. It was fun at first, when I was learning. But, after a while, it began to grate on me. It became a dance without its charm and my excitement made a side-door exit. This is when I discovered ConsoleApplicationBase by TypecastException -- also on GitHub. It is "A Useful, Interactive, and Extensible .Net Console Application Template for Developing and Testing". I found it most useful for a while but I grew frustrated, again. Before I continue, I would like to say ConsoleApplicationBase is a useful bit of kit. And, you should check it out. But, the project template side of it always felt too heavy -- once I learnt how it works. So, I took ConsoleApplicationBase as my starting point and began writing Console.Waterworks. Now I am able to write command-based console programs faster. And, I have a couple of extra tricks up my sleeve, as well. They are useful things like a run-time help section and outputting program information.
The reason why I have made Console.Waterworks an open source project is because of two things. The first one is I believe the value of this "product" extends beyond the "final outcome". What I mean by that is the Nuget package Console.Waterworks ends up as is only a starting point. The way I built Console.Waterworks allows and encourages people to expand it beyond the scope I have set. Because of this, Console.Waterworks needs to be accessible beyond its Nuget form. The second one is I believe it is only fair for me to put it on GitHub. If TypecastException did not put ConsoleApplicationBase on GitHub, Console.Waterworks would not exist. Even if it did, it would not look or operate like it does today. In other words, I would be a selfish moron if I did not share.
If this is the first thing you have read in this repository, you might be wondering what Console.Waterworks is. So, to answer that question, I will say is it is a Nuget package. You use it for writing extendable command-based console programs in .Net 4.7, or higher. I wrote Console.Waterworks in C# and I based it on ConsoleApplicationBase. The main problem it aims to solve is the "plumbing code" part of writing console programs. In other words, it parses end-user input for you and passes the data on to the correct part of your code. I do not want to get into the details of how Console.Waterworks does that here. But, I will provide a couple of diagrams to help sum up the process.
## Good Input Data Flow
![Valid Input](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/Valid_Input.png "Valid input diagram")
## Bad Input Data Flow
![Invalid Input](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/Invalid_Input.png "Invalid input diagram")

12
Preface.md
Unescape

@ -1,12 +0,0 @@
## Prerequisites
- You have experience with [C#](https://docs.microsoft.com/en-us/dotnet/csharp/) (Ver. 5.0+).
- You can create a [.Net console program](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/hello-world-your-first-program) in [Visual Studio 2017](https://www.visualstudio.com/).
- You have experience with [Nuget](https://www.nuget.org/).
- You have Microsoft [.Net Framework 4.7](https://docs.microsoft.com/en-us/dotnet/standard/) or higher.
## Assumptions and Disclaimers
- I have written this guide under the assumption you are using C#. If you would like to use Console.Waterworks with VB or F#, you will need to translate this in to your respective language. I know that is not the best response. But, I do not have any experience in those languages. And, if I may be frank for a moment, I don't have the willingness to learn them at this moment in time, either. There is a chance I will change my mind in the future but I recommend you do not hold out for that.
- This guide will assume you are using Visual Studio 2017, for the most part. There are moments when it does venture outside of Visual Studio but they are exceptions. With that said, I don't discourage people from going outside Visual Studio. If you are more comfortable using something else, feel free to carry-on using that. But, I am not lying when I say you might feel like I've left you hanging in parts.
- Console.Waterworks is based on the [ConsoleApplicationBase](https://github.com/TypecastException/ConsoleApplicationBase) repository by [TypecastException](https://github.com/TypecastException).

6
Recommendations-for-Those-Wanting-to-Alter-Console.Waterworks.md
Unescape

@ -1,6 +0,0 @@
This bit is an odd section. The reason why is because I am second guessing your intensions and goals. The truth is I have no idea what you intend to do if you want to change things. So, take what I am about to say with a pinch of salt -- as the saying goes.
1. Try to keep the `Liaison` as a wrapper class. Or, another way to look at is treat it like a public-facing API. It will help you maintain control over what people can and cannot access.
1. Try to keep the "`Liasion`-`CoOrdinator` only" relationship. Again, this will help you maintain control over data access. Having said that, it does not mean you must have only one `CoOrdinator`.
1. Try to keep things as modular as possible. Use the folders provided to help keep things small and separate. This will allow you to change and update code with ease.
1. Try to stick to the small team analogy. It will help your code's predictability. This might appear frustrating at first but it will help in the long-run.
1. Try not to venture too far outside of the original scope of Console.Waterworks. If you find it difficult to get it to do what you want, take that as a sign to stop using it. It is okay if it does not work for the task you are trying to complete. And, if that is the case, you should prepare to use something else. There is nothing stopping you from using Console.Waterworks as the basis for your design.

33
Setting-up-the-"Help-Section".md
Unescape

@ -1,33 +0,0 @@
1 To get started, create a command-method in ConsoleComands.cs. you can call it whatever you want but I prefer to call it ```Help```.
```cs
using Console.Waterworks;
using System;
namespace CW_Console
{
public class ConsoleCommands
{
public static string Help()
{
return "";
}
}
}
```
2 Once you have created the "Help" command-method, you must create a ```CW_Liaison``` object. When you have created the liaison, call the ```RequestHelpDocumentation``` method. Remember to include the namespace for ```ConsoleCommands.cs```.
```cs
public static string Help()
{
CW_Liaison liaison = new CW_Liaison();
return liaison.RequestHelpDocumentation("CW_Console");
}
```
3 Add ```using Console.Waterworks.Attributes;``` to ```ConsoleCommands.cs```.
If you run the program, you will see nothing appear when you enter the "Help" command. This is expected. It means you have set it up correctly. It just does not have any information to show yet.
See [Console.Waterworks Code Example (in Full)](https://github.com/CraigOates/Console.Waterworks/wiki/Console.Waterworks-Code-Example-(in-Full)) for further information.

8
The-"Help"-Attributes.md
Unescape

@ -1,8 +0,0 @@
To use the "Help Section" feature, you will need to know about the four attributes it is built with. They are as follows,
- **ListCommand**: When you attach this attribute to a command-method, that method will appear in the help section at run-time. You can, also, pass in a false Boolean, as a parameter. This explicit declaration means the method will not appear at run-time. I use this option to turn things on an off without needing to rewrite the whole line every time. It helps with reducing temporary comment code, as well.
- **Parameters**: You can use this attribute to list out the parameters the end-user will need to pass into the command-method. The reason why you need to pass in a string to the attributes constructor is so you have flexibility. Some methods have parameter lists which are large and difficult to read. Because of this, it is in your end-user's interest for you to simplify it. I admit I could have programmed Console.Waterworks to figure it out for you. But, that would have taken that decision away from you. Whilst it is not perfect, I believe the string approach is the most practical solution.
- **Describe**: This attribute allows you to offer contextual information to the end-user. To use it, you pass in a string to the attribute's constructor.
- **Usage**: To help your end-users even more, you can provide them with an example of how to use your command-methods. To use this attribute, pass in a string to its constructor.
See [Console.Waterworks Code Example (in Full)](https://github.com/CraigOates/Console.Waterworks/wiki/Console.Waterworks-Code-Example-(in-Full)) for further information.

100
The-Flow-of-the-System.md
Unescape

@ -1,100 +0,0 @@
There is a general flow to how the program will move through Console.Waterworks. Before continuing, though, I recommend you read [Department Breakdown: Teams](https://github.com/CraigOates/Console.Waterworks/wiki/Department-Breakdown:-Teams), alongside this. It will help you build a better image of how Console.Waterworks... works.
At the beginning, I said there is a general flow to Console.Waterworks. I said this because it was designed to have a default -- and for the most part rigid -- path to follow. Although, you can break out of that path if you need to. If you decide to alter the code in some way and you are new to the codebase, I have one piece of advice: Stick to the default path as much as possible. The general flow of Console.Waterworks looks like this.
![Basic flow.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/General_Flow.png)
What is important to note here is the group called "Rest of the Team". The reason why is because the general rule is each member reports back to the `CoOrdinator` and not each other. That does not mean there is no direct communication between the rest of the team. But, they are exceptions and uncommon. Also, if you do need to have workers (specialists, assistants Etc.) talk to each other, try to have the `CoOrdinator` arrange it. Here is an example of what I mean.
### The Department's Default Communication Process
```cs
internal string DisplayHelpSection(string commandsNamespace)
{
_logger.LogInfoMessage("Attempting to display help section..");
var commandClasses = _commSpec.GetCommandClasses(commandsNamespace);
if (commandClasses.Count == 0)
{
_logger.LogErrorMessage("Unable to find any help information. Make sure the commands hace the correct atrributes applied");
_consoleSpec.WriteErrorSuffix();
return "Unable to find help information";
}
_logger.LogSuccessMessage("Found help information");
_logger.LogInfoMessage("Attempting to display the help information..");
_consoleSpec.WriteOutputToConsole("Displaying Help section...");
_consoleSpec.LineBreak();
var commandMembers = _helpSpec.GetCommandMembers(commandClasses);
foreach (var command in commandMembers)
{
if (_helpSpec.ListCommand(command) == true)
{
_consoleSpec.WriteOutputToConsole($"Command Name: {command.Name}");
_consoleSpec.WriteOutputToConsole($"Parameters: {_helpSpec.GetParametres(command)}");
_consoleSpec.WriteOutputToConsole($"Description: {_helpSpec.GetDescription(command)}");
_consoleSpec.WriteOutputToConsole($"Example: {_helpSpec.GetUsageExamples(command)}");
_consoleSpec.LineBreak();
}
}
_logger.LogSuccessMessage("Help section displayed in the console");
return "End of Help section.";
}
```
![Implied team talk.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/Department_Talk_Implied.png)
### When the Department's Teams Need to Speak to Each Other
```cs
class CoOrdinator
{
CoOrdinatorAssistant _assistant = new CoOrdinatorAssistant();
ProgramInfoSpecialist _progInfoSpec = new ProgramInfoSpecialist();
ConsoleIOSpecialist _consoleSpec = new ConsoleIOSpecialist();
CommandsSpecialist _commSpec = new CommandsSpecialist();
HelpSpecialist _helpSpec = new HelpSpecialist();
CW_Logger _logger = new CW_Logger();
// Some more code...
internal void DisplayProgramInfo()
{
// Check the parameter names being passed in with the class variables above.
_assistant.SetConsoleTitle(_logger, _progInfoSpec, _consoleSpec);
_assistant.OutputProgramInfo(_logger, _progInfoSpec, _consoleSpec);
}
}
```
![Actual team talk.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/Department_Talk_Detail.png)
Instead of working through example of code here, I recommend you run through the code with a debugger. The **entry point** is the **Liaison** class, with the most notable method being `RunProgram`.
Having said the above, I will point out one part of the codebase. It is the `RunProgram` method in `CoOrdinator`. I am point it out because this is what I consider to be the heart of Console.Waterworks flow.
It is, for intents and purposes, an infinite loop and what keeps the program running.
```cs
internal void RunProgram(string commandsNamespace)
{
var commandClasses = _commSpec.GetCommandClasses(commandsNamespace);
var commandLibraries = _commSpec.GetCommandLibraries(commandClasses);
while (true)
{
var consoleInput = _consoleSpec.GetInputFromUser();
if (string.IsNullOrEmpty(consoleInput)) continue;
try
{
var command = new Command(consoleInput, commandsNamespace, CW_Constants.COMMAND_CLASS_NAME);
var result = _commSpec.ExecuteCommand(commandsNamespace, command, commandClasses, commandLibraries, _consoleSpec);
_consoleSpec.WriteOutputToConsole(result);
}
catch (Exception ex)
{
_consoleSpec.WriteErrorMessage(ex.Message);
}
_consoleSpec.ResetConsoleColour();
}
}
```
Please note, I have removed the logging parts of the method in the actual code. The main functionality is still there, though.

5
The-Missing-Piece:-ConsoleCommands.cs.md
Unescape

@ -1,5 +0,0 @@
For Console.Waterworks to work, it needs the client to create a class called "ConsoleCommands.cs". This is very important because without it, Console.Waterworks is use to them (clients).
I tend to think of ConsoleCommands.cs like a (standardised) instruction manual. The client fills it out (to Console.Waterworks specifications) and hands it over to Console.Waterworks. This is so Console.Waterworks knows what to do when commands are passed to it at runtime. When it receives a command, it will pass the instructions on to the clients "business logic". It, then, awaits the "business logic’s" response so Console.Waterworks can pass it on to the console. (This is all happening at runtime).
![Flow with ConsoleCommands.cs.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/ConsoleCommands_Flow.png)

42
Things-to-Consider-for-Run-time.md
Unescape

@ -1,42 +0,0 @@
Here is a list of things I recommend you consider when writing console programs, using Console.Waterworks. What is list ed here is not essential reading but it will be useful for you to know -- or get round to knowing at some point.
## Naming Command-Methods
The name you give your command-methods is important. The reason why is because they are the commands your end-user will use. So, in effect they are your programs public API. On top of that, your command-methods are case-sensitive and must follow C#'s syntax. This means your methods can not have spaces or hyphens in them. You can negate this, though, by including underscores in their place. You can, also, adopt a casing style of your choice (E.G. Camel Case).
In the examples above, the commands I have written are clear but verbose. This is a useful tactic to use when helping new comers to your program. But, as your end-users settle into your program, they might like leaner commands. If this is the case, you can add alias' to the list of your command-methods. Unfortunately, this is not a strong point for Console.Waterworks. You can do it but it is more of a hack than a solution. Although, it is easy to do. To do it, write a command-method with the leaner syntax. Once you have done that, return the result from its verbose counterpart.
(Image: Show alias tactic - return from verbose method.
This is, also, a good time to mention the "help section" attributes. Because you need to declare what you want shown at run-time, you can reduce duplicate methods. (You can list verbose methods to help beginners or not.) The choice is yours.
## Using Parameters
The use of parameters in your command-methods is important from the end-user’s perspective. It allows them to pass data into your program. This is important because it expands the range of your programs capabilities. So, Console.Waterworks must treat input mechanisms with respect. This is why Console.Waterworks has tried to make it as easy as possible for end-users to enter data and for you to receive it. With that said, there are limitations on what Console.Waterworks can do in this regard. The first limitation is due to the nature of console programs. They are very text orientated. This means Console.Waterworks needs to coerce the input into a type .Net and C# understands. Which is why I have decided to keep things simple. Here is a list of data types Console.Waterworks can convert input in to:
1. String
1. Int16
1. Int32
1. Int64
1. Boolean
1. Byte
1. Char
1. DateTime
1. Decimal
1. Double
1. Single
1. UInt16
1. UInt64
If you need thigs like arrays or dictionaries, you will need to build them yourself. And, you will need to build them using the data types listed above.
Here is usually where you will determine in Console.Waterworks is the right tool for the job. I cannot stress enough the importance of the list above. For the most part, I would argue the types on the list will suffice. But, the moment they are not, it is okay to leave Console.Waterworks in the toolbox. It is not going to solve every problem and that is okay.
Of all the input types, strings have an interesting quirk. Console.Waterworks has the ability to parse a string without quotes. But, it can only do that if it has no spaces in it. If the end-user fails to wrap the sentence in double quotes, Console.Waterworks will display an error. So, it is important you relay that information to your end-users if they need to know this. The reason why I included this feature is because I find it cumbersome when passing in one word strings. This happened a lot during development.
![String input variations.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/String_Input.gif)
If you are wondering if you can use null in your parameter list, the answer is no. The reason why is because Console.Waterworks cannot interpret intent, in this regard. It does not know if the end-user left a parameter input out on purpose or not. I am confident I could add a feature like this but I will be honest; I have no intention of adding this feature. The reason why is because Console.Waterworks was not made to solve every problem. I made it to reduce the amount of code I usually write for small and general purpose programs. If you need something as exact as this, you do have a few options. The first one is write several command-methods with different parameter requirements. In other words, you can do some method overloading. The second is to accept the range of Console.Waterworks and write command-methods which do not need nulls. And, the last one is write a console program without Console.Waterworks.
## Outputting Data to the Console
For the most part, Console.Waterworks would like to take this part of the process off your hands. The reason why is because it frees you up to focus on writing the code which solves your problem. Displaying data in the console is a formality after the fact. You cannot display data if you do not have it. With that said, Console.Waterworks does not stop you from writing something to the console. If you want to write something to the console in the middle of a method, feel free to do so. The only restriction is you must return a string at the end of your command-method. That does not mean the string must contain anything in it. Console.Waterworks is okay with you returning an empty string. Which leads me on to my next point. if you do find yourself returning empty string, do not worry. This does not mean you are using Console.Waterworks wrong.

45
Using-the-"Help-Attributes".md
Unescape

@ -1,45 +0,0 @@
This feature is built on top of the [Attributes](https://msdn.microsoft.com/en-us/library/system.attribute(v=vs.110).aspx) feature in Microsoft's .Net Framework. Please use the link provided if you are unfamiliar with them.
For a command-method to appear in the "Help Section", you need to decorate it with attributes. The ones you will use are called ```ListCommand```, ```Description```, ```Parameters``` and ```Usage```. To use these attributes, make sure you have ```using Console.Waterworks.Attributes;``` included in ```ConsoleCommands.cs```.
When decorating a command-method, it should something link this,
```cs
using Console.Waterworks;
using Console.Waterworks.Attributes;
using System;
namespace CW_Console
{
public class ConsoleCommands
{
[ListCommand()]
[Description("Repeats back to the user the string they entered.")]
[Parameters("<string> input")]
[Usage("CW_Console> Say \"Hello, World.\"")]
public static string Say(string input)
{
// Enter some code here if you want....
return $"{input}";
}
}
}
```
See [Console.Waterworks Code Example (in Full)](https://github.com/CraigOates/Console.Waterworks/wiki/Console.Waterworks-Code-Example-(in-Full)) for further information.
## Tip
When developing, pass "false" in to ```ListCommand()``` to remove that command-method from showing up in the "help Section" at run-time. It will stop you from having to comment and uncomment all the time... or delete and re-write. When you are ready to put in back in, just remove the ```false``` parameter.
```cs
[ListCommand(false)]
[Description("Repeats back to the user the string they entered.")]
[Parameters("<string> input")]
[Usage("CW_Console> Say \"Hello, World.\"")]
public static string Say(string input)
{
// This command-method will not show up in the "Help Section" at run-time.
return $"{input}";
}
```

57
Wire-Console.Waterworks-into-Your-Program.md
Unescape

@ -1,57 +0,0 @@
To save time, I will assume you know how to setup a console program project, using .NetFramework 4.7+ (in Visual Studio 2017).
The first thing you need to do is create a class called `ConsoleCommands`. It does not matter where you put it, as long as it is in the same project. What does matter, though, is its namespace. Once you have created `ConsoleCommands`, copy its namespace, to the clipboard, and head back to the `Main` method. Within its curly braces, enter the following lines of code,
```cs
var liaison = new CW_Liaison();
liaison.Run("ENTER NAMESPACE HERE", true);
```
Tip: Pass "true" as a parameter when using the `Run` method. It will make Console.Waterworks output general program information about your program. It grabs the information from the assembly information file.
## Pass "true" into "Run"
![When "true" is passed as a parameter into Run.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/True_At_RunTime.JPG)
## Pass "false" into "Run"
![When "false" is passed into Run.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/False_At_RunTime.JPG)
Congratulations, you have successfully setup Console.Waterworks. From here on out, your play area will be in `ConsoleCommands`.
In `ConsoleCommands` make sure you label the class as `public`. Once you have done that, you can begin writing commands-methods.
## Program.cs
```cs
using Console.Waterworks;
namespace CW_Console
{
class Program
{
static void Main(string[] args)
{
CW_Liaison liaison = new CW_Liaison();
liaison.Run("CW_Console", true);
// That is it. You are done here.
// Head over to ConsoleCommands.cs to begin adding features...
}
}
}
```
## ConsoleCommands.cs
```cs
using Console.Waterworks;
using Console.Waterworks.Attributes;
using System;
namespace CW_Console
{
public class ConsoleCommands
{
// You can start writing command-methods in here...
}
}
```

61
Writing-Command-Methods.md
Unescape

@ -1,61 +0,0 @@
Before continuing, I would like to stress a "command-method" is just a regular C# method. The reason I have concocted this term is to help separate certain methods from others. The most notable **methods** are the ones which mimic the **commands** the end-user will enter at run-time -- hence **command-method** Another way to think of them is like a controller in MVC based websites.
When it comes to writing command-methods, there is a structure each one must follow. You must label each command-method as ```public``` and ```static``` and you must make sure it returns a ```string```. As long as you adhere to this structure when you write you command-methods, you can do whatever you want in them. With that said, I would like to point out how loose the "must return a string" rule is. First of all, feel free to output information to the console at any time. Console.Waterworks does not rob you of that ability. If you need to output something to the console before the method has finished executing, then go for it. On top of that, Console.Waterworks can handle empty strings if that is what you want to return. Of course, this will feel like you are using Console.Waterworks wrong. But, if this is what your method requires then do it. Console.Waterworks is an aid and nothing more.
The reason command-methods need to return a string is due to a default behaviour. Console.Waterworks wants to handle as much of the "plumbing code" as possible. This is so you can get on with solving the actual problem you are wanting to solve.
**Command-methods can only be used in ```ConsoleCommands.cs```.**
Here is an example of how your ```Main``` method and ```ConsoleCommands``` class should look.
```cs
using Console.Waterworks;
namespace CW_Console
{
class Program
{
static void Main(string[] args)
{
CW_Liaison liaison = new CW_Liaison();
liaison.Run("CW_Console", true);
// That is it. You are done here.
// Head over to ConsoleCommands.cs to begin adding features...
}
}
}
```
## ConsoleCommands.cs
```cs
using Console.Waterworks;
using Console.Waterworks.Attributes;
using System;
namespace CW_Console
{
public class ConsoleCommands
{
public static string CommandMethod1()
{
// Your code goes in here...
return "CW_Console is working.";
}
public static string CommandMethod2(string name)
{
// Your code goes in here...
return $"Hello, {name}.";
}
void DoSomething()
{
// This is not a command-method
var x = 56 + 24;
}
}
}
```
![Commands mirroring methods at run-time.](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/Command_Mirroring_At_RunTime.gif)

1
_Footer.md
Unescape

@ -1 +0,0 @@
Web: [craigoates.net](http://www.craigoates.net, "Craig's website") | Email: craig@craigoates.net | Project: [http://craigsappshed.azurewebsites.net/Waterworks](http://craigsappshed.azurewebsites.net/Waterworks, "CW's home site")

36
_Sidebar.md
Unescape

@ -1,36 +0,0 @@
# ![Sidebar Logo](https://github.com/CraigOates/Console.Waterworks/blob/master/Documentation/GitHub_Assets/Sidebar_Logo.png)
## Console.Waterworks
- [Home](https://github.com/CraigOates/Console.Waterworks/wiki)
- [Preface](https://github.com/CraigOates/Console.Waterworks/wiki/Preface)
- [Introduction](https://github.com/CraigOates/Console.Waterworks/wiki/Introduction)
## As a Nuget Package
### Setting Up
- [Adding Console.Waterworks to Your Project](https://github.com/CraigOates/Console.Waterworks/wiki/Adding-Console.Waterworks-to-Your-Project)
- [Wire Console.Waterworks into Your Program](https://github.com/CraigOates/Console.Waterworks/wiki/Wire-Console.Waterworks-into-Your-Program)
- [Writing Command-Methods](https://github.com/CraigOates/Console.Waterworks/wiki/Writing-Command-Methods)
### Creating a "Help Section"
- [Setting up the "Help Section"](https://github.com/CraigOates/Console.Waterworks/wiki/Setting-up-the-%22Help-Section%22)
- [The "Help" Attributes](https://github.com/CraigOates/Console.Waterworks/wiki/The-%22Help%22-Attributes)
- [Using the "Help" Attributes](https://github.com/CraigOates/Console.Waterworks/wiki/Using-the-%22Help-Attributes%22)
### Useful References
- [Console.Waterworks Code Example (in Full)](https://github.com/CraigOates/Console.Waterworks/wiki/Console.Waterworks-Code-Example-(in-Full))
- [Things to Consider for Run-time](https://github.com/CraigOates/Console.Waterworks/wiki/Things-to-Consider-for-Run-time)
- [Example Projects](https://github.com/CraigOates/Console.Waterworks/wiki/Example-Projects)
## Architecture
- [Architecture Overview](https://github.com/CraigOates/Console.Waterworks/wiki/Architecture-Overview)
- [Department Breakdown: Teams](https://github.com/CraigOates/Console.Waterworks/wiki/Department-Breakdown:-Teams)
- [Coercion Types List](https://github.com/CraigOates/Console.Waterworks/wiki/Coercion-Types-List)
- [The Flow of the System](https://github.com/CraigOates/Console.Waterworks/wiki/The-Flow-of-the-System)
- [The Missing Piece: ConsoleCommands.cs](https://github.com/CraigOates/Console.Waterworks/wiki/The-Missing-Piece:-ConsoleCommands.cs)
- [Recommendations for Altering Console.Waterworks](https://github.com/CraigOates/Console.Waterworks/wiki/Recommendations-for-Those-Wanting-to-Alter-Console.Waterworks)
Write Preview
Loading…
Cancel
Save