{"id":14067278,"url":"https://github.com/RDocTaskForce/pkgcond","last_synced_at":"2025-07-30T00:33:08.877Z","repository":{"id":56935014,"uuid":"156271440","full_name":"RDocTaskForce/pkgcond","owner":"RDocTaskForce","description":"Classed Error and Warning Conditions","archived":false,"fork":false,"pushed_at":"2021-04-27T21:39:43.000Z","size":167,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-12T22:04:30.454Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"R","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/RDocTaskForce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-05T19:30:00.000Z","updated_at":"2024-02-15T09:59:16.000Z","dependencies_parsed_at":"2022-08-21T00:40:30.567Z","dependency_job_id":null,"html_url":"https://github.com/RDocTaskForce/pkgcond","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/RDocTaskForce/pkgcond","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RDocTaskForce%2Fpkgcond","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RDocTaskForce%2Fpkgcond/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RDocTaskForce%2Fpkgcond/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RDocTaskForce%2Fpkgcond/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RDocTaskForce","download_url":"https://codeload.github.com/RDocTaskForce/pkgcond/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RDocTaskForce%2Fpkgcond/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267785798,"owners_count":24144122,"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","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-08-13T07:05:31.084Z","updated_at":"2025-07-30T00:33:08.311Z","avatar_url":"https://github.com/RDocTaskForce.png","language":"R","readme":"# pkgcond \u003cimg src=\"man/figures/logo.png\" align=\"right\" height=140/\u003e\n[![Travis build status](https://travis-ci.org/RDocTaskForce/pkgcond.svg?branch=master)](https://travis-ci.org/RDocTaskForce/pkgcond)\n[![Coverage status](https://codecov.io/gh/RDocTaskForce/pkgcond/branch/master/graph/badge.svg)](https://codecov.io/github/RDocTaskForce/pkgcond?branch=master)\n\nThe goal of pkgcond is to facilitate the creation of errors, warnings,\nand messages (collectively called signals or conditions) that are more informative\nthan the base versions.\n\nSignals can be created through `pkg_error()`, `pkg_warning()` and `pkg_message()`.\nWhen these are used a scope is computed and used to create errors, warnings and \nsignals, respectively, with classes set to the combinations of the scope.\nThe scope, while is could be set explicitly, infers where the condition is created,\nand will typically include the function call and package name.\n\n\n## Installation\n\nYou can install the released version of pkgcond from [CRAN](https://CRAN.R-project.org) with:\n\n``` r\ninstall.packages(\"pkgcond\")\n```\n\n## Understanding Scope\n\nLet's consider a toy example to understand the scope.\nSay that we are creating a package named `hw` with a function `hello_world()`\ndefined as follows:\n\n```r\nhello_world \u003c- function(greeting = 'hello', who = 'world'){\n    if (!is.character(greeting) \u0026\u0026 length(greeting) == 1L) \n        pkg_error(\"greeting must be a string.\")\n    if (!is.character(who) \u0026\u0026 length(who) == 1L) \n        pkg_error(\"who must be a string.\")\n    pkg_message(paste(greeting, who))\n}\n```\nIf the function is called with the defaults the `pkg_message()` function will \nbe called.  The effect is the same as if a `base::message()` call were here; \nA message with \"hello world\" would appear in the console.  However,\n`pkg_message()` does a little more.  The base call would create a '`message`' object \nand signal it.  With `pkg_message()` since it was invoked inside the `hello_world()`\nfunction inside the `hw` package the scope would be set to `c('hw', 'hello_world')`\nThis in turn would be used to create the message signal with the following classes.\n\n* `hw::hello_world-message`\n* `hw::hello_world-condition`\n* `hw-message`\n* `hw-condition`\n* `message`\n* `condition`\n\nThe `pkg_error()` and `pkg_warning()` functions have similar scoping however with \nerror and warning replacing message, respectively.\n\nThis becomes really useful if one wishes to capture conditions.  This is done with \nthe `tryCatch()` function.  In this way one can easily catch the conditions that originate from a specific function call or a specific package while passing others through or handling them differently.\n\n```r\ntryCatch( hello_world(\"die\", stop)\n        , \"hw::hello_world-error\" = function(cond){\n            # This would handle the error that is raised from passing\n            # `stop` into the `hello_world function()\n            }\n        , \"hw-condition\" = function(cond){\n            # This would capture all error originating in the hw package\n            # that were signaled using any of the `pkg_*` functions.\n        }\n        # Errors that did not originate from the hw package or were created \n        # with the traditional stop, warning, or message functions\n        # will be passed through since they will not be \"Caught\"\n)\n```\n\n\n## Helpers included:\n\nThese functions are included with `pkgcond` to help create error messages.\n\n* `assert_that()`  This intentionally masks `assertthat::assert_that()` when an assertion fails from this call the scope is set as above but a type is also created that indicates this is a 'assertion failure' that can also be used to catch specific errors.\n* `comma_list()` takes a list of items and creates a correctly formatted (for English at least) comma separated list contained in a single string.\n* `collapse()` takes a character vector and collapses it to a single string separated by a space.\n* `collapse0()` same as previous but no space separating parts.\n* `lhs %\u003c\u003c% rhs` an infix operator version of paste but will attempt to coerce and collapse lhs and rhs as well.\n* `lhs %\u003c\u003c\u003c%` an infix operator version of paste0, will use collapse0 on lhs and rhs prior to concatenation of the two.\n* `lhs %\\% rhs` Similar to the previous two but separates with a new line.  This will use collapse prior to concatenation.\n* `._()` Used to enable translation for a signal message.  When used with a single argument acts as an alias for `gettext()` when given multiple arguments it wraps\n`gettextf()`.\n\n## Documentation\n\nThe `pkgcond` package is developed by the R Documentation Task Force, an \n[R Consortium](https://www.r-consortium.org)\n[Infrastructure Steering Committee working group](https://www.r-consortium.org/projects/isc-working-groups).\n\n","funding_links":[],"categories":["R"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRDocTaskForce%2Fpkgcond","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FRDocTaskForce%2Fpkgcond","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FRDocTaskForce%2Fpkgcond/lists"}