front_matter_parser 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 411f187a41903eee5a896a2f44262d5f38aeb085
-  data.tar.gz: 0b2e9a84f6db0fb0f525fef1c0e64d9a27a0d668
+  metadata.gz: 13c37dbe3e0903b91a2e77bfbbd1c9f9688dcbc9
+  data.tar.gz: 9eabdd6757046433de4737ffd79d1b228e75093e
 SHA512:
-  metadata.gz: 927cf23e937dbe7d51e77ede738b7ace2fbe110353a96b7903e66eaac52d6cefef7043524f502cdfd14b0676c84a02aa9f635966d3a161ce0cda655dd47eb60d
-  data.tar.gz: ab89467326d6da288666290f14043a81a31afd2ecdf9b0e50b6028e0f78ecfeb46194adb69ec366e386c836f7aecfd19a19dd54af95fea12b212f1b390780958
+  metadata.gz: b0b6dfc6756089ac5740a5f55429c83189219dbabc9e07ab05a25dd666765a57d9fba55c6d34e65da5148ce5c7761aaec5e6666d5892a119b7952f5892e19f71
+  data.tar.gz: 8d8461da5eb3bb983ec19e1ec7e11b59d4028b6484e6fcb574bf0e30a7d4c2c52bf56898371cf93bb2d4ada80bd78aa572890daa1b87a85d721e4939677bdca3

data/.codeclimate.yml

@@ -0,0 +1,19 @@
+engines:
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - ruby
+  fixme:
+    enabled: true
+  rubocop:
+    enabled: true
+  reek:
+    enabled: true
+ratings:
+  paths:
+  - "**.rb"
+exclude_paths:
+  - spec/
+  - Gemfile
+  - front_matter_parser.gemspec

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.overcommit_gems.rb.lock

data/.overcommit.yml

@@ -0,0 +1,54 @@
+#
+# Select version of overcommit and the other tools from Gemfile
+#
+gemfile: .overcommit_gems.rb
+
+#
+# Hooks that are run against every commit message after a user has written it.
+#
+CommitMsg:
+  ALL:
+    required: true
+    exclude: &default_excludes
+      - Gemfile
+      - CHANGELOG.md
+      - front_matter_parser.gemspec
+      - README.md
+
+  HardTabs:
+    enabled: true
+
+  SingleLineSubject:
+    enabled: true
+
+#
+# Hooks that are run after `git commit` is executed, before the commit message
+# editor is displayed.
+#
+PreCommit:
+  ALL:
+    required: true
+    exclude: *default_excludes
+
+  BundleAudit:
+    enabled: true
+
+  BundleCheck:
+    enabled: true
+
+  LocalPathsInGemfile:
+    enabled: true
+
+  ExecutePermissions:
+    enabled: true
+    exclude:
+      - bin/*
+
+  Reek:
+    enabled: true
+
+  RuboCop:
+    enabled: true
+
+  TrailingWhitespace:
+    enabled: true

data/.overcommit_gems.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'overcommit', '~> 0.36'
+
+# Patch-level verification for Bundled apps
+gem 'bundler-audit', '~> 0.5'
+
+# Ruby code smell reporter
+gem 'reek', '~> 4.5'
+
+# Ruby code style checking
+gem 'rubocop', '~> 0.43'
+gem 'rubocop-rspec', '~> 1.7'

data/.rspec

@@ -1 +1,2 @@
+--format documentation
 --color

data/.rubocop.yml

@@ -0,0 +1,8 @@
+require: rubocop-rspec
+AllCops:
+  TargetRubyVersion: 2.4
+RSpec/NestedGroups:
+  Max: 3
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*.rb"

data/.travis.yml

@@ -1,3 +1,20 @@
+sudo: false
 language: ruby
 rvm:
-  - 1.9.3
+  - 2.3.3
+  - 2.4.0
+before_install:
+  - gem update --system --no-doc
+  - bundle install --gemfile=.overcommit_gems.rb
+before_script:
+  - git config --global user.email 'travis@travis.ci'
+  - git config --global user.name 'Travis CI'
+script:
+  - bundle exec rspec
+  - bundle exec codeclimate-test-reporter
+  - overcommit --sign
+  - overcommit --run
+addons:
+  code_climate:
+    repo_token:
+      secure: cgk8uvht7GhBupk3mYwjMVx73r/YzJ0YaiwKI66x150CIfvqS5bheZR/Wn6wb09llB1giuyEh32TLqbScQoPW/dFynO7FsvXIMHxn4Gup2Nkc36LkQhg+8EN3xxrzirNoqfxfaFWzJh7X/jbNdmLKLQvlh+5ey+nNPF+gdPVerXhqxg8AjE4EbDbeq3JnCi+jHlr/SxMB+zJe4PipLbeVSONSfSbraN/1IPJzHvItfQWSnEGIpRnAAb7URt2SAWcje/5CiH6QUA9C/ZyztfPEeCPfO2L1V3dp3pxbAyxzrhBtbVhw66mBO+Q6xB1xK8qv5LBQhlosn+TPOA66GMfHGo/tFP+aksq3CiVj6YfMaVy6AqzT0uocXFKvweznAfgiF5N+k4rq4+YBRXPEUtqmfaDka2hekKfewvMTDFGWQaoetU1Z/9WWJqaVlJQVSdeqYYLYpwur1wEeiPrz2nR0z3xn2LpdyGAeCpZW08dLBr/ASsjQhKGs3woIV+ZKSH3fJMmEh0CIulIm4qkcXN7izUUrNaPfNi4sUvaNNiomdLkaVbuv9hLlJByGciPHbBzajeqYFsPrGQWynHHDoFZ4/Tt2kTryNLqXGzqAqe0GozSRYx13z7frrGBYAXXMLPtViA2y568W2wiRh/MXM4noBRTQY8rETAfuaS+XuKfqTw=

data/Dockerfile

@@ -0,0 +1,8 @@
+FROM ruby:2.4.0
+ENV APP_HOME /app/
+ENV LIB_DIR lib/front_matter_parser/
+RUN mkdir -p $APP_HOME/$LIB_DIR
+WORKDIR $APP_HOME
+COPY Gemfile *gemspec $APP_HOME
+COPY $LIB_DIR/version.rb $APP_HOME/$LIB_DIR
+RUN bundle install

data/Gemfile

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

data/README.md

@@ -1,6 +1,11 @@
 # FrontMatterParser
 
-FrontMatterParser is a library to parse files or strings with YAML front matters. 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.
+[![Gem Version](https://badge.fury.io/rb/front_matter_parser.svg)](https://badge.fury.io/rb/front_matter_parser)
+[![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)
+[![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)
+[![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)
+
+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
 
@@ -24,7 +29,7 @@ Or install it yourself as:
 
 Front matters must be between two lines with three dashes `---`.
 
-Given a file `example.md`:
+For example, given a file `example.md`:
 
 ```md
 ---
@@ -37,12 +42,12 @@ Some actual content
 You can parse it:
 
 ```ruby
-parsed = FrontMatterParser.parse_file('example.md')
+parsed = FrontMatterParser::Parser.parse_file('example.md')
 parsed.front_matter #=> {'title' => 'Hello World', 'category' => 'Greetings'}
 parsed.content #=> 'Some actual content'
 ```
 
-You can apply directly `[]` method to get a front matter value:
+You can directly apply `[]` method to get a front matter value:
 
 ```ruby
 parsed['category'] #=> 'Greetings'
@@ -50,9 +55,9 @@ 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 comments delimiters.
+`FrontMatterParser` detects the syntax of a file by its extension and it supposes that the front matter is within that syntax comment delimiters.
 
-Given a file `example.haml`:
+For example, given a file `example.haml`:
 
 ```haml
 -#
@@ -65,7 +70,7 @@ 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.parse_file('example.haml')['title'] #=> 'Hello'
+title = FrontMatterParser::Parser.parse_file('example.haml')['title'] #=> 'Hello'
 ```
 
 Following there is a relation of known syntaxes and their known comment delimiters:
@@ -84,28 +89,69 @@ Following there is a relation of known syntaxes and their known comment delimite
 | scss   | //                  |                         |                        |
 </pre>
 
-For unknown syntaxes or alternative ones, you can provide your own single line comment delimiter with the `:comment` option, or multiline comment delimiters with `:start_comment` and `:end_comment`. If `:start_comment` is provided but it isn't `:end_comment`, then it is supposed that the multiline comment is ended by indentation.
+### Parsing a string
+
+You can as well parse a string providing manually the syntax:
 
 ```ruby
-FrontMatterParser.parse_file('example.haml', start_comment: '<!--', end_comment: '-->') # start and end multiline comment delimiters
-FrontMatterParser.parse_file('example.slim', start_comment: '/!') # multiline comment closed by indentation
-FrontMatterParser.parse_file('example.foo', comment: '#') # single line comments
+string = File.read('example.slim')
+FrontMatterParser::Parser.new(:slim).parse(string)
 ```
 
-### Parsing a string
+### Custom parsers
 
-You can as well parse a string, providing manually the `syntax`:
+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
-string = File.read('example.slim')
-FrontMatterParser.parse(string, syntax: :slim)
+CoffeeParser = FrontMatterParser::SyntaxParser::SingleLineComment['#']
+HtmlParser = FrontMatterParser::SyntaxParser::MultiLineComment['<!--', '-->']
+SlimParser = FrontMatterParser::SyntaxParser::IndentationComment['/']
 ```
 
-or the comment delimiters:
+You would use them like this:
 
 ```ruby
-string = File.read('example.slim')
-FrontMatterParser.parse(string, start_comment: '/!')
+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).parse(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).parse(string)
+```
+
+## 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`
+
+This gem uses [overcommit](https://github.com/brigade/overcommit) to execute some code review engines. If you submit a pull request, it will be executed in the CI process. In order to set it up, you need to do:
+
+```ruby
+bundle install --gemfile=.overcommit_gems.rb
+overcommit --sign
+overcommit --run # To test if it works
 ```
 
 ## Contributing
@@ -120,12 +166,6 @@ FrontMatterParser.parse(string, start_comment: '/!')
 
 `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.

data/Rakefile

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

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'front_matter_parser'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docker-compose.yml

@@ -0,0 +1,7 @@
+version: '2'
+services:
+  app:
+    build: .
+    command: tail -f Gemfile
+    volumes:
+      - .:/app

data/front_matter_parser.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   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.description   = %q{Parse a front matter from syntactically correct strings or files}
+  spec.summary       = %q{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.}
   spec.homepage      = "https://github.com/waiting-for-dev/front_matter_parser"
   spec.license       = "LGPL3"
 
@@ -18,7 +18,11 @@ Gem::Specification.new do |spec|
   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"
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 12.0"
+  spec.add_development_dependency "rspec", "~> 3.5"
+  spec.add_development_dependency "pry-byebug", "~> 3.4"
+  # Test reporting
+  spec.add_development_dependency 'simplecov', '~> 0.14'
+  spec.add_development_dependency 'codeclimate-test-reporter', '~> 1.0'
 end

data/lib/front_matter_parser.rb

@@ -1,117 +1,13 @@
-require 'yaml'
-require "front_matter_parser/version"
-require "front_matter_parser/parsed"
+# frozen_string_literal: true
 
-# 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 for FrontMatterParser known syntaxes. Keys are file extensions for {FrontMatterParser.parse_file} or :syntax option values for {FrontMatterParser.parse}, 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, '<!--', '-->'],
-    erb: [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. The syntax of the string can be set with :syntax option. Otherwise, comment marks can be manually indicated with :comment, :start_comment and :end_comment options.
-  #
-  # @param string [String] The string to parse
-  # @param opts [Hash] Options
-  # @option opts [Symbol] :syntax The syntax used in the string. See {FrontMatterParser::COMMENT_DELIMITERS} for allowed values and the comment delimiters that are supposed.
-  # @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. If it is `nil` and :start_comment isn't, the multiline comment is supposed to be closed by indentation
-  # @return [Parsed]
-  # @raise [ArgumentError] If :syntax is not within {COMMENT_DELIMITERS} keys
-  # @raise [ArgumentError] If :end_comment option is given but not :start_comment
-  # @raise [ArgumentError] If :comment and :start_comment options are given
-  # @see COMMENT_DELIMITERS
-  def self.parse(string, opts = {})
-    opts = {
-      comment: nil,
-      start_comment: nil,
-      end_comment: nil,
-      syntax: nil,
-    }.merge(opts)
-
-    raise(ArgumentError, "If you provide :end_comment, you must also provide :start_comment") if (opts[:end_comment] != nil and opts[:start_comment] == nil)
-    raise(ArgumentError, "You can not provide :comment and :start_comment options at the same time") if (opts[:start_comment] != nil and opts[:comment] != nil)
+require 'front_matter_parser/version'
+require 'front_matter_parser/syntax_parser'
+require 'front_matter_parser/loader'
+require 'front_matter_parser/parser'
+require 'front_matter_parser/parsed'
 
-    if opts[:comment].nil? and opts[:start_comment].nil? and not opts[:syntax].nil?
-      raise(ArgumentError, "#{opts[:syntax]} syntax not known. Please call parse providing manually comment delimiters for that syntax.") unless COMMENT_DELIMITERS.has_key?(opts[:syntax])
-      opts[:comment], opts[:start_comment], opts[:end_comment] = COMMENT_DELIMITERS[opts[:syntax]]
-    end
-
-    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(/^[[:blank:]]*#{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. Syntax is automatically guessed from the file extension, unless :comment, :start_comment or :end_comment options are given. See {COMMENT_DELIMITERS} for a list of known extensions and the comment delimiters values that are supposed.
-  #
-  # @param pathname [String] The path to the file
-  # @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. If it is `nil`, the multiline comment is supposed to be closed by indentation.
-  # @return [Parsed]
-  # @raise [ArgumentError] If :start_comment option is provided but not :end_comment
-  # @raise [ArgumentError] If :comment and :start_comment options are both provided
-  # @raise [ArgumentError] If :end_comment is provided but :start_comment isn't
-  # @raise [RuntimeError] If the syntax of the file (the extension) is not within the keys of {COMMENT_DELIMITERS} or the file has no extension, and none of :comment, :start_comment or :end_comment are provided
-  # @see COMMENT_DELIMITERS
-  def self.parse_file(pathname, opts={})
-    opts = {
-      comment: nil,
-      start_comment: nil,
-      end_comment: nil,
-    }.merge(opts)
-    if opts[:comment].nil? and opts[:start_comment].nil?
-      ext = File.extname(pathname)[1 .. -1]
-      ext = ext.to_sym unless ext.nil?
-      raise(RuntimeError, "Comment delimiters for extension #{ext.to_s} not known. Please, call #parse_file providing manually comment delimiters for that extension.") unless COMMENT_DELIMITERS.has_key?(ext)
-      File.open(pathname) do |file|
-        parse(file.read, syntax: ext)
-      end
-    else
-      File.open(pathname) do |file|
-        parse(file.read, comment: opts[:comment], start_comment: opts[:start_comment], end_comment: opts[:end_comment])
-      end
-    end
-  end
+# 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.
+module FrontMatterParser
 end