{"id":15512151,"url":"https://github.com/waiting-for-dev/front_matter_parser","last_synced_at":"2025-04-04T19:14:57.211Z","repository":{"id":15106992,"uuid":"17833836","full_name":"waiting-for-dev/front_matter_parser","owner":"waiting-for-dev","description":"Ruby library to parse files or strings with a front matter. It has automatic syntax detection.","archived":false,"fork":false,"pushed_at":"2023-04-19T12:48:54.000Z","size":120,"stargazers_count":104,"open_issues_count":2,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-12T19:14:34.587Z","etag":null,"topics":["front-matter-parser","frontmatter","ruby-gem"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mgechev/angular-seed","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/waiting-for-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"COPYING.LESSER","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},"funding":{"github":"waiting-for-dev"}},"created_at":"2014-03-17T15:54:34.000Z","updated_at":"2024-10-07T01:39:02.000Z","dependencies_parsed_at":"2024-06-18T17:04:32.546Z","dependency_job_id":"01d5efb9-a110-4cf9-a706-793687a90f20","html_url":"https://github.com/waiting-for-dev/front_matter_parser","commit_stats":{"total_commits":146,"total_committers":6,"mean_commits":"24.333333333333332","dds":0.04109589041095896,"last_synced_commit":"01187017cb5b20ff1cf92809969ecd385d613aaa"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waiting-for-dev%2Ffront_matter_parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waiting-for-dev%2Ffront_matter_parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waiting-for-dev%2Ffront_matter_parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waiting-for-dev%2Ffront_matter_parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waiting-for-dev","download_url":"https://codeload.github.com/waiting-for-dev/front_matter_parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234923,"owners_count":20905854,"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":["front-matter-parser","frontmatter","ruby-gem"],"created_at":"2024-10-02T09:53:29.003Z","updated_at":"2025-04-04T19:14:57.185Z","avatar_url":"https://github.com/waiting-for-dev.png","language":"Ruby","funding_links":["https://github.com/sponsors/waiting-for-dev"],"categories":["Ruby"],"sub_categories":[],"readme":"# FrontMatterParser\n\n[![Gem Version](https://badge.fury.io/rb/front_matter_parser.svg)](https://badge.fury.io/rb/front_matter_parser)\n[![Build Status](https://travis-ci.org/waiting-for-dev/front_matter_parser.svg?branch=master)](https://travis-ci.org/waiting-for-dev/front_matter_parser)\n[![Code Climate](https://codeclimate.com/github/waiting-for-dev/front_matter_parser/badges/gpa.svg)](https://codeclimate.com/github/waiting-for-dev/front_matter_parser)\n[![Test Coverage](https://codeclimate.com/github/waiting-for-dev/front_matter_parser/badges/coverage.svg)](https://codeclimate.com/github/waiting-for-dev/front_matter_parser/coverage)\n\nFrontMatterParser is a library to parse a front matter from strings or files. It allows writing syntactically correct source files, marking front matters as comments in the source file language.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'front_matter_parser'\n\nor, to get the development version:\n\n    gem 'front_matter_parser', github: 'waiting-for-dev/front_matter_parser'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install front_matter_parser\n\n## Usage\n\nFront matters must be between two lines with three dashes `---`.\n\nFor example, given a file `example.md`:\n\n```md\n---\ntitle: Hello World\ncategory: Greetings\n---\nSome actual content\n```\n\nYou can parse it:\n\n```ruby\nparsed = FrontMatterParser::Parser.parse_file('example.md')\nparsed.front_matter #=\u003e {'title' =\u003e 'Hello World', 'category' =\u003e 'Greetings'}\nparsed.content #=\u003e 'Some actual content'\n```\n\nYou can directly apply `[]` method to get a front matter value:\n\n```ruby\nparsed['category'] #=\u003e 'Greetings'\n```\n\n### Syntax autodetection\n\n`FrontMatterParser` detects the syntax of a file by its extension and it supposes that the front matter is within that syntax comment delimiters.\n\nFor example, given a file `example.haml`:\n\n```haml\n-#\n   ---\n   title: Hello\n   ---\nContent\n```\n\nThe `-#` and the indentation enclose the front matter as a comment. `FrontMatterParser` is aware of that, so you can simply do:\n\n```ruby\ntitle = FrontMatterParser::Parser.parse_file('example.haml')['title'] #=\u003e 'Hello'\n```\n\nFollowing there is a relation of known syntaxes and their known comment delimiters:\n\n| Syntax | Single line comment | Start multiline comment | End multiline comment |\n| ------ | ------------------- | ----------------------- | --------------------- |\n| haml   |                     | -#                      | (indentation)         |\n| slim   |                     | /                       | (indentation)         |\n| liquid |                     | {% comment %}           | {% endcomment %}      |\n| md     |                     |                         |                       |\n| html   |                     | \u0026lt;!--                 | --\u0026gt;                |\n| erb    |                     | \u0026lt;%#                  | %\u0026gt;                 |\n| coffee | #                   |                         |                       |\n| sass   | //                  |                         |                       |\n| scss   | //                  |                         |                       |\n\n### Parsing a string\n\nYou can as well parse a string providing manually the syntax:\n\n```ruby\nstring = File.read('example.slim')\nFrontMatterParser::Parser.new(:slim).call(string)\n```\n\n### Custom parsers\n\nYou can implement your own parsers for other syntaxes. Most of the times, they will need to parse a syntax with single line comments, multi line comments or closed by indentation comments. For these cases, this library provides helper factory methods. For example, if they weren't already implemented, you could do something like:\n\n```ruby\nCoffeeParser = FrontMatterParser::SyntaxParser::SingleLineComment['#']\nHtmlParser = FrontMatterParser::SyntaxParser::MultiLineComment['\u003c!--', '--\u003e']\nSlimParser = FrontMatterParser::SyntaxParser::IndentationComment['/']\n```\n\nYou would use them like this:\n\n```ruby\nslim_parser = SlimParser.new\n\n# For a file\nFrontMatterParser::Parser.parse_file('example.slim', syntax_parser: slim_parser)\n\n# For a string\nFrontMatterParser::Parser.new(slim_parser).call(string)\n```\n\nFor more complex scenarios, a parser can be anything responding to a method `call(string)` which returns a hash interface with `:front_matter` and `:content` keys, or `nil` if no front matter is found.\n\n### Custom loaders\n\nOnce a front matter is matched from a string, it is loaded as if it were a YAML text. However, you can also implement your own loaders. They just need to implement a `call(string)` method. You would use it like the following:\n\n```ruby\njson_loader = -\u003e(string) { JSON.load(string) }\n\n# For a file\nFrontMatterParser::Parser.parse_file('example.md', loader: json_loader)\n\n# For a string\nFrontMatterParser::Parser.new(:md, loader: json_loader).call(string)\n```\n\nIf you need to allow one or more classes for the built-in YAML loader, you can just create a custom loader based on it and provide needed classes in a `allowlist_classes:` param:\n\n```ruby\nloader = FrontMatterParser::Loader::Yaml.new(allowlist_classes: [Time])\nparsed = FrontMatterParser::Parser.parse_file('example.md', loader: loader)\nputs parsed['timestamp']\n```\n\n## Development\n\nThere are docker and docker-compose files configured to create a development environment for this gem. So, if you use Docker you only need to run:\n\n`docker-compose up -d`\n\nAn then, for example:\n\n`docker-compose exec app rspec`\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n## Release Policy\n\n`front_matter_parser` follows the principles of [semantic versioning](http://semver.org/).\n\n## Other ruby front matter parsers\n\n* [front-matter](https://github.com/zhaocai/front-matter.rb) Can parse YAML front matters with single line comments delimiters. YAML must be correctly indented.\n* [ruby_front_matter](https://github.com/F-3r/ruby_front_matter) Can parse JSON front matters and can configure front matter global delimiters, but does not accept comment delimiters.\n\n## LICENSE\n\nCopyright 2013 Marc Busqué - \u003cmarc@lamarciana.com\u003e\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaiting-for-dev%2Ffront_matter_parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaiting-for-dev%2Ffront_matter_parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaiting-for-dev%2Ffront_matter_parser/lists"}