diff --git a/Home.md b/Home.md index a7a817a..511bdb9 100644 --- a/Home.md +++ b/Home.md @@ -58,6 +58,7 @@ Before continuing, I recommend you are familiar with the following; #### DeathSocketCLI - [C.L.I. Project Breakdown](CLI-Project-Breakdown) +- [The C.L.I's Flow](The-CLIs-Flow.md) - [Changing the C.L.I. Icon](Changing-the-CLI-Icon) #### TestCentre diff --git a/The-CLIs-Flow.md b/The-CLIs-Flow.md new file mode 100644 index 0000000..0743a12 --- /dev/null +++ b/The-CLIs-Flow.md @@ -0,0 +1,57 @@ +To help you get up to speed on the way DeathSocketCLI works, please consider the following diagram. + +CLI FLOW DIAGRAM. + +The way it works is as follows; + +1. The console receives input from the end-user. +2. The console parses the input and matches it with a "command-method" in "ConsoleCommands.fs". +3. The command-method executes its task and returns its result to the console. + +That's the simple version at least. + +**Note/Aside:** "Command-method" is a term used within C.W. A "command-method" is a method which resides in the `ConsoleCommands` class and is accessible to the end-user at run-time. From a technical point-of-view, they are no different from a normal method/function. I am aware F# uses functions by default but I will continue to use "command-method". This is so I remain consistent with C.W's terminology. I know it's not great but it is what it is. + +The reason the program runs this way is because I built it on top off Console.Waterworks (C.W.). I will not go into too much detail about how C.W. works here because it is out of scope for this wiki. Instead, I will provide links to its repository and wiki. Which are: + +- [Console.Waterworks Repository](https://gitlab.com/craig.oates/Console.Waterworks) +- [Console.Waterworks Wiki](https://gitlab.com/craig.oates/Console.Waterworks/wikis/home) +- [Console.Waterworks.Core Repository](https://gitlab.com/craig.oates/Console.Waterworks.Core) +- [Console.Waterworks.Core Wiki](https://gitlab.com/craig.oates/Console.Waterworks.Core/wikis/home) + +At a basic level, C.W. is a NuGet package which helps you write console programs. **From a distance**, C.W. programs look **a bit like** MVC programs. To help explain, here is a diagram of C.W's basic structure/flow. + +IMAGE OF C.W'S FLOW. + +For C.W. to operate the way it does, it needs to rely on certain things. Which are as follows; + +1. It controls the input-loop from within `main`, in "Program.fs. +2. There is a `ConsoleCommands` module/ (C#) class within the project. +3. The ` ConsoleCommands` module/(C#) class must live in a name-space. +4. The `ConsoleCommands` module/(C#) class is public. +5. The functions/(C#) methods the end-user can use at run-time are marked as `public`, `static` and live in `ConsoleCommands`. + +As an aside... + +I wrote C.W. with C# and without F# in mind. (I did not know any F# at the time either.) Because of that, some of the code in DeathSocketCLI might look a little "off" -- catering to some C# requirements. The most obvious one is the methods in `ConsoleCommands` must be `static`. This is something you should not notice because F# does not have an explicit notion of `static` methods in its modules -- like C#. + +If you would like to know more about utilising C.W. in an F#-only context, head over to another repository of mine. Its name is Brittle Fish and it is a tutorial/reference repository for F# developers wanting to use C.W.. One of its main strengths is it points out potential pitfalls you might run into when using C.W. with F#. This is useful because C.W. makes no reservations for F#. So, knowing where and why you might need to alter your idiomatic F# code should help reduce bugs and frustration levels. The links for Brittle Fish are as follows; + +- [Brittle Fish Repository](https://gitlab.com/craig.oates/Brittle-Fish) +- [Brittle Fish Wiki](https://gitlab.com/craig.oates/Brittle-Fish/wikis/home) + +End of aside. + +FLOW OF THE THREE MAIN FILES. + +When you start working with the code base, I recommend you stick to "ConsoleCommands.fs", "Programs.fs" and "Validation.fs". Although, that should quickly drop to "ConsoleCommands.fs" and "Validation.fs". This is because you will not need to work/alter anything in "Program.fs" when you understand what it is doing. + +How the three files work together are as follows; + +1. The `main` function in "Program.fs" creates an input-loop at run-time. This allows the end-user to enter commands. +2. The input entered with the command is parsed and passed to the appropriate command-method in "ConsoleCommands.fs". +3. Because C.W. does not provide context-specific checks, the command-method passes the input to "Validation.fs". +4. If the input is valid, the command-method proceeds and completes its task. +5. When completed, the command-method returns a message to the console. + +It is worth pointing out the `Validation` module provides "helper" functions alongside it validation ones. This is because the program, as a whole, is not that big. It seemed/seems pointless to "over-engineer" the solution. So, for now, some "helper" functions sitting next to validation functions is okay. Although, that means "Validation.fs" will need refactoring if the project's features grow in size/complexity. diff --git a/_sidebar.md b/_sidebar.md index f2016ae..3cee3ce 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -15,6 +15,7 @@ #### DeathSocketCLI - [C.L.I. Project Breakdown](CLI-Project-Breakdown) +- [The C.L.I's Flow](The-CLIs-Flow.md) - [Changing the C.L.I. Icon](Changing-the-CLI-Icon) #### TestCentre