nodaire 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76e0ecf8fe992a52851c1c2f92aba32c4fa1e8c66a5442f7766521860624bdda
-  data.tar.gz: ecee4fc90ee93e2728177cce12b4d53383a0cbd6133cf8b4fc8a1e321a54b8e9
+  metadata.gz: '088490e1cd30efae42ca1f6ac32639378df03eb8fe5e65782744280dcd050ada'
+  data.tar.gz: b0dafd1457ab1db55e2200037fc834f54b5d3fbec5a408d4de93fc788bd97ece
 SHA512:
-  metadata.gz: 47c3f94ae222712071c9a0cce903c9b400cfbc6ebda95fb3ff384b49cc42cade26cb3207bbaf298bfad7e5d60bfa6d402ddd48b0999f936b7cf5bcfa86040f52
-  data.tar.gz: f326c0167bcb4ba1af947e6689cb3059693d96116d83a65e6f1bb12f21801bf7d70f8898ac4c196a1d8abc01f1211314021d9a031b18d717fec6f8e1556e7a08
+  metadata.gz: cf2d5f24bc4a8f60b8328cae06945e1f2978d7b488112e15152d1fadefc9d2130192e8ab918c64398366e279f5120f4590760235d18a6aca9abcf35b601cc931
+  data.tar.gz: 7ddeca02582654ebaf4237cf57602e757920a93ff681faf8ecda89dec76daa8e7a1066b26c797d7e9e749f81039316bc3d2ad26532dc09de9ed3604b28ea255d

data/README.md

@@ -8,10 +8,12 @@ Expect breaking API changes before v1.0.0 is released.
 
 ## File formats
 
-Nodaire currently supports the following text file formats:
+Nodaire supports the following text file formats:
 
-  - __Indental__ — <https://wiki.xxiivv.com/#indental>
-  - __Tablatal__ — <https://wiki.xxiivv.com/#tablatal>
+| File format | Documentation and examples | Origin |
+|---|---|---|
+| __Indental__ | [`Nodaire::Indental`](https://slisne.github.io/nodaire/Nodaire/Indental.html) | https://wiki.xxiivv.com/#indental |
+| __Tablatal__ | [`Nodaire::Tablatal`](https://slisne.github.io/nodaire/Nodaire/Tablatal.html) | https://wiki.xxiivv.com/#tablatal |
 
 ## Install
 
@@ -27,14 +29,12 @@ gem install nodaire
 
 Keep reading below for examples of how to use Nodaire.
 
-## Usage examples
-
-### Indental
+## Usage example
 
 ```ruby
 require 'nodaire/indental'
 
-doc = Nodaire::Indental.parse! <<~NDTL
+source = <<~NDTL
   NAME
     KEY : VALUE
     LIST
@@ -42,29 +42,22 @@ doc = Nodaire::Indental.parse! <<~NDTL
       ITEM2
 NDTL
 
-doc.valid?     # true
-doc.categories # ["NAME"]
-doc.to_h       # {"NAME"=>{"KEY"=>"VALUE", "LIST"=>["ITEM1", "ITEM2"]}}
-doc.to_json    # '{"NAME":{"KEY":"VALUE","LIST":["ITEM1","ITEM2"]}}'
-```
+doc = Nodaire::Indental.parse(source)
 
-### Tablatal
+doc.valid?
+#=> true
 
-```ruby
-require 'nodaire/tablatal'
-
-doc = Nodaire::Tablatal.parse! <<~TBTL
-  NAME    AGE   COLOR
-  Erica   12    Opal
-  Alex    23    Cyan
-  Nike    34    Red
-  Ruca    45    Grey
-TBTL
-
-doc.valid?    # true
-doc.keys      # ["NAME", "AGE", "COLOR"]
-doc.to_a.last # {"NAME"=>"Ruca", "AGE"=>"45", "COLOR"=>"Grey"}
-doc.to_csv    # "NAME,AGE,COLOR\nErica,12,Opal\nAlex,23,..."
+doc.categories
+#=> ["NAME"]
+
+doc['NAME']['KEY']
+#=> "VALUE"
+
+doc.to_h
+#=> {"NAME" => {"KEY"=>"VALUE", "LIST"=>["ITEM1", "ITEM2"]}}
+
+doc.to_json
+#=> '{"NAME":{"KEY":"VALUE","LIST":["ITEM1","ITEM2"]}}'
 ```
 
 ## Development

data/lib/nodaire/base.rb

@@ -3,9 +3,11 @@
 ##
 # Nodaire is a collection of text file parsers.
 #
+# @author Liam Cooke
+#
 module Nodaire
   # The version number.
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
   # The date when this version was released.
-  DATE = '2019-08-22'
+  DATE = '2019-08-26'
 end

data/lib/nodaire/errors.rb

@@ -6,5 +6,7 @@ module Nodaire
   ##
   # This exception is raised if a parser error occurs.
   #
+  # @since 0.1.0
+  #
   class ParserError < StandardError; end
 end

data/lib/nodaire/indental/indental.rb

@@ -5,14 +5,16 @@ require 'json'
 require_relative 'parser'
 
 ##
-# Interface for documents in _Indental_ format.
+# Interface for documents in Indental format.
 #
-# _Indental_ is a 'dictionary-type database format' by Devine Lu Linvega.
-# See: https://wiki.xxiivv.com/#indental
+# Indental is a text file format which represents a 'dictionary-type database'.
+# This format was created by Devine Lu Linvega --
+# see https://wiki.xxiivv.com/#indental for more information.
 #
+# @example
 #   require 'nodaire/indental'
 #
-#   doc = Nodaire::Indental.parse! <<~NDTL
+#   source = <<~NDTL
 #     NAME
 #       KEY : VALUE
 #       LIST
@@ -20,34 +22,58 @@ require_relative 'parser'
 #         ITEM2
 #   NDTL
 #
-#   doc.valid?     # true
-#   doc.categories # ["NAME"]
-#   doc.to_h       # {"NAME"=>{"KEY"=>"VALUE", "LIST"=>["ITEM1", "ITEM2"]}}
-#   doc.to_json    # '{"NAME":{"KEY":"VALUE","LIST":["ITEM1","ITEM2"]}}'
+#   doc = Nodaire::Indental.parse(source)
+#
+#   doc.valid?
+#   #=> true
+#
+#   doc.categories
+#   #=> ["NAME"]
+#
+#   doc['NAME']['KEY']
+#   #=> "VALUE"
+#
+#   doc.to_h
+#   #=> {"NAME" => {"KEY"=>"VALUE", "LIST"=>["ITEM1", "ITEM2"]}}
+#
+#   doc.to_json
+#   #=> '{"NAME":{"KEY":"VALUE","LIST":["ITEM1","ITEM2"]}}'
 #
 # @since 0.2.0
 #
 class Nodaire::Indental
-  # A hash containing the data parsed from the source.
+  include Enumerable
+
+  # @deprecated This will be removed in a future release. Use {#to_h} instead.
   # @return [Hash]
   attr_reader :data
-  # An array of category names.
+  # @return [Array<String>] the category names.
   # @since 0.3.0
-  # @return [Array<String>]
   attr_reader :categories
-  # An array of error messages.
-  # @return [Array<String>]
+  # @return [Array<String>] an array of zero or more error message strings.
+  # @see #valid?
   attr_reader :errors
 
-  alias_method :to_h, :data
-
   ##
   # Parse the document +source+.
   #
+  # @example Read an Indental file
+  #   source = File.read('example.ndtl')
+  #
+  #   doc = Nodaire::Indental.parse(source)
+  #   puts doc['MY CATEGORY']
+  #
+  # @example Read an Indental file and symbolize names
+  #   source = File.read('example.ndtl')
+  #
+  #   doc = Nodaire::Indental.parse(source, symbolize_names: true)
+  #   puts doc[:my_category]
+  #
   # @param [String] source The document source to parse.
   # @param [Boolean] symbolize_names
-  #   If true, normalize category and key names and convert them to
+  #   If +true+, normalize category and key names and convert them to
   #   lowercase symbols.
+  #   If +false+, convert category and key names to uppercase strings.
   #
   # @return [Indental]
   #
@@ -60,13 +86,18 @@ class Nodaire::Indental
   ##
   # Parse the document +source+, raising an exception if a parser error occurs.
   #
-  # @param [String] source The document source to parse.
-  # @param [boolean] symbolize_names
-  #   If true, normalize category and key names and convert them to
-  #   lowercase symbols.
+  # @example Error handling
+  #   begin
+  #     doc = Nodaire::Indental.parse(source)
+  #     puts doc['EXAMPLE']
+  #   rescue Nodaire::ParserError => error
+  #     puts error
+  #   end
+  #
+  # @param (see .parse)
   #
-  # @raise [ParserError]
   # @return [Indental]
+  # @raise [ParserError]
   #
   def self.parse!(source, symbolize_names: false)
     parser = Parser.new(source, true, symbolize_names: symbolize_names)
@@ -75,21 +106,49 @@ class Nodaire::Indental
   end
 
   ##
-  # A boolean indicating whether the source was parsed without errors.
-  #
-  # @return [Boolean]
+  # @return [Boolean] whether the source was parsed without errors.
+  # @see #errors
   #
   def valid?
     @errors.empty?
   end
 
+  ##
+  # Returns the data for a given +category+.
+  #
+  # @example
+  #   doc = Nodaire::Indental.parse(source)
+  #   puts doc['CATEGORY']
+  #
+  # @return [Hash] the data for +category+. If not found, returns +nil+.
+  # @since 0.5.0
+  #
+  def [](category)
+    @data[category]
+  end
+
+  ##
+  # Convert the document to a hash.
+  #
+  # @return [Hash]
+  #
+  def to_h(*args)
+    @data.to_h(*args)
+  end
+
   ##
   # Convert the document to JSON.
   #
   # @return [String]
   #
-  def to_json(*_args)
-    JSON.generate(data)
+  def to_json(*args)
+    @data.to_json(*args)
+  end
+
+  # Enumerable
+  # @private
+  def each(&block)
+    @data.each(&block)
   end
 
   private

data/lib/nodaire/tablatal/tablatal.rb

@@ -5,14 +5,16 @@ require 'csv'
 require_relative 'parser'
 
 ##
-# Interface for documents in _Tablatal_ format.
+# Interface for documents in Tablatal format.
 #
-# _Tablatal_ is a 'list-type database format' by Devine Lu Linvega.
-# See: https://wiki.xxiivv.com/#tablatal
+# Tablatal is a text file format which represents a 'list-type database'.
+# This format was created by Devine Lu Linvega --
+# see https://wiki.xxiivv.com/#tablatal for more information.
 #
+# @example
 #   require 'nodaire/tablatal'
 #
-#   doc = Nodaire::Tablatal.parse! <<~TBTL
+#   source = <<~TBTL
 #     NAME    AGE   COLOR
 #     Erica   12    Opal
 #     Alex    23    Cyan
@@ -20,36 +22,63 @@ require_relative 'parser'
 #     Ruca    45    Grey
 #   TBTL
 #
-#   doc.valid?    # true
-#   doc.keys      # ["NAME", "AGE", "COLOR"]
-#   doc.to_a.last # {"NAME"=>"Ruca", "AGE"=>"45", "COLOR"=>"Grey"}
-#   doc.to_csv    # "NAME,AGE,COLOR\nErica,12,Opal\nAlex,23,..."
+#   doc = Nodaire::Tablatal.parse(source)
+#
+#   doc.valid?
+#   #=> true
+#
+#   doc.keys
+#   #=> ["NAME", "AGE", "COLOR"]
+#
+#   doc[0]['NAME']
+#   #=> "Erica"
+#
+#   doc.to_a
+#   #=> [{"NAME"=>"Erica", "AGE"=>"12", "COLOR"=>"Opal"}, ...]
+#
+#   doc.to_json
+#   #=> '[{"NAME":"Erica","AGE":"12","COLOR":"Opal"},...]'
+#
+#   doc.to_csv
+#   #=> "NAME,AGE,COLOR\nErica,12,Opal\nAlex,23,Cyan\n..."
 #
 # @since 0.1.0
 #
 class Nodaire::Tablatal
-  # An array of hashes containing the data parsed from the source.
+  include Enumerable
+
+  # @deprecated This will be removed in a future release. Use {#to_a} instead.
   # @return [Array<Hash>]
   attr_reader :data
-  # An array of keys parsed from the source header line.
-  # @return [Array]
+  # @return [Array] the keys from the first line of the source.
   attr_reader :keys
-  # An array of error message strings.
+  # @return [Array<String>] an array of zero or more error message strings.
+  # @see #valid?
   # @since 0.2.0
-  # @return [Array<String>]
   attr_reader :errors
 
-  alias_method :to_a, :data
-
   ##
   # Parse the document +source+.
   #
+  # @example Read a Tablatal file
+  #   source = File.read('example.tbtl')
+  #
+  #   doc = Nodaire::Tablatal.parse(source)
+  #   puts doc.first['NAME']
+  #
+  # @example Read a Tablatal file and symbolize names
+  #   source = File.read('example.tbtl')
+  #
+  #   doc = Nodaire::Tablatal.parse(source, symbolize_names: true)
+  #   puts doc.first[:name]
+  #
   # @param [String] source The document source to parse.
   # @param [Boolean] symbolize_names
-  #   If true, normalize key names and convert them to lowercase symbols.
+  #   If +true+, normalize key names and convert them to lowercase symbols.
+  #   If +false+, convert keys to uppercase strings.
   #
-  # @since 0.2.0
   # @return [Tablatal]
+  # @since 0.2.0
   #
   def self.parse(source, symbolize_names: false)
     parser = Parser.new(source, false, symbolize_names: symbolize_names)
@@ -60,13 +89,19 @@ class Nodaire::Tablatal
   ##
   # Parse the document +source+, raising an exception if a parser error occurs.
   #
-  # @param [String] source The document source to parse.
-  # @param [Boolean] symbolize_names
-  #   If true, normalize key names and convert them to lowercase symbols.
+  # @example Error handling
+  #   begin
+  #     doc = Nodaire::Tablatal.parse(source)
+  #     puts doc.first
+  #   rescue Nodaire::ParserError => error
+  #     puts error
+  #   end
+  #
+  # @param (see .parse)
   #
-  # @since 0.2.0
-  # @raise [ParserError]
   # @return [Tablatal]
+  # @raise [ParserError]
+  # @since 0.2.0
   #
   def self.parse!(source, symbolize_names: false)
     parser = Parser.new(source, true, symbolize_names: symbolize_names)
@@ -75,15 +110,48 @@ class Nodaire::Tablatal
   end
 
   ##
-  # A boolean indicating whether the source was parsed without errors.
-  #
+  # @return [Boolean] whether the source was parsed without errors.
+  # @see #errors
   # @since 0.2.0
-  # @return [Boolean]
   #
   def valid?
     @errors.empty?
   end
 
+  ##
+  # Returns the data for a given row +index+.
+  #
+  # @example
+  #   doc = Nodaire::Tablatal.parse(source)
+  #   puts doc[0]
+  #
+  # @return [Hash] the data for the given row +index+.
+  #   If not found, returns +nil+.
+  # @since 0.5.0
+  #
+  def [](index)
+    @data[index]
+  end
+
+  ##
+  # Convert the document to an array of hashes.
+  #
+  # @return [Array<Hash>]
+  #
+  def to_a(*args)
+    @data.to_a(*args)
+  end
+
+  ##
+  # Convert the document to JSON.
+  #
+  # @return [String]
+  # @since 0.5.0
+  #
+  def to_json(*args)
+    @data.to_json(*args)
+  end
+
   ##
   # Convert the document to CSV.
   #
@@ -98,6 +166,12 @@ class Nodaire::Tablatal
     end
   end
 
+  # Enumerable
+  # @private
+  def each(&block)
+    @data.each(&block)
+  end
+
   private
 
   def initialize(parser)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nodaire
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Liam Cooke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-22 00:00:00.000000000 Z
+date: 2019-08-26 00:00:00.000000000 Z
 dependencies: []
 description: Nodaire is a collection of text file parsers.
 email: nodaire@liamcooke.com