ptolemy 0.0.1 → 0.0.2

data/README.md

@@ -1,5 +1,58 @@
 ![Ptolemy](https://raw.github.com/natansh/ptolemy/master/ptolemy.jpg)
+
 [![Build Status](https://travis-ci.org/natansh/ptolemy.png?branch=master)](https://travis-ci.org/natansh/ptolemy)
-=======
+[![Gem Version](https://badge.fury.io/rb/ptolemy.png)](http://badge.fury.io/rb/ptolemy)
+
+===
+Ptolemy is a simple TOML parser for Ruby, based on Treetop. It is useful for parsing the [TOML Format](https://github.com/mojombo/toml).
+
+Ptolemy currently supports version [0.1.0](https://github.com/mojombo/toml/blob/master/versions/toml-v0.1.0.md) of TOML.
+
+Installation
+---
+
+# Bundler
+Add this to your `Gemfile`
+
+    gem 'ptolemy', '~> 0.0.2'
+
+And then run
+
+    bundle install
+
+# Manual
+You can install it manually using
+
+    gem install ptolemy
+
+Usage
+---
+* `Ptolemy.parse` can parse a string in TOML format.
+
+  ```ruby
+  data = <<END
+  # This is an example TOML input
+  [group]
+  string = "hello"
+  integer = 0
+  END
+
+  Ptolemy.parse(data)
+
+  # => {"group"=>{"string"=>"hello", "integer"=>0}}
+
+  ```
+* `Ptolemy.parse_file` can read from a UTF-8 encoded file directly.
+
+  ```ruby
+  filename = 'example.toml'
+  Ptolemy.parse_file(filename)
+  ```
+
+Test Suite
+---
+Ptolemy has a fairly exhaustive test suite built on `rspec` and can
+successfully parse the specification file and hard example given
+in the TOML specification.
 
-Ptolemy is a simple TOML parser.
+You can run the test suite by running `rake`.

data/lib/ptolemy.rb

@@ -5,10 +5,23 @@ require "ptolemy/parser"
 
 module Ptolemy
 
+  # Parses TOML string input
+  #
+  #   Ptolemy.parse 'key = "value"'
+  #
+  # @param data [String] the input string
+  # @return [Hash] the input parsed into a ruby hash
   def self.parse data
     Parser.parse data
   end
 
+  # Parses data from a file containing TOML.
+  # The file should be UTF-8 encoded.
+  #
+  #   Ptolemy.parse_file 'example.toml'
+  #
+  # @param filename [String] full path of the file
+  # @return [Hash] the input parsed into a ruby hash
   def self.parse_file filename
     File.open filename, 'r:utf-8' do |file|
       # TODO: Should the check for valid UTF-8 be done over here?

data/lib/ptolemy/exceptions.rb

@@ -2,6 +2,13 @@
 
 module Ptolemy
 
+  # Represents the error that occurs while parsing a TOML
+  # input.
+  #
+  # Possible sources of error are
+  # * Encoding issues
+  # * Issues while parsing into AST
+  # * Duplication issues
   class ParseError < StandardError; end
 
 end

data/lib/ptolemy/nodes.rb

@@ -7,7 +7,16 @@ require 'ptolemy/exceptions'
 module Ptolemy
 module TOML
 
+  # Represents the top level node of TOML AST
   class Toml < Treetop:: Runtime::SyntaxNode
+
+    # Evaluate the individual subtrees of the AST
+    # and then combine them to form the complete hash.
+    #
+    # @return [Hash] a (possibly nested) hash containing all
+    #   key value pairs.
+    # @raise [ParseError] if there are duplications in
+    #   key groups or key value pairs.
     def to_value
       result = {}
       # Keep track of location under which all the key value pairs must be
@@ -47,7 +56,12 @@ module TOML
     end
   end
 
+  # Represents an element of the form [x.y.z.w]
   class KeyGroup < Treetop::Runtime::SyntaxNode
+
+    # Evaluate an array of keys split by the '.'
+    #
+    # @return [Array] the array of nested keys represented by the key group
     def to_value
       result = [keys.key.to_value]
       keys.remaining_keys.elements.each do |elem|
@@ -57,23 +71,43 @@ module TOML
     end
   end
 
+  # Represents an element of the form key = value
   class KeyValue < Treetop::Runtime::SyntaxNode
+
+    # Evaluate both key and value and return as a 2 element array
+    #
+    # @return [Array] Two-element array containing key and value
     def to_value
       [key.to_value, value.to_value]
     end
   end
 
+  # Represents a valid key
   class Key < Treetop::Runtime::SyntaxNode
+
+    # Evaluates the key which is just the text_value of the node
     def to_value
       text_value
     end
   end
 
+  # Represents a Comment
   class Comment < Treetop::Runtime::SyntaxNode
   end
 
+  # Represents a homogeneous array. Mixing of types is not allowed
+  # for elements of an array.
+  #
+  # * [1, 2, 3, 4]
+  # * ["Hello", "World"]
+  # * [ ["Alpha", "Beta"], [1, 2]] <-- This is fine
   class ArrayLiteral < Treetop::Runtime::SyntaxNode
-   def to_value
+
+    # Evaluate the array by mapping the individual elements
+    # of the array to their evaluated selves.
+    #
+    # @return [Array] evaluated array
+    def to_value
       result = list.elements.map do|elem|
         elem.item.to_value
       end
@@ -84,24 +118,44 @@ module TOML
     end
   end
 
+  # Represents an integer. Ruby doesn't have overflow issues
+  # so any big integer is going to be fine.
   class IntegerLiteral < Treetop::Runtime::SyntaxNode
-   def to_value
+
+    # Evaluate an integer by converting the text_value to
+    # integer directly.
+    #
+    # @return [Integer] evaluated integer
+    def to_value
       text_value.to_i
     end
   end
 
+  # Represents a Float
   class FloatLiteral < Treetop::Runtime::SyntaxNode
+
+    # Evaluate a float by converting the text_value to a
+    # float directly
+    #
+    # @return [Float] evaluated float
     def to_value
       text_value.to_f
     end
   end
 
+  # Represents a Boolean
   class BooleanLiteral < Treetop::Runtime::SyntaxNode
+
+    # Evaluate a boolean by checking whether its
+    # text value matches true
+    #
+    # @return [true, false] evaluated boolean
     def to_value
       text_value == 'true'
     end
   end
 
+  # Represents a UTF-8 encoded string
   class StringLiteral < Treetop::Runtime::SyntaxNode
 
     private
@@ -119,6 +173,10 @@ module TOML
 
     public
 
+    # Evaluate a string by unescaping the escaped characters and
+    # unicode characters written in the form \uXXXX
+    #
+    # @return [String] evaluated string
     def to_value
       elem = string.text_value
       # Unescape unicode characters of the form \uXXXX
@@ -132,6 +190,11 @@ module TOML
   end
 
   class DateLiteral < Treetop::Runtime::SyntaxNode
+
+    # Evaluate the date by extracting individual elements such as year, month etc.
+    # from the parsed date and using that to construct a {DateTime} object.
+    #
+    # @return [DateTime] the evaluated date represented by the elements
     def to_value
       args = [year, month, day, hour, min, sec].map(&:text_value).map(&:to_i)
       DateTime.new(*args)

data/lib/ptolemy/parser.rb

@@ -7,6 +7,8 @@ require 'ptolemy/exceptions'
 
 module Ptolemy
 
+  # The main class that encapsulates all the parsing functionality.
+  # It includes the parser generated by the treetop grammar.
   class Parser
 
     # Load TOML grammar into Treetop
@@ -16,6 +18,13 @@ module Ptolemy
     # Treetop would've generated a parser for TOML based on the grammar
     @@parser = TOMLParser.new
 
+    # Verifies that the data is encoded in UTF-8 and that
+    # the encoding is valid.
+    # Parses the data using the {TOMLParser} generated by Treetop
+    #
+    # @param data [String] input to be parsed
+    # @return [Hash] the input parsed into a ruby hash
+    # @raise [ParseError] if there are encoding issues or parsing issues.
     def self.parse data
       # Data should be a valid UTF-8 encoded string.
       if data.encoding != Encoding::UTF_8

data/lib/ptolemy/version.rb

@@ -1,5 +1,5 @@
 # encoding: UTF-8
 
 module Ptolemy
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ptolemy
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-12 00:00:00.000000000 Z
+date: 2013-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: treetop
@@ -137,7 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1717741281203789886
+      hash: -1910015093891202054
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24