{"id":16965003,"url":"https://github.com/propensive/digression","last_synced_at":"2025-04-05T15:46:04.960Z","repository":{"id":80754931,"uuid":"593625930","full_name":"propensive/digression","owner":"propensive","description":"Utilities for working with exceptions in Scala","archived":false,"fork":false,"pushed_at":"2025-01-29T18:35:40.000Z","size":2718,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-28T20:49:17.931Z","etag":null,"topics":["error","error-message","error-messages","exceptions","scala"],"latest_commit_sha":null,"homepage":"https://soundness.dev/digression/","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/propensive.png","metadata":{"files":{"readme":".github/readme.md","changelog":null,"contributing":".github/contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-26T13:31:37.000Z","updated_at":"2025-01-29T18:35:44.000Z","dependencies_parsed_at":"2023-12-20T08:02:46.045Z","dependency_job_id":"b7e594cd-c036-48f8-862c-f3f8f9dacda8","html_url":"https://github.com/propensive/digression","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Fdigression","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Fdigression/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Fdigression/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/propensive%2Fdigression/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/propensive","download_url":"https://codeload.github.com/propensive/digression/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247361598,"owners_count":20926642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error","error-message","error-messages","exceptions","scala"],"created_at":"2024-10-13T23:44:48.890Z","updated_at":"2025-04-05T15:46:04.926Z","avatar_url":"https://github.com/propensive.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"[\u003cimg alt=\"GitHub Workflow\" src=\"https://img.shields.io/github/actions/workflow/status/propensive/digression/main.yml?style=for-the-badge\" height=\"24\"\u003e](https://github.com/propensive/digression/actions)\n[\u003cimg src=\"https://img.shields.io/discord/633198088311537684?color=8899f7\u0026label=DISCORD\u0026style=for-the-badge\" height=\"24\"\u003e](https://discord.com/invite/MBUrkTgMnA)\n\u003cimg src=\"/doc/images/github.png\" valign=\"middle\"\u003e\n\n# Digression\n\n__Make Scala stack traces more understandable__\n\nStack traces correspond to the classes, interfaces and methods as they exist on\nthe running JVM. The Scala definitions from which they originate may have\nundergone various name changes during compilation, and features of Scala which\ndo not exist in Java may have been encoded in method and class names, such that\nthe original Scala names and features are harder to discern. _Digression_\nbelieves that a Scala developer (particularly a beginner, who will still be\nexposed to stack traces) should not have to understand how Scala is encoded in\norder to work with the language.\n\n## Features\n\n- decodes Scala encodings in stack traces\n- disambiguates between objects and types in stack frames\n- syntax highlights stack traces\n- tabulates stack traces to make them easier to read\n- introduces a `Codepoint` contextual value containing the sourcefile and line\n\n\n## Availability\n\n\n\n\n\n\n\n## Getting Started\n\n### `safely` and `unsafely`\n\nWhen `language.experimental.saferExceptions` is enabled, any expression which\nmay throw an exception must be handled with a `try`/`catch`, or the exception\ndeclared in its signature.  Sometimes, we know enough about the execution state\nto circumvent this.\n\nIf we know that the exception will not be thrown (or we are confident that it\ndoesn't matter!), then we can wrap the expression in `unsafely`, for example,\ninvoking a `send()` method which could throw a `SendError`,\n```scala\ndef send(): Response throws SendError = ...\n```\ncan be performed without any error handling with:\n```scala\nimport digression.*\nimport language.experimental.saferExceptions\n\nval response: Response = unsafely(send())\n```\n\nThe `unsafely` method works by providing a contextual `CanThrow[Exception]`\ninstance in its parameter.\n\nThe `safely` method can be used in the same way, but will catch thrown\nexceptions and convert them to the `Unset` value, effectively changing the\nreturn type from `ReturnType` to `Maybe[ReturnType]`.\n\nThis is useful in cases where an exception may be expected, but enough is known\nabout it to handle it without examining it. An additional use-case is\n_fire-and-forgat_ method calls where we care neither about the normal nor an\nexceptional result.\n\n### `Codepoint`\n\nA method may request a `Codepoint` value in `using` clause, like so:\n```scala\ndef callMe()(using codepoint: Codepoint): Unit\n```\n\nThe `codepoint` parameter will contain, _at runtime_, two values which will be\ncomputed _during compilation_ at the callsite: the source file of the callsite,\nand the line number of that file.\n\nSo, compiling a file called `src/tests.scala` which contains calls to\n`callMe()` on lines `138` and `211` will provide the instances,\n`Codepoint(\"src/tests.scala\", 138)` and `Codepoint(\"src/tests.scala\", 211)` as\n`using` parameters to these invocations.\n\nSubsequent recompilations may, of course, potentially change the line numbers\nif the invocations move within the file.\n\n### The `Error` type and `err\"\"` messages\n\nError messages for exceptions are usually constructed as a single string. For\nmost purposes, this is sufficient, but by eagerly converting the exception's\nparameters to strings, it makes a compromise on the flexibility of the message\nat a later time when it may be presented to a user.\n\nA typical exception will include one or more parameters, which capture,\nsomehow, the conditions in which the exception was thrown. An error message\nwill present those parameters in context, in a human-readable form, for\n(usually) a programmer to decipher. However, converting those parameters to\nstrings at the point of costruction makes it impossible to inspect them later,\nand capturing the parameters in the exception independently of the message\nwould duplicate them unnecessarily. One particular compromise made is the\ninability to distinguish between the parts of the message that are static for\nall instances of the exception, and those which vary depending on its state.\n\nThe essence of an uncompromising, structured error message would be a `Tuple` of\n_n_ parameters, with _n + 1_ fragments of text interleaving it. For example, an\nerror message about a missing file could be structured,\n```scala\ncase class MissingFile(dir: Directory, child: Text) extends Exception\n```\nwith a message that reads:\n```scala\nt\"The directory $dir did not contain the file $child.\"\n```\n\nBy representing this as the tuple, `(dir: Directory, child: Text)` and the\ntext fragments, `List(t\"The directory \", t\" did not contain the file \", t\".\")`,\nwe would store precisely the state we want, and is provided in\n[Rudiments](https://github.com/propensive/rudiments/)' `ErrorMessage` type:\n```scala\nimport rudiments.*\nval dir: Directory = ...\nval child: Text = ...\nval message = ErrorMessage[(Directory, Text)](List(t\"The directory \",\n    t\" did not contain the file \", t\".\"), (dir, child))\n```\n\nUnfortunately, this is a very inconvenient way to write a message.\n\nThe `err\"\"` interpolator constructs an instance of `ErrorMessage` without such\nconvoluted code:\n```scala\nval message = err\"The directory $directory did not contain the file $child.\"\n```\n\nCombining this with Digression's `Error` class, distinct from\n`java.lang.Error`, provides a convenient way of defining a new exception type:\n```scala\nimport digression.*\ncase class MissingFile(dir: Directory, child: Text)\nextends Error(err\"The directory $directory did not contain the file $child.\")\n```\n\n### Rewritten stack traces\n\nDigression provides an immutable representation of an exception's stack trace,\ncalled `StackTrace`, constructed from a `Throwable`, but with stack frames\nrewritten to make it easier to relate Java's raw method names with the Scala\ncode which created them.\n\nThis includes the following rewrites:\n - symbolic names are decoded\n - class vs object calls are distinguished with `#` or `.`\n - primitives are written with full names\n - package file objects and extenion methods are indicated as such\n - lambdas and anonymous classes are identified\n - `Function` types are written inline\n\n[Escapade](https://github.com/propensive/escapade) provides a contextual\n`AnsiShow` instance for `StackTrace`, and by extension, `Exception`.\n\n\n\n\n## Status\n\nDigression is classified as __fledgling__. For reference, Soundness projects are\ncategorized into one of the following five stability levels:\n\n- _embryonic_: for experimental or demonstrative purposes only, without any guarantees of longevity\n- _fledgling_: of proven utility, seeking contributions, but liable to significant redesigns\n- _maturescent_: major design decisions broady settled, seeking probatory adoption and refinement\n- _dependable_: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version `1.0.0` or later\n- _adamantine_: proven, reliable and production-ready, with no further breaking changes ever anticipated\n\nProjects at any stability level, even _embryonic_ projects, can still be used,\nas long as caution is taken to avoid a mismatch between the project's stability\nlevel and the required stability and maintainability of your own project.\n\nDigression is designed to be _small_. Its entire source code currently consists\nof 313 lines of code.\n\n## Building\n\nDigression will ultimately be built by Fury, when it is published. In the\nmeantime, two possibilities are offered, however they are acknowledged to be\nfragile, inadequately tested, and unsuitable for anything more than\nexperimentation. They are provided only for the necessity of providing _some_\nanswer to the question, \"how can I try Digression?\".\n\n1. *Copy the sources into your own project*\n   \n   Read the `fury` file in the repository root to understand Digression's build\n   structure, dependencies and source location; the file format should be short\n   and quite intuitive. Copy the sources into a source directory in your own\n   project, then repeat (recursively) for each of the dependencies.\n\n   The sources are compiled against the latest nightly release of Scala 3.\n   There should be no problem to compile the project together with all of its\n   dependencies in a single compilation.\n\n2. *Build with [Wrath](https://github.com/propensive/wrath/)*\n\n   Wrath is a bootstrapping script for building Digression and other projects in\n   the absence of a fully-featured build tool. It is designed to read the `fury`\n   file in the project directory, and produce a collection of JAR files which can\n   be added to a classpath, by compiling the project and all of its dependencies,\n   including the Scala compiler itself.\n   \n   Download the latest version of\n   [`wrath`](https://github.com/propensive/wrath/releases/latest), make it\n   executable, and add it to your path, for example by copying it to\n   `/usr/local/bin/`.\n\n   Clone this repository inside an empty directory, so that the build can\n   safely make clones of repositories it depends on as _peers_ of `digression`.\n   Run `wrath -F` in the repository root. This will download and compile the\n   latest version of Scala, as well as all of Digression's dependencies.\n\n   If the build was successful, the compiled JAR files can be found in the\n   `.wrath/dist` directory.\n\n## Contributing\n\nContributors to Digression are welcome and encouraged. New contributors may like\nto look for issues marked\n[beginner](https://github.com/propensive/digression/labels/beginner).\n\nWe suggest that all contributors read the [Contributing\nGuide](/contributing.md) to make the process of contributing to Digression\neasier.\n\nPlease __do not__ contact project maintainers privately with questions unless\nthere is a good reason to keep them private. While it can be tempting to\nrepsond to such questions, private answers cannot be shared with a wider\naudience, and it can result in duplication of effort.\n\n## Author\n\nDigression was designed and developed by Jon Pretty, and commercial support and\ntraining on all aspects of Scala 3 is available from [Propensive\nO\u0026Uuml;](https://propensive.com/).\n\n\n\n## Name\n\nA _digression_ is a deviation from the main subject, much like an exception departs from the main path.\n\nIn general, Soundness project names are always chosen with some rationale,\nhowever it is usually frivolous. Each name is chosen for more for its\n_uniqueness_ and _intrigue_ than its concision or catchiness, and there is no\nbias towards names with positive or \"nice\" meanings—since many of the libraries\nperform some quite unpleasant tasks.\n\nNames should be English words, though many are obscure or archaic, and it\nshould be noted how willingly English adopts foreign words. Names are generally\nof Greek or Latin origin, and have often arrived in English via a romance\nlanguage.\n\n## Logo\n\nThe logo is an explosion, indicative of the most disastrous of exceptions.\n\n## License\n\nDigression is copyright \u0026copy; 2025 Jon Pretty \u0026 Propensive O\u0026Uuml;, and\nis made available under the [Apache 2.0 License](/license.md).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpropensive%2Fdigression","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpropensive%2Fdigression","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpropensive%2Fdigression/lists"}