craig.oates
/
death-socket
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

master
Craig Oates 4 years ago
parent
37361a16d2
commit
f620ec073b
1 changed files with 57 additions and 57 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. 114
      The-CLIs-Flow.md

114
The-CLIs-Flow.md
Unescape

@ -1,57 +1,57 @@
To help you get up to speed on the way DeathSocketCLI works, please consider the following diagram.
![deathsocketcli general flow](deathsocketcli-general-flow.png)
The way it works is as follows:
1. The console receives input from the end-user.
2. The console parses the input, via the Console.Waterworks (C.W.) NuGet, and matches it with a "command-method" in "Commands.fs".
3. The command-method executes its task -- by calling out to DeathSocket -- 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 (module in our case) 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 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://git.abbether.net/craig.oates/Console.Waterworks)
- [Console.Waterworks Wiki](https://git.abbether.net/craig.oates/Console.Waterworks/wikis/home)
- [Console.Waterworks.Core Repository](https://git.abbether.net/craig.oates/Console.Waterworks.Core) (This is the .Net Core version.)
- [Console.Waterworks.Core Wiki](https://git.abbether.net/craig.oates/Console.Waterworks.Core/wikis/home) (The .Net Core version operates the same way as the traditional .Net one. So, this wiki is not as comprehensive and mostly serves as a place to set-up the .Net Core version of C.W.)
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** Model-View-Controller (M.V.C.) programs. To help explain, here is a diagram of C.W's basic structure/flow.
![console.waterworks data flow](console.waterworks-data-flow.png)
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" -- as it is 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://git.abbether.net/craig.oates/Brittle-Fish)
- [Brittle Fish Wiki](https://git.abbether.net/craig.oates/Brittle-Fish/wikis/home)
End of aside.
![deathsocketcli file flow](deathsocketcli-file-flow.png)
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 "Commands.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.
To help you get up to speed on the way DeathSocketCLI works, please consider the following diagram.
![deathsocketcli general flow](deathsocketcli-general-flow.png)
The way it works is as follows:
1. The console receives input from the end-user.
2. The console parses the input, via the Console.Waterworks (C.W.) NuGet, and matches it with a "command-method" in "Commands.fs".
3. The command-method executes its task -- by calling out to DeathSocket -- 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 (module in our case) 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 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://git.abbether.net/craig.oates/Console.Waterworks)
- [Console.Waterworks Wiki](https://git.abbether.net/craig.oates/Console.Waterworks/wiki)
- [Console.Waterworks.Core Repository](https://git.abbether.net/craig.oates/Console.Waterworks.Core) (This is the .Net Core version.)
- [Console.Waterworks.Core Wiki](https://git.abbether.net/craig.oates/Console.Waterworks.Core/wiki) (The .Net Core version operates the same way as the traditional .Net one. So, this wiki is not as comprehensive and mostly serves as a place to set-up the .Net Core version of C.W.)
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** Model-View-Controller (M.V.C.) programs. To help explain, here is a diagram of C.W's basic structure/flow.
![console.waterworks data flow](console.waterworks-data-flow.png)
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" -- as it is 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://git.abbether.net/craig.oates/Brittle-Fish)
- [Brittle Fish Wiki](https://git.abbether.net/craig.oates/Brittle-Fish/wiki)
End of aside.
![deathsocketcli file flow](deathsocketcli-file-flow.png)
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 "Commands.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.

Write Preview
Loading…
Cancel
Save