@ -5,7 +5,7 @@ Because Death Socket (D.S.) is a .Net Standard 2.0 library, you can use it in tr
Install-Package DeathSocket -Version 1.0
```
If you are using Visual Studio, you can search for and add it to your project using its built-in NuGet Package Manager. When searching for it, enter "DeathSocket" and you should see something like the following;
If you are using Visual Studio, you can search for and add it to your project using its built-in NuGet Package Manager. When searching for it, enter "DeathSocket" and you should see something like the following:
Up above, I said "resources.res" is not a "normal" file and would come back to it. The reason why is because it is a "system" file, like the ".fsproj" one, but it is not created by Visual Studio like the other system/configuration files. If anything, you have to go out of your way to make it and add it to your project. The reason it is here is because F# console programs do not cater to adding/registering an icon that well (like C#). So, it is essentially doing that -- and nothing else. (It is capable of doing other things but we don't need them.) You should not need to open the file because an icon already exists and I have already connected it. There are other things .res files can do but they are not used here. If you would like to know more about .res files, please use the links below. I should point out, though, .res files require a separate compile from the main project. It, also, needs the C++ tools bundled with Visual Studio -- which you might not have installed. So, unless I am unaware of an easier way, I do not recommend you faff around with "resources.res" or "logo.ico". The links for working with .res files are as follows;
Up above, I said "resources.res" is not a "normal" file and would come back to it. The reason why is because it is a "system" file, like the ".fsproj" one, but it is not created by Visual Studio like the other system/configuration files. If anything, you have to go out of your way to make it and add it to your project. The reason it is here is because F# console programs do not cater to adding/registering an icon that well (like C#). So, it is essentially doing that -- and nothing else. (It is capable of doing other things but we don't need them.) You should not need to open the file because an icon already exists and I have already connected it. There are other things .res files can do but they are not used here. If you would like to know more about .res files, please use the links below. I should point out, though, .res files require a separate compile from the main project. It, also, needs the C++ tools bundled with Visual Studio -- which you might not have installed. So, unless I am unaware of an easier way, I do not recommend you faff around with "resources.res" or "logo.ico". The links for working with .res files are as follows:
- [A link to the Stack Overflow question I found which got me started on my path to icon-including enlightenment](https://stackoverflow.com/questions/26841947/changing-f-application-icon)
This is the third of the main three files you will work -- within this (CLI) project. At this moment in time, "Validation.fs" provides too many features. It handles the validation logic, as the name implies, and houses all the "helper" functions. Because the program is rather small, it seemed like overkill to fragment the code too much. So, for now, the "helper" functions will remain in "Validation.fs". If the project's feature-set grows, this file will need refactoring. Until then, the code will stay as it is.
The type of validation this file provides is **complimentary** to what Console.Waterworks (C.W.) provides. To help explain, consider the following;
The type of validation this file provides is **complimentary** to what Console.Waterworks (C.W.) provides. To help explain, consider the following:
> A command-method takes a `string` which indicates a save-path. C.W. checks the input type is a `string` and "Validate.fs" makes sure the path is valid/accessible.
The reason why is because C.W. does the type checking automatically. So, it seems foolish not to use it.
If you would like to know more about how C.W. performs its validation checks, please use the following links;
If you would like to know more about how C.W. performs its validation checks, please use the following links:
- [Console.Waterworks -- Coercion Type List](https://gitlab.com/craig.oates/Console.Waterworks/wikis/Coercion-Types-List)
- [Brittle Fish Wiki -- Writing Command-Methods in F#](https://gitlab.com/craig.oates/Brittle-Fish/wikis/Writing-Command-Methods-in-F%23) (provides specific information for F# projects)
Instead of copying and pasting the code from "Validation.fs" into this page, I recommend reading the actual file yourself. You can view it using the following link;
Instead of copying and pasting the code from "Validation.fs" into this page, I recommend reading the actual file yourself. You can view it using the following link:
As you work your way through the file, try keeping the relationship between "Validation.fs" and "ConsoleCommands.fs" in mind. Everything in "Validation.fs" aids "ConsoleCommands.fs" and nothing else.
As a general rule, "Validation.fs" consists of three "sections". They are as follows;
As a general rule, "Validation.fs" consists of three "sections". They are as follows:
1. Creating an "image specification" (E.G. `BrushSpec`)
@ -25,7 +25,7 @@ As a general rule, "Validation.fs" consists of three "sections". They are as fol
It is worth pointing out two and three reflect the nature of console programs (I.E. text based). Also, I limited the `colourList` and `skiaColourList` as a way to keep things simple. The console does not provide a way for the end-user to look at the colour before confirming it. And, people tend to find remembering "blue" a lot easier than `#068BEC`. Having said that, the main (NuGet) library, allows you to specify your colours using RGB values. So, you can do that if/when you hook it up to a GUI if you want.
If you have not viewed the code in "Validation.fs", here a quick look at the available colours users can use with the C.L.I.;
If you have not viewed the code in "Validation.fs", here a quick look at the available colours users can use with the C.L.I.:
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;
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:
- [Console.Waterworks Wiki -- Writing Command-Methods](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;
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`.)
@ -10,7 +10,7 @@ For command-methods to work properly, there are several things they need. Which
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;
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)
@ -43,20 +43,20 @@ let ``list-colours`` () =
printfn "%s" item.Key
showEndOfCommandMessage // This is what is returned.
```
To help explain what the above code does, please consider the following image;
To help explain what the above code does, please consider the following image:
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;
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 -- Using the "Help Attributes"](https://gitlab.com/craig.oates/Console.Waterworks/wikis/Using-the-%22Help-Attributes%22)
- [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;
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:
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;
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:
That snippet of code is all what is in "Program.fs". Once you know what is happening in here, you should never need to look at this file much -- if at all.
What is happening is a new `CW_Liaison` object is created and is told to `run`. This is where C.W. creates the input-loop which runs indefinitely until the end-user closes the console (or the program crashes). The first argument passed into `run` refers to the name-space of the `ConsoleCommands` module. In this case, it is `Commands`. The second one refers to the information displayed in the console when you run it. When set to `true`, the console displays information found in "AssemblyInfo.fs". If you use `false`, the only thing you will see is the prompt. You can check the code and the name-space of the `ConsoleCommands` module via the following link;
What is happening is a new `CW_Liaison` object is created and is told to `run`. This is where C.W. creates the input-loop which runs indefinitely until the end-user closes the console (or the program crashes). The first argument passed into `run` refers to the name-space of the `ConsoleCommands` module. In this case, it is `Commands`. The second one refers to the information displayed in the console when you run it. When set to `true`, the console displays information found in "AssemblyInfo.fs". If you use `false`, the only thing you will see is the prompt. You can check the code and the name-space of the `ConsoleCommands` module via the following link:
Up above, I said I would elaborate on why the end-user's commands must match the name of the commands in the `ConsoleCommands` module. I will do that but not here because it ventures a little too far off topic for this section. So, I have created a dedicated section for it. You can access it with the following link;
Up above, I said I would elaborate on why the end-user's commands must match the name of the commands in the `ConsoleCommands` module. I will do that but not here because it ventures a little too far off topic for this section. So, I have created a dedicated section for it. You can access it with the following link:
This section focuses on the source code within the project called "DeathSocket". This is the .Net Standard 2.0 library which provides users with a way to add a grid overlay onto images. If you would like to know more about the other projects, please use the following links;
This section focuses on the source code within the project called "DeathSocket". This is the .Net Standard 2.0 library which provides users with a way to add a grid overlay onto images. If you would like to know more about the other projects, please use the following links:
This section focuses on the source code within the project called "DeathSocketCLI". This is the console project which provides users with a way to uses the features in "DeathSocket" without the need to write code. If you would like to know more about the other projects, please use the following links;
This section focuses on the source code within the project called "DeathSocketCLI". This is the console project which provides users with a way to uses the features in "DeathSocket" without the need to write code. If you would like to know more about the other projects, please use the following links:
- [DeathSocket](https://gitlab.com/craig.oates/Death-Socket/wikis/DeathSocket-Home) (.Net Standard 2.0 library)
@ -27,7 +27,7 @@ This file deals with converting/creating `Colors` and `Brushes` which are used t
There are no functions for the *SkiaSharp* part of the library because it does not have a notion of `Brushes` like `System.Drawing`. So, I have found little need to add any functions for this part of library in here.
If you are unfamiliar with either *System.Drawing* or *SkiaSharp*, please use the following links;
If you are unfamiliar with either *System.Drawing* or *SkiaSharp*, please use the following links:
@ -54,7 +54,7 @@ This file provides functions which aids the functions in "ImageServices.fs". Wit
This file focuses on creating and saving the new image, with its grid. You will see **a** lot of duplicated code in here but do not worry too much. There are comments within the file explaining the rationale behind it. The short version why is to reduce the memory footprint of the library at run-time. I decided to solve this by utilising the `use` keyword. This means I do not need to manually dispose of images which reduces the chances of memory leaks. The result of this is duplicated but self-contained (I.E. function bound/scoped) code.
If you are unsure what the `use` keyword does, please you the following link for more information;
If you are unsure what the `use` keyword does, please you the following link for more information:
This section is for those wanting to use Death Socket's features in their project. If you are more interested in using the features without writing any code, head over to the "As a CLI" section. If you want to add new features or improve existing ones to Death Socket, head over to the "As Source Code" section. The links to these sections are as follows;
This section is for those wanting to use Death Socket's features in their project. If you are more interested in using the features without writing any code, head over to the "As a CLI" section. If you want to add new features or improve existing ones to Death Socket, head over to the "As Source Code" section. The links to these sections are as follows:
- ["As Source Code" section](Source-Code-Home) (if you want to add/change features to the code in the repository)
- ["As a Command Line Interface" section](CLI-Home) (if you want to use the console program which comes with this repository)
Within TestCentre, you will see a collection of property and unit tests. Each type of test uses their own testing library. I have used xUnit for the unit tests and FsCheck for the property tests. If you are unfamiliar with either of these libraries. please use the following links;
Within TestCentre, you will see a collection of property and unit tests. Each type of test uses their own testing library. I have used xUnit for the unit tests and FsCheck for the property tests. If you are unfamiliar with either of these libraries. please use the following links:
- [xUnit](https://xunit.net/)
- [FsCheck](https://fscheck.github.io/FsCheck/)
It is worth pointing out, TestCentre uses xUnit's Test Runner for Visual Studio. This means you can use Visual Studio's Test Explorer -- which show you the project's (unit and property) tests with a G.U.I. If you are unsure what the Test Runner is, here is a screenshot of what it looks like;
It is worth pointing out, TestCentre uses xUnit's Test Runner for Visual Studio. This means you can use Visual Studio's Test Explorer -- which show you the project's (unit and property) tests with a G.U.I. If you are unsure what the Test Runner is, here is a screenshot of what it looks like:
As you can see, it is a good way to determine what tests are passing and failing. On top of that, it highlights how the tests are organised within TestCentre.
For more information about Visual Studio's Test Explorer, use the following link;
For more information about Visual Studio's Test Explorer, use the following link:
- [Visual Studio's Test Explorer Overview](https://docs.microsoft.com/en-us/visualstudio/test/run-unit-tests-with-test-explorer?view=vs-2019)
The code-base in this repository is a typical Visual Studio solution. Within the solution is three projects which are as follows;
The code-base in this repository is a typical Visual Studio solution. Within the solution is three projects which are as follows:
- a .Net Standard 2.0 library (F#);
- a .Net console program (F#); and
- a .Net 4.7 library (for testing and written in F#).
The solution's main project is the .Net Standard library, called "DeathSocket". This is where you will most likely want to start your exploration into the code-base. The other two projects are secondary but important parts of the solution. There project names are "DeathSocketCLI" (the console program) and "TestCentre" (the testing library). To help you grasp how they all fit together, please consider the following diagram;
The solution's main project is the .Net Standard library, called "DeathSocket". This is where you will most likely want to start your exploration into the code-base. The other two projects are secondary but important parts of the solution. There project names are "DeathSocketCLI" (the console program) and "TestCentre" (the testing library). To help you grasp how they all fit together, please consider the following diagram:
The console program provides a way for people to use the features in DeathSocket without them needing to write code. The testing library is as the name implies: the place where the unit and property tests for the .Net Standard library and the console program reside. To see how each project is referenced, please view the following diagram;
The console program provides a way for people to use the features in DeathSocket without them needing to write code. The testing library is as the name implies: the place where the unit and property tests for the .Net Standard library and the console program reside. To see how each project is referenced, please view the following diagram:
The reason "ScratchPad.fsx" exists is to provide a way for you to interact with the code via F# Interactive (FSI). If you are new to the project, this is a good place to start. All the code within here has comments to help signify what it is doing or which part of the library it is using. So, I will avoid going through each line of code here and provide a link to the actual file for you. If you are unsure what F# Interactive is or how to use it, I have provided a link for that, also. They are as follows;
The reason "ScratchPad.fsx" exists is to provide a way for you to interact with the code via F# Interactive (FSI). If you are new to the project, this is a good place to start. All the code within here has comments to help signify what it is doing or which part of the library it is using. So, I will avoid going through each line of code here and provide a link to the actual file for you. If you are unsure what F# Interactive is or how to use it, I have provided a link for that, also. They are as follows:
This section is for those wanting to work with the repository's source code. If you are more interested in using Death Socket's features via NuGet or the CLI, use the following links;
This section is for those wanting to work with the repository's source code. If you are more interested in using Death Socket's features via NuGet or the CLI, use the following links:
- ["As a Command Line Interface" section](CLI-Home) (if you want to use the console program which comes with this repository)
- [“As a NuGet” section](NuGet-Home) (if you want to add
This section focuses on the source code within the project called "Test Centre". As the name implies, this project houses the unit and property tests for the other two projects. If you would like to know more about the other projects, please use the following links;
This section focuses on the source code within the project called "Test Centre". As the name implies, this project houses the unit and property tests for the other two projects. If you would like to know more about the other projects, please use the following links:
- [DeathSocket](DeathSocket-Home) (.Net Standard 2.0 library)
@ -16,7 +16,7 @@ As stated above, there is a script file called "Script.fsx" included in TestCent
If you find any of your tests failing, cross-reference the names of the failing tests with any of the functions in "Script.fsx" to see if they can help. The most likely one is `createSavingTestArea`.
If you are unfamiliar with using F# scripts and F# Interactive (FSI), please use the following links;
If you are unfamiliar with using F# scripts and F# Interactive (FSI), please use the following links:
- [Scripting with F#](https://fsharpforfunandprofit.com/installing-and-using/) (it's a little dated but it contains enough information to get you going)
@ -2,7 +2,7 @@ To help you get up to speed on the way DeathSocketCLI works, please consider the
The way it works is as follows;
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".
@ -23,7 +23,7 @@ At a basic level, C.W. is a NuGet package which helps you write console programs
For C.W. to operate the way it does, it needs to rely on certain things. Which are as follows;
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.
@ -35,7 +35,7 @@ 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;
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)
@ -46,7 +46,7 @@ End of aside.
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;
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".
For a more real-world example (with extra cruft), please read the `add-grid` function in "Commands.fs". This file is part of the DeathSocketCLI project and the link for it is as follows;
For a more real-world example (with extra cruft), please read the `add-grid` function in "Commands.fs". This file is part of the DeathSocketCLI project and the link for it is as follows:
- [ Add-Grid example in Commands.fs](https://gitlab.com/craig.oates/Death-Socket/blob/master/DeathSocketCLI/Commands.fs)
**Note:** Most of the "add-grid" functions will (by default) save the gridded image for you (using the save location part of the image specification). If you prefer, D.S. can create a gridded image and not save it. When that happens, it will return it as an in-memory buffer. If you are not sure on which function does what, use Visual Studio's intellisense. It will help you identify those which saves the image for you and those which return an in-memory buffer. Having said that, you are free to read the source code for these functions with the following link;
**Note:** Most of the "add-grid" functions will (by default) save the gridded image for you (using the save location part of the image specification). If you prefer, D.S. can create a gridded image and not save it. When that happens, it will return it as an in-memory buffer. If you are not sure on which function does what, use Visual Studio's intellisense. It will help you identify those which saves the image for you and those which return an in-memory buffer. Having said that, you are free to read the source code for these functions with the following link:
If you would like to know more about these graphics libraries, please use the following links;
If you would like to know more about these graphics libraries, please use the following links:
- [Graphics Class](https://docs.microsoft.com/en-us/dotnet/api/system.drawing.graphics?view=netframework-4.8#applies-to) (this is probably a good place to start with *System.Drawing*)
- [SkiaSharp Graphics in Xamarin Forms](https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/graphics/skiasharp/) (provides an introductory overview to SkiaSharp)
@ -50,7 +50,7 @@ As a consumer of D.S., you will not have access to every part of it. Instead, yo
The above image shows the flow of a typical code-base using D.S. Looking at this, you would think the `GridPainter` module is where you should focus most of your time. This is not immediately true, though. If anything, forming good image-specifications is the more time consuming task.
To help you get started, I recommend you keep the following two files open when writing your code;
To help you get started, I recommend you keep the following two files open when writing your code:
@ -125,17 +125,17 @@ let determineImageDimensions (imgType: ImageType) =
The purpose of this function is to determine the dimensions of the image at the location specified in the `ImageType`. Having said that, DeathSocket uses *System.Drawing* and *SkiaSharp*. So, it needs to provide a way to use both libraries. I could have written two separate functions, one for each graphics library. But, that felt like a waste of effort. So, I used the `ImageType` and condensed it into one. To be clear, all this function needs is the path of the image. What the `ImageType` provides is extra context.
Instead of repeating all the code in "Domain.fs", I recommend you take a look at the file yourself. The link for that is as follows;
Instead of repeating all the code in "Domain.fs", I recommend you take a look at the file yourself. The link for that is as follows:
I have documented the code within the file using XML comments. So, you should get intellisense overlays when you use Visual Studio or Visual Studio Code. I have, also, provided templates/examples in the "Snippets" section. Feel free to use them as starting points for creating your own specifications. The link for the snippets section is as follows;
I have documented the code within the file using XML comments. So, you should get intellisense overlays when you use Visual Studio or Visual Studio Code. I have, also, provided templates/examples in the "Snippets" section. Feel free to use them as starting points for creating your own specifications. The link for the snippets section is as follows:
Within `GridPainter`, you will find ten functions, which are as follows;
Within `GridPainter`, you will find ten functions, which are as follows:
1. `applyImageToGridAsync`
2. `scaleLineThickness`
@ -148,7 +148,7 @@ Within `GridPainter`, you will find ten functions, which are as follows;
9. `determineSKHorizontalLines`
10. `determineSKVerticalLines`
Instead of repeating the code from that file here, I recommend you open up "GridPainter.fs" in a separate tab. Every function has XML comments explaining what they do. So, you should have intellisense in Visual Studio and Visual Studio Code. If you read "GridPainter.fs", you will notice I have marked out areas called "SkiaSharp Functions" and "System.Drawing Functions". This should help you denote which function use which graphics library. If you are unsure which function uses which library, you can refer back to the XML comments/intellisense. As a general rule, if a function has "SK" in its name, it uses *SkiaSharp*. If it does not, it uses *System.Drawing*. The link for GridPainter.fs is as follows;
Instead of repeating the code from that file here, I recommend you open up "GridPainter.fs" in a separate tab. Every function has XML comments explaining what they do. So, you should have intellisense in Visual Studio and Visual Studio Code. If you read "GridPainter.fs", you will notice I have marked out areas called "SkiaSharp Functions" and "System.Drawing Functions". This should help you denote which function use which graphics library. If you are unsure which function uses which library, you can refer back to the XML comments/intellisense. As a general rule, if a function has "SK" in its name, it uses *SkiaSharp*. If it does not, it uses *System.Drawing*. The link for GridPainter.fs is as follows:
