{"id":13437458,"url":"https://github.com/vubiostat/r-yaml","last_synced_at":"2025-09-11T03:02:39.411Z","repository":{"id":395159,"uuid":"13136","full_name":"vubiostat/r-yaml","owner":"vubiostat","description":"R package for converting objects to and from YAML","archived":false,"fork":false,"pushed_at":"2024-12-30T16:14:35.000Z","size":708,"stargazers_count":166,"open_issues_count":12,"forks_count":38,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-02-27T09:14:16.343Z","etag":null,"topics":["cran","r","yaml"],"latest_commit_sha":null,"homepage":"http://biostat.app.vumc.org/wiki/Main/YamlR","language":"C","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/vubiostat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2008-04-28T21:52:03.000Z","updated_at":"2025-01-16T16:45:31.000Z","dependencies_parsed_at":"2024-01-24T05:47:32.537Z","dependency_job_id":"319ee298-2efa-45a4-98a6-cf39ce3af60d","html_url":"https://github.com/vubiostat/r-yaml","commit_stats":{"total_commits":324,"total_committers":19,"mean_commits":17.05263157894737,"dds":0.6574074074074074,"last_synced_commit":"735fb414987e3e373d72570837b0938de399f84e"},"previous_names":["viking/r-yaml"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vubiostat%2Fr-yaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vubiostat%2Fr-yaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vubiostat%2Fr-yaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vubiostat%2Fr-yaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vubiostat","download_url":"https://codeload.github.com/vubiostat/r-yaml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244371067,"owners_count":20442332,"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":["cran","r","yaml"],"created_at":"2024-07-31T03:00:57.239Z","updated_at":"2025-03-19T06:31:11.472Z","avatar_url":"https://github.com/vubiostat.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"\nR YAML package\n==============\n\n[![](https://cranlogs.r-pkg.org/badges/yaml)](https://cran.r-project.org/package=yaml)\n[![R-CMD-check](https://github.com/vubiostat/r-yaml/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/vubiostat/r-yaml/actions/workflows/R-CMD-check.yaml)\n\nThe R [YAML](http://yaml.org) package implements the\n[libyaml](https://pyyaml.org/wiki/LibYAML) YAML parser and emitter for R.\n\n## Table of Contents\n\n* [What is YAML?](#what-is-yaml)\n* [Installation](#installation)\n* [Usage](#usage)\n  * [yaml.load](#yamlload)\n  * [yaml.load_file](#yamlload_file)\n  * [read_yaml](#read_yaml)\n  * [as.yaml](#asyaml)\n  * [write_yaml](#write_yaml)\n* [Development](#development)\n\n## What is YAML?\n\nYAML is a human-readable markup language. With it, you can create easily\nreadable documents that can be consumed by a variety of programming languages.\n\n### Examples\n\nHash of baseball teams per league:\n\n    american:\n    - Boston Red Sox\n    - Detroit Tigers\n    - New York Yankees\n    national:\n    - New York Mets\n    - Chicago Cubs\n    - Atlanta Braves\n\nData dictionary specification:\n\n    - field: ID\n      description: primary identifier\n      type: integer\n      primary key: yes\n    - field: DOB\n      description: date of birth\n      type: date\n      format: yyyy-mm-dd\n    - field: State\n      description: state of residence\n      type: string\n\n## Installation\n\n### CRAN\n\nYou can install this package directly from CRAN by running (from within R):\n`install.packages('yaml')`\n\n### Zip/Tarball\n\n1. Download the appropriate zip file or tar.gz file from the\n[Github releases](https://github.com/vubiostat/r-yaml/releases) page.\n2. Run `R CMD INSTALL \u003cfilename\u003e`\n\n### Git (via devtools)\n\n1. Install the `devtools` package from CRAN.\n2. In R, run the following:\n    ```R\n    library(devtools)\n    install_github('vubiostat/r-yaml')\n    ```\n\n## Usage\n\nThe `yaml` package provides three functions: `yaml.load`, `yaml.load_file` and\n`as.yaml`.\n\n### yaml.load\n\n`yaml.load` is the YAML parsing function. It accepts a YAML document as a\nstring. Here's a simple example that parses a YAML sequence:\n\n    x \u003c- \"\n    - 1\n    - 2\n    - 3\n    \"\n    yaml.load(x)  #=\u003e [1] 1 2 3\n\n#### Scalars\n\nA YAML scalar is the basic building block of YAML documents. Example of a YAML\ndocument with one element:\n\n    1.2345\n\nIn this case, the scalar \"1.2345\" is typed as a `float` (or numeric) by the\nparser.  `yaml.load` would return a numeric vector of length 1 for this\ndocument.\n\n    yaml.load(\"1.2345\")  #=\u003e [1] 1.2345\n\n#### Sequences\n\nA YAML sequence is a list of elements. Here's an example of a simple YAML\nsequence:\n\n    - this\n    - is\n    - a\n    - simple\n    - sequence\n    - of\n    - scalars\n\nIf you pass a YAML sequence to `yaml.load`, a couple of things can happen. If\nall of the elements in the sequence are uniform, `yaml.load` will return a\nvector of that type (i.e. character, integer, real, or logical). If the\nelements are _not_ uniform, `yaml.load` will return a list of the elements.\n\n#### Maps\n\nA YAML map is a list of paired keys and values, or hash, of elements. Here's\nan example of a simple YAML map:\n\n    one: 1\n    two: 2\n    three: 3\n    four: 4\n\nPassing a map to `yaml.load` will produce a named list by default. That is,\nkeys are coerced to strings. Since it is possible for the keys of a YAML map\nto be almost anything (not just strings), you might not want `yaml.load` to\nreturn a named list. If you want to preserve the data type of keys, you can\npass `as.named.list = FALSE` to `yaml.load`. If `as.named.list` is FALSE,\n`yaml.load` will create a `keys` attribute for the list it returns instead of\ncoercing the keys into strings.\n\n#### Handlers\n\n`yaml.load` has the capability to accept custom handler functions. With\nhandlers, you can customize `yaml.load` to do almost anything you want.\nExample of handler usage:\n\n    integer.handler \u003c- function(x) { as.integer(x) + 123 }\n    yaml.load(\"123\", handlers = list(int = integer.handler))  #=\u003e [1] 246\n\nHandlers are passed to `yaml.load` through the `handlers` argument. The\n`handlers` argument must be a named list of functions, where each name is the\nYAML type that you want to be handled by your function. The functions you\nprovide must accept one argument and must return an R object.\n\nHandler functions will be passed a string or list, depending on the original\ntype of the object. In the example above, `integer.handler` was passed the\nstring \"123\".\n\n##### Sequence handlers\n\nCustom sequence handlers will be passed a list of objects. You can then\nconvert the list into whatever you want and return it. Example:\n\n    sequence.handler \u003c- function(x) {\n      tmp \u003c- as.numeric(x)\n      tmp / 5\n    }\n    string \u003c- \"\n    - foo\n    - bar\n    - 123\n    - 4.567\n    \"\n    yaml.load(string, handlers = list(seq = sequence.handler))  #=\u003e [1]      NA      NA 24.6000  0.9134\n\n##### Map handlers\n\nCustom map handlers work much in the same way as custom list handlers. A map\nhandler function is passed a named list, or a list with a `keys` attribute\n(depending on the value of `as.named.list`). Example:\n\n    string \u003c- \"\n    a:\n    - 1\n    - 2\n    b:\n    - 3\n    - 4\n    \"\n    yaml.load(string, handlers = list(map = function(x) { as.data.frame(x) }))\n\nReturns:\n\n      a b\n    1 1 3\n    2 2 4\n\n### yaml.load_file\n\n`yaml.load_file` does the same thing as `yaml.load`, except it reads a file\nfrom a connection. For example:\n\n    x \u003c- yaml.load_file(\"Data/document.yml\")\n\nThis function takes the same arguments as `yaml.load`, with the exception that\nthe first argument is a filename or a connection.\n\n### read_yaml\n\nThe `read_yaml` function is a convenience function that works similarly to\nfunctions in the [readr package](https://cran.r-project.org/package=readr). You\ncan use it instead of `yaml.load_file` if you prefer.\n\n### as.yaml\n\n`as.yaml` is used to convert R objects into YAML strings. Example `as.yaml`\nusage:\n\n    x \u003c- as.yaml(1:5)\n    cat(x, \"\\n\")\n\nOutput from above example:\n\n    - 1\n    - 2\n    - 3\n    - 4\n    - 5\n\n#### Notable arguments\n\n##### indent\n\nYou can control the number of spaces used to indent by setting the `indent`\noption. By default, `indent` is 2.\n\nFor example:\n\n    cat(as.yaml(list(foo = list(bar = 'baz')), indent = 3))\n\nOutputs:\n\n    foo:\n       bar: baz\n\n##### indent.mapping.sequence\n\nBy default, sequences that are within a mapping context are not indented.\n\nFor example:\n\n    cat(as.yaml(list(foo = 1:10)))\n\nOutputs:\n\n    foo:\n    - 1\n    - 2\n    - 3\n    - 4\n    - 5\n    - 6\n    - 7\n    - 8\n    - 9\n    - 10\n\nIf you want sequences to be indented in this context, set the `indent.mapping.sequence` option to `TRUE`.\n\nFor example:\n\n    cat(as.yaml(list(foo = 1:10), indent.mapping.sequence=TRUE))\n\nOutputs:\n```\nfoo:\n  - 1\n  - 2\n  - 3\n  - 4\n  - 5\n  - 6\n  - 7\n  - 8\n  - 9\n  - 10\n```\n\n##### column.major\n\nThe `column.major` option determines how a data frame is converted into YAML.\nBy default, `column.major` is TRUE.\n\nExample of `as.yaml` when `column.major` is TRUE:\n\n    x \u003c- data.frame(a=1:5, b=6:10)\n    y \u003c- as.yaml(x, column.major = TRUE)\n    cat(y, \"\\n\")\n\nOutputs:\n\n    a:\n    - 1\n    - 2\n    - 3\n    - 4\n    - 5\n    b:\n    - 6\n    - 7\n    - 8\n    - 9\n    - 10\n\nWhereas:\n\n    x \u003c- data.frame(a=1:5, b=6:10)\n    y \u003c- as.yaml(x, column.major = FALSE)\n    cat(y, \"\\n\")\n\nOutputs:\n\n    - a: 1\n      b: 6\n    - a: 2\n      b: 7\n    - a: 3\n      b: 8\n    - a: 4\n      b: 9\n    - a: 5\n      b: 10\n\n##### handlers\n\nYou can specify custom handler functions via the `handlers` argument.\nThis argument must be a named list of functions, where the names are R object\nclass names (i.e., 'numeric', 'data.frame', 'list', etc).  The function(s) you\nprovide will be passed one argument (the R object) and can return any R object.\nThe returned object will be emitted normally.\n\n##### YAML 1.2(-ish) Logical Handling\n\nTo get YAML 1.2 like behavior for logical vectors, you can use the \n`verbatim_logical` handler function passed as the logical element of the \nhandlers list.\n\n```r\nas.yaml(c(TRUE, FALSE) , handlers = list(logical=verbatim_logical))\n```\n\n#### Special features\n\n##### Verbatim(-ish) text\n\nCharacter vectors that have a class of `'verbatim'` will not be quoted in the\noutput YAML document except when the YAML specification requires it.  This\nmeans that you cannot do anything that would result in an invalid YAML\ndocument, but you can emit strings that would otherwise be quoted.  This is\nuseful for changing how logical vectors are emitted. For example:\n\n```r\nas.yaml(c(TRUE, FALSE), handlers = list(\n  logical = function(x) {\n    result \u003c- ifelse(x, \"true\", \"false\")\n    class(result) \u003c- \"verbatim\"\n    return(result)\n  }\n))\n```\n\n##### Quoted Strings\n\nThere are times you might need to ensure a string scalar is quoted.  Apply a\nnon-null attribute of \"quoted\" to the string you need quoted and it will come\nout with double quotes around it.\n\n```r\nport_def \u003c- \"80:80\"\nattr(port_def, \"quoted\") \u003c- TRUE\nx \u003c- list(ports = list(port_def))\nas.yaml(x)\n```\n\n##### Custom tags\n\nYou can specify YAML tags for R objects by setting the `'tag'` attribute\nto a character vector of length 1.  If you set a tag for a vector, the tag\nwill be applied to the YAML sequence as a whole, unless the vector has only 1\nelement.  If you wish to tag individual elements, you must use a list of\n1-length vectors, each with a tag attribute.  Likewise, if you set a tag for\nan object that would be emitted as a YAML mapping (like a data frame or a\nnamed list), it will be applied to the mapping as a whole.  Tags can be used\nin conjunction with YAML deserialization functions like\n`yaml.load` via custom handlers, however, if you set an internal\ntag on an incompatible data type (like `!seq 1.0`), errors will occur\nwhen you try to deserialize the document.\n\n### write_yaml\n\nThe `write_yaml` function is a convenience function that works similarly to\nfunctions in the [readr package](https://cran.r-project.org/package=readr). It\ncalls `as.yaml` and writes the result to a file or a connection.\n\n### Additional documentation\n\nFor more information, run `help(package='yaml')` or `example('yaml-package')`\nfor some examples.\n\n## Development\n\nThere is a `Makefile` for use with\n[GNU Make](https://www.gnu.org/software/make/) to help with development. There\nare several `make` targets for building, debugging, and testing. You can run\nthese by executing `make \u003ctarget-name\u003e` if you have the `make` program\ninstalled.\n\n| Target name     | Description                                 |\n| --------------- | ------------------------------------------- |\n| `compile`       | Compile the source files                    |\n| `check`         | Run CRAN checks                             |\n| `gct-check`     | Run CRAN checks with gctorture              |\n| `test`          | Run unit tests                              |\n| `gdb-test`      | Run unit tests with gdb                     |\n| `valgrind-test` | Run unit tests with valgrind                |\n| `tarball`       | Create tarball suitable for CRAN submission |\n| `all`           | Default target, runs `compile` and `test`   |\n\n### Local development and testing in Docker\n\nIf you'd like to set up a local development and testing environment using Docker,\nyou can follow these instructions:\n\n* clone the repository\n\n```\ngit clone git@github.com:vubiostat/r-yaml.git\ncd r-yaml\n```\n\n* Start Docker container called r-yaml\n\n```\ndocker run -it --name r-yaml --workdir /opt -v$(pwd):/opt r-base:4.2.3 bash\n```\n\n* Install external dependencies\n\n```\napt-get update\napt-get install -y texlive-latex-base texlive-fonts-extra texlive-latex-recommended texlive-fonts-recommended\n```\n\n* Install RUint\n\n```\nRscript -e 'install.packages(\"RUnit\")'\n```\n\n* Run the tests\n\n```\nmake check\nmake test\n```\n\n* Exit from Docker container\n\n```\nexit\n```\n\n* Restart Docker container\n\n```\ndocker container start -i r-yaml\n```\n\n* Remove Docker container\n\n```\ndocker rm r-yaml\n```\n\n### Implicit tag discovery\n\nThe algorithm used whenever there is no YAML tag explicitly provided is located\nin the [implicit.re](src/implicit.re) file. This file is used to create the\n[implicit.c](src/implicit.c) file via the [re2c](http://re2c.org/) program. If\nyou want to change this algorithm, make your changes in `implicit.re`, not\n`implicit.c`. The `make` targets will automatically update the C file as needed,\nbut you'll need to have the `re2c` program installed for it to work.\n\n### VERSION file\n\nThe `VERSION` file is used to track the current version of the package.\nWarnings are displayed if the `DESCRIPTION` and `CHANGELOG` files are not\nproperly updated when creating a tarball. This is to help prevent problems\nduring the CRAN submission process.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvubiostat%2Fr-yaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvubiostat%2Fr-yaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvubiostat%2Fr-yaml/lists"}