From a98a5d75b09a9b97b4f36b9993bb486507f1899d Mon Sep 17 00:00:00 2001 From: thinker227 Date: Sun, 14 Jan 2024 14:00:49 +0100 Subject: [PATCH] Fix links --- docs/api/index.md | 6 +++--- docs/diagnostics/rascal001.md | 2 +- docs/diagnostics/rascal002.md | 2 +- docs/diagnostics/rascal003.md | 2 +- docs/diagnostics/rascal004.md | 2 +- docs/diagnostics/rascal005.md | 2 +- docs/diagnostics/rascal006.md | 2 +- docs/index.md | 10 +++++----- docs/samples/index.md | 16 ++++++++-------- 9 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/api/index.md b/docs/api/index.md index 6c77e4e..f292604 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -4,6 +4,6 @@ See the table of contents for an overview of the library API. ## Important types -- [`Result`](/api/Rascal.Result-1.html) -- [`Prelude`](/api/Rascal.Prelude.html) -- [`Error`](/api/Rascal.Error.html) +- [`Result`](~/api/Rascal.Result-1.yml) +- [`Prelude`](~/api/Rascal.Prelude.yml) +- [`Error`](~/api/Rascal.Error.yml) diff --git a/docs/diagnostics/rascal001.md b/docs/diagnostics/rascal001.md index 2f82235..8d4918e 100644 --- a/docs/diagnostics/rascal001.md +++ b/docs/diagnostics/rascal001.md @@ -15,7 +15,7 @@ Has code fix: yes ## Description -*RASCAL001* is reported when [`Ok`](/api/Rascal.Prelude.html#Rascal_Prelude_Ok__1___0_) or any other form of result construction is used as the immediate return from the lambda inside a [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) call. Because [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) chains results, this is equivalent to a much simpler [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) call. The warning can be resolved by replacing the [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) call with a [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) which maps to the expression inside the [`Ok`](/api/Rascal.Prelude.html#Rascal_Prelude_Ok__1___0_). +*RASCAL001* is reported when [`Ok`](~/api/Rascal.Prelude.yml#Rascal_Prelude_Ok__1___0_) or any other form of result construction is used as the immediate return from the lambda inside a [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) call. Because [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) chains results, this is equivalent to a much simpler [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) call. The warning can be resolved by replacing the [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) call with a [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) which maps to the expression inside the [`Ok`](~/api/Rascal.Prelude.yml#Rascal_Prelude_Ok__1___0_).
diff --git a/docs/diagnostics/rascal002.md b/docs/diagnostics/rascal002.md index f17366a..3f0eaa4 100644 --- a/docs/diagnostics/rascal002.md +++ b/docs/diagnostics/rascal002.md @@ -15,7 +15,7 @@ Has code fix: yes ## Description -*RASCAL002* is reported when [`Unnest`](/api/Rascal.ResultExtensions.html#Rascal_ResultExtensions_Unnest__1_Rascal_Result_Rascal_Result___0___) is called immediately after a [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) call. This operation is equivalent to calling [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) with the same mapping function, which improves clarity and performance. The warning can be resolved by removing the [`Unnest`](/api/Rascal.ResultExtensions.html#Rascal_ResultExtensions_Unnest__1_Rascal_Result_Rascal_Result___0___) call and replacing the [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) call with a [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__). +*RASCAL002* is reported when [`Unnest`](~/api/Rascal.ResultExtensions.yml#Rascal_ResultExtensions_Unnest__1_Rascal_Result_Rascal_Result___0___) is called immediately after a [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) call. This operation is equivalent to calling [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) with the same mapping function, which improves clarity and performance. The warning can be resolved by removing the [`Unnest`](~/api/Rascal.ResultExtensions.yml#Rascal_ResultExtensions_Unnest__1_Rascal_Result_Rascal_Result___0___) call and replacing the [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) call with a [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__).
diff --git a/docs/diagnostics/rascal003.md b/docs/diagnostics/rascal003.md index 9f6a9a9..cf9d633 100644 --- a/docs/diagnostics/rascal003.md +++ b/docs/diagnostics/rascal003.md @@ -15,7 +15,7 @@ Has code fix: yes ## Description -*RASCAL003* is reported when [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) is used with an *identity function*, i.e. a lambda in the form `x => x`. Because [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) transforms the ok value of a result, applying an identity function onto the value does nothing and returns the same result as the input, and the call is completely useless. The warning can be resolved by removing the call altogether. +*RASCAL003* is reported when [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) is used with an *identity function*, i.e. a lambda in the form `x => x`. Because [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) transforms the ok value of a result, applying an identity function onto the value does nothing and returns the same result as the input, and the call is completely useless. The warning can be resolved by removing the call altogether.
diff --git a/docs/diagnostics/rascal004.md b/docs/diagnostics/rascal004.md index bda1e15..a4edfa9 100644 --- a/docs/diagnostics/rascal004.md +++ b/docs/diagnostics/rascal004.md @@ -15,7 +15,7 @@ Has code fix: no ## Description -*RASCAL004* is reported when [`To`](/api/Rascal.Result-1.html#Rascal_Result_1_To__1_Rascal_Error_) is called with the same type as that of the result it is called on. Because `.To()` is equivalent to an `is T` pattern, calling `.To` on a `Result` where both `T`s are the same type will always succeed if the result is ok, and the call is redundant. The warning can be resolved by removing the call altogether. +*RASCAL004* is reported when [`To`](~/api/Rascal.Result-1.yml#Rascal_Result_1_To__1_Rascal_Error_) is called with the same type as that of the result it is called on. Because `.To()` is equivalent to an `is T` pattern, calling `.To` on a `Result` where both `T`s are the same type will always succeed if the result is ok, and the call is redundant. The warning can be resolved by removing the call altogether.
diff --git a/docs/diagnostics/rascal005.md b/docs/diagnostics/rascal005.md index 0a854df..10e8921 100644 --- a/docs/diagnostics/rascal005.md +++ b/docs/diagnostics/rascal005.md @@ -15,7 +15,7 @@ Has code fix: no ## Description -*RASCAL005* is reported when [`To`](/api/Rascal.Result-1.html#Rascal_Result_1_To__1_Rascal_Error_) is called with a type which is incompatible with the type of the result. This mainly applies to class types which do not inherit each other, and structs which aren't the same type. Interfaces, type parameters, and `object` may always succeed regardless of which type they are casted to/from. +*RASCAL005* is reported when [`To`](~/api/Rascal.Result-1.yml#Rascal_Result_1_To__1_Rascal_Error_) is called with a type which is incompatible with the type of the result. This mainly applies to class types which do not inherit each other, and structs which aren't the same type. Interfaces, type parameters, and `object` may always succeed regardless of which type they are casted to/from.
diff --git a/docs/diagnostics/rascal006.md b/docs/diagnostics/rascal006.md index f74555f..229579c 100644 --- a/docs/diagnostics/rascal006.md +++ b/docs/diagnostics/rascal006.md @@ -15,7 +15,7 @@ Has code fix: yes ## Description -*RASCAL006* is reported when [`Match`](/api/Rascal.Result-1.html#Rascal_Result_1_Match__1_System_Func__0___0__System_Func_Rascal_Error___0__) is called with an *identity function* as its first argument, i.e. a lambda with the form `x => x`. Such a call is equivalent to [`GetValueOr`](/api/Rascal.Result-1.html#Rascal_Result_1_GetValueOr_System_Func_Rascal_Error__0__), with the remaining argument being a function which returns a value based on the result's error. Note that [`GetValueOr`](/api/Rascal.Result-1.html#Rascal_Result_1_GetValueOr_System_Func_Rascal_Error__0__) has three different overloads which are suitable depending on whether the result's error is needed when retrieving the value. The warning can be resolved by removing the first argument and replacing the call to [`Match`](/api/Rascal.Result-1.html#Rascal_Result_1_Match__1_System_Func__0___0__System_Func_Rascal_Error___0__) with [`GetValueOr`](/api/Rascal.Result-1.html#Rascal_Result_1_GetValueOr_System_Func_Rascal_Error__0__). +*RASCAL006* is reported when [`Match`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Match__1_System_Func__0___0__System_Func_Rascal_Error___0__) is called with an *identity function* as its first argument, i.e. a lambda with the form `x => x`. Such a call is equivalent to [`GetValueOr`](~/api/Rascal.Result-1.yml#Rascal_Result_1_GetValueOr_System_Func_Rascal_Error__0__), with the remaining argument being a function which returns a value based on the result's error. Note that [`GetValueOr`](~/api/Rascal.Result-1.yml#Rascal_Result_1_GetValueOr_System_Func_Rascal_Error__0__) has three different overloads which are suitable depending on whether the result's error is needed when retrieving the value. The warning can be resolved by removing the first argument and replacing the call to [`Match`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Match__1_System_Func__0___0__System_Func_Rascal_Error___0__) with [`GetValueOr`](~/api/Rascal.Result-1.yml#Rascal_Result_1_GetValueOr_System_Func_Rascal_Error__0__).
diff --git a/docs/index.md b/docs/index.md index a61659b..8f77727 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ Rascal is a simple yet powerful [result type](https://www.youtube.com/watch?v=sr Rascal is first and foremost an aggregate of the result types I personally find myself implementing in a majority of my own projects, and a competetor other result libraries second. As such, this library implements some things I think other result implementations are lacking, while omitting some features other libraries do implement. -Additionally, Rascal comes with a suite of analyzers and code fixes to help you write better and more reliable code using the library. The documentation for these analyzers can be found in the [diagnostics documentation](/diagnostics/index.html). +Additionally, Rascal comes with a suite of analyzers and code fixes to help you write better and more reliable code using the library. The documentation for these analyzers can be found in the [diagnostics documentation](~/diagnostics/index.md).
@@ -66,7 +66,7 @@ After installing the package, create a file called `Usings.cs` and add the follo global using static Rascal.Prelude; ``` -[`Prelude`](/api/Rascal.Prelude.html) includes a variety of utility functions which you can now access from anywhere in your project. +[`Prelude`](~/api/Rascal.Prelude.yml) includes a variety of utility functions which you can now access from anywhere in your project. Now, let's pretend you have an ASP.NET Core app with the following method in a service: @@ -92,7 +92,7 @@ public Task> GetUser(int userId) => TryAsync(async () => }); ``` -This code will handle catching any exceptions thrown by [`FirstOrDefaultAsync`](https://learn.microsoft.com/en-us/dotnet/api/system.data.entity.queryableextensions.firstordefaultasync) and will return a [`NotFoundError`](/api/Rascal.Errors.NotFoundError.html) if the user isn't found. Now you can use this method as such: +This code will handle catching any exceptions thrown by [`FirstOrDefaultAsync`](https://learn.microsoft.com/en-us/dotnet/api/system.data.entity.queryableextensions.firstordefaultasync) and will return a [`NotFoundError`](~/api/Rascal.Errors.NotFoundError.yml) if the user isn't found. Now you can use this method as such: # [Minimal API](#tab/minimal) @@ -140,13 +140,13 @@ public sealed class UsersController(IUserService userService) : ControllerBase ### More samples -A plethora of additional code samples are available in the [samples](/samples/index.html) section of the documentation. +A plethora of additional code samples are available in the [samples](~/samples/index.md) section of the documentation.
### Explore the API -Once you're ready to dive into the library, feel free to refer to the [API documentation](/api/index.html) for an in-depth look into each of the methods provided by the library. You can of course also explore the API through intellisense in your IDE of choice. +Once you're ready to dive into the library, feel free to refer to the [API documentation](~/api/index.md) for an in-depth look into each of the methods provided by the library. You can of course also explore the API through intellisense in your IDE of choice.
diff --git a/docs/samples/index.md b/docs/samples/index.md index 9c30202..889d22f 100644 --- a/docs/samples/index.md +++ b/docs/samples/index.md @@ -4,7 +4,7 @@ This article contains a variety of code samples demonstrating common usages for ## Creating results -Results in Rascal can be created in a variety of ways, the two most common of which are through the [`Ok`](/api/Rascal.Prelude.html#Rascal_Prelude_Ok__1___0_) and [`Err`](/api/Rascal.Prelude.html#Rascal_Prelude_Err__1_Rascal_Error_) methods defined in the prelude, or through implicitly converting ok values or errors into results. +Results in Rascal can be created in a variety of ways, the two most common of which are through the [`Ok`](~/api/Rascal.Prelude.yml#Rascal_Prelude_Ok__1___0_) and [`Err`](~/api/Rascal.Prelude.yml#Rascal_Prelude_Err__1_Rascal_Error_) methods defined in the prelude, or through implicitly converting ok values or errors into results. [!code-csharp[](../../samples/Construction.csx#L7-L13)] @@ -12,30 +12,30 @@ Results in Rascal can be created in a variety of ways, the two most common of wh ## Mapping -"Mapping" refers to taking a result containing some value some type (`T`) and *mapping* said value to a new value of some other type (`TNew`). The principal method of mapping is the aptly named [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__). +"Mapping" refers to taking a result containing some value some type (`T`) and *mapping* said value to a new value of some other type (`TNew`). The principal method of mapping is the aptly named [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__). [!code-csharp[](../../samples/Map.csx#L6-L14)]
-Another operation, commonly referred to as "bind" or "chaining", exists, which looks quite similar to mapping, the only difference being that the lambda you supply to the method returns a *new* result rather than a plain value. The principal method of chaining is [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___), which can be read as "a, then b, then c". +Another operation, commonly referred to as "bind" or "chaining", exists, which looks quite similar to mapping, the only difference being that the lambda you supply to the method returns a *new* result rather than a plain value. The principal method of chaining is [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___), which can be read as "a, then b, then c". [!code-csharp[](../../samples/Then.csx#L6-L19)]
-[`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) and [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) together make up the core of the [`Result`](/api/Rascal.Result-1.html) type, allowing for chaining multiple operations on a single result. In functional terms, these are what makes [`Result`](/api/Rascal.Result-1.html) a functor and monad respectively (although not an applicative). +[`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) and [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) together make up the core of the [`Result`](~/api/Rascal.Result-1.yml) type, allowing for chaining multiple operations on a single result. In functional terms, these are what makes [`Result`](~/api/Rascal.Result-1.yml) a functor and monad respectively (although not an applicative).
> [!TIP] -> The aliases [`Select`](/api/Rascal.Result-1.html#Rascal_Result_1_Select__1_System_Func__0___0__) and [`SelectMany`](/api/Rascal.Result-1.html#Rascal_Result_1_SelectMany__1_System_Func__0_Rascal_Result___0___) are available for [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) and [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) respectively. These exist to supply support for *query expressions* as an alternative to method chaining. Query syntax can in specific situations be more readable than the method chaining alternative, although in *most* scenarios, method chaning is better. [`Select`](/api/Rascal.Result-1.html#Rascal_Result_1_Select__1_System_Func__0___0__) and [`SelectMany`](/api/Rascal.Result-1.html#Rascal_Result_1_SelectMany__1_System_Func__0_Rascal_Result___0___) should ***not*** be used outside query syntax. +> The aliases [`Select`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Select__1_System_Func__0___0__) and [`SelectMany`](~/api/Rascal.Result-1.yml#Rascal_Result_1_SelectMany__1_System_Func__0_Rascal_Result___0___) are available for [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) and [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) respectively. These exist to supply support for *query expressions* as an alternative to method chaining. Query syntax can in specific situations be more readable than the method chaining alternative, although in *most* scenarios, method chaning is better. [`Select`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Select__1_System_Func__0___0__) and [`SelectMany`](~/api/Rascal.Result-1.yml#Rascal_Result_1_SelectMany__1_System_Func__0_Rascal_Result___0___) should ***not*** be used outside query syntax.
### Combine -[`Combine`](/api/Rascal.Result-1.html#Rascal_Result_1_Combine__1_Rascal_Result___0__) is an addition to [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) and [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) which streamlines the specific case where you have two results and want to *combine* them into a single result only if both results are ok. +[`Combine`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Combine__1_Rascal_Result___0__) is an addition to [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) and [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___) which streamlines the specific case where you have two results and want to *combine* them into a single result only if both results are ok. [!code-csharp[](../../samples/Combine.csx#L6-L15)] @@ -53,12 +53,12 @@ Rascal supports a simple way of validating the value of a result, returning an e One of the major kinks of adapting C# into a more functional style (such as using results) is the already existing standard of using exceptions for error-handling. Exceptions have *many* flaws, and result types explicitly exist to provide a better alternative to exceptions, but Rascal nontheless provides a way to interoperate with traditional exception-based error handling. -The [`Try`](/api/Rascal.Prelude.html#Rascal_Prelude_Try__1_System_Func___0__) method in the prelude is the premiere exception-handling method, which runs another function inside a `try`-`catch` block, and returns an [`ExceptionError`](/api/Rascal.Errors.ExceptionError.html) in case an exception is thrown. +The [`Try`](~/api/Rascal.Prelude.yml#Rascal_Prelude_Try__1_System_Func___0__) method in the prelude is the premiere exception-handling method, which runs another function inside a `try`-`catch` block, and returns an [`ExceptionError`](~/api/Rascal.Errors.ExceptionError.yml) in case an exception is thrown. [!code-csharp[](../../samples/Try.csx#L6-L11)]
-`Try` variants also exist for [`Map`](/api/Rascal.Result-1.html#Rascal_Result_1_Map__1_System_Func__0___0__) and [`Then`](/api/Rascal.Result-1.html#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___), namely [`TryMap`](/api/Rascal.Result-1.html#Rascal_Result_1_TryMap__1_System_Func__0___0__) and [`ThenTry`](/api/Rascal.Result-1.html#Rascal_Result_1_ThenTry__1_System_Func__0_Rascal_Result___0___). +`Try` variants also exist for [`Map`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Map__1_System_Func__0___0__) and [`Then`](~/api/Rascal.Result-1.yml#Rascal_Result_1_Then__1_System_Func__0_Rascal_Result___0___), namely [`TryMap`](~/api/Rascal.Result-1.yml#Rascal_Result_1_TryMap__1_System_Func__0___0__) and [`ThenTry`](~/api/Rascal.Result-1.yml#Rascal_Result_1_ThenTry__1_System_Func__0_Rascal_Result___0___). [!code-csharp[](../../samples/TryMap.csx#L6-L11)]