Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/waiting-for-dev/front_matter_parser
Ruby library to parse files or strings with a front matter. It has automatic syntax detection.
https://github.com/waiting-for-dev/front_matter_parser
front-matter-parser frontmatter ruby-gem
Last synced: 6 days ago
JSON representation
Ruby library to parse files or strings with a front matter. It has automatic syntax detection.
- Host: GitHub
- URL: https://github.com/waiting-for-dev/front_matter_parser
- Owner: waiting-for-dev
- License: mit
- Created: 2014-03-17T15:54:34.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2023-04-19T12:48:54.000Z (over 1 year ago)
- Last Synced: 2024-10-12T19:14:34.587Z (26 days ago)
- Topics: front-matter-parser, frontmatter, ruby-gem
- Language: Ruby
- Homepage:
- Size: 117 KB
- Stars: 104
- Watchers: 3
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: COPYING.LESSER
Awesome Lists containing this project
README
# FrontMatterParser
[](https://badge.fury.io/rb/front_matter_parser)
[](https://travis-ci.org/waiting-for-dev/front_matter_parser)
[](https://codeclimate.com/github/waiting-for-dev/front_matter_parser)
[](https://codeclimate.com/github/waiting-for-dev/front_matter_parser/coverage)
FrontMatterParser 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.
## Installation
Add this line to your application's Gemfile:
gem 'front_matter_parser'
or, to get the development version:
gem 'front_matter_parser', github: 'waiting-for-dev/front_matter_parser'
And then execute:
$ bundle
Or install it yourself as:
$ gem install front_matter_parser
## Usage
Front matters must be between two lines with three dashes `---`.
For example, given a file `example.md`:
```md
---
title: Hello World
category: Greetings
---
Some actual content
```
You can parse it:
```ruby
parsed = FrontMatterParser::Parser.parse_file('example.md')
parsed.front_matter #=> {'title' => 'Hello World', 'category' => 'Greetings'}
parsed.content #=> 'Some actual content'
```
You can directly apply `[]` method to get a front matter value:
```ruby
parsed['category'] #=> 'Greetings'
```
### Syntax autodetection
`FrontMatterParser` detects the syntax of a file by its extension and it supposes that the front matter is within that syntax comment delimiters.
For example, given a file `example.haml`:
```haml
-#
---
title: Hello
---
Content
```
The `-#` and the indentation enclose the front matter as a comment. `FrontMatterParser` is aware of that, so you can simply do:
```ruby
title = FrontMatterParser::Parser.parse_file('example.haml')['title'] #=> 'Hello'
```
Following there is a relation of known syntaxes and their known comment delimiters:
| Syntax | Single line comment | Start multiline comment | End multiline comment |
| ------ | ------------------- | ----------------------- | --------------------- |
| haml | | -# | (indentation) |
| slim | | / | (indentation) |
| liquid | | {% comment %} | {% endcomment %} |
| md | | | |
| html | | <!-- | --> |
| erb | | <%# | %> |
| coffee | # | | |
| sass | // | | |
| scss | // | | |
### Parsing a string
You can as well parse a string providing manually the syntax:
```ruby
string = File.read('example.slim')
FrontMatterParser::Parser.new(:slim).call(string)
```
### Custom parsers
You 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:
```ruby
CoffeeParser = FrontMatterParser::SyntaxParser::SingleLineComment['#']
HtmlParser = FrontMatterParser::SyntaxParser::MultiLineComment['']
SlimParser = FrontMatterParser::SyntaxParser::IndentationComment['/']
```
You would use them like this:
```ruby
slim_parser = SlimParser.new
# For a file
FrontMatterParser::Parser.parse_file('example.slim', syntax_parser: slim_parser)
# For a string
FrontMatterParser::Parser.new(slim_parser).call(string)
```
For 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.
### Custom loaders
Once 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:
```ruby
json_loader = ->(string) { JSON.load(string) }
# For a file
FrontMatterParser::Parser.parse_file('example.md', loader: json_loader)
# For a string
FrontMatterParser::Parser.new(:md, loader: json_loader).call(string)
```
If 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:
```ruby
loader = FrontMatterParser::Loader::Yaml.new(allowlist_classes: [Time])
parsed = FrontMatterParser::Parser.parse_file('example.md', loader: loader)
puts parsed['timestamp']
```
## Development
There 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:
`docker-compose up -d`
An then, for example:
`docker-compose exec app rspec`
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
## Release Policy
`front_matter_parser` follows the principles of [semantic versioning](http://semver.org/).
## Other ruby front matter parsers
* [front-matter](https://github.com/zhaocai/front-matter.rb) Can parse YAML front matters with single line comments delimiters. YAML must be correctly indented.
* [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.
## LICENSE
Copyright 2013 Marc Busqué -
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .