add Command-Methods Overview page.

master
Craig Oates 5 years ago
parent
commit
58fa324da6
  1. 64
      Command-Methods-Overview.md

64
Command-Methods-Overview.md

@ -0,0 +1,64 @@
Without going into too much detail, a "command-method" is a function within the `ConsoleCommands` module. The name "command-method" is inaccurate here but I have used it to remain consistent with Console.Waterworks' (C.W.) terminology. If you would like to know more about command-methods, I recommend you read the following wiki entry;
- [C.W. wiki command-method](https://gitlab.com/craig.oates/Console.Waterworks/wikis/Writing-Command-Methods)
For command-methods to work properly, there are several things they need. Which are as follows;
1. There is a module called `ConsoleCommands` in the project.
2. The module must live in a name-space. (The module is this project resides in `Commands`.)
3. `ConsoleCommands` must reference the `Console.Waterworks` name-space (I.E. `open Console.Waterworks`).
4. If you are using C.W's "help" attributes, you must reference the `Console.Waterworks.Attributes` name-space.
5. Command-methods must be a function (I.E. include unit/`()` in their declaration).
Please note, this list is not complete. But, the extra stuff is more to do with using C.W. in a C# project so it is not relevant here. If you would like to know more about using C.W. with F# and how it differs from using it with C#, checkout the following link;
- [Brittle Fish Repository](https://gitlab.com/craig.oates/Brittle-Fish)
Having got the above out of the way, here is a couple of command-method example to help you get a feel for how they look. (Each on includes the "help" attributes.)
```f#
[<ListCommand>]
[<Parameters "(image-width: int) (image-height: int)" >]
[<Description
("Saves an image to the desktop, using the default setting.\n" +
"The user must specify the width and the height of the image.")>]
[<Usage "draw-default 500 500">]
let ``draw-default`` imgWidth imgHeight =
try
buildDefaultSpec imgWidth imgHeight
|> makeImage
|> Async.RunSynchronously
showEndOfCommandMessage // This is what is returned.
with
| :? ArgumentException as ex -> ex.Message
| _ as ex -> ex.Message
[<ListCommand>]
[<Parameters "None">]
[<Description "Lists out the colours this program uses to draw its images.">]
[<Usage "list-colours">]
let ``list-colours`` () =
printfn "[INFO.] Listing available colours..."
for item in colourList do
printfn "%s" item.Key
showEndOfCommandMessage // This is what is returned.
```
To help explain what the above code does, please consider the following image;
IMAGE OF COMMAND-METHOD BREAKDOWN
It is not essential to include the help attributes but they do provide help for the end-user and future developers. For more information about the help attributes, please use the following links;
- [Console.Waterworks Wiki](https://gitlab.com/craig.oates/Console.Waterworks)
- [Brittle Fish Wiki](https://gitlab.com/craig.oates/Brittle-Fish/wikis/home)
The name of the command-method is what the end-user must enter into the console. If the command-method requires input arguments, the end-user must provide them, as well. For example, please consider the following image;
SCREENSHOT OF C-M MATCHING CONSOLE INPUT
If all has gone well, you should be able to work your way through "Commands.fs" and understand it. With that said, you will come across functions which appear to have no explanation for where/why they exist. If you dig around a little bit, you will notice these functions are either situated in "Validation.fs" or the .Net Standard library (I.E. "DeathSocket"). Use the following links for more information;
- [Commands.fs](https://gitlab.com/craig.oates/Death-Socket/blob/master/DeathSocketCLI/Commands.fs)
- [Validation.fs](https://gitlab.com/craig.oates/Death-Socket/blob/master/DeathSocketCLI/Validation.fs)
- [GridPainter.fs (DeathSocket)](https://gitlab.com/craig.oates/Death-Socket/blob/master/DeathSocket/GridPainter.fs)
- [Console(Commands) A.P.I. (As C.L.I. section)](https://gitlab.com/craig.oates/Death-Socket/wikis/Console-API)
Loading…
Cancel
Save