{"id":16569210,"url":"https://github.com/rich-iannone/messaging","last_synced_at":"2025-10-13T11:38:34.469Z","repository":{"id":56937251,"uuid":"123668640","full_name":"rich-iannone/messaging","owner":"rich-iannone","description":"Conveniently issue messages, warnings, and errors","archived":false,"fork":false,"pushed_at":"2021-07-07T02:00:14.000Z","size":42,"stargazers_count":12,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-11T16:59:41.568Z","etag":null,"topics":["errors","functions","messages","r","warnings"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rich-iannone.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-03T07:09:41.000Z","updated_at":"2023-07-25T17:17:46.000Z","dependencies_parsed_at":"2022-08-21T06:50:11.190Z","dependency_job_id":null,"html_url":"https://github.com/rich-iannone/messaging","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rich-iannone%2Fmessaging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rich-iannone%2Fmessaging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rich-iannone%2Fmessaging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rich-iannone%2Fmessaging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rich-iannone","download_url":"https://codeload.github.com/rich-iannone/messaging/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244135908,"owners_count":20403798,"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":["errors","functions","messages","r","warnings"],"created_at":"2024-10-11T21:12:45.589Z","updated_at":"2025-10-13T11:38:29.450Z","avatar_url":"https://github.com/rich-iannone.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n[![Travis build status](https://travis-ci.org/rich-iannone/messaging.svg?branch=master)](https://travis-ci.org/rich-iannone/messaging)\n[![Coverage status](https://codecov.io/gh/rich-iannone/messaging/branch/master/graph/badge.svg)](https://codecov.io/github/rich-iannone/messaging?branch=master)\n[![CRAN status](https://www.r-pkg.org/badges/version/messaging)](https://cran.r-project.org/package=messaging)\n\n# The **messaging** Package\n\nThe goal of **messaging** is to provide a toolset for creating and issuing nicely-formatted text within R diagnostic messages and those messages given during warnings and errors. The formatting of the messages can be customized using templating features. Issues with singular and plural forms can be handled through specialized syntax.\n\n## Example for Emitting Messages\n\nFor for the purpose of demonstrating how **messaging** can help you format and issue messages, we can create a function (`yield_a_message()`) that uses the `emit_message()` function for the sole purpose of displaying a message.\n\n```{r}\nlibrary(messaging)\n\nyield_a_message \u003c- function() {\n  \n  # This function's only aim is to produce\n  # a message; throughout the function body, we\n  # can generate objects that can be assembled\n  # into a customizable message with `emit_message()`\n  \n  # Create some strings can serve as additional\n  # info for the message \n  important_message_parts \u003c- \n    c(\"* message info part 1\",\n      \"* message info part 2\",\n      \"* message info part 3\")\n  \n  # Get a numeric value to use in the message\n  n_info_lines \u003c- length(important_message_parts)\n  \n  # Generate and emit a formatted message\n  emit_message(\n    \"There (is/are) {number} thing(s) to note\", # on line 1; singular/plural syntax\n    important_message_parts, # 3 additional lines (all lines are separated with `/n`)\n    number = n_info_lines, # a named argument; `n_info_lines` inserted into {number}\n    .format = \"{.f_name} info: {text}\") # an optional template\n}\n```\n\nWithin the main function body, there's the creation of character (`important_message_parts`) and numeric (`number_of_info_lines`) values that will help us compose our message. This combination of function-scope objects will work alongside templated expression strings in the `emit_message()` function. Multiple expression strings can be provided to `emit_message()` to serve as components of the message (newlines will separate each of the expressions provided).\n\nUsing curly braces, we can enable text interpolation (e.g., `The number is {number} and this is considered {level}`) where named arguments (e.g., `number = 3`, `level = \"high\"`, etc.) provide the values for the message components. \n\nIf there is interpolation of numerical values, there is also the option to provide singular and plural forms for words associated with the the values. Simply enclose the singular and plural alternatives in parentheses and the function will finalize the statement based on the associated numerical values. Some syntax examples are: `(is/are)`, `analys(is/es)`, `result(s)`.\n\nUpon calling `yield_a_message()` we see that a message does appear and that the text on the first line has been processed such that it's grammatically correct.  \n\n```{r}\n# Call the `yield_a_message()` function\nyield_a_message()\n```\n\nWe can also emit warnings and errors by using the `emit_warning()` and `emit_error()` functions within those functions of our own design. Here's a function that might provide a warning (if the sum of `x` and `y` is greater than 100):\n\n```{r}\nmight_warn_you \u003c- function(x, y) {\n  \n  sum_xy \u003c- x + y\n\n  if (sum_xy \u003e 100) {\n    emit_warning(\n      \"This value ({sum_xy}) is greater than 100.\",\n      sum_xy = sum_xy)\n  }\n  \n  return(sum_xy)\n}\n```\n\nThis won't warn:\n\n```{r}\nmight_warn_you(40, 50)\n```\n\nThis warns and provides the custom warning.\n\n```{r}\nmight_warn_you(60, 50)\n```\n\nWe can exit a function early with a message using the `emit_error()` function:\n\n```{r}\nwill_stop_if_not_careful \u003c- function(x, y) {\n  \n  sum_xy \u003c- x + y\n\n  if (sum_xy \u003e 100) {\n    emit_error(\n      \"This value ({sum_xy}) is greater than 100. That is bad.\",\n      sum_xy = sum_xy)\n  }\n  \n  return(sum_xy)\n}\n```\n\nThis function call will stop the function:\n\n```{r eval=FALSE}\nwill_stop_if_not_careful(60, 50)\n```\n\nHere is a reproduction of the error message:\n\n```\nError: `will_stop_if_not_careful()`: This value (110) is greater than 100. That is bad.\n```\n\n## Installation of the package\n\n**messaging** is used in an R environment. If you don't have an R installation, it can be obtained from the [**Comprehensive R Archive Network (CRAN)**](https://cran.r-project.org/).\n\nYou can install **messaging** from **CRAN** with `install.packages()`.\n\n```r\ninstall.packages(\"messaging\")\n```\n\nAlso, the development version of **messaging** from **GitHub** can be installed using the **devtools** package.\n\n```r\ndevtools::install_github(\"rich-iannone/messaging\")\n```\n\nIf you encounter a bug, have usage questions, or want to share ideas to make this package better, feel free to file an [issue](https://github.com/rich-iannone/messaging/issues).\n\n## Code of Conduct\n\n[Contributor Code of Conduct](https://github.com/rich-iannone/messaging/blob/master/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.\n\n## License\n\nMIT \u0026copy; Richard Iannone\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frich-iannone%2Fmessaging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frich-iannone%2Fmessaging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frich-iannone%2Fmessaging/lists"}