point images paths to root folder.

master
Craig Oates 4 years ago
parent
commit
6e6bac7010
  1. 4
      CLI-Project-Breakdown.md
  2. 4
      Command-Methods-Overview.md
  3. 8
      Console-and-Library-Tests-Overview.md
  4. 4
      Creating-the-Input-Loop.md
  5. 4
      DeathSocket-Project-Breakdown.md
  6. 2
      DeathSockets-Flow.md
  7. 2
      DeathSockets-Internal-Flow.md
  8. 4
      Introduction-to-Death-Socket.md
  9. 2
      Property-and-Unit-Tests-Overview.md
  10. 4
      Repository-Breakdown.md
  11. 2
      ScratchPad-Overview.md
  12. 6
      TestCentre-Breakdown.md
  13. 6
      The-CLIs-Flow.md
  14. 4
      Using-Death-Socket-in-Your-Project.md
  15. 6
      Using-the-Console-Program.md

4
CLI-Project-Breakdown.md

@ -1,12 +1,12 @@
This section focuses on the source code within the console project (A.K.A DeathSocketCLI). This project provides a way to use the features in the .Net Standard 2.0 library (A.K.A. DeathSocket) without writing code.
![deathsocketcli selected](attachments/deathsocketcli-selected.png)
![deathsocketcli selected](/deathsocketcli-selected.png)
## Project Breakdown
This project is a traditional .Net console program, written in F#. Within the project, you will see nine files with "DeathSocketCLI.fsproj" amongst them. This is a typical ".fsproj" file you will find in most (if not all) F# projects made with Visual Studio; You should not need to ever open it. This, also, applies to "App.config", "AssemblyInfo.fs" and "packages.config". "resources.res" is another file you should not need to open but it is not a "normal" file so I will need to come back to that. "logo.ico" is the program's icon which is what people will see (in the task bar) when the program is running. Again, you should not need to open or alter this in any way. This leaves "Commands.fs", "Program.fs" and "Validation.fs" as the remaining three files. They are, also, where you will you spend most of your time.
![deathsocketcli file structure](attachments/deathsocketcli-file-structure.png)
![deathsocketcli file structure](/deathsocketcli-file-structure.png)
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:

4
Command-Methods-Overview.md

@ -45,7 +45,7 @@ let ``list-colours`` () =
```
To help explain what the above code does, please consider the following image:
![command-method binding example](attachments/command-method-binding-example.png)
![command-method binding example](/command-method-binding-example.png)
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:
@ -54,7 +54,7 @@ It is not essential to include the help attributes but they do provide help for
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:
![deathsocketcli run-time commands screenshot](attachments/deathsocketcli-run-time-commands-screenshot.png)
![deathsocketcli run-time commands screenshot](/deathsocketcli-run-time-commands-screenshot.png)
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:

8
Console-and-Library-Tests-Overview.md

@ -14,7 +14,7 @@ module names. If you are wondering why I did it this way, it is because
it makes it easier to read the Test Explorer (in Visual Studio).
![test explorere screenshot
simple](attachments/test-explorer-screenshot-simple.png)
simple](/test-explorer-screenshot-simple.png)
As an aside, I have kept the "helper" functions next to the actual
tests for a reason: to avoid "over-engineering". It seemed a little
@ -25,7 +25,7 @@ will need refactoring. Keep this in mind if you decide to add your own
changes/features.
![test files basic
structure](attachments/test-files-basic-structure.png).
structure](/test-files-basic-structure.png).
One way to denote a property test from a unit test is by looking at
their attributes. If a test has `[<Property>]` next to it, it is a
@ -59,7 +59,7 @@ TestCentre uses it as a place to save and check the images it
creates. To help you check, here is what your TestCentre project
should look like:
![testcenre file structure](attachments/testcentre-file-structure.png)
![testcenre file structure](/testcentre-file-structure.png)
The easiest way to add this folder to TestCentre is by right-clicking
on "TestCentre" in Visual Studio's Solution Explorer. From there, head
@ -69,4 +69,4 @@ want. This is because Visual Studio does not need to know it
exists. You just need it on your machine.
![add new folder
screenshot](attachments/add-new-folder-screenshot.png)
screenshot](/add-new-folder-screenshot.png)

4
Creating-the-Input-Loop.md

@ -22,9 +22,9 @@ How C.W. creates and manages the input-loop is out of this wiki's scope. Althoug
Here are examples of what is displayed at run-time when you pass `true` or `false` into the `liaison.Run` command, mentioned above.
![deathsocket cli assembly info](attachments/deathsocketcli-assembly-info.png)
![deathsocket cli assembly info](/deathsocketcli-assembly-info.png)
![deathsocket cli assembly info](attachments/deathsocketcli-no-assembly-info.png)
![deathsocket cli assembly info](/deathsocketcli-no-assembly-info.png)
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:

4
DeathSocket-Project-Breakdown.md

@ -1,7 +1,7 @@
This section focuses on the source code within the "DeathSocket" project. It is the main project within the solution/repository.
![deathsocket selected](attachments/deathsocket-selected.png)
![deathsocket selected](/deathsocket-selected.png)
This project is a .Net Standard 2.0 library, written in F#. Within the project you will see eight files, including "DeathSocket.fsproj". This "fsproj" file is a typical file found in most (if not all) F# projects created with Visual Studio. For the most part, you should rarely need to touch this. The other seven files build out the project and are where you will do most of your work. With that in mind, I should point out "Scratchpad.fsx" operates in a different manner to the other six. That is because it is a script file and not part of the binary/DLL when you compile it. So, you can avoid using working with this file too if you want.
![deathsocket file structure](attachments/deathsocket-file-structure.png)
![deathsocket file structure](/deathsocket-file-structure.png)

2
DeathSockets-Flow.md

@ -1,6 +1,6 @@
To help you get up to speed on the way DeathSocket works, please consider the following image:
![deathsocket general flow](attachments/deathsocket-general-flow.png)
![deathsocket general flow](/deathsocket-general-flow.png)
The way it works is you construct an `ImageSpec` record, found in "Domain.fs". When you have done that, you call one of the functions in "GridPainter.fs". After that, the image creation process begins. This is done via the functions within the other files and your `ImageSpec`. While this is happening, the function in "GridPainter.fs" (housed in the `GridPainter` module) maintains overall control and essentially co-ordinates the task.

2
DeathSockets-Internal-Flow.md

@ -1,6 +1,6 @@
Although the system has a restricted input-output (I/O) flow from the outside, the internal flow is a bit more flexible. There is still a rigidity to it but it is not as one-dimensional. To help explain, please consider the image below.
![deathsocket internal flow](attachments/deathsocket-internal-flow.png)
![deathsocket internal flow](/deathsocket-internal-flow.png)
How this works is `GridPainter` receives input, usually a record type provided by `Domain`. From there, `GridPainter` will validate the input by making calls to `ValidationServices`. If the input is valid, `GridPainter` calls into `ImageServices` which then makes the various calls into `ColourServices` and `ImagePrep`. When the task is complete, `ImagesServices` returns the output to `GridPainter` which then returns it to your/the bigger system. *If the input is invalid, DeathSocket will throw a `FileNotFoundExcpetion`.*

4
Introduction-to-Death-Socket.md

@ -19,7 +19,7 @@ referencing the .Net library and console project. To help give you a
sense of what I mean, here is a diagram showing the relationships
between the three projects.
![project references](attachments/proj-refs.png)
![project references](/proj-refs.png)
## Why this Repository Exists
@ -46,7 +46,7 @@ altering several variables, which are:
- the thickness and colour of the grid's lines; and
- the number of rows and columns the grid has.
![examples](attachments/examples.png)
![examples](/examples.png)
Images provided by:

2
Property-and-Unit-Tests-Overview.md

@ -5,7 +5,7 @@ Within TestCentre, you will see a collection of property and unit tests. Each ty
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:
![test-explorer screenshot](attachments/test-explorer-screenshot.png)
![test-explorer screenshot](/test-explorer-screenshot.png)
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.

4
Repository-Breakdown.md

@ -6,11 +6,11 @@ The code-base in this repository is a typical Visual Studio solution. Within the
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:
![folder structure](attachments/solution-overview.png)
![folder structure](/solution-overview.png)
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:
![project references](attachments/proj-refs.png)
![project references](/proj-refs.png)
- DeathSocket is referenced in DeathSocketCLI and TestCentre.
- DeathSocketCLI is referenced in TestCentre.

2
ScratchPad-Overview.md

@ -4,7 +4,7 @@ The reason "ScratchPad.fsx" exists is to provide a way for you to interact with
- [F# Interactive (FSI)](https://docs.microsoft.com/en-us/dotnet/fsharp/tutorials/fsharp-interactive/)
- [Scripting with F#](https://fsharpforfunandprofit.com/installing-and-using/) (it's a little dated but it contains enough information to get you going)
![scratchpad.fsx relationship](attachments/scratchpad-relationship.png)
![scratchpad.fsx relationship](/scratchpad-relationship.png)
If you decide to use "ScratchPad.fsx", you must build the project ("F5" in Visual Studio) beforehand. On top of that, you must change the path when referencing the "SkiaSharp" DLL. This is because I have hard-coded the path (yes, I'm lazy). So, within "ScratchPad.fsx", you should see something like the following at the top of the file,

6
TestCentre-Breakdown.md

@ -1,14 +1,14 @@
This project is a traditional .Net (4.7) library, written in F#. Its main purpose is to house the solution's unit and property tests.
![testcentre selected](attachments/testcentre-selected.png)
![testcentre selected](/testcentre-selected.png)
Within the project, you will see six files and two folders. Although, you should only need to work with two of them files. They are "ConsoleTests.fs" and "LibraryTests.fs".
![testcentre file structure](attachments/testcentre-file-structure.png)
![testcentre file structure](/testcentre-file-structure.png)
The "AssemblyInfo.fs", "TestCentre.fsproj" and "packages.config" files are all standard files. You will find them in most, if not all, F# based (traditional) .Net libraries. "Script.fsx" contains code I will go over a little later. Although, if you know how to work F-Sharp Interactive (FSI), you will already know how to use this file. There is not much code in it and you can avoid using it at all it if you want. As their names imply, "ConsoleTests.fs" and "LibraryTests.fs" houses the tests of their project's namesake. So, "ConsoleTests.fs" contains the tests for the console (CLI) project. And, "LibraryTests.fs" contains the tests for the (.Net Standard) library project.
![testcentre split overview](attachments/testcentre-split-overview.png)
![testcentre split overview](/testcentre-split-overview.png)
The folder ("SavingTestArea"), provides an area for TestCentre to actually save the images it produces. If you do not see it in your solution, **you might need to create it yourself**. This will become clear when you run the tests, because they will fail. If you need to add "SavingTestArea" to your copy of TestCentre, make sure it matches the location in the above diagram. Alongside "SavingTestArea" is its counterpart, "LoadingTestArea". This is where TestCentre loads the pre-made images from to test DeathSocket's ability to add the overlays to them. Within "LoadingTestArea" is another folder called "RequiredInfo" which contains files which some tests rely on for them to pass. An example of some of the things these tests rely on is an image having certain dimensions. Usually, TestCentre generates random images to test against which means you cannot reliably check the dimensions of an image. So, do not delete the images in "RequiredInfo".

6
The-CLIs-Flow.md

@ -1,6 +1,6 @@
To help you get up to speed on the way DeathSocketCLI works, please consider the following diagram.
![deathsocketcli general flow](attachments/deathsocketcli-general-flow.png)
![deathsocketcli general flow](/deathsocketcli-general-flow.png)
The way it works is as follows:
@ -21,7 +21,7 @@ The reason the program runs this way is because I built it on top off C.W. I wil
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](attachments/console.waterworks-data-flow.png)
![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:
@ -42,7 +42,7 @@ If you would like to know more about utilising C.W. in an F#-only context, head
End of aside.
![deathsocketcli file flow](attachments/deathsocketcli-file-flow.png)
![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.

4
Using-Death-Socket-in-Your-Project.md

@ -33,7 +33,7 @@ If you look at the source code for D.S., you will see I have included two graphi
I have included these two libraries because D.S. is a .Net Standard 2.0 library. This means the code in D.S. can run on the traditional .Net framework and .Net Core. If you are building a traditional .Net application (E.G. a W.P.F. app.), I recommend you use *System.Drawing*. If you are creating a cross-platform application (E.G. a Xamarin app.), you will need to use the *SkiaSharp* parts of D.S. This means the general flow of the system looks like this,
![deathsocket graphics lib. divide](attachments/deathsocket-graphics-lib-divide.png)
![deathsocket graphics lib. divide](/deathsocket-graphics-lib-divide.png)
 If you would like to know more about these graphics libraries, please use the following links:
@ -46,7 +46,7 @@ This next bit is an aside; So, feel free to skip over this bit and jump straight
As a consumer of D.S., you will not have access to every part of it. Instead, you work with two modules within a single name-space, called `DeathSocket`. The module's names are `Domain` and `GridPainter`.
![deathsocket public modules](attachments/deathsocket-pubic-modules.png)
![deathsocket public modules](/deathsocket-pubic-modules.png)
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.

6
Using-the-Console-Program.md

@ -31,13 +31,13 @@ using the following links:
When you start the console, you will see something similar to the following
image:
![deathsocketcli assembly info](attachments/deathsocketcli-assembly-info.png)
![deathsocketcli assembly info](/deathsocketcli-assembly-info.png)
From here, you can begin entering commands. Before continuing,though, it is worth
noting the "help" command. When you enter `help` into the prompt, the console will
list out all the commands the program has to offer.
![deathsocketcli help screenshot](attachments/deathsocketcli-help-screenshot.png)
![deathsocketcli help screenshot](/deathsocketcli-help-screenshot.png)
To keep things simple to start with, I assume you are probably best sticking to
the following commands -- until you are comfortable with what and how the console works:
@ -49,7 +49,7 @@ When using `add-default`, you need to specify the path of the image you want to
add a grid to and where you want to store it. So, when you use `add-default`,
the console should look like the following:
![deathsocket add-default screenshot](attachments/deathsocketcli-add-default-screenshot.png)
![deathsocket add-default screenshot](/deathsocketcli-add-default-screenshot.png)
If you would like to view the source code of the commands or the program's A.P.I, you can
peruse through them both using the following links:

Loading…
Cancel
Save