{"id":20010426,"url":"https://github.com/magynhard/yaml_extend","last_synced_at":"2025-07-08T22:04:41.501Z","repository":{"id":48232149,"uuid":"99323168","full_name":"magynhard/yaml_extend","owner":"magynhard","description":"Ruby gem that extends YAML to support file based inheritance, including command line version","archived":false,"fork":false,"pushed_at":"2024-08-08T10:20:46.000Z","size":101,"stargazers_count":24,"open_issues_count":1,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-30T23:03:10.999Z","etag":null,"topics":["configuration","deep","environment","extend","file-extension","inheritance","ruby","ruby-gem","yaml","yaml-extension"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magynhard.png","metadata":{"files":{"readme":"README.md","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["magynhard"]}},"created_at":"2017-08-04T08:44:25.000Z","updated_at":"2024-08-05T14:35:54.000Z","dependencies_parsed_at":"2025-04-13T08:48:06.453Z","dependency_job_id":null,"html_url":"https://github.com/magynhard/yaml_extend","commit_stats":{"total_commits":53,"total_committers":9,"mean_commits":5.888888888888889,"dds":0.6415094339622642,"last_synced_commit":"5305026940446422783804d61830c458dba24d9a"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/magynhard/yaml_extend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magynhard%2Fyaml_extend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magynhard%2Fyaml_extend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magynhard%2Fyaml_extend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magynhard%2Fyaml_extend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magynhard","download_url":"https://codeload.github.com/magynhard/yaml_extend/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magynhard%2Fyaml_extend/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264357295,"owners_count":23595576,"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":["configuration","deep","environment","extend","file-extension","inheritance","ruby","ruby-gem","yaml","yaml-extension"],"created_at":"2024-11-13T07:19:44.972Z","updated_at":"2025-07-08T22:04:41.482Z","avatar_url":"https://github.com/magynhard.png","language":"Ruby","readme":"# yaml_extend\n[![Gem](https://img.shields.io/gem/v/yaml_extend?color=default\u0026style=plastic\u0026logo=ruby\u0026logoColor=red)](https://rubygems.org/gems/yaml_extend)\n![downloads](https://img.shields.io/gem/dt/yaml_extend?color=blue\u0026style=plastic)\n[![License: MIT](https://img.shields.io/badge/License-MIT-gold.svg?style=plastic\u0026logo=mit)](LICENSE)\n\n\u003e Extends YAML to support file based inheritance.\n\nThat can be very handy to build a configuration hierarchy.\n\nBasic support for ERB (embedded ruby) is included and automatically applied when config files are named `*.erb` or `*.erb.*`.\n\nIf you are just doing administration without knowing ruby, you can also just use the command line tool that is included to use this librarys features. Ensure, that [ruby](https://www.ruby-lang.org/) is installed on your system, before following further instructions. \n\n### Contents\n* [Common information](#common-information)\n* [Installation](#installation)\n* [Usage](#usage)\n* [Command line](#command-line-usage)\n* [Documentation](#documentation)\n* [Contributing](#contributing)\n\n\n\n\u003ca name=\"common-information\"\u003e\u003c/a\u003e    \n## Common information\n\nIt is possible to build inheritance trees like:\n```\n     defaults.yml   \n  ________\\_________    \n  \\        \\        \\                         \n dev.yml  int.yml  prod.yml                   \n```\nor like this:\n```\nfruits.yml   vegetables.yml          default.yml   extensions.yml       \n         \\    /                             \\    /                \n          food.yml                          merged.yml\n                                              |\n                                            another_extended.yml\n```\n\nA file can inherit from as many as you want. Trees can be nested as deep as you want.\n\nYAML files are deep merged, the latest specified child file overwrites the former ones.\nArray values are merged as well by default. You can specifiy this with the 3rd Parameter.\n\nThe files to inherit from are specified by the key 'extends:' in the YAML file.\nThat key can be customized if you prefer another one.\nSee the examples below.\n\n\n\n\n\u003ca name=\"installation\"\u003e\u003c/a\u003e\n## Installation\n### Ruby\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'yaml_extend'\n```\n\nAnd then execute:\n\n    bundle install\n\n### Command line\nIf you just want to use the command line then run\n\n    gem install yaml_extend\n\n\n\n\n\n\u003ca name=\"usage\"\u003e\u003c/a\u003e\n## Usage\nyaml_extend adds the method YAML.ext_load_file to YAML.\n\nThis method works like the original YAML.load_file, by extending it with file inheritance.\n\n### Examples\n\n#### Basic Inheritance\nGiven the following both files are defined:\n\n```yaml\n# start.erb.yml\nextends: 'super.yml'\ndata:\n    name: 'Mr. Superman'\n    age: 134\n    # using ERB templating with ruby code \n    foo: '\u003c%= 'bar' %\u003e'\n    favorites:\n        - 'Raspberrys'\n```\n\n```yaml\n# super.yml\ndata:\n    name: 'Unknown'\n    power: 2000\n    favorites:\n        - 'Bananas'\n        - 'Apples'\n```\n\nWhen you then call `ext_load_file`\n\n```ruby\nconfig = YAML.ext_load_file 'start.erb.yml'\n```\n\nthe returned YAML value results in\n\n```yaml\ndata:\n    name: 'Mr. Superman'\n    age: 134\n    foo: 'bar'\n    power: 2000\n    favorites:\n        - 'Bananas'\n        - 'Apples'\n        - 'Raspberrys'\n```\n\n#### Inherit from several files\n\nIf you want to inherit from several files, you can specify a list (Array) of files.\nThey are merged from top to bottom, so the latest file \"wins\" - that means it overwrites duplicate values if they exist with the values in the latest file where they occur.\n\n```yaml\nextends:\n    - 'super_file.yml'\n    - 'parent_file.yml'\n...\n```\n\n#### Using custom extend key\n\nIf you don't want to use the default key 'extends:', you can specify your own custom key in two ways.\n\n```yaml\n#custom1.yml\ninherit_from:\n    - 'super_file.yml'\nfoo: 'bar'\n...\n```\n##### 1. Specify by parameter\nYou can specify the key by parameter, this is the way to go if you want to  use the different key only once or you use the `ext_load_file` method only once in your application.\n```ruby\nconfig = YAML.ext_load_file 'custom1.yml', 'inherit_from'\n```\n##### 2. Global configuration of the key\nYou can specify the key by configuration globally. So you only need to set the key once and not as parameter anymore\n```ruby\nYAML.ext_load_key = 'inherit_from'\nconfig = YAML.ext_load_file 'custom1.yml'\n```\n##### Reset the global key\nTo reset the global inheritance key, you can either set it to nil or call the `reset_load_key`  method.\n```ruby\nYAML.reset_load_key # more readable\nYAML.ext_load_key = nil # more explicit\n```\n#### Using custom nested extend key\n```yaml\n#custom2.yml\noptions:\n    extend_file: 'super_file.yml'\n    database: false\nfoo: 'bar'\n...\n```\n\n```ruby\nconfig = YAML.ext_load_file 'custom2.yml', ['options','extend_file']\n```\n\n\n\n\u003ca name=\"command-line-usage\"\u003e\u003c/a\u003e\n## Command line\n\n`yaml_extend` is also available on the command line after installation.\n\nTo parse and merge a prepared YAML file, just run\n\n```\nyaml_extend path/to/my/yaml_file.yml\n```\n\nUsually you might want to put the result into resulting YAML file. So just use the basic command line features to do so:\n\n\n```\nyaml_extend path/to/my/yaml_file.yml \u003e combined_yaml.yml\n```\n\nDefault options are used, custom options are not yet supported as parameters.\n\n\n\u003ca name=\"documentation\"\u003e\u003c/a\u003e\n## Documentation\n```ruby\nYAML.ext_load_file(yaml_path, inheritance_key='extends', options = {})\n```\n- `yaml_path` (String) relative or absolute path to yaml file to inherit from\n- `inheritance_key` (String) you can overwrite the default key, if you use the default 'extends' already as part of your configuration. The inheritance_key is NOT included, that means it will be deleted, in the final merged file. Default: `'extends'`\n- `options` (Hash) collection of optional options, including all options of the based `deep_merge` gem\n  - `:preserve_inheritance_key` (Boolean) Preserve inheritance key(s) from resulting yaml, does most time not make sense especially in multiple inheritance - DEFAULT: false\n  - The following options are deep merge options that can be passed by - but the defaults differ from original\n    https://github.com/danielsdeleo/deep_merge#options\n  - `:preserve_unmergeables` (Boolean) Set to true to skip any unmergeable elements from source - DEFAULT: false\n  - `:knockout_prefix` (String) Set to string value to signify prefix which deletes elements from existing element - DEFAULT: nil\n  - `:overwrite_arrays` (Boolean) Set to true if you want to avoid merging arrays - DEFAULT: false\n  - `:sort_merged_arrays` (Boolean) Set to true to sort all arrays that are merged together - DEFAULT: false\n  - `:unpack_arrays` (String) Set to string value to run \"Array::join\" then \"String::split\" against all arrays - DEFAULT: nil\n  - `:merge_hash_arrays` (Boolean) Set to true to merge hashes within arrays - DEFAULT: false\n  - `:extend_existing_arrays` (Boolean) Set to true to extend existing arrays, instead of overwriting them - DEFAULT: true\n  - `:merge_nil_values` (Boolean) Set to true to merge nil hash values, overwriting a possibly non-nil value - DEFAULT: false\n  - `:merge_debug` (Boolean) Set to true to get console output of merge process for debugging - DEFAULT: false\n\nSee also rubydoc at [https://www.rubydoc.info/gems/yaml_extend](https://www.rubydoc.info/gems/yaml_extend)\n\n\n\n\u003ca name=\"documentation\"\u003e\u003c/a\u003e\n## Contributing\nBug reports and pull requests are welcome on GitHub at https://github.com/magynhard/yaml_extend. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n","funding_links":["https://github.com/sponsors/magynhard"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagynhard%2Fyaml_extend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagynhard%2Fyaml_extend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagynhard%2Fyaml_extend/lists"}