Add description of method declarations to sequence and data

Author: macite

book

@@ -0,0 +1 @@
+/workspaces/the-programmers-field-guide/src/content/docs/book

resources/guide-diagrams.graffle

@@ -0,0 +1,77 @@
+---
+title: Methods to Use
+---
+
+At this point the programs we create will include sequences of method calls, with variables that we can use to work with data within our program.
+
+To build programs we will need to have some [methods](/book/part-1-instructions/1-sequence-and-data/1-concepts/02-method) that we can [call](/book/part-1-instructions/1-sequence-and-data/1-concepts/03-method-call). The great this is that [library](/book/part-1-instructions/1-sequence-and-data/1-concepts/10-library) creators will describe the methods that they have created so that we can find and use them. In order to use this documentation we need to know how these methods will be described.
+
+## Method Declarations
+
+Methods are usually communicated using part of their declaration. We will look at building these ourselves in [Part 2](/book/part-2-organised-code/2-organising-code/0-overview), but for now we need to know some basics so that we can start calling methods.
+
+![Method declaration visualisation](./images/method-decl.png)
+
+The above image helps show the components of a method declaration. The key parts are:
+
+- The *name* of the method. Remember, to call the method you use its name.
+- The variables and types of any *arguments* you will need to pass when you call the method. These will be listed as variables after the method name in parentheses.
+- You can also see the type of data that is returned (where `void` means none).
+- You also need to check that the method is `public` and `static`. We can call these directly if you have `using static ClassName;` at the top of your code file. For example, `WriteLine` is in the `System.Console` code, so you can call it if you have `using static System.Console` at the top of the code.
+
+The following code snippets show example method declarations.
+
+In the  details of the [Console code](https://learn.microsoft.com/en-us/dotnet/api/system.console.writeline?view=net-8.0#system-console-writeline(system-string)) in the .NET documentation, there is the following documentation to show one of the `WriteLine` methods.
+
+```cs
+public static void WriteLine (string? value);
+```
+
+This is available to call directly, as it is `public` and `static`. We can use this in our code using:
+
+```cs
+using static System.Console;
+
+WriteLine("Hello World");
+```
+
+The following shows the declaration of the [Open Window](https://splashkit.io/api/windows/#open-window) method from the SplashKit documentation. It is similar to the code above, but also includes the class name so that you know where the method exists. We can call it directly as it is `public` and `static`.
+
+```cs
+public static Window SplashKit.OpenWindow(string caption, int width, int height);
+```
+
+This is in the `SplashkitSDK.SplashKit` class, so you can call the `OpenWindow` method using the following code. This will pass "This is the caption" to the `caption` data, 800 to the `width`, and 600 to the `height`. This code will return a `Winddow` value, which we can ignore or store in a `Window` variable.
+
+```cs
+using static SplashkitSDK.SplashKit;
+
+OpenWindow("This is the caption", 800, 600);
+```
+
+For the final example let's look at [Fill Circle](https://splashkit.io/api/graphics/#fill-circle-3) and [Color Red](https://splashkit.io/api/color/#color-red). These have the following declaration on the SplashKit website.
+
+```cs
+public static void SplashKit.FillCircle(Color clr, double x, double y, double radius);
+public static Color SplashKit.ColorRed();
+```
+
+We can see from its declaration that we can call these (they are public and static). Their names are `FillCircle` and `ColorRed`. Will `FillCircle` we need to pass it a Color, and three double values. `ColorRed` does not need to be passed anything, and will return a Color value. The following is an example of calling this method. Here we use the result of `ColorRed()` as the value passed into the color for `FillCircle`.
+
+```cs
+using static SplashkitSDK.SplashKit;
+
+OpenWindow("This is the caption", 800, 600);
+ClearScreen(ColorWhite());
+
+FillCircle(ColorRed(), 400, 300, 100);
+RefreshScreen();
+```
+
+In the next pages we will list the different methods that you will use to complete the activities in this chapter both for terminal and graphical programs.
+
+## Other Websites
+
+You can call these methods on the *class* in which they are defined, and we will work up to this over the next few parts. To simplify things, we want to avoid doing this for now and instead call these directly as we have seen here.
+
+When you read other websites, you will often see them calling methods like this: `Console.WriteLine();`. This is the equivalent of calling `WriteLine();` when you have `using static System.Console;` at the top of your code. When you find code like this, you will need to convert it so that you can call the method directly.

src/content/docs/book/part-1-instructions/1-sequence-and-data/1-concepts/11-0-methods-to-use.md

@@ -0,0 +1,75 @@
+---
+title: Terminal Methods
+sidebar:
+    label: " - Terminal Methods"
+---
+
+Interacting with the [Terminal](/book/part-0-getting-started/2-computer-use/1-concepts/01-terminal) is pretty simple in code. There are basically three methods that you need to care about: `WriteLine`, `Write`, and `ReadLine`. These are all described in the [Console](https://learn.microsoft.com/en-us/dotnet/api/system.console?view=net-8.0#methods) page in the .NET documentation which we will summarise below, along with some methods from the [Convert](https://learn.microsoft.com/en-us/dotnet/api/system.convert?view=net-8.0#methods) code.
+
+## WriteLine and Write
+
+When you want to display something on the terminal, you use either the `WriteLine` or `Write` method. There are lots of different versions of these methods which will allow you to pass many values to be output - so we can think of these as having this declaration, where `...` is replaced with data of the different basic data types (integers, numbers, text):
+
+```cs
+public static void Console.WriteLine(...);
+public static void Console.Write(...);
+```
+
+These methods differ only slightly. The `Write` method outputs the data that you pass it, while the `WriteLine` method outputs the data and adds a new line. This means that with `Write`, the cursor will remain on the same line, and the next output (or input) will appear on the same line as the data written out. Whereas, `WriteLine` will advance the cursor to the start of the next line.
+
+## ReadLine
+
+You can use the Terminal for input as well as output. The `ReadLine` method allows you to read data from the Terminal, capturing the text the user types, placing it in a string, and returning it to you in a string when the user hits the enter or return key.
+
+You can think of this as having the following method declaration:
+
+```cs
+public static string Console.ReadLine();
+```
+
+:::tip
+[ReadLine](https://learn.microsoft.com/en-us/dotnet/api/system.console.readline?view=net-8.0#system-console-readline) in the Console class uses a feature that lets you indicate that it may not return any data. This will generate warnings when we use it. To remove these warnings, for now, you need to set the *nullable* property in your *.csproj* file to *disable*.
+:::
+
+## Converting Data
+
+As you can see above, `ReadLine` only returns string data. When you need this to be a number, you need to convert it. The C# library provides a number of conversion methods in its [Convert](https://learn.microsoft.com/en-us/dotnet/api/system.convert?view=net-8.0#methods) code. We can use these with `ReadLine` to convert data the user enters into either an integer (int32) or a double.
+
+```cs
+public static int Convert.ToInt32();
+public static double Convert.ToDouble();
+```
+
+## Example
+
+You can use these as shown below:
+
+```cs
+using static System.Console;
+using static System.Convert;
+
+string name;
+int age;
+
+Write("Enter your name: ");
+name = ReadLine();
+
+WriteLine($"Hello {name}!");
+
+Write("How old are you? Enter your age: ");
+age = ToInt32(ReadLine());
+```
+
+To remove the warning about the data returned from `ReadLine`, I have updated my csproj file to be as shown below.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>disable</Nullable>
+  </PropertyGroup>
+</Project>
+```