diff options
Diffstat (limited to 'aoc2023/build/packages/snag')
-rw-r--r-- | aoc2023/build/packages/snag/LICENCE | 211 | ||||
-rw-r--r-- | aoc2023/build/packages/snag/README.md | 81 | ||||
-rw-r--r-- | aoc2023/build/packages/snag/gleam.toml | 16 | ||||
-rw-r--r-- | aoc2023/build/packages/snag/include/snag_Snag.hrl | 1 | ||||
-rw-r--r-- | aoc2023/build/packages/snag/src/snag.app.src | 8 | ||||
-rw-r--r-- | aoc2023/build/packages/snag/src/snag.erl | 74 | ||||
-rw-r--r-- | aoc2023/build/packages/snag/src/snag.gleam | 141 |
7 files changed, 0 insertions, 532 deletions
diff --git a/aoc2023/build/packages/snag/LICENCE b/aoc2023/build/packages/snag/LICENCE deleted file mode 100644 index b8c2e9e..0000000 --- a/aoc2023/build/packages/snag/LICENCE +++ /dev/null @@ -1,211 +0,0 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2021 - present Louis Pilfold - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - - -## Runtime Library Exception to the Apache 2.0 License: ## - - - As an exception, if you use this Software to compile your source code and - portions of this Software are embedded into the binary product as a result, - you may redistribute such product without providing attribution as would - otherwise be required by Sections 4(a), 4(b) and 4(d) of the License. diff --git a/aoc2023/build/packages/snag/README.md b/aoc2023/build/packages/snag/README.md deleted file mode 100644 index aaedcf5..0000000 --- a/aoc2023/build/packages/snag/README.md +++ /dev/null @@ -1,81 +0,0 @@ -# Snag - -A Snag is a boilerplate-free ad-hoc error type. - -Use `Result(value, Snag)` (or the `snag.Result(value)` alias) in functions -that may fail. - -A low level message like "Unexpected status 401" or "No such file or -directory" can be confusing or difficult to debug, so use the `snag.context` -function to add extra contextual information. - -```gleam -import gleam/io -import my_app.{User} -import snag.{Result} - -pub fn log_in(user_id: Int) -> Result(User) { - try api_key = - my_app.read_file("api_key.txt") - |> snag.context("Could not load API key") - - try session_token = - user_id - |> my_app.create_session(api_key) - |> snag.context("Session creation failed") - - Ok(session_token) -} - -pub fn main() { - case log_in(42) { - Ok(session) -> io.println("Logged in!") - Error(snag) -> { - io.print(snag.pretty_print(snag)) - my_app.exit(1) - } - } -} -``` - -In this code when an error occurs within the `create_session` function an -error message like this is printed using the added contextual information: - -```text -error: Session creation failed - -cause: - 0: Unable to exchange token with authentication service - 1: Service authentication failed - 2: Unexpected HTTP status 401 -``` - -## When should I use Snag? - -Snag is useful in code where it must either pass or fail, and when it fails we -want good debugging information to print to the user. i.e. Command line -tools, data processing pipelines, etc. Here Snag provides a convenient way to -create errors with a reasonable amount of debugging information, without the -boilerplate of a custom error type. - -It is not suited to code where the application needs to make a decision about -what to do in the event of an error, such as whether to give up or to try -again. i.e. Libraries, web application backends, API clients, etc. In these -situations it is recommended to create a custom type for your errors as it -can be pattern matched on and have any additional detail added as fields. - -## Installation - -Add `snag` to your Gleam project - -``` -gleam add snag -``` - -## Prior art - -This library is inspired by the following projects: - -- Rust's [`anyhow`](https://github.com/dtolnay/anyhow) and - [`std::error::Error`](https://doc.rust-lang.org/std/error/trait.Error.html) -- Go's [`error`](https://golang.org/pkg/errors/). diff --git a/aoc2023/build/packages/snag/gleam.toml b/aoc2023/build/packages/snag/gleam.toml deleted file mode 100644 index 4f2d670..0000000 --- a/aoc2023/build/packages/snag/gleam.toml +++ /dev/null @@ -1,16 +0,0 @@ -name = "snag" -version = "0.2.1" -licences = ["Apache-2.0"] -description = "A boilerplate-free ad-hoc error type" - -repository = { type = "github", user = "gleam-experiments", repo = "snag" } -links = [ - { title = "Website", href = "https://gleam.run" }, - { title = "Sponsor", href = "https://github.com/sponsors/lpil" }, -] - -[dependencies] -gleam_stdlib = "~> 0.18" - -[dev-dependencies] -gleeunit = "~> 0.5" diff --git a/aoc2023/build/packages/snag/include/snag_Snag.hrl b/aoc2023/build/packages/snag/include/snag_Snag.hrl deleted file mode 100644 index 5d6614e..0000000 --- a/aoc2023/build/packages/snag/include/snag_Snag.hrl +++ /dev/null @@ -1 +0,0 @@ --record(snag, {issue :: binary(), cause :: list(binary())}). diff --git a/aoc2023/build/packages/snag/src/snag.app.src b/aoc2023/build/packages/snag/src/snag.app.src deleted file mode 100644 index 175e326..0000000 --- a/aoc2023/build/packages/snag/src/snag.app.src +++ /dev/null @@ -1,8 +0,0 @@ -{application, snag, [ - {vsn, "0.2.1"}, - {applications, [gleam_stdlib, - gleeunit]}, - {description, "A boilerplate-free ad-hoc error type"}, - {modules, [snag]}, - {registered, []} -]}. diff --git a/aoc2023/build/packages/snag/src/snag.erl b/aoc2023/build/packages/snag/src/snag.erl deleted file mode 100644 index a07f242..0000000 --- a/aoc2023/build/packages/snag/src/snag.erl +++ /dev/null @@ -1,74 +0,0 @@ --module(snag). --compile([no_auto_import, nowarn_unused_vars]). - --export([new/1, error/1, layer/2, context/2, pretty_print/1, line_print/1]). --export_type([snag/0]). - --type snag() :: {snag, binary(), list(binary())}. - --spec new(binary()) -> snag(). -new(Issue) -> - {snag, Issue, []}. - --spec error(binary()) -> {ok, any()} | {error, snag()}. -error(Issue) -> - {error, new(Issue)}. - --spec layer(snag(), binary()) -> snag(). -layer(Snag, Issue) -> - {snag, Issue, [erlang:element(2, Snag) | erlang:element(3, Snag)]}. - --spec context({ok, EXX} | {error, snag()}, binary()) -> {ok, EXX} | - {error, snag()}. -context(Result, Issue) -> - case Result of - {ok, _} -> - Result; - - {error, Snag} -> - {error, layer(Snag, Issue)} - end. - --spec pretty_print_cause(list(binary())) -> gleam@string_builder:string_builder(). -pretty_print_cause(Cause) -> - _pipe = Cause, - _pipe@1 = gleam@list:index_map( - _pipe, - fun(Index, Line) -> - gleam@string:concat( - [<<" "/utf8>>, - gleam@int:to_string(Index), - <<": "/utf8>>, - Line, - <<"\n"/utf8>>] - ) - end - ), - gleam@string_builder:from_strings(_pipe@1). - --spec pretty_print(snag()) -> binary(). -pretty_print(Snag) -> - Builder = gleam@string_builder:from_strings( - [<<"error: "/utf8>>, erlang:element(2, Snag), <<"\n"/utf8>>] - ), - gleam@string_builder:to_string(case erlang:element(3, Snag) of - [] -> - Builder; - - Cause -> - _pipe = Builder, - _pipe@1 = gleam@string_builder:append( - _pipe, - <<"\ncause:\n"/utf8>> - ), - gleam@string_builder:append_builder( - _pipe@1, - pretty_print_cause(Cause) - ) - end). - --spec line_print(snag()) -> binary(). -line_print(Snag) -> - _pipe = [gleam@string:append(<<"error: "/utf8>>, erlang:element(2, Snag)) | - erlang:element(3, Snag)], - gleam@string:join(_pipe, <<" <- "/utf8>>). diff --git a/aoc2023/build/packages/snag/src/snag.gleam b/aoc2023/build/packages/snag/src/snag.gleam deleted file mode 100644 index 8d39537..0000000 --- a/aoc2023/build/packages/snag/src/snag.gleam +++ /dev/null @@ -1,141 +0,0 @@ -import gleam -import gleam/string_builder -import gleam/string -import gleam/list -import gleam/int - -/// A Snag is a boilerplate-free error type that can be used to track why an -/// error happened, though does not store as much detail on specific errors as a -/// custom error type would. -/// -/// It is useful in code where it must either pass or fail, and when it fails we -/// want good debugging information to print to the user. i.e. Command line -/// tools, data processing pipelines, etc. -/// -/// If it not suited to code where the application needs to make a decision about -/// what to do in the event of an error, such as whether to give up or to try -/// again. i.e. Libraries, web application backends, API clients, etc. -/// In these situations it is recommended to create a custom type for your errors -/// as it can be pattern matched on and have any additional detail added as -/// fields. -pub type Snag { - Snag(issue: String, cause: List(String)) -} - -/// A concise alias for a `Result` that uses a `Snag` as the error value. -pub type Result(t) = - gleam.Result(t, Snag) - -/// Create a new `Snag` with the given issue text. -/// -/// See also the `error` function for creating a `Snag` wrapped in a `Result`. -/// -/// # Example -/// -/// ```gleam -/// > new("Not enough credit") -/// > |> line_print -/// "error: Not enough credit" -/// ``` -pub fn new(issue: String) -> Snag { - Snag(issue: issue, cause: []) -} - -/// Create a new `Snag` wrapped in a `Result` with the given issue text. -/// -/// # Example -/// -/// ```gleam -/// > error("Not enough credit") -/// Error(new("Not enough credit")) -/// ``` -pub fn error(issue: String) -> Result(success) { - Error(new(issue)) -} - -/// Add additional contextual information to a `Snag`. -/// -/// See also the `context` function for adding contextual information to a `Snag` -/// wrapped in a `Result`. -/// -/// # Example -/// -/// ```gleam -/// > new("Not enough credit") -/// > |> layer("Unable to make purchase") -/// > |> line_print -/// "error: Unable to make purchase <- Not enough credit" -/// ``` -pub fn layer(snag: Snag, issue: String) -> Snag { - Snag(issue: issue, cause: [snag.issue, ..snag.cause]) -} - -/// Add additional contextual information to a `Snag` wrapped in a `Result`. -/// -/// # Example -/// -/// ```gleam -/// > error("Not enough credit") -/// > |> context("Unable to make purchase") -/// > |> result.map_error(line_print) -/// Error("error: Unable to make purchase <- Not enough credit") -/// ``` -pub fn context(result: Result(success), issue: String) -> Result(success) { - case result { - Ok(_) -> result - Error(snag) -> Error(layer(snag, issue)) - } -} - -/// Turn a snag into a multi-line string, optimised for readability. -/// -/// # Example -/// -/// ```gleam -/// > new("Not enough credit") -/// > |> layer("Unable to make purchase") -/// > |> layer("Character creation failed") -/// > |> pretty_print -/// "error: Character creation failed -/// -/// cause: -/// 0: Unable to make purchase -/// 1: Not enough credit -/// " -/// ``` -pub fn pretty_print(snag: Snag) -> String { - let builder = string_builder.from_strings(["error: ", snag.issue, "\n"]) - - string_builder.to_string(case snag.cause { - [] -> builder - cause -> - builder - |> string_builder.append("\ncause:\n") - |> string_builder.append_builder(pretty_print_cause(cause)) - }) -} - -fn pretty_print_cause(cause) { - cause - |> list.index_map(fn(index, line) { - string.concat([" ", int.to_string(index), ": ", line, "\n"]) - }) - |> string_builder.from_strings -} - -/// Turn a snag into a single-line string, optimised for compactness. This may be -/// useful for logging snags. -/// -/// # Example -/// -/// ```gleam -/// > new("Not enough credit") -/// > |> layer("Unable to make purchase") -/// > |> layer("Character creation failed") -/// > |> pretty_print -/// "error: Character creation failed <- Unable to make purchase <- Not enough credit" -/// ``` -pub fn line_print(snag: Snag) -> String { - [string.append("error: ", snag.issue), ..snag.cause] - |> string.join(" <- ") -} |