csdl 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f8bac9da29e72abe7b9ed3d735c9e43dd0299f8
-  data.tar.gz: fbddc9f5fe3edd6c023acfad56e2dac01e3baff6
+  metadata.gz: a90262fd16ee8936dd0fe2de172ca90a443603f6
+  data.tar.gz: 89cb93fa4bdcb617dbd066edc004bde34f33c1af
 SHA512:
-  metadata.gz: bbe665e31c04cacc5922e9f66a6e09835b63516cf900b785df53ade0939aa78e170f29b37723ebe88b3fca8d905467a438a26eff9ab604dc6d899376928c711e
-  data.tar.gz: cdff5b7766ac63008c2c0421f84294a9046bc6d4657149f15675e2768c94fdf24014c8b4daffab0f98f246602979bb7f01bba0c19cf9feff7656e6f5b70326b1
+  metadata.gz: 485e7164255da714fb1d5bc59e4a9d01b7568e6a58acb5c6b865d85bcef56063cc4c904482482e45c9bdbcb82fab90f097a99fbc2778f2b2b8b46c49c041f494
+  data.tar.gz: 55d987844a46743cc6013402225279458aa33419ea38b38e5226ea1ea665debff6124f8671030d76df24236f4d506e8f16fef13129c63ecc5470159a48b7530b

data/README.md

@@ -3,7 +3,10 @@
 CSDL is a gem for producing Abstract Syntax Trees for the [DataSift CSDL Filter Language](http://dev.datasift.com/docs/csdl).
 Working with an AST instead of raw strings provides a simpler way to test and validate any given CSDL filter.
 
+[![Gem Version](https://badge.fury.io/rb/csdl.svg)](http://badge.fury.io/rb/csdl)
 [![Build Status](https://travis-ci.org/localshred/csdl.svg)](https://travis-ci.org/localshred/csdl)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/csdl)
+[![Inline docs](http://inch-ci.org/github/localshred/csdl.svg?branch=master)](http://inch-ci.org/github/localshred/csdl)
 
 ## Installation
 
@@ -25,41 +28,47 @@ Or install it yourself as:
 
 Use the DSL provided by `CSDL::Builder` to produce an AST representation of your query, and use `CSDL::Processor` to turn your AST into a raw CSDL string.
 
-Valid builder methods are `closure`, `filter`, `_and`, `_or`, and `_not`. The last three are prefixed to avoid keyword collision.
+Be sure to read the [Processor](http://www.rubydoc.info/gems/csdl/CSDL/Processor) and [Processor](http://www.rubydoc.info/gems/csdl/CSDL/Builder) docs if you get stuck.
+
+Valid builder methods are:
+
+- `_and` - `AND`s two or more child statements together.
+- `_not` - Negates a `condition` statement.
+- `_or` - `OR`s two or more child statements together.
+- `_return` - Creates a return statement with an implicit `statement_scope`.
+- `condition` - Builds a `target + operator + argument` group. Ensures `target` and `operator` are valid.
+- `logical_group` - Create a parenthetical grouping for nested statements. Optionally takes a logical operator as the first argument since we commonly want to wrap OR'd or AND'd statements in a logical group.
+- `statement_scope` - Create a braced grouping for nested statements used by tag and return blocks.
+- `tag_tree` - Builds a tag tree classifier (e.g. `tag.movies "Video" { ... }`).
+- `tag` - Builds a tag classifier (e.g. `tag "Desire" { ... }`).
+
+Methods prefixed with "\_" are to avoid ruby keyword collisions.
 
 ```ruby
 builder = ::CSDL::Builder.new._or do
   [
-    closure {
-      _and {
-        [
-          closure {
-            _or {
-              [
-                filter("fb.content", :contains_any, "ebola"),
-                filter("fb.parent.content", :contains_any, "ebola")
-              ]
-            }
-          },
-          _not("fb.content", :contains_any, "government,politics"),
-          filter("fb.author.country_code", :in, "GB")
-        ]
-      }
+    logical_group(:and) {
+      [
+        logical_group(:or) {
+          [
+            condition("fb.content", :contains_any, "ebola"),
+            condition("fb.parent.content", :contains_any, "ebola")
+          ]
+        },
+        _not("fb.content", :contains_any, "government,politics"),
+        condition("fb.author.country_code", :in, "GB")
+      ]
     },
-    closure {
-      _and {
-        [
-          closure {
-            _or {
-              [
-                filter("fb.content", :contains_any, "malta,malta island,#malta"),
-                filter("fb.parent.content", :contains_any, "malta,malta island,#malta")
-              ]
-            }
-          },
-          _not("fb.content", :contains_any, "vacation,poker awards")
-        ]
-      }
+    logical_group(:and) {
+      [
+        logical_group(:or) {
+          [
+            condition("fb.content", :contains_any, "malta,malta island,#malta"),
+            condition("fb.parent.content", :contains_any, "malta,malta island,#malta")
+          ]
+        },
+        _not("fb.content", :contains_any, "vacation,poker awards")
+      ]
     }
   ]
 end
@@ -78,16 +87,16 @@ The previous script produces the following output:
 ```
 Builder...
 (or
-  (closure
+  (logical_group
     (and
-      (closure
+      (logical_group
         (or
-          (filter
+          (condition
             (target "fb.content")
             (operator :contains_any)
             (argument
               (string "ebola")))
-          (filter
+          (condition
             (target "fb.parent.content")
             (operator :contains_any)
             (argument
@@ -97,21 +106,21 @@ Builder...
         (operator :contains_any)
         (argument
           (string "government,politics")))
-      (filter
+      (condition
         (target "fb.author.country_code")
         (operator :in)
         (argument
           (string "GB")))))
-  (closure
+  (logical_group
     (and
-      (closure
+      (logical_group
         (or
-          (filter
+          (condition
             (target "fb.content")
             (operator :contains_any)
             (argument
               (string "malta,malta island,#malta")))
-          (filter
+          (condition
             (target "fb.parent.content")
             (operator :contains_any)
             (argument

data/csdl.gemspec

@@ -5,13 +5,17 @@ require 'csdl/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "csdl"
-  spec.version       = Csdl::VERSION
+  spec.version       = CSDL::VERSION
   spec.authors       = ["BJ Neilsen"]
   spec.email         = ["bj.neilsen@gmail.com"]
 
   spec.summary       = %q{AST Processor and Query Builder for DataSift's CSDL language}
-  spec.description   = spec.summary
-  spec.homepage      = "https://localshred.github.io"
+  spec.description   = %q{
+CSDL is a gem for producing Abstract Syntax Trees for the [DataSift CSDL Filter Language](http://dev.datasift.com/docs/csdl).
+Working with an AST instead of raw strings provides a simpler way to test and validate any given CSDL filter.
+}
+
+  spec.homepage      = "https://github.com/localshred/csdl"
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.require_paths = ["lib"]
@@ -21,4 +25,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest"
+  spec.add_development_dependency "yard"
 end

data/lib/csdl.rb

@@ -1,6 +1,15 @@
 require "ast"
 require "csdl/version"
 
+# CSDL is a library for manipulating Abstract Syntax Trees that represent raw CSDL defintions. Using an AST
+# makes it much simpler to manipulate, traverse, validate, and test complex CSDL queries.
+#
+# Use the DSL {Builder} class to produce a tree of nodes, then process those nodes
+# with {Processor}, {InteractionFilterProcessor}, or {QueryFilterProcessor}. See
+# those individuals classes for usage documentation.
+#
+# @see http://dev.datasift.com/docs/csdl DataSift CSDL Language Documentation
+#
 module CSDL
 end
 

data/lib/csdl/builder.rb

@@ -1,30 +1,143 @@
 module CSDL
+
+  # {Builder} is a class used to produce {http://www.rubydoc.info/gems/ast/AST/Node AST::Node} objects built to be processed
+  # by any one of {Processor}, {InteractionFilterProcessor}, or {QueryFilterProcessor}.
+  #
+  # @example
+  #   # Generate your CSDL nodes using the Builder
+  #   root_node = CSDL::Builder.new.logical_group(:or) do
+  #     #...
+  #     condition("fb.content", :contains, "match this string")
+  #     #...
+  #   end
+  #
+  #   # Process the root node and its children calling the instance method #process
+  #   CSDL::Processor.new.process(root_node)
+  #
+  # @see http://dev.datasift.com/docs/csdl DataSift CSDL Language Documentation
+  #
   class Builder
     include ::AST::Sexp
 
-    def __one_or_more_child_nodes(&block)
-      children = instance_eval(&block)
-      [ children ].flatten
-    end
-
-    def _or(&block)
-      s(:or, *__one_or_more_child_nodes(&block))
-    end
-
+    # Logically AND two or more child nodes together. Does not implicitly create a logical group with parentheses.
+    # If you want to logically group the ANDs, see {#logical_group}.
+    #
+    # @example
+    #   nodes = CSDL::Builder.new._and do
+    #     [
+    #       condition("fb.content", :contains, "this is a string"),
+    #       condition("fb.parent.content", :contains, "this is a string"),
+    #     ]
+    #   end
+    #   CSDL::Processor.new.process(nodes) # => 'fb.content contains "this is a string" AND fb.parent.content contains "this is a string"'
+    #
+    # @param block [Proc] Block to return child nodes to apply to this :and node. Block is evaluated against the builder instance.
+    # @yieldreturn [AST::Node, Array<AST::Node>] An AST node or array of AST nodes to be wrapped by an :and node.
+    #
+    # @return [AST::Node] An AST :and node with its children being the node(s) returned by the block.
+    #
+    # @see #logical_group
+    #
     def _and(&block)
       s(:and, *__one_or_more_child_nodes(&block))
     end
 
+    # Negate a condition. Analogous to {#condition} with NOT prepended to the condition.
+    #
+    # @example
+    #   node = CSDL::Builder.new._not("fb.content", :contains, "do not match this string")
+    #   CSDL::Processor.new.process(node) # => 'NOT fb.content contains "do not match this string"'
+    #
+    # @example Multiple negations ANDed together
+    #   nodes = CSDL::Builder.new._and do
+    #     [
+    #       _not("fb.content", :contains, "this is a string"),
+    #       _not("fb.parent.content", :contains, "this is a string"),
+    #     ]
+    #   end
+    #   CSDL::Processor.new.process(nodes) # => 'NOT fb.content contains "this is a string" AND NOT fb.parent.content contains "this is a string"'
+    #
+    # @param target [#to_s] A valid Target specifier (see {CSDL::TARGETS}).
+    # @param operator [#to_s] A valid Operator specifier (see {CSDL::OPERATORS}).
+    # @param argument [String, Numeric, nil] The comparator value, if applicable for the given operator.
+    #
+    # @return [AST::Node] An AST :not node with child target, operator, and argument nodes.
+    #
+    # @see #condition
+    #
     def _not(target, operator, argument = nil)
-      node = filter(target, operator, argument)
+      node = condition(target, operator, argument)
       node.updated(:not)
     end
 
+    # Logically OR two or more child nodes together. Does not implicitly create a logical group with parentheses.
+    # If you want to logically group the ORs, see {#logical_group}.
+    #
+    # @example
+    #   nodes = CSDL::Builder.new._or do
+    #     [
+    #       condition("fb.content", :contains, "this is a string"),
+    #       condition("fb.parent.content", :contains, "this is a string")
+    #     ]
+    #   end
+    #   CSDL::Processor.new.process(nodes) # => 'fb.content contains "this is a string" OR fb.parent.content contains "this is a string"'
+    #
+    # @param block [Proc] Block to return child nodes to apply to this :or node. Block is evaluated against the builder instance.
+    # @yieldreturn [AST::Node, Array<AST::Node>] An AST node or array of AST nodes to be wrapped by an :or node.
+    # @return [AST::Node] An AST :or node with its children being the node(s) returned by the block.
+    #
+    # @see #logical_group
+    #
+    def _or(&block)
+      s(:or, *__one_or_more_child_nodes(&block))
+    end
+
+    # Wrap child nodes in a return statement scope.
+    #
+    # @note The base {Processor} will not process return statement nodes, use {InteractionFilterProcessor} instead.
+    #
+    # @example
+    #   nodes = CSDL::Builder.new._return do
+    #     condition("fb.content", :contains, "this is a string")
+    #   end
+    #   CSDL::InteractionFilterProcessor.new.process(nodes) # => 'return {fb.content contains "this is a string"}'
+    #
+    # @param block [Proc] Block to return child nodes to apply to a :statement_scope node. Block is evaluated against the builder instance.
+    # @yieldreturn [AST::Node, Array<AST::Node>] An AST node or array of AST nodes to be wrapped by a :statement_scope node.
+    #
+    # @return [AST::Node] An AST :return node with a single child :statement_scope node, its children being the node(s) returned by the block.
+    #
+    # @see #statement_scope
+    #
     def _return(&block)
       s(:return, statement_scope(&block))
     end
 
-    def filter(target, operator, argument = nil)
+    # Create a "target + operator[ + argument]" CSDL condition. This method is the workhorse of any CSDL Filter.
+    # See {#_not} if you wish to negate a single condition.
+    #
+    # @example
+    #   node = CSDL::Builder.new.condition("fb.content", :contains, "match this string")
+    #   CSDL::Processor.new.process(node) # => 'fb.content contains "match this string"'
+    #
+    # @example Multiple conditions ANDed together
+    #   nodes = CSDL::Builder.new._and do
+    #     [
+    #       condition("fb.content", :contains, "this is a string"),
+    #       condition("fb.parent.content", :contains, "this is a string"),
+    #     ]
+    #   end
+    #   CSDL::Processor.new.process(nodes) # => 'fb.content contains "this is a string" AND fb.parent.content contains "this is a string"'
+    #
+    # @param target [#to_s] A valid Target specifier (see {CSDL::TARGETS}).
+    # @param operator [#to_s] A valid Operator specifier (see {CSDL::OPERATORS}).
+    # @param argument [String, Numeric, nil] The comparator value, if applicable for the given operator.
+    #
+    # @return [AST::Node] An AST :condition node with child target, operator, and argument nodes.
+    #
+    # @see #_not
+    #
+    def condition(target, operator, argument = nil)
       target_node   = s(:target, target)
       operator_node = s(:operator, operator)
       argument_node = nil
@@ -35,9 +148,72 @@ module CSDL
         argument_node       = s(:argument, child_argument_node)
       end
 
-      s(:filter, *[target_node, operator_node, argument_node].compact)
+      s(:condition, *[target_node, operator_node, argument_node].compact)
     end
 
+    # Wrap any child nodes in a logical grouping with parentheses. Additionally specify a logical
+    # operator to wrap all block child nodes. See {#_or} and {#_and}.
+    #
+    # @example
+    #   nodes = CSDL::Builder.new.logical_group do
+    #     condition("fb.content", :contains, "this is a string")
+    #   end
+    #   CSDL::Processor.new.process(nodes) # => '(fb.content contains "this is a string")'
+    #
+    # @example Without logical operator argument (default)
+    #   nodes = CSDL::Builder.new.logical_group do
+    #     _or do
+    #       [
+    #         condition("fb.content", :contains, "this is a string"),
+    #         condition("fb.parent.content", :contains, "this is a string")
+    #       ]
+    #     end
+    #   end
+    #   CSDL::Processor.new.process(nodes) # => '(fb.content contains "this is a string" OR fb.parent.content contains "this is a string")'
+    #
+    # @example With logical operator argument, notice removal of _or block from previous example
+    #   nodes = CSDL::Builder.new.logical_group(:or) do
+    #     [
+    #       condition("fb.content", :contains, "this is a string"),
+    #       condition("fb.parent.content", :contains, "this is a string")
+    #     ]
+    #   end
+    #   CSDL::Processor.new.process(nodes) # => '(fb.content contains "this is a string" OR fb.parent.content contains "this is a string")'
+    #
+    # @example Complex example
+    #   nodes = CSDL::Builder.new._and do
+    #     [
+    #       logical_group(:or) {
+    #         [
+    #           condition("fb.content", :contains, "this is a string"),
+    #           condition("fb.parent.content", :contains, "this is a string")
+    #         ]
+    #       },
+    #       logical_group(:or) {
+    #         [
+    #           condition("fb.author.age", :==, "25-34"),
+    #           condition("fb.parent.author.age", :==, "25-34")
+    #         ]
+    #       },
+    #       logical_group(:or) {
+    #         [
+    #           condition("fb.author.gender", :==, "male"),
+    #           condition("fb.parent.author.gender", :==, "male")
+    #         ]
+    #       },
+    #       condition("fb.author.region", :==, "texas")
+    #     ]
+    #   end
+    #   CSDL::Processor.new.process(nodes) # => '(fb.content contains "this is a string" OR fb.parent.content contains "this is a string") AND (fb.author.age == "25-34" OR fb.parent.author.age == "25-34") AND (fb.author.gender == "male" OR fb.parent.author.gender == "male") AND fb.author.region == "texas"'
+    #
+    # @param block [Proc] Block to return child nodes to apply to this :logical_group node. Block is evaluated against the builder instance.
+    # @yieldreturn [AST::Node, Array<AST::Node>] An AST node or array of AST nodes to be wrapped by a :logical_group node (and possibly also a node for the logical operator).
+    #
+    # @return [AST::Node] An AST :logical_operator node with its children being the node(s) returned by the block.
+    #
+    # @see #_and
+    # @see #_or
+    #
     def logical_group(logical_operator = nil, &block)
       if logical_operator.nil?
         s(:logical_group, *__one_or_more_child_nodes(&block))
@@ -46,10 +222,80 @@ module CSDL
       end
     end
 
+    # Wrap child nodes in a root node. Useful for building CSDL with tagging and a return statement.
+    #
+    # @example
+    #   nodes = CSDL::Builder.new.root do
+    #     [
+    #       tag_tree(["movies"], "Video") { condition("links.url", :any, "youtube.com,vimeo.com") },
+    #       tag_tree(["movies"], "Social Networks") { condition("links.url", :any, "twitter.com,facebook.com") },
+    #
+    #       return {
+    #         _or {
+    #           [
+    #             condition("fb.topics.category", :in, "Movie,Film,TV"),
+    #             condition("fb.parent.topics.category", :in, "Movie,Film,TV")
+    #           ]
+    #         }
+    #       }
+    #     ]
+    #   end
+    #   CSDL::InteractionFilterProcessor.new.process(nodes) # => 'tag.movies "Video" {links.url any "youtube.com,vimeo.com"} tag.movies "Social Networks" {links.url any "twitter.com,facebook.com"} return {fb.topics.category in "Movie,Film,TV" OR fb.parent.topics.cateogry in "Movie,Film,TV"}'
+    #
+    # @param block [Proc] Block to return child nodes to apply to this :statement_scope node. Block is evaluated against the builder instance.
+    # @yieldreturn [AST::Node, Array<AST::Node>] An AST node or array of AST nodes to be wrapped by a :statement_scope node.
+    #
+    # @return [AST::Node] An AST :statement_scope node with its children being the node(s) returned by the block.
+    #
+    # @see #_return
+    # @see #tag_tree
+    #
+    def root(&block)
+      s(:root, *__one_or_more_child_nodes(&block))
+    end
+
+    # Wrap child nodes in braces. @note Generally not useful on its own, see {#_return}, {#tag}, or {#tag_tree} usage.
+    #
+    # @note The base {Processor} will not process statement_scope nodes, use {InteractionFilterProcessor} instead.
+    #
+    # @example
+    #   nodes = CSDL::Builder.new.statement_scope do
+    #     condition("fb.content", :contains, "this is a string")
+    #   end
+    #   CSDL::InteractionFilterProcessor.new.process(nodes) # => '{fb.content contains "this is a string"}'
+    #
+    # @param block [Proc] Block to return child nodes to apply to this :statement_scope node. Block is evaluated against the builder instance.
+    # @yieldreturn [AST::Node, Array<AST::Node>] An AST node or array of AST nodes to be wrapped by a :statement_scope node.
+    #
+    # @return [AST::Node] An AST :statement_scope node with its children being the node(s) returned by the block.
+    #
+    # @see #_return
+    # @see #tag
+    # @see #tag_tree
+    #
     def statement_scope(&block)
       s(:statement_scope, *__one_or_more_child_nodes(&block))
     end
 
+    # Wrap child nodes in a VEDO tag classification.
+    #
+    # @note The base {Processor} will not process tag nodes, use {InteractionFilterProcessor} instead.
+    #
+    # @example
+    #   nodes = CSDL::Builder.new.tag("MyTag") do
+    #     condition("fb.content", :contains, "this is a string")
+    #   end
+    #   CSDL::InteractionFilterProcessor.new.process(nodes) # => 'tag "MyTag" {fb.content contains "this is a string"}'
+    #
+    # @param tag_class [#to_s] The tag classification.
+    # @param block [Proc] Block to return child nodes to apply to a :statement_scope node nested under the :tag node. Block is evaluated against the builder instance.
+    # @yieldreturn [AST::Node, Array<AST::Node>] An AST node or array of AST nodes to be wrapped by a :statement_scope node, to be a child of the returned :tag node.
+    #
+    # @return [AST::Node] An AST :tag node with a :tag_class child node and :statement_scope child node.
+    #
+    # @see #statement_scope
+    # @see #tag_tree
+    #
     def tag(tag_class, &block)
       s(:tag,
         s(:tag_class,
@@ -57,17 +303,45 @@ module CSDL
         statement_scope(&block))
     end
 
-    def tag_tree(tag_nodes, tag_class, &block)
-      tag_node_nodes = tag_nodes.map do |tag_node|
-        s(:tag_node, tag_node)
+    # Wrap child nodes in a VEDO tag classification tree.
+    #
+    # @note The base {Processor} will not process tag_tree nodes, use {InteractionFilterProcessor} instead.
+    #
+    # @example
+    #   nodes = CSDL::Builder.new.tag_tree(%w(foo bar), "MyTag") do
+    #     condition("fb.content", :contains, "this is a string")
+    #   end
+    #   CSDL::InteractionFilterProcessor.new.process(nodes) # => 'tag.foo.bar "MyTag" {fb.content contains "this is a string"}'
+    #
+    # @param tag_namespaces [Array<#to_s>] List of classification namespaces.
+    # @param tag_class [#to_s] The tag classification.
+    # @param block [Proc] Block to return child nodes to apply to a :statement_scope node nested under the :tag node. Block is evaluated against the builder instance.
+    # @yieldreturn [AST::Node, Array<AST::Node>] An AST node or array of AST nodes to be wrapped by a :statement_scope node, to be a child of the returned :tag node.
+    #
+    # @return [AST::Node] An AST :tag node with a :tag_namespaces child node, :tag_class child node, and :statement_scope child node.
+    #
+    # @see #statement_scope
+    # @see #tag
+    #
+    def tag_tree(tag_namespaces, tag_class, &block)
+      tag_namespace_nodes = tag_namespaces.map do |tag_namespace|
+        s(:tag_namespace, tag_namespace)
       end
 
       s(:tag,
-        s(:tag_nodes,
-          *tag_node_nodes),
+        s(:tag_namespaces,
+          *tag_namespace_nodes),
         s(:tag_class,
           s(:string, tag_class)),
         statement_scope(&block))
     end
+
+    private
+
+    def __one_or_more_child_nodes(&block)
+      children = instance_eval(&block)
+      [ children ].flatten
+    end
+
   end
 end

data/lib/csdl/interaction_filter_processor.rb

@@ -1,6 +1,54 @@
 module CSDL
+
+  # {InteractionFilterProcessor} is a class that inherits from {Processor}, providing additional methods
+  # for building CSDL specifically for Interaction Filters.
+  #
+  # Additional DSL methods provide the return statement, curly brace scopes (statement scopes), and VEDO tagging.
+  #
+  # @example
+  #   nodes = CSDL::Builder.new.root do
+  #     [
+  #       tag_tree(%w(movies), "Video") {
+  #         condition("links.url", :any, "youtube.com,vimeo.com")
+  #       },
+  #       tag_tree(%w(movies), "Social Networks") {
+  #         condition("links.url", :any, "twitter.com,facebook.com")
+  #       },
+  #
+  #       return {
+  #         _or {
+  #           [
+  #             condition("fb.topics.category", :in, "Movie,Film,TV"),
+  #             condition("fb.parent.topics.category", :in, "Movie,Film,TV")
+  #           ]
+  #         }
+  #       }
+  #     ]
+  #   end
+  #   CSDL::InteractionFilterProcessor.new.process(nodes) # => 'tag.movies "Video" {links.url any "youtube.com,vimeo.com"} tag.movies "Social Networks" {links.url any "twitter.com,facebook.com"} return {fb.topics.category in "Movie,Film,TV" OR fb.parent.topics.cateogry in "Movie,Film,TV"}'
+  #
+  # @see Processor
+  # @see Builder
+  # @see http://www.rubydoc.info/gems/ast/AST/Processor AST::Processor
+  # @see http://www.rubydoc.info/gems/ast/AST/Node AST::Node
+  # @see http://dev.datasift.com/docs/csdl DataSift CSDL Language Documentation
+  #
   class InteractionFilterProcessor < ::CSDL::Processor
 
+    # Generate a return statement by processing the child statement_scope node.
+    #
+    # @raise [MissingReturnStatementScopeError] When the :return node is missing a :statement_scope child node.
+    #
+    # @example
+    #   node = s(:return,
+    #            s(:statement_scope,
+    #             s(:string, "foo")))
+    #   CSDL::InteractionFilterProcessor.new.process(node) # => 'return {"foo"}'
+    #
+    # @param node [AST::Node] The :return node to be processed.
+    #
+    # @return [String] The processed :statement_scope child node, prepended by the "return" keyword.
+    #
     def on_return(node)
       statement_scope = node.children.find { |child| child.type == :statement_scope }
 
@@ -11,12 +59,55 @@ module CSDL
       "return #{process(statement_scope)}"
     end
 
+    # Wrap child nodes in braces. Generally not useful on its own, see {#on_return} or {#on_tag} for integrated usage.
+    #
+    # @example
+    #   node = s(:statement_scope,
+    #           s(:string, "foo"))
+    #   CSDL::InteractionFilterProcessor.new.process(node) # => '{"foo"}'
+    #
+    # @param node [AST::Node] The :statement_scope node to be processed.
+    #
+    # @return [String] The processed child nodes, joined by an empty space and wrapped in braces.
+    #
+    # @see #on_return
+    # @see #on_tag
+    #
     def on_statement_scope(node)
       "{" + process_all(node.children).join(" ") + "}"
     end
 
+    # Process :tag node with it's child nodes :tag_namespaces (optional), :tag_class, and :statement_scope.
+    #
+    # @example Tag Classification
+    #   node = s(:tag,
+    #           s(:tag_class,
+    #            s(:string, "MyTag")),
+    #           s(:statement_scope,
+    #            s(:string, "foo")))
+    #   CSDL::InteractionFilterProcessor.new.process(node) # => 'tag "MyTag" {"foo"}'
+    #
+    # @example Tag Tree Classification
+    #   node = s(:tag,
+    #           s(:tag_namespaces,
+    #            s(:tag_namespace, "foo"),
+    #            s(:tag_namespace, "bar"),
+    #            s(:tag_namespace, "baz")),
+    #           s(:tag_class,
+    #            s(:string, "MyTag")),
+    #           s(:statement_scope,
+    #            s(:string, "value")))
+    #   CSDL::InteractionFilterProcessor.new.process(node) # => 'tag.foo.bar.baz "MyTag" {"value"}'
+    #
+    # @param node [AST::Node] The :tag node to be processed.
+    #
+    # @return [String] The tag classifier raw CSDL.
+    #
+    # @raise [MissingTagClassError] When we don't have a first-level :tag_namespaces child.
+    # @raise [MissingTagStatementScopeError] When we don't have a first-level :statement_scope child.
+    #
     def on_tag(node)
-      tag_nodes       = node.children.find { |child| child.type == :tag_nodes }
+      tag_namespaces       = node.children.find { |child| child.type == :tag_namespaces }
       tag_class       = node.children.find { |child| child.type == :tag_class }
       statement_scope = node.children.find { |child| child.type == :statement_scope }
 
@@ -29,32 +120,78 @@ module CSDL
       end
 
       tag_namespace = "tag"
-      unless tag_nodes.nil?
-        tag_namespace += process(tag_nodes)
+      unless tag_namespaces.nil?
+        tag_namespace += process(tag_namespaces)
       end
 
       children = [tag_namespace] + process_all([ tag_class, statement_scope ])
       children.join(" ")
     end
 
+    # Process the first child of the :tag_class node.
+    #
+    # @param node [AST::Node] The :tag_class node to be processed.
+    #
+    # @return [String] The processed value of the first child node.
+    #
+    # @see #on_tag
+    #
     def on_tag_class(node)
       process(node.children.first)
     end
 
-    def on_tag_node(node)
+    # Process the terminal value of the :tag_namespace node.
+    #
+    # @param node [AST::Node] The :tag_namespace node to be processed.
+    #
+    # @return [String] Terminal value as a string.
+    #
+    # @see #on_tag_namespaces
+    #
+    def on_tag_namespace(node)
       node.children.first.to_s
     end
 
-    def on_tag_nodes(node)
-      child_tag_nodes = node.children.select { |child| child.type == :tag_node }
-
-      if child_tag_nodes.empty?
-        fail ::CSDL::MissingTagNodesError, "Invalid CSDL AST: A :tag_nodes node must have at least one :tag_node child"
+    # Process the :tag_namespace child nodes of a :tag_namespaces node.
+    #
+    # @example
+    #   node = s(:tag_namespaces,
+    #           s(:tag_namespace, "foo"),
+    #           s(:tag_namespace, "bar"),
+    #           s(:tag_namespace, "baz"))
+    #   CSDL::InteractionFilterProcessor.new.process(node) # => '.foo.bar.baz'
+    #
+    # @param node [AST::Node] The :tag_namespaces node to be processed.
+    #
+    # @return [String] Dot-delimited tag node namespace.
+    #
+    # @raise [MissingTagNodesError] When there aren't any first-level :tag_namespace child nodes.
+    #
+    def on_tag_namespaces(node)
+      child_tag_namespaces = node.children.select { |child| child.type == :tag_namespace }
+
+      if child_tag_namespaces.empty?
+        fail ::CSDL::MissingTagNodesError, "Invalid CSDL AST: A :tag_namespaces node must have at least one :tag_namespace child"
       end
 
-      "." + process_all(child_tag_nodes).join(".")
+      "." + process_all(child_tag_namespaces).join(".")
     end
 
+    # Raises an {InvalidInteractionTargetError} if the target isn't a valid CSDL target for interaction filters. Will
+    # be called from the base class when given a :condition node with a :target node.
+    #
+    # @example
+    #   CSDL::InteractionFilterProcessorProcessor.new.validate_target!("fake") # => raises InvalidInteractionTargetError
+    #
+    # @param target_key [String] The target to validate.
+    #
+    # @return [void]
+    #
+    # @raise [InvalidInteractionTargetError] When the terminator value is not a valid ineraction filter target. See {CSDL.interaction_target?}.
+    #
+    # @see Processor#on_condition
+    # @see Processor#on_target
+    #
     def validate_target!(target_key)
       unless ::CSDL.interaction_target?(target_key)
         fail ::CSDL::InvalidInteractionTargetError, "Interaction filters cannot use target '#{target_key}'"

data/lib/csdl/operators.rb

@@ -1,8 +1,19 @@
 module CSDL
 
+  # A CSDL Operator definition with indication as to valid data types to be used with the operator.
+  #
+  # @attr name [String] The name of the operator.
+  # @attr argument_types [Array<Symbol>] List of valid argument node types that can be associated with an operator.
+  #
+  # @see OPERATORS
+  #
   Operator = Struct.new(:name, :argument_types)
 
-  raw_operators = [
+  # A raw array of operators with their valid argument types.
+  #
+  # @return [Array<String, Array<Symbol>>] Array of operators used to produce {OPERATORS} hash.
+  #
+  RAW_OPERATORS = [
     [ "contains"         , [ :string ] ],
     [ "cs contains"      , [ :string ] ],
     [ "substr"           , [ :string ] ],
@@ -39,11 +50,26 @@ module CSDL
     [ "geo_polygon"      , [ :string ] ]
   ]
 
-  OPERATORS = raw_operators.reduce({}) do |accumulator, (operator_name, argument_types)|
+  # All possible operators.
+  #
+  # @return [Hash<String, Operator>] Hash of {Operator} structs, keyed by the string name of the operator.
+  #
+  OPERATORS = RAW_OPERATORS.reduce({}) do |accumulator, (operator_name, argument_types)|
     accumulator[operator_name] = Operator.new(operator_name, argument_types)
     accumulator
   end.freeze
 
+  # Check if the given target is a valid operator.
+  #
+  # @example
+  #   CSDL.operator?("fake") # => false
+  #   CSDL.operator?("contains") # => true
+  #   CSDL.operator?(">=") # => true
+  #
+  # @param operator [String] The name of the target.
+  #
+  # @return [Boolean] Whether or not the value is a valid CSDL Operator.
+  #
   def self.operator?(operator)
     OPERATORS.key?(operator)
   end

data/lib/csdl/processor.rb

@@ -1,28 +1,142 @@
 module CSDL
+
+  # {Processor} is a class that can take a tree of AST::Node objects built with {Builder}
+  # and produce a valid CSDL string representation according to DataSift's CSDL specification.
+  #
+  # @example
+  #   # Generate your CSDL nodes using the Builder
+  #   root_node = CSDL::Builder.new.logical_group(:or) do
+  #     #...
+  #     condition("fb.content", :contains, "match this string")
+  #     #...
+  #   end
+  #
+  #   # Process the root node and its children calling the instance method #process
+  #   CSDL::Processor.new.process(root_node)
+  #
+  # @see Builder
+  # @see http://www.rubydoc.info/gems/ast/AST/Processor AST::Processor
+  # @see http://www.rubydoc.info/gems/ast/AST/Node AST::Node
+  # @see http://dev.datasift.com/docs/csdl DataSift CSDL Language Documentation
+  #
   class Processor < ::AST::Processor
 
+    # AND two or more child nodes together.
+    #
+    # @example
+    #   node = s(:and,
+    #            s(:string, "foo"),
+    #            s(:string, "bar"),
+    #            s(:string, "baz"))
+    #   CSDL::Processor.new.process(node) # => '"foo" AND "bar" AND "baz"'
+    #
+    # @param node [AST::Node] The :and node to be processed.
+    #
+    # @raise [MissingChildNodesError] When less than 2 child nodes are present.
+    #
+    # @return [String] Processed child nodes ANDed together into a raw CSDL string representation.
+    #
     def on_and(node)
-      initial = process(node.children.first)
-      rest = node.children.drop(1)
-
-      rest.reduce(initial) do |csdl, child|
-        csdl += " AND " + process(child)
-        csdl
-      end
+      logically_join_nodes("AND", node.children)
     end
 
+    # Process the first child node as the "argument" in a condition node tree (target + operator + argument).
+    #
+    # @example
+    #   node = s(:argument,
+    #            s(:string, "foo"))
+    #   CSDL::Processor.new.process(node) # => '"foo"'
+    #
+    # @param node [AST::Node] The :argument node to be processed.
+    #
+    # @return [String] The first child node, processed by its node type into a raw CSDL string representation.
+    #
+    # @todo Raise if the node doesn't have any children.
+    #
     def on_argument(node)
       process(node.children.first)
     end
 
+    # Process :condition node and it's expected children :target, :operator, and :argument nodes.
+    #
+    # @example
+    #   node = s(:condition,
+    #             s(:target, "fb.content"),
+    #             s(:operator, :contains_any),
+    #             s(:argument,
+    #               s(:string, "foo")))
+    #   CSDL::Processor.new.process(node) # => 'fb.content contains_any "foo"'
+    #
+    # @param node [AST::Node] The :condition node to be processed.
+    #
+    # @return [String] The child nodes :target, :operator, and :argument, processed and joined.
+    #
+    # @todo Raise when we don't have a target node.
+    # @todo Raise when we don't have a operator node.
+    # @todo Raise when we don't have a argument node, assuming the operator is binary.
+    # @todo Raise if the argument node's child is not of a valid node type for the given operator.
+    #
+    def on_condition(node)
+      target   = node.children.find { |child| child.type == :target }
+      operator = node.children.find { |child| child.type == :operator }
+      argument = node.children.find { |child| child.type == :argument }
+      process_all([ target, operator, argument ].compact).join(" ")
+    end
+
+    # Wrap all processed child nodes in parentheses.
+    #
+    # @example
+    #   node = s(:logical_group,
+    #            s(:or,
+    #             s(:string, "foo"),
+    #             s(:string, "bar"),
+    #             s(:string, "baz")))
+    #   CSDL::Processor.new.process(node) # => '("foo" OR "bar" OR "baz")'
+    #
+    # @param node [AST::Node] The :logical_group node to be processed.
+    #
+    # @return [String] All child nodes processed by their node types into a raw CSDL string representation, wrapped in parentheses.
+    #
     def on_logical_group(node)
       "(" + process_all(node.children).join(" ") + ")"
     end
 
+    # Process :not node as a :condition node, prepending the logical operator NOT to the processed :condition node.
+    #
+    # @example
+    #   node = s(:not,
+    #             s(:target, "fb.content"),
+    #             s(:operator, :contains_any),
+    #             s(:argument,
+    #               s(:string, "foo")))
+    #   CSDL::Processor.new.process(node) # => 'NOT fb.content contains_any "foo"'
+    #
+    # @param node [AST::Node] The :not node to be processed.
+    #
+    # @return [String] The child nodes :target, :operator, and :argument, processed and joined.
+    #
+    # @todo Raise when we don't have a target node.
+    # @todo Raise when we don't have a operator node.
+    # @todo Raise when we don't have a argument node, assuming the operator is binary.
+    # @todo Raise if the argument node's child is not of a valid node type for the given operator.
+    # @todo Support negating logical groupings.
+    #
     def on_not(node)
-      "NOT " + process(node.updated(:filter))
+      "NOT " + process(node.updated(:condition))
     end
 
+    # Process :operator nodes, ensuring the the given terminator value is a valid operator.
+    #
+    # @example
+    #   node = s(:operator, :contains)
+    #   CSDL::Processor.new.process(node) # => 'contains'
+    #
+    # @param node [AST::Node] The :operator node to be processed.
+    #
+    # @return [String] The first child, stringified.
+    #
+    # @raise [UnknownOperatorError] When the terminator value is not a valid operator. See {CSDL.operator?}.
+    #
     def on_operator(node)
       operator = node.children.first.to_s
       unless ::CSDL.operator?(operator)
@@ -31,44 +145,104 @@ module CSDL
       operator
     end
 
+    # OR two or more child nodes together.
+    #
+    # @example
+    #   node = s(:or,
+    #             s(:string, "foo"),
+    #             s(:string, "bar"),
+    #             s(:string, "baz"))
+    #   CSDL::Processor.new.process(node) # => '"foo" OR "bar" OR "baz"'
+    #
+    # @param node [AST::Node] The :or node to be processed.
+    #
+    # @raise [MissingChildNodesError] When less than 2 child nodes are present.
+    #
+    # @return [String] Processed child nodes OR'd together into a raw CSDL string representation.
+    #
     def on_or(node)
-      if node.children.empty?
-        fail ::CSDL::MissingChildNodesError, "Invalid CSDL AST: 'or' nodes must contain at least two child nodes. Expected >= 2, got 0"
-      end
-
-      initial = process(node.children.first)
-      rest = node.children.drop(1)
-
-      if rest.empty?
-        fail ::CSDL::MissingChildNodesError, "Invalid CSDL AST: 'or' nodes must contain at least two child nodes. Expected >= 2, got #{node.children.size}"
-      end
+      logically_join_nodes("OR", node.children)
+    end
 
-      rest.reduce(initial) do |csdl, child|
-        csdl += " OR " + process(child)
-        csdl
-      end
+    # Process all child nodes. Useful for grouping child nodes without any syntax introduction.
+    #
+    # @see InteractionFilterProcessor#_return
+    # @see InteractionFilterProcessor#tag
+    # @see InteractionFilterProcessor#tag_tree
+    #
+    def on_root(node)
+      process_all(node.children).join(" ")
     end
 
+    # Wrap the stringified terminal value in quotes.
+    #
+    # @example
+    #   node = s(:string, "foo")
+    #   CSDL::Processor.new.process(node) # => '"foo"'
+    #
+    # @param node [AST::Node] The :string node to be processed.
+    #
+    # @return [String] The first child node, processed by its node type into a raw CSDL string representation.
+    #
+    # @todo Raise if the node doesn't have any children.
+    #
     def on_string(node)
       '"' + node.children.first.to_s.gsub(/"/, '\"') + '"'
     end
 
+    # Process :target nodes, ensuring the the given terminator value is a valid operator.
+    #
+    # @example
+    #   node = s(:target, "fb.content")
+    #   CSDL::Processor.new.process(node) # => 'fb.content'
+    #
+    # @param node [AST::Node] The :target node to be processed.
+    #
+    # @return [String] The first child, stringified.
+    #
+    # @raise [UnknownTargetError] When the terminator value is not a valid operator. See {#validate_target!}.
+    #
+    # @see #validate_target!
+    #
     def on_target(node)
       target = node.children.first.to_s
       validate_target!(target)
       target
     end
 
-    def on_filter(node)
-      target   = node.children.find { |child| child.type == :target }
-      operator = node.children.find { |child| child.type == :operator }
-      argument = node.children.find { |child| child.type == :argument }
-      process_all([ target, operator, argument ].compact).join(" ")
-    end
-
+    # Raises an {UnknownTargetError} if the target isn't a valid CSDL target. Useful for implenting a
+    # child processor that can ensure the target is known and valid for a given use-case
+    # (e.g. {InteractionFilterProcessor Interaction Filters} vs {QueryFilterProcessor Query Filters}).
+    # Generally not useful to be called directly, use {CSDL.target?} instead.
+    #
+    # @example
+    #   CSDL::Processor.new.validate_target!("fake") # => raises UnknownTargetError
+    #
+    # @param target_key [String] The target to validate.
+    #
+    # @return [void]
+    #
+    # @raise [UnknownTargetError] When the terminator value is not a valid operator. See {CSDL.operator?}.
+    #
     def validate_target!(target_key)
       unless ::CSDL.target?(target_key)
-        fail ::CSDL::InvalidQueryTargetError, "Query filters cannot use target '#{target_key}'"
+        fail ::CSDL::UnknownTargetError, "Target '#{target_key}' is not a known target type."
+      end
+    end
+
+    private
+
+    def logically_join_nodes(logical_operator, child_nodes)
+      if child_nodes.size < 2
+        fail ::CSDL::MissingChildNodesError, ":#{logical_operator} nodes must contain at least two child nodes. Expected >= 2, got #{child_nodes.size}"
+      end
+
+      initial = process(child_nodes.first)
+      rest = child_nodes.drop(1)
+
+      rest.reduce(initial) do |csdl, child|
+        csdl += " #{logical_operator.upcase} " + process(child)
+        csdl
       end
     end
 

data/lib/csdl/query_filter_processor.rb

@@ -1,6 +1,31 @@
 module CSDL
+
+  # {QueryFilterProcessor} is a class that inherits from {Processor}, providing additional methods
+  # for building CSDL specifically for Query Filters.
+  #
+  # @see Processor
+  # @see Builder
+  # @see http://www.rubydoc.info/gems/ast/AST/Processor AST::Processor
+  # @see http://www.rubydoc.info/gems/ast/AST/Node AST::Node
+  # @see http://dev.datasift.com/docs/csdl DataSift CSDL Language Documentation
+  #
   class QueryFilterProcessor < ::CSDL::Processor
 
+    # Raises an {InvalidQueryTargetError} if the target isn't a valid CSDL target for query filters. Will
+    # be called from the base class when given a :condition node with a :target node.
+    #
+    # @example
+    #   CSDL::QueryFilterProcessorProcessor.new.validate_target!("fake") # => raises InvalidQueryTargetError
+    #
+    # @param target_key [String] The target to validate.
+    #
+    # @return [void]
+    #
+    # @raise [InvalidQueryTargetError] When the terminator value is not a valid query filter target. See {CSDL.query_target?}.
+    #
+    # @see Processor#on_condition
+    # @see Processor#on_target
+    #
     def validate_target!(target_key)
       unless ::CSDL.query_target?(target_key)
         fail ::CSDL::InvalidQueryTargetError, "Query filters cannot use target '#{target_key}'"

data/lib/csdl/targets.rb

@@ -1,8 +1,21 @@
 module CSDL
 
+  # A CSDL Target definition with indication as to where the target can be used.
+  #
+  # @attr name [String] The name of the target.
+  # @attr interaction? [Boolean] True if the target is availble for use in an Interaction Filter.
+  # @attr analysis? [Boolean] True if the target is availble for use as an Analysis Target.
+  # @attr query? [Boolean] True if the target is availble for use in a Query Filter.
+  #
+  # @see TARGETS
+  #
   Target = Struct.new(:name, :interaction?, :analysis?, :query?)
 
-  raw_targets = [
+  # A raw array of targets with their usage flags.
+  #
+  # @return [Array<String, Boolean, Boolean, Boolean>] Array of targets used to produce {TARGETS} hash.
+  #
+  RAW_TARGETS = [
 
     [ "fb.author.age"                     , true  , true  , true  ] ,
     [ "fb.author.country"                 , true  , true  , true  ] ,
@@ -67,7 +80,11 @@ module CSDL
     [ "links.url"                         , true  , true  , true  ]
   ]
 
-  TARGETS = raw_targets.reduce({}) do |accumulator, (target_name, interaction, analysis, query)|
+  # All possible targets.
+  #
+  # @return [Hash<String, Target>] Hash of {Target} structs, keyed by the string name of the target.
+  #
+  TARGETS = RAW_TARGETS.reduce({}) do |accumulator, (target_name, interaction, analysis, query)|
     accumulator[target_name] = Target.new(target_name, interaction, analysis, query)
     accumulator
   end.freeze
@@ -76,18 +93,58 @@ module CSDL
   ANALYSIS_TARGETS    = TARGETS.select { |_, target| target.analysis? }
   QUERY_TARGETS       = TARGETS.select { |_, target| target.query? }
 
+  # Check if the given target is a valid target.
+  #
+  # @example
+  #   CSDL.target?("fake") # => false
+  #   CSDL.target?("fb.content") # => true
+  #
+  # @param target_name [String] The name of the target.
+  #
+  # @return [Boolean] Whether or not the value is a valid CSDL Target.
+  #
   def self.target?(target_name)
     TARGETS.key?(target_name)
   end
 
+  # Check if the given target is a valid interaction target.
+  #
+  # @example
+  #   CSDL.interaction_target?("interaction.tags") # => false
+  #   CSDL.interaction_target?("interaction.content") # => true
+  #
+  # @param target_name [String] The name of the target.
+  #
+  # @return [Boolean] Whether or not the value is a valid CSDL Interaction Filter Target.
+  #
   def self.interaction_target?(target_name)
     INTERACTION_TARGETS.key?(target_name)
   end
 
+  # Check if the given target is a valid analysis target.
+  #
+  # @example
+  #   CSDL.analysis_target?("interaction.content") # => false
+  #   CSDL.analysis_target?("interaction.tags") # => true
+  #
+  # @param target_name [String] The name of the target.
+  #
+  # @return [Boolean] Whether or not the value is a valid CSDL Analysis Target.
+  #
   def self.analysis_target?(target_name)
     ANALYSIS_TARGETS.key?(target_name)
   end
 
+  # Check if the given target is a valid query target.
+  #
+  # @example
+  #   CSDL.query_target?("fb.topics.website") # => false
+  #   CSDL.query_target?("fb.topic_ids") # => true
+  #
+  # @param target_name [String] The name of the target.
+  #
+  # @return [Boolean] Whether or not the value is a valid CSDL Query Filter Target.
+  #
   def self.query_target?(target_name)
     QUERY_TARGETS.key?(target_name)
   end

data/lib/csdl/version.rb

@@ -1,3 +1,3 @@
-module Csdl
-  VERSION = "0.1.0"
+module CSDL
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: csdl
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - BJ Neilsen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-16 00:00:00.000000000 Z
+date: 2015-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ast
@@ -66,7 +66,24 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: AST Processor and Query Builder for DataSift's CSDL language
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+
+  CSDL is a gem for producing Abstract Syntax Trees for the [DataSift CSDL Filter Language](http://dev.datasift.com/docs/csdl).
+  Working with an AST instead of raw strings provides a simpler way to test and validate any given CSDL filter.
 email:
 - bj.neilsen@gmail.com
 executables: []
@@ -89,7 +106,7 @@ files:
 - lib/csdl/query_filter_processor.rb
 - lib/csdl/targets.rb
 - lib/csdl/version.rb
-homepage: https://localshred.github.io
+homepage: https://github.com/localshred/csdl
 licenses: []
 metadata: {}
 post_install_message: 
@@ -113,3 +130,4 @@ signing_key:
 specification_version: 4
 summary: AST Processor and Query Builder for DataSift's CSDL language
 test_files: []
+has_rdoc: