[v3] Update Markdown files to latest spec

.github/dependabot.yml

@@ -0,0 +1,9 @@
+version: 2
+
+updates:
+
+  # Keep dependencies for GitHub Actions up-to-date
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'daily'

.github/workflows/configlet.yml

@@ -0,0 +1,16 @@
+name: Configlet CI
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  configlet:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
+
+    - name: Fetch configlet
+      uses: exercism/github-actions/configlet-ci@main
+
+    - name: Configlet Linter
+      run: configlet lint

.github/workflows/test.yml

@@ -4,12 +4,12 @@ on: [push, pull_request]
 
 jobs:
   test:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f # 2.3.4
       - uses: actions/setup-dotnet@51f68377c181a79065c61bd492bd49be4575c439 # 1.7.2
         with:
-          dotnet-version: "3.0.100"
+          dotnet-version: "5.0.102"
       - run: pwsh ./test.ps1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

bin/fetch-configlet

@@ -1,37 +1,58 @@
-#!/bin/bash
-
-LATEST=https://api.github.com/repos/exercism/configlet/releases/latest
-
-OS=$(
-case $(uname) in
-    (Darwin*)
-        echo "mac";;
-    (Linux*)
-        echo "linux";;
-    (*)
-        echo "linux";;
-esac)
-
-ARCH=$(
-case $(uname -m) in
-    (*64*)
-        echo 64bit;;
-    (*686*)
-        echo 32bit;;
-    (*386*)
-        echo 32bit;;
-    (*)
-        echo 64bit;;
-esac)
-
-FILENAME="configlet-${OS}-${ARCH}.tgz"
-
-if [ -z "${GITHUB_TOKEN}" ]
-then
-    HEADER=""
-else
-    HEADER="authorization: Bearer ${GITHUB_TOKEN}"
+#!/usr/bin/env bash
+
+set -eo pipefail
+
+readonly LATEST='https://api.github.com/repos/exercism/configlet/releases/latest'
+
+case "$(uname)" in
+  Darwin*)   os='mac'     ;;
+  Linux*)    os='linux'   ;;
+  Windows*)  os='windows' ;;
+  MINGW*)    os='windows' ;;
+  MSYS_NT-*) os='windows' ;;
+  *)         os='linux'   ;;
+esac
+
+case "${os}" in
+  windows*) ext='zip' ;;
+  *)        ext='tgz' ;;
+esac
+
+case "$(uname -m)" in
+  *64*)  arch='64bit' ;;
+  *686*) arch='32bit' ;;
+  *386*) arch='32bit' ;;
+  *)     arch='64bit' ;;
+esac
+
+curlopts=(
+  --silent
+  --show-error
+  --fail
+  --location
+  --retry 3
+)
+
+if [[ -n "${GITHUB_TOKEN}" ]]; then
+  curlopts+=(--header "authorization: Bearer ${GITHUB_TOKEN}")
 fi
 
-URL=$(curl --header $HEADER -s $LATEST | awk -v filename=$FILENAME '$1 ~ /browser_download_url/ && $2 ~ filename { print $2 }' | tr -d '"')
-curl --header $HEADER -s --location $URL | tar xz -C bin/
+suffix="${os}-${arch}.${ext}"
+
+get_download_url() {
+  curl "${curlopts[@]}" --header 'Accept: application/vnd.github.v3+json' "${LATEST}" |
+    grep "\"browser_download_url\": \".*/download/.*/configlet.*${suffix}\"$" |
+    cut -d'"' -f4
+}
+
+download_url="$(get_download_url)"
+output_dir="bin"
+output_path="${output_dir}/latest-configlet.${ext}"
+curl "${curlopts[@]}" --output "${output_path}" "${download_url}"
+
+case "${ext}" in
+  *zip) unzip "${output_path}" -d "${output_dir}"   ;;
+  *)    tar xzf "${output_path}" -C "${output_dir}" ;;
+esac
+
+rm -f "${output_path}"

bin/fetch-configlet.ps1

@@ -1,24 +1,26 @@
-Function DownloadUrl ([string] $FileName, $Headers) {
-    $latestUrl = "https://api.github.com/repos/exercism/configlet/releases/latest"
-    $json = Invoke-RestMethod -Headers $Headers -Uri $latestUrl
-    $json.assets | Where-Object { $_.browser_download_url -match $FileName } | Select-Object -ExpandProperty browser_download_url
-}
+$ErrorActionPreference = "Stop"
+$ProgressPreference = "SilentlyContinue"
 
-Function Headers {
-    If ($GITHUB_TOKEN) { $headers = @{ Authorization = "Bearer ${GITHUB_TOKEN}" } } Else { $headers = @{ } }
+$requestOpts = @{
+    Headers = If ($env:GITHUB_TOKEN) { @{ Authorization = "Bearer ${env:GITHUB_TOKEN}" } } Else { @{ } }
+    MaximumRetryCount = 3
+    RetryIntervalSec = 1
 }
 
-Function Arch {
-    If ([Environment]::Is64BitOperatingSystem) { "64bit" } Else { "32bit" }
+$arch = If ([Environment]::Is64BitOperatingSystem) { "64bit" } Else { "32bit" }
+$fileName = "configlet-windows-$arch.zip"
+
+Function Get-DownloadUrl {
+    $latestUrl = "https://api.github.com/repos/exercism/configlet/releases/latest"
+    Invoke-RestMethod -Uri $latestUrl -PreserveAuthorizationOnRedirect @requestOpts
+    | Select-Object -ExpandProperty assets
+    | Where-Object { $_.browser_download_url -match $FileName }
+    | Select-Object -ExpandProperty browser_download_url
 }
 
-$arch = Arch
-$headers = Headers
-$fileName = "configlet-windows-$arch.zip"
+$downloadUrl = Get-DownloadUrl
 $outputDirectory = "bin"
 $outputFile = Join-Path -Path $outputDirectory -ChildPath $fileName
-$zipUrl = DownloadUrl -FileName $fileName -Headers $headers
-
-Invoke-WebRequest -Headers $headers -Uri $zipUrl -OutFile $outputFile
+Invoke-WebRequest -Uri $downloadUrl -OutFile $outputFile @requestOpts
 Expand-Archive $outputFile -DestinationPath $outputDirectory -Force
-Remove-Item -Path $outputFile
+Remove-Item -Path $outputFile

concepts/arrays/about.md

@@ -0,0 +1,103 @@
+# About
+
+TODO: about.md files and links.json files are the same for arrays, for-loops and foreach. Consider how to prise these apart of otherwise treat these closely coupled concepts.
+Data structures that can hold zero or more elements are known as _collections_. An **array** is a collection that has a fixed size/length and whose elements must all be of the same type. Elements can be assigned to an array or retrieved from it using an index. C# arrays are zero-based, meaning that the first element's index is always zero:
+
+```csharp
+// Declare array with explicit size (size is 2)
+int[] twoInts = new int[2];
+
+// Assign second element by index
+twoInts[1] = 8;
+
+// Retrieve the second element by index
+twoInts[1] == 8; // => true
+
+// Check the length of the array
+twoInts.Length == 2; // => true
+```
+
+Arrays can also be defined using a shortcut notation that allows you to both create the array and set its value. As the compiler can now tell how many elements the array will have, the length can be omitted:
+
+```csharp
+// Three equivalent ways to declare and initialize an array (size is 3)
+int[] threeIntsV1 = new int[] { 4, 9, 7 };
+int[] threeIntsV2 = new[] { 4, 9, 7 };
+int[] threeIntsV3 = { 4, 9, 7 };
+```
+
+Arrays can be manipulated by either calling an array instance's [methods][array-methods] or [properties][array-properties], or by using the static methods defined in the [`Array` class][array-class].
+
+An array is also a _collection_, which means that you can iterate over _all_ its values using a [`foreach` loop][foreach-statement]:
+
+```csharp
+char[] vowels = new [] { 'a', 'e', 'i', 'o', 'u' };
+
+foreach (char vowel in vowels)
+{
+    // Output the vowel
+    System.Console.Write(vowel);
+}
+
+// => aeiou
+```
+
+One could use a [`for` loop][for-statement] to iterate over an array:
+
+```csharp
+char[] vowels = new [] { 'a', 'e', 'i', 'o', 'u' };
+
+for (int i = 0; i < vowels.Length; i++)
+{
+    // Output the vowel
+    System.Console.Write(vowels[i]);
+}
+
+// => aeiou
+```
+
+However, generally a `foreach` loop is preferrable over a `for` loop for the following reasons:
+
+- A `foreach` loop is guaranteed to iterate over _all_ values. With a `for` loop, it is easy to miss elements, for example due to an off-by-one error.
+- A `foreach` loop is more _declarative_, your code is communicating _what_ you want it to do, instead of a `for` loop that communicates _how_ you want to do it.
+- A `foreach` loop is foolproof, whereas with `for` loops it is easy to have an off-by-one error.
+- A `foreach` loop works on all collection types, including those that don't support using an indexer to access elements.
+
+To guarantee that a `foreach` loop will iterate over _all_ values, the compiler will not allow updating of a collection within a `foreach` loop:
+
+```csharp
+char[] vowels = new [] { 'a', 'e', 'i', 'o', 'u' };
+
+foreach (char vowel in vowels)
+{
+    // This would result in a compiler error
+    // vowel = 'Y';
+}
+```
+
+A `for` loop does have some advantages over a `foreach` loop:
+
+- You can start or stop at the index you want.
+- You can use any (boolean) termination condition you want.
+- You can skip elements by customizing the incrementing of the loop variable.
+- You can process collections from back to front by counting down.
+- You can use `for` loops in scenarios that don't involve collections.
+
+Related Topics:
+
+- You should be aware that C# supports [multi-dimensional arrays][multi-dimensional-arrays] like `int[,] arr = new int[10, 5]` which can be very useful.
+- You should also be aware that you can instantiate objects of type [`System.Array`][system-array-object] with `Array.CreateInstance`. Such objects are of little use - mainly for interop with VB.NET code. They are not interchangeable with standard arrays (`T[]`). They can have a non-zero lower bound.
+
+Both the above topics are discussed more fully in a later exercise.
+
+[implicitly-typed-arrays]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/implicitly-typed-arrays
+[array-foreach]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/using-foreach-with-arrays
+[single-dimensional-arrays]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/single-dimensional-arrays
+[array-class]: https://docs.microsoft.com/en-us/dotnet/api/system.array?view=netcore-3.1
+[array-properties]: https://docs.microsoft.com/en-us/dotnet/api/system.array?view=netcore-3.1#properties
+[array-methods]: https://docs.microsoft.com/en-us/dotnet/api/system.array?view=netcore-3.1#methods
+[foreach-statement]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/foreach-in
+[for-statement]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/for
+[break-keyword]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/break
+[multi-dimensional-arrays]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/multidimensional-arrays
+[system-array-object]: https://docs.microsoft.com/en-us/dotnet/api/system.array.createinstance?view=netcore-3.1#System_Array_CreateInstance_System_Type_System_Int32_

concepts/arrays/introduction.md

@@ -0,0 +1,25 @@
+# Introduction
+
+In C#, data structures that can hold zero or more elements are known as _collections_. An **array** is a collection that has a fixed size/length and whose elements must all be of the same type. Elements can be assigned to an array or retrieved from it using an index. C# arrays are zero-based, meaning that the first element's index is always zero:
+
+```csharp
+// Declare array with explicit size (size is 2)
+int[] twoInts = new int[2];
+
+// Assign second element by index
+twoInts[1] = 8;
+
+// Retrieve the second element by index
+twoInts[1] == 8; // => true
+```
+
+Arrays can also be defined using a shortcut notation that allows you to both create the array and set its value. As the compiler can now tell how many elements the array will have, the length can be omitted:
+
+```csharp
+// Three equivalent ways to declare and initialize an array (size is 3)
+int[] threeIntsV1 = new int[] { 4, 9, 7 };
+int[] threeIntsV2 = new[] { 4, 9, 7 };
+int[] threeIntsV3 = { 4, 9, 7 };
+```
+
+Arrays can be manipulated by either calling an array instance's methods or properties, or by using the static methods defined in the `Array` class.

concepts/arrays/links.json

@@ -0,0 +1,30 @@
+[
+  {
+    "url": "https://docs.microsoft.com/en-us/dotnet/api/system.array?view=netcore-3.1#methods",
+    "description": "array-methods"
+  },
+  {
+    "url": "https://docs.microsoft.com/en-us/dotnet/api/system.array?view=netcore-3.1#properties",
+    "description": "array-properties"
+  },
+  {
+    "url": "https://docs.microsoft.com/en-us/dotnet/api/system.array?view=netcore-3.1",
+    "description": "array-class"
+  },
+  {
+    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/foreach-in",
+    "description": "foreach-statement"
+  },
+  {
+    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/for",
+    "description": "for-statement"
+  },
+  {
+    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/arrays/multidimensional-arrays",
+    "description": "multi-dimensional-arrays"
+  },
+  {
+    "url": "https://docs.microsoft.com/en-us/dotnet/api/system.array.createinstance?view=netcore-3.1#System_Array_CreateInstance_System_Type_System_Int32_",
+    "description": "system-array-object"
+  }
+]

concepts/attributes/about.md

@@ -0,0 +1,30 @@
+# About
+
+A [C# `Attribute`][attribute-concept] provides a way to decorate a declaration to associate metadata to: a class, a method, an enum, a field, a property or any [other supported][attribute-targets] declarations.
+
+You can apply [an attribute][attribute] to a declaration by adding it between brackets `[]` before the declaration, the following example uses both a `ClassAttribute` and a `FieldAttribute`:
+
+```csharp
+[Class]
+public class MyClass
+{
+    [Field] public int myField;
+}
+```
+
+The declarative metadata only associates additional structured information to the code and does not modify its behavior, but that metadata is used by other part of the code to change how its target would behave or add, change or remove, restrict some its functionalities.
+
+Multiple predefined attributes exist like: `Flags`, `Obsolete`, `Conditional`. Note that the full name of the [`Flags` attribute][flags-attribute] is `FlagsAttribute`, but "Attribute" suffix can be omitted when using in the attribute.
+
+The following four predefined attributes are used regularly:
+
+- `[Flags]`: Predefined in the System namespace. Indicates the enum supports both bitwise operations and the method `Enum.HasFlag()`, additionally `ToString` would display all the flags: [see example][flags-example].
+- `[Obsolete]`: Predefined in the System namespace. Allows to add a message about why the code is obsolete, it can be used to display compiler warnings or errors.
+- `[Conditional]`: Predefined in the System.Diagnostics namespace. Allows to remove some method calls at compile time for debugging (diagnostics) purposes.
+- `[CallerMemberName]`: Predefined in the System.Runtime.CompilerServices namespace. Allows a method to obtain information about its caller.
+
+[attribute-concept]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/attributes/
+[attribute]: https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/attributes
+[attribute-targets]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/attributes/#attribute-targets
+[flags-attribute]: https://docs.microsoft.com/en-us/dotnet/api/system.flagsattribute?view=net-5.0
+[flags-example]: https://docs.microsoft.com/en-us/dotnet/api/system.flagsattribute?view=net-5.0#examples

concepts/attributes/introduction.md

@@ -0,0 +1,18 @@
+# Introduction
+
+A [C# `Attribute`](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/attributes/) provides a way to decorate a declaration to associate metadata to: a class, a method, an enum, a field, a property or any [other supported](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/attributes/#attribute-targets) declarations.
+
+You can apply an attribute by adding it on the line before the declaration using a `ClassAttribute` and a `FieldAttribute`:
+
+```csharp
+[Class]
+class MyClass
+{
+    [Field]
+    int myField;
+}
+```
+
+This declarative metadata only associates additional structured information to the code and does not modify its behavior, but that metadata is used by other part of the code to change how its target would behave or add, change or remove, restrict some its functionalities.
+
+There is many [predefined and reserved attributes](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/attributes/general#conditional-attribute), for example: `Flags`, `Obsolete`, `Conditional`, each has a specific that can be looked up on the C# documentation. Note that the full name of an attribute like [`Flags`](https://docs.microsoft.com/en-us/dotnet/api/system.flagsattribute?view=net-5.0) is `FlagsAttribute` by convention, but the suffix _Attribute_ can be omitted when applied on a declaration.