front_matter_parser 0.0.1

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+ruby File.read('.ruby-version').strip
+
+# Specify your gem's dependencies in front_matter_parser.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 marc
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,123 @@
+# FrontMatterParser
+
+FrontMatterParser is a library to parse files or strings with YAML front matters. When working with files, it can automatically detect the syntax of a file from its extension and it supposes that the front matter is marked as that syntax comments.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem '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 `---`.
+
+Given a file `example.md`:
+
+    ---
+    title: Hello World
+    category: Greetings
+    ---
+    Some actual content
+
+You can parse it:
+
+    parsed = FrontMatterParser.parse_file('example.md')
+    parsed.front_matter #=> {'title' => 'Hello World'}
+    parsed.content #=> 'Some actual content'
+
+You can apply directly `[]` method to get a front matter value:
+
+    parsed['category'] #=> 'Greetings'
+
+### Syntax autodetection
+
+`FrontMatterParser` detects the syntax of a file by its extension and suppose that the front matter is within that syntax comments delimiters.
+
+Given a file `example.haml`:
+
+    -#
+       ---
+       title: Hello
+       ---
+    Content
+
+The `-#` and the indentation enclose the front matter as a comment. `FrontMatterParser` is aware of it and you can simply do:
+
+    title = FrontMatterParser.parse_file('example.haml')['title'] #=> 'Hello'
+
+Following there is a relation of known syntaxes and their known comment delimiters:
+
+<pre>
+| Syntax | Single line comment | Start multiline comment | End multiline comment  |
+| ------ | ------------------- | ----------------------- | ---------------------- |
+| haml   |                     | -#                      | (indentation)          |
+| slim   |                     | /                       | (indentation)          |
+| liquid |                     | <% comment %>           | <% endcomment %>       |
+| md     |                     |                         |                        |
+| html   |                     | &lt;!--                    | --&gt;                    |
+| coffee | #                   |                         |                        |
+| sass   | //                  |                         |                        |
+| scss   | //                  |                         |                        |
+</pre>
+
+You can provide your own by passing `autodetect: false` and options for single line comment delimiter (`:comment`) or start multiline comment (`:start_comment`) and end multiline comment (`:end_comment`) delimiters. If `:start_comment` is provided but it isn't `:end_comment`, then it is supposed that the multiline comment is ended by indentation.
+
+    FrontMatterParser.parse_file('example.haml', autodetect: false, start_comment: '<!--', end_comment: '-->') # start and end multiline comment delimiters
+    FrontMatterParser.parse_file('example.slim', autodetect: false, start_comment: '/!') # multiline comment closed by indentation
+    FrontMatterParser.parse_file('example.foo', autodetect: false, comment: '#') # single line comments
+
+### Parsing a string
+
+You can as well parse a string, providing manually its comment delimiters if needed:
+
+    string = File.read('example.slim')
+    FrontMatterParser.parse(string, start_comment: '/')
+
+## 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/).
+
+## To Do
+
+* Add more known syntaxes.
+* Allow configuration of global front matter delimiters. It would be easy, but I'm not sure if too useful.
+* Allow different formats (as JSON). Again, I'm not sure if it would be very useful.
+
+## 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é - <marc@lamarciana.com>
+
+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 <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/autospec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'autospec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'autospec')

data/bin/rake

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/front_matter_parser.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'front_matter_parser/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "front_matter_parser"
+  spec.version       = FrontMatterParser::VERSION
+  spec.authors       = ["marc"]
+  spec.email         = ["marc@lamarciana.com"]
+  spec.description   = %q{Library to parse files or strings with YAML front matters with syntax autodetection.}
+  spec.summary       = %q{FrontMatterParser is a library to parse files or strings with YAML front matters. When working with files, it can automatically detect the syntax of a file from its extension and it supposes that the front matter is marked as that syntax comments.}
+  spec.homepage      = "https://github.com/laMarciana/front_matter_parser"
+  spec.license       = "LGPL3"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5", "<1.6"
+  spec.add_development_dependency "rake", "~>10.1"
+  spec.add_development_dependency "rspec", "~> 2.14"
+end

data/lib/front_matter_parser.rb

@@ -0,0 +1,103 @@
+require 'yaml'
+require "front_matter_parser/version"
+require "front_matter_parser/parsed"
+
+# FrontMatterParser module is the entry point to parse strings or files with YAML front matters. When working with files, it can automatically detect the syntax of a file from its extension and it supposes that the front matter is marked as that syntax comments.
+module FrontMatterParser
+  # {Hash {Symbol => Array}} Comments delimiters used in FrontMatterParser known syntaxes. Keys are file extensions, and values are three elements array:
+  #
+  # * First element is single line comment delimiter.
+  # * Second element is the start multiline comment delimiter.
+  # * Third element is the end multiline comment delimiter. If it is `nil` and start multiline comment delimiter isn't, it means that the comment is closed by indentation.
+  COMMENT_DELIMITERS = {
+    slim: [nil, '/', nil],
+    html: [nil, '<!--', '-->'],
+    coffee: ['#', nil, nil],
+    haml: [nil, '-#', nil],
+    liquid: [nil, '<% comment %>', '<% endcomment %>'],
+    sass: ['//', nil, nil],
+    scss: ['//', nil, nil],
+    md: [nil, nil, nil],
+  }
+
+  # Parses a string into a {Parsed} instance. For comment options, see {COMMENT_DELIMITERS} values (but they are not limited to those for the known syntaxes).
+  #
+  # @param string [String] The string to parse
+  # @param opts [Hash] Options
+  # @option opts [String, nil] :comment Single line comment delimiter
+  # @option opts [String, nil] :start_comment Start multiline comment delimiter
+  # @option opts [String, nil] :end_comment End multiline comment delimiter
+  # @return [Parsed]
+  # @raise [ArgumentError] If end_comment option is provided but not start_comment
+  # @see COMMENT_DELIMITERS
+  def self.parse(string, opts = {})
+    opts = {
+      comment: nil,
+      start_comment: nil,
+      end_comment: nil,
+    }.merge(opts)
+    raise(ArgumentError, "If you provide the `end_comment` option, you must provide also the `start_comment` option") if (opts[:end_comment] != nil and opts[:start_comment] == nil)
+    parsed = Parsed.new
+    if matches = (string.match(/
+                               # Start of string
+                               \A
+                               # Zero or more space characters
+                               ([[:space:]]*)
+                               # Start multiline comment
+                               #{'(?-x:(?<multiline_comment_indentation>^[[:blank:]]*)'+opts[:start_comment]+'[[:blank:]]*[\n\r][[:space:]]*)' unless opts[:start_comment].nil?}
+                               # Begin front matter
+                               (?-x:^[[:blank:]]*#{opts[:comment]}[[:blank:]]*---[[:blank:]]*$[\n\r])
+                               # The front matter
+                               (?<front_matter>.*)
+                               # End front matter
+                               (?-x:^[[:blank:]]*#{opts[:comment]}[[:blank:]]*---[[:blank:]]*$[\n\r])
+                               # End multiline comment
+                               #{'(?-x:\k<multiline_comment_indentation>)' if opts[:end_comment].nil? and not opts[:start_comment].nil?}
+                               #{'(?-x:[[:space:]]*^[[:blank:]]*'+opts[:end_comment]+'[[:blank:]]*[\n\r])' if not opts[:end_comment].nil?}
+                               # The content
+                               (?<content>.*)
+                               # End of string
+                               \z
+                               /mx))
+      front_matter = matches[:front_matter].gsub(/^#{opts[:comment]}/, '')
+      parsed.front_matter = YAML.load(front_matter)
+      parsed.content = matches[:content]
+    else
+      parsed.front_matter = {}
+      parsed.content = string
+    end
+    parsed
+  end
+
+  # Parses a file into a {Parsed} instance. If autodetect option is `true`, comment delimiters are guessed from the file extension. If it is `false` comment options are taken into consideration. See {COMMENT_DELIMITERS} for a list of known syntaxes and the comment delimiters values.
+  #
+  # @param pathname [String] The path to the file
+  # @param opts [Hash] Options
+  # @option opts [Boolean] :autodetect If it is true, FrontMatterParser uses the comment delimiters known for the syntax of the file and comment options are ignored. If it is false, comment options are taken into consideration.
+  # @option opts [String, nil] :comment Single line comment delimiter
+  # @option opts [String, nil] :start_comment Start multiline comment delimiter
+  # @option opts [String, nil] :end_comment End multiline comment delimiter
+  # @return [Parsed]
+  # @raise [ArgumentError] If autodetect option is false, and start_comment option is provided but not end_comment
+  # @raise [RuntimeError] If the syntax of the file (the extension) is not within the keys of {COMMENT_DELIMITERS}
+  # @see COMMENT_DELIMITERS
+  def self.parse_file(pathname, opts={})
+    opts = {
+      autodetect: true,
+      comment: nil,
+      start_comment: nil,
+      end_comment: nil,
+    }.merge(opts)
+    if opts[:autodetect]
+      ext = File.extname(pathname)[1 .. -1].to_sym
+      raise(RuntimeError, "Comment delimiters for extension #{ext.to_s} not known. Please, call #parse_file without autodetect option and provide comment delimiters.") unless COMMENT_DELIMITERS.has_key?(ext)
+      comment_delimiters = COMMENT_DELIMITERS[ext]
+      opts[:comment] = comment_delimiters[0]
+      opts[:start_comment] = comment_delimiters[1]
+      opts[:end_comment] = comment_delimiters[2]
+    end
+    File.open(pathname) do |file|
+      parse(file.read, comment: opts[:comment], start_comment: opts[:start_comment], end_comment: opts[:end_comment])
+    end
+  end
+end

data/lib/front_matter_parser/parsed.rb

@@ -0,0 +1,18 @@
+# Parsed is the result of calling {FrontMatterParser.parse} or {FrontMatterParser.parse_file} in {FrontMatterParser}. It keeps the front matter and the content parsed and it has some useful methods to work with them.
+class FrontMatterParser::Parsed
+  # @!attribute [rw] front_matter
+  #   @return [Hash{String => String, Array, Hash}] the parsed front matter
+  # @!attribute [rw] content
+  #   @return [String] the parsed content
+  attr_accessor :front_matter, :content
+
+  alias_method :to_hash, :front_matter
+
+  # Returns the front matter value for the given key
+  #
+  # @param key [String] The key of the front matter
+  # @return [String, Array, Hash] The value of the front matter for the given key
+  def [](key)
+    @front_matter[key]
+  end
+end

data/lib/front_matter_parser/version.rb

@@ -0,0 +1,3 @@
+module FrontMatterParser
+  VERSION = "0.0.1"
+end

data/spec/fixtures/example.coffee

@@ -0,0 +1,4 @@
+# ---
+# title: Hello
+# ---
+Content

data/spec/fixtures/example.haml

@@ -0,0 +1,5 @@
+-#
+   ---
+   title: Hello
+   ---
+Content

data/spec/fixtures/example.html

@@ -0,0 +1,6 @@
+<!--
+  ---
+  title: Hello
+  ---
+-->
+Content

data/spec/fixtures/example.liquid

@@ -0,0 +1,6 @@
+{ %comment% }
+---
+title: Hello
+---
+{ %endcomment% }
+Content

data/spec/fixtures/example.md

@@ -0,0 +1,4 @@
+---
+title: Hello
+---
+Content

data/spec/fixtures/example.sass

@@ -0,0 +1,4 @@
+// ---
+// title: Hello
+// ---
+Content

data/spec/fixtures/example.scss

@@ -0,0 +1,4 @@
+// ---
+// title: Hello
+// ---
+Content

data/spec/fixtures/example.slim

@@ -0,0 +1,5 @@
+/
+  ---
+  title: Hello
+  ---
+Content

data/spec/front_matter_parser/parsed_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+module FrontMatterParser
+  describe Parsed do
+
+    let(:sample) { {'title' => 'hello'} }
+
+    let(:string) { %Q(
+---
+title: hello
+---
+Content) }
+
+    let(:parsed) { FrontMatterParser.parse(string) }
+
+    describe "#to_hash" do
+      it "returns @front_matter" do
+        expect(parsed.to_hash).to eq(sample)
+      end
+    end
+
+    describe "#[]" do
+      it "returns the front matter value for the given key" do
+        expect(parsed['title']).to eq('hello')
+      end
+    end
+  end
+end