{"id":13858112,"url":"https://github.com/r-lib/zeallot","last_synced_at":"2025-12-12T01:05:15.954Z","repository":{"id":54675315,"uuid":"77959109","full_name":"r-lib/zeallot","owner":"r-lib","description":"Variable assignment with zeal! (or multiple, unpacking, and destructuring assignment in R)","archived":false,"fork":false,"pushed_at":"2025-04-26T13:04:27.000Z","size":253,"stargazers_count":260,"open_issues_count":8,"forks_count":14,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-26T14:20:01.901Z","etag":null,"topics":["destructuring-assignment","multiple-assignment","pattern-matching","r","unpacking-assignment"],"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/r-lib.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2017-01-03T22:33:47.000Z","updated_at":"2025-04-17T23:42:15.000Z","dependencies_parsed_at":"2025-04-26T14:20:06.196Z","dependency_job_id":"667a0927-a3e5-4619-b510-cee16be0c96f","html_url":"https://github.com/r-lib/zeallot","commit_stats":null,"previous_names":["nteetor/zeallot"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fzeallot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fzeallot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fzeallot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fzeallot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-lib","download_url":"https://codeload.github.com/r-lib/zeallot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252902671,"owners_count":21822273,"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":["destructuring-assignment","multiple-assignment","pattern-matching","r","unpacking-assignment"],"created_at":"2024-08-05T03:01:57.027Z","updated_at":"2025-12-12T01:05:15.894Z","avatar_url":"https://github.com/r-lib.png","language":"R","readme":"# zeallot\n\nVariable assignment with zeal!\n\n[coverage]: https://codecov.io/gh/r-lib/zeallot/branch/master/graph/badge.svg \"deep fat fry\"\n[cran]: https://www.r-pkg.org/badges/version/zeallot \"green means go!\"\n\n![alt text][coverage] ![alt text][cran]\n\n## What's there to be excited about?\n\nzeallot allows multiple, unpacking, or destructuring assignment in R by\nproviding the `%\u003c-%` operator. With zeallot you can tighten code with explicit\nvariable names, unpack pieces of a lengthy list or the entirety of a small list,\ndestructure and assign object elements, or do it all at once.\n\nUnpack a vector of values.\n```R\nc(x, y) %\u003c-% c(0, 1)\n#\u003e x\n#[1] 0\n#\u003e y\n#[1] 1\n```\n\nUnpack a list of values.\n```R\nc(r, d) %\u003c-% list(2, 2)\n#\u003e r\n#[1] 2\n#\u003e d\n#[1] 2\n```\n\nDestructure a data frame and assign its columns.\n```R\nc(duration, wait) %\u003c-% head(faithful)\n\n#\u003e duration\n#[1] 3.600 1.800 3.333 2.283 4.533 2.883\n#\u003e wait\n#[1] 79 54 74 62 85 55\n```\n\nUnpack a nested list into nested left-hand side variables.\n```R\nc(c(a, b), c(c, d)) %\u003c-% list(list(1, 2), list(3, 4))\n#\u003e a\n#[1] 1\n#\u003e b\n#[1] 2\n#\u003e c\n#[1] 3\n#\u003e d\n#[1] 4\n```\n\nDestructure and partially unpack a list. \"a\" is assigned to `first`, but\n\"b\", \"c\", \"d\", and \"e\" are grouped and assigned to one variable.\n```R\nc(first, ...rest) %\u003c-% list(\"a\", \"b\", \"c\", \"d\", \"e\")\nfirst\n#[1] \"a\"\nrest\n#[[1]]\n#[1] \"b\"\n#\n#[[2]]\n#[1] \"c\"\n#\n#[[3]]\n#[1] \"d\"\n#\n#[[4]]\n#[1] \"e\"\n```\n\n### Installation\n\nYou can install zeallot from CRAN.\n\n```R\ninstall.packages(\"zeallot\")\n```\n\nUse devtools to install the latest, development version of zeallot from GitHub.\n\n```R\ndevtools::install_github(\"nteetor/zeallot\")\n```\n\n## Getting Started\n\nBelow is a simple example using the [purrr](https://github.com/hadley/purrr)\npackage and the safely function.\n\n### Safe Functions\n\nThe `purrr::safely` function returns a \"safe\" version of a function. The\nfollowing example is borrowed from the safely documentation. In this example a\nsafe version of the log function is created.\n\n```R\nsafe_log \u003c- purrr::safely(log)\nsafe_log(10)\n#$result\n#[1] 2.302585\n#\n#$error\n#NULL\n\nsafe_log(\"a\")\n#$result\n#NULL\n#\n#$error\n#\u003csimpleError in .f(...): non-numeric argument to mathematical function\u003e\n```\n\nA safe function always returns a list of two elements and will not throw an\nerror. Instead of throwing an error, the error element of the return list is set\nand the value element is NULL. When called successfully the result element is\nset and the error element is NULL.\n\nSafe functions are a great way to write self-documenting code. However, dealing\nwith a return value that is always a list could prove tedious and may undo\nefforts to write concise, readable code. Enter zeallot.\n\n### The `%\u003c-%` Operator\n\nWith zeallot's unpacking operator `%\u003c-%` we can unpack a safe function's return\nvalue into two explicit variables and avoid dealing with the list return value\nall together.\n\n```R\nc(res, err) %\u003c-% safe_log(10)\nres\n#[1] 2.302585\nerr\n#NULL\n```\n\nThe name structure of the operator is a flat or nested set of bare variable\nnames built with calls to `c()`. . These variables do not need to be previously\ndefined. On the right-hand side is a vector, list, or other R object to unpack.\n`%\u003c-%` unpacks the right-hand side, checks the number of variable names against\nthe number of unpacked values, and then assigns each unpacked value to a\nvariable. The result, instead of dealing with a list of values there are two\ndistinct variables, `res` and `err`.\n\n### Further Reading and Examples\n\nFor more on the above example, other examples, and a thorough introduction to\nzeallot check out the vignette on [unpacking\nassignment](vignettes/unpacking-assignment.Rmd).\n\nBelow are links to discussions about multiple, unpacking, and destructuring\nassignment in R,\n\n* https://stackoverflow.com/questions/7519790/assign-multiple-new-variables-on-lhs-in-a-single-line-in-r\n* https://stackoverflow.com/questions/1826519/how-to-assign-from-a-function-which-returns-more-than-one-value\n\n## Related work\n\nThe [vadr](https://github.com/crowding/vadr) package includes a\n[bind](https://github.com/crowding/vadr/blob/master/R/bind.R#L65) operation\nwith much of the same functionality as `%\u003c-%`. As the author states, \"[they]\nstrongly prefer there to be a `\u003c-` anywhere that there is a modification to the\nenvironment.\" If you feel similarly I suggest looking at vadr. Unfortunately the\nvadr package is not on CRAN and will need to be installed using\n`devtools::install_github()`.\n\n---\n\nThank you to Paul Teetor for inspiring me to build zeallot.\n\nWithout his encouragement nothing would have gotten off the ground.\n","funding_links":[],"categories":["R"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fzeallot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-lib%2Fzeallot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fzeallot/lists"}