node_query 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8376d63c29cbdec1d39e74083667724b0b84e872d7a26fc281b18061e82f02
-  data.tar.gz: '078fc70a86d2bfca404c791c6f9466780daca529aca5e984aca4ecdc6fb4c760'
+  metadata.gz: 95dcf07d501c704e59bb792454be0bae1ddfafb915c77b6a062c6331d654564b
+  data.tar.gz: 7b835b8479ff5239ea77dcb5ed09f4868b1a09cbdf5edc2f4ab9413d352030be
 SHA512:
-  metadata.gz: 444e804e949a7ebd40ebc10312de06bd570115995044598fe324210a60e85fd90931393f0eaa6845ec46c916101ab69e23ccd9490ffa40c99626ecc96c0acfb1
-  data.tar.gz: e0c5ab049ddc1f608b6559b186bd9f43b16b4d6a6b8ed906bcf261cebdb18a482768673727644797dc8f29465d423fc3148c722db001904439d1890cd80541db
+  metadata.gz: e2dbea64418363ad059ea2b6e9d93b3c2d010bdba59317327904b6a48411517a511ab6737fe40bdf4847b2833ec4d81eb5d474be7db7d831a6119c89fe904fea
+  data.tar.gz: c2cf0bfec6edfa28b644a38957dce1276cc287507c3c3034a39e0ce018f25e420faded6ad0c7c3c3838757df5107082c30d05fcf9f4323c5d5d3f32bc68337f1

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## 1.4.0 (2022-09-14)
+
+* Add options `including_self`, `stop_on_match` and `recursive`
+* Fix regex to match evaluated value
+
+## 1.3.0 (2022-09-13)
+
+* Rename `NodeQuery#parse` to `NodeQuery#query_nodes`
+* `NodeQuery#query_ndoes` accepts `including_self` argument
+* `NodeQuery#query_ndoes` supports both nql and rules
+* Add `NodeQuery#match_node?`
+* Add `NdoeRules`
+* Drop `EvaluatedValue`, use `String` instead
+* Write better test cases
+
 ## 1.2.0 (2022-07-01)
 
 * Rename `NodeQuery.get_adapter` to `NodeQuery.adapter`

data/Gemfile.lock

@@ -1,17 +1,18 @@
 PATH
   remote: .
   specs:
-    node_query (1.2.0)
-      activesupport
+    node_query (1.4.0)
+      activesupport (< 7.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.3)
+    activesupport (6.1.7)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
     ast (2.4.2)
     coderay (1.1.3)
     concurrent-ruby (1.1.10)
@@ -35,14 +36,14 @@ GEM
       guard (~> 2.1)
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
-    i18n (1.10.0)
+    i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     listen (3.7.1)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     lumberjack (1.2.8)
     method_source (1.0.0)
-    minitest (5.16.1)
+    minitest (5.16.3)
     nenv (0.3.0)
     notiffany (0.1.3)
       nenv (~> 0.1)
@@ -50,7 +51,7 @@ GEM
     oedipus_lex (2.6.0)
     parser (3.1.2.0)
       ast (~> 2.4.1)
-    parser_node_ext (0.2.0)
+    parser_node_ext (0.4.0)
       parser
     pry (0.14.1)
       coderay (~> 1.1)
@@ -75,8 +76,9 @@ GEM
     rspec-support (3.11.0)
     shellany (0.0.1)
     thor (1.2.1)
-    tzinfo (2.0.4)
+    tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
+    zeitwerk (2.6.0)
 
 PLATFORMS
   x86_64-darwin-21

data/README.md

@@ -1,6 +1,44 @@
 # NodeQuery
 
-NodeQuery defines an AST node query language, which is a css like syntax for matching nodes.
+NodeQuery defines an AST node query language, which is a css like syntax for matching nodes,
+it supports other ast parser if it implements `NodeQuery::Adapter`.
+
+## Table of Contents
+
+- [NodeQuery](#nodequery)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Node Query Language](#node-query-language)
+    - [nql matches node type](#nql-matches-node-type)
+    - [nql matches attribute](#nql-matches-attribute)
+    - [nql matches nested attribute](#nql-matches-nested-attribute)
+    - [nql matches evaluated value](#nql-matches-evaluated-value)
+    - [nql matches nested selector](#nql-matches-nested-selector)
+    - [nql matches method result](#nql-matches-method-result)
+    - [nql matches operators](#nql-matches-operators)
+    - [nql matches array node attribute](#nql-matches-array-node-attribute)
+    - [nql matches * in attribute key](#nql-matches--in-attribute-key)
+    - [nql matches multiple selectors](#nql-matches-multiple-selectors)
+      - [Descendant combinator](#descendant-combinator)
+      - [Child combinator](#child-combinator)
+      - [Adjacent sibling combinator](#adjacent-sibling-combinator)
+      - [General sibling combinator](#general-sibling-combinator)
+    - [nql matches goto scope](#nql-matches-goto-scope)
+    - [nql matches pseudo selector](#nql-matches-pseudo-selector)
+    - [nql matches multiple expressions](#nql-matches-multiple-expressions)
+  - [Node Rules](#node-rules)
+    - [rules matches node type](#rules-matches-node-type)
+    - [rules matches attribute](#rules-matches-attribute)
+    - [rules matches nested attribute](#rules-matches-nested-attribute)
+    - [rules matches evaluated value](#rules-matches-evaluated-value)
+    - [rules matches nested selector](#rules-matches-nested-selector)
+    - [rules matches method result](#rules-matches-method-result)
+    - [rules matches operators](#rules-matches-operators)
+    - [rules matches array nodes attribute](#rules-matches-array-nodes-attribute)
+  - [Write Adapter](#write-adapter)
+  - [Development](#development)
+  - [Contributing](#contributing)
 
 ## Installation
 
@@ -20,12 +58,408 @@ Or install it yourself as:
 
 ## Usage
 
-It provides only one api:
+It provides two apis: `query_nodes` and `match_node?`
+
+```ruby
+node_query = NodeQuery.new(nqlOrRules: String | Hash) # Initialize NodeQuery
+node_query.query_nodes(node: Node, options = { including_self: true, stop_on_match: false, recursive: true }): Node[] # Get the matching nodes.
+node_query.match_node?(node: Node): boolean # Check if the node matches nql or rules.
+```
+
+Here is an example for parser ast node.
+
+```ruby
+source = `
+  class User
+    def initialize(id, name)
+      @id = id
+      @name = name
+    end
+  end
+
+  user = User.new(1, "Murphy")
+`
+node = Parser::CurrentRuby.parse(source)
+
+# It will get the node of initialize.
+NodeQuery.new('.def[name=initialize]').query_nodes(node)
+NodeQuery.new({ nodeType: 'def', name: 'initialize' }).query_nodes(node)
+```
+
+## Node Query Language
+
+### nql matches node type
+
+```
+.class
+```
+
+It matches class node
+
+### nql matches attribute
+
+```
+.class[name=User]
+```
+
+It matches class node whose name is User
+
+### nql matches nested attribute
+
+```
+.class[parent_class.name=Base]
+```
+
+It matches class node whose parent class name is Base
+
+### nql matches evaluated value
+
+```
+.ivasgn[left_value="@{{right_value}}"]
+```
+
+It matches ivasgn node whose left value equals '@' plus the evaluated value of right value.
+
+### nql matches nested selector
+
+```
+.def[body.0=.ivasgn]
+```
+
+It matches def node whose first child node is an ivasgn node.
+
+### nql matches method result
+
+```
+.def[arguments.size=2]
+```
+
+It matches def node whose arguments size is 2.
+
+### nql matches operators
+
+```
+.class[name=User]
+```
+
+Value of name is equal to User
+
+```
+.class[name^=User]
+```
+
+Value of name starts with User
+
+```
+.class[name$=User]
+```
+
+Value of name ends with User
+
+```
+.class[name*=User]
+```
+
+Value of name contains User
+
+```
+.def[arguments.size!=2]
+```
+
+Size of arguments is not equal to 2
+
+```
+.def[arguments.size>=2]
+```
+
+Size of arguments is greater than or equal to 2
+
+```
+.def[arguments.size>2]
+```
+
+Size of arguments is greater than 2
+
+```
+.def[arguments.size<=2]
+```
+
+Size of arguments is less than or equal to 2
+
+```
+.def[arguments.size<2]
+```
+
+Size of arguments is less than 2
+
+```
+.class[name IN (User Account)]
+```
+
+Value of name is either User or Account
+
+```
+.class[name NOT IN (User Account)]
+```
+
+Value of name is neither User nor Account
+
+```
+.def[arguments INCLUDES id]
+```
+
+Value of arguments includes id
+
+```
+.class[name=~/User/]
+```
+
+Value of name matches User
+
+```
+.class[name!~/User/]
+```
+
+Value of name does not match User
+
+```
+.class[name IN (/User/ /Account/)]
+```
+
+Value of name matches either /User/ or /Account/
+
+### nql matches array node attribute
+
+```
+.def[arguments=(id name)]
+```
+
+It matches def node whose arguments are id and name.
+
+### nql matches * in attribute key
+
+```
+.def[arguments.*.name IN (id name)]
+```
+
+It matches def node whose arguments are either id or name.
+
+### nql matches multiple selectors
+
+#### Descendant combinator
+
+```
+.class .send
+```
+
+It matches send node whose ansestor is class node.
+
+#### Child combinator
+
+```
+.def > .send
+```
+
+It matches send node whose parent is def node.
+
+#### Adjacent sibling combinator
+
+```
+.send[left_value=@id] + .send
+```
+
+It matches send node only if it is immediately follows the send node whose left value is @id.
+
+#### General sibling combinator
+
+```
+.send[left_value=@id] ~ .send
+```
+
+It matches send node only if it is follows the send node whose left value is @id.
+
+### nql matches goto scope
+
+```
+.def body .send
+```
+
+It matches send node who is in the body of def node.
+
+### nql matches pseudo selector
+
+```
+.class:has(.def[name=initialize])
+```
+
+It matches class node who has an initialize def node.
+
+```
+.class:not_has(.def[name=initialize])
+```
+
+It matches class node who does not have an initialize def node.
+
+### nql matches multiple expressions
+
+```
+.ivasgn[left_value=@id], .ivasgn[left_value=@name]
+```
+
+It matches ivasgn node whose left value is either @id or @name.
+
+## Node Rules
+
+### rules matches node type
+
+```
+{ nodeType: 'class' }
+```
+
+It matches class node
+
+### rules matches attribute
+
+```
+{ nodeType: 'def', name: 'initialize' }
+```
+
+It matches def node whose name is initialize
+
+```
+{ nodeType: 'def', arguments: { "0": 1, "1": "Murphy" } }
+```
+
+It matches def node whose arguments are 1 and Murphy.
+
+### rules matches nested attribute
+
+```
+{ nodeType: 'class', parent_class: { name: 'Base' } }
+```
+
+It matches class node whose parent class name is Base
+
+### rules matches evaluated value
+
+```
+{ nodeType: 'ivasgn', left_value: '@{{right_value}}' }
+```
+
+It matches ivasgn node whose left value equals '@' plus the evaluated value of right value.
+
+### rules matches nested selector
+
+```
+{ nodeType: 'def', body: { "0": { nodeType: 'ivasgn' } } }
+```
+
+It matches def node whose first child node is an ivasgn node.
+
+### rules matches method result
+
+```
+{ nodeType: 'def', arguments: { size: 2 } }
+```
+
+It matches def node whose arguments size is 2.
+
+### rules matches operators
+
+```
+{ nodeType: 'class', name: 'User' }
+```
+
+Value of name is equal to User
+
+```
+{ nodeType: 'def', arguments: { size { not: 2 } }
+```
+
+Size of arguments is not equal to 2
+
+```
+{ nodeType: 'def', arguments: { size { gte: 2 } }
+```
+
+Size of arguments is greater than or equal to 2
+
+```
+{ nodeType: 'def', arguments: { size { gt: 2 } }
+```
+
+Size of arguments is greater than 2
+
+```
+{ nodeType: 'def', arguments: { size { lte: 2 } }
+```
+
+Size of arguments is less than or equal to 2
+
+```
+{ nodeType: 'def', arguments: { size { lt: 2 } }
+```
+
+Size of arguments is less than 2
+
+```
+{ nodeType: 'class', name: { in: ['User', 'Account'] } }
+```
+
+Value of name is either User or Account
+
+```
+{ nodeType: 'class', name: { not_in: ['User', 'Account'] } }
+```
+
+Value of name is neither User nor Account
+
+```
+{ nodeType: 'def', arguments: { includes: 'id' } }
+```
+
+Value of arguments includes id
+
+```
+{ nodeType: 'class', name: /User/ }
+```
+
+Value of name matches User
+
+```
+{ nodeType: 'class', name: { not: /User/ } }
+```
+
+Value of name does not match User
+
+```
+{ nodeType: 'class', name: { in: [/User/, /Account/] } }
+```
+
+Value of name matches either /User/ or /Account/
+
+### rules matches array nodes attribute
+
+```
+{ nodeType: 'def', arguments: ['id', 'name'] }
+```
+
+It matches def node whose arguments are id and name.
+
+## Write Adapter
+
+Different parser, like parser, will generate different AST nodes, to make NodeQuery work for them all,
+we define an [Adapter](https://github.com/xinminlabs/node-query-ruby/blob/main/lib/node_query/adapter.rb) interface,
+if you implement the Adapter interface, you can set it as NodeQuery's adapter.
 
 ```ruby
-NodeQuery.new(nodeQueryString).parse(node)
+NodeQuery.configure(adapter: ParserAdapter.new)
 ```
 
+Here is the ParserAdapter implementation:
+
+[ParserAdapter](https://github.com/xinminlabs/node-query-ruby/blob/main/lib/node_query/parser_adapter.rb)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/node_query/compiler/attribute.rb

@@ -17,7 +17,7 @@ module NodeQuery::Compiler
     # @param node [Node] the node
     # @return [Boolean]
     def match?(node)
-      @value.base_node = node if @value.is_a?(EvaluatedValue)
+      @value.base_node = node if @value.is_a?(String)
       node && @value.match?(NodeQuery::Helper.get_target_node(node, @key), @operator)
     end
 

data/lib/node_query/compiler/comparable.rb

@@ -25,7 +25,7 @@ module NodeQuery::Compiler
           !actual.is_a?(::Array) || actual.size != expected_value.size ||
             actual.zip(expected_value).any? { |actual_node, expected_node| expected_node.match?(actual_node, '!=') }
         else
-          actual_value(node) != expected_value
+          !is_equal?(node)
         end
       when '=~'
         actual_value(node) =~ expected_value
@@ -65,16 +65,23 @@ module NodeQuery::Compiler
           actual.is_a?(::Array) && actual.size == expected_value.size &&
             actual.zip(expected_value).all? { |actual_node, expected_node| expected_node.match?(actual_node, '==') }
         else
-          actual_value(node) == expected_value
+          is_equal?(node)
         end
       end
     end
 
+    # Check if the actual value equals the node value.
+    # @param node [Node] the node
+    # @return [Boolean] true if the actual value equals the node value.
+    def is_equal?(node)
+      actual_value(node) == expected_value
+    end
+
     # Get the actual value from ast node.
     # @param node [Node] ast node
     # @return the node value, could be integer, float, string, boolean, nil, range, and etc.
     def actual_value(node)
-      if node.is_a?(::Parser::AST::Node)
+      if NodeQuery.adapter.is_node?(node)
         case NodeQuery.adapter.get_node_type(node)
         when :int, :float, :str, :sym
           NodeQuery.adapter.get_children(node).last

data/lib/node_query/compiler/expression.rb

@@ -11,22 +11,19 @@ module NodeQuery::Compiler
       @rest = rest
     end
 
-    # Check if the node matches the expression.
-    # @param node [Node] the node
-    # @return [Boolean]
-    def match?(node)
-      !query_nodes(node).empty?
-    end
-
     # Query nodes by the selector and the rest expression.
     # @param node [Node] node to match
+    # @param options [Hash] if query the current node
+    # @option options [boolean] :including_self if query the current node, default is ture
+    # @option options [boolean] :stop_on_match if stop on first match, default is false
+    # @option options [boolean] :recursive if stop on first match, default is true
     # @return [Array<Node>] matching nodes.
-    def query_nodes(node)
-      matching_nodes = @selector.query_nodes(node)
+    def query_nodes(node, options = {})
+      matching_nodes = @selector.query_nodes(node, options)
       return matching_nodes if @rest.nil?
 
       matching_nodes.flat_map do |matching_node|
-        @rest.query_nodes(matching_node)
+        @rest.query_nodes(matching_node, options)
       end
     end
 

data/lib/node_query/compiler/expression_list.rb

@@ -13,12 +13,23 @@ module NodeQuery::Compiler
 
     # Query nodes by the current and the rest expression.
     # @param node [Node] node to match
+    # @param options [Hash] if query the current node
+    # @option options [boolean] :including_self if query the current node, default is ture
+    # @option options [boolean] :stop_on_match if stop on first match, default is false
+    # @option options [boolean] :recursive if stop on first match, default is true
     # @return [Array<Node>] matching nodes.
-    def query_nodes(node)
-      matching_nodes = @expression.query_nodes(node)
+    def query_nodes(node, options = {})
+      matching_nodes = @expression.query_nodes(node, options)
       return matching_nodes if @rest.nil?
 
-      matching_nodes + @rest.query_nodes(node)
+      matching_nodes + @rest.query_nodes(node, options)
+    end
+
+    # Check if the node matches the expression list.
+    # @param node [Node] the node
+    # @return [Boolean]
+    def match_node?(node)
+      !query_nodes(node).empty?
     end
 
     def to_s

data/lib/node_query/compiler/identifier.rb

@@ -19,7 +19,7 @@ module NodeQuery::Compiler
     # if the node is an Array, return the array of each element's actual value,
     # otherwise, return the String value.
     def actual_value(node)
-      if node.is_a?(::Parser::AST::Node)
+      if NodeQuery.adapter.is_node?(node)
         NodeQuery.adapter.get_source(node)
       elsif node.is_a?(::Array)
         node.map { |n| actual_value(n) }

data/lib/node_query/compiler/regexp.rb

@@ -13,16 +13,13 @@ module NodeQuery::Compiler
 
     # Check if the regexp value matches the node value.
     # @param node [Node] the node
-    # @param operator [String] the operator
-    # @return [Boolean] true if the regexp value matches the node value, otherwise, false.
-    def match?(node, operator = '=~')
-      match =
-        if node.is_a?(::Parser::AST::Node)
-          @value.match(NodeQuery.adapter.get_source(node))
-        else
-          @value.match(node.to_s)
-        end
-      operator == '=~' ? match : !match
+    # @return [Boolean] true if the regexp value matches the node value.
+    def is_equal?(node)
+      if NodeQuery.adapter.is_node?(node)
+        @value.match(NodeQuery.adapter.get_source(node))
+      else
+        @value.match(node.to_s)
+      end
     end
 
     # Get valid operators.