scrubyt 0.1.0

data/README

@@ -0,0 +1,41 @@
+============================================
+scRUBYt! - Hpricot and Mechanize on steroids
+============================================
+
+A simple to learn and use, yet very powerful web extraction framework written in Ruby. Navigate through the Web, Extract, query, transform and save relevant data from the Web page of interest by the concise and easy to use DSL provided by scRUBYt!.
+
+=============================================
+Why do we need one more web-scraping toolkit?
+=============================================
+
+After all, we have HPricot, and Rubyful soup, and Mechanize, and scrAPI, and ARIEL and ...
+Well, because scRUBYt! is different. It has entirely different philosophy, underlying techniques, use cases - shortly it should be used in different situations with different requirements than the previosly mentioned ones.
+
+If you need something quick and/or would like to have maximal control over the scaping process, I recommend HPricot. Mechanize shines when it comes to Web page navigation. Since scRUBYt! is operating based on XPaths, sometimes you will chose scrAPI because CSS selectors will better suit your needs. The list goes on and on, boiling down to the good old mantra: use the right tool for the right job!
+
+I hope there will be times when you will want to experiment with Pandora's box and reach after the power of scRUBYt! :-)
+
+========================================
+OK, OK, I believe you, what should I do?
+========================================
+
+Useful adresses
+
+scrubyt.rubyforge.org
+rubyrailways.com (some theory)
+future: public extractor repository
+
+==============
+How to install
+==============
+
+ragel
+hpricot from trunk
+
+scrubyt gem
+subversion
+
+
+
+
+

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+
+###################################################
+# Dependencies
+###################################################
+
+task "default" => ["test"]
+task "fulltest" => ["test", "blackbox"] 
+
+###################################################
+# Gem specification
+###################################################
+
+gem_spec = Gem::Specification.new do |s|           
+  s.name = 'scrubyt' 
+  s.version = '0.1.0' 
+  s.summary = 'A powerful Web-scraping framework'
+  s.description = %{scRUBYt! is an easy to learn and use, yet powerful and effective web scraping framework. It's most interesting part is a Web-scraping DSL built on HPricot and WWW::Mechanize, which allows to navigate to the page of interest, then extract and query data records with a few lines of code. It is hard to describe scRUBYt! in a few sentences - you have to see it for yourself!} 
+  # Files containing Test::Unit test cases. 
+  s.test_files = FileList['test/unittests/**/*'] 
+  # List of other files to be included. 
+  s.files = FileList['README', 'Rakefile', 'lib/**/*.rb']
+  s.author = 'Peter Szinek'
+  s.email = 'peter@rubyrailways.com' 
+  s.homepage = 'http://www.scrubyt.rubyforge.org'
+end 
+
+###################################################
+# Tasks
+###################################################
+
+Rake::RDocTask.new do |rdoc|
+     files = ['lib/**/*.rb']
+     rdoc.rdoc_files.add(files)
+     rdoc.main = "README" # page to start on
+     rdoc.title = "Scrubyt Documentation"
+     rdoc.template = "resources/allison/allison.rb"
+     rdoc.rdoc_dir = 'doc' # rdoc output folder
+     rdoc.options << '--line-numbers' << '--inline-source'
+end
+
+Rake::TestTask.new do |test|           
+     test.pattern = 'test/unittests/*_test.rb' 
+end 
+
+task "blackbox" do
+  ruby "test/blackbox/run_blackbox_tests.rb"
+end
+
+Rake::GemPackageTask.new(gem_spec) do |pkg|           
+  pkg.need_zip = false
+  pkg.need_tar = false 
+end 

data/lib/scrubyt.rb

@@ -0,0 +1,9 @@
+require 'scrubyt/constraint_adder.rb'
+require 'scrubyt/constraint.rb'
+require 'scrubyt/export.rb'
+require 'scrubyt/extractor.rb'
+require 'scrubyt/filter.rb'
+require 'scrubyt/pattern.rb'
+require 'scrubyt/result_dumper.rb'
+require 'scrubyt/result.rb'
+require 'scrubyt/xpathutils.rb'

data/lib/scrubyt/constraint.rb

@@ -0,0 +1,185 @@
+module Scrubyt
+  ##
+  #=<tt>Rejecting result instances based on further rules</tt>
+  # 
+  #The two  most trivial problems with a set of rules is that they match either less
+  #or more instances than we would like them to. Constraints are a way to remedy the second problem:
+  #they serve as a tool to filter out some result instances based on rules. A typical
+  #example:
+  # 
+  #* *ensure_presence_of_ancestor_pattern* consider this model:
+  #    <book>
+  #      <author>...</author>
+  #      <title>...</title>
+  #    </book>
+  # 
+  #If I attach the *ensure_presence_of_ancestor_pattern* to the pattern 'book' with values
+  #'author' and 'title', only those books will be matched which have an author and a 
+  #title (i.e.the child patterns author and title must extract something). This is a way
+  #to say 'a book MUST have an author and a title'. 
+  class Constraint
+    #There are more possible ways of applying/checking constraints in the case of
+    #ones that can not be checked in the context node (e.g. ensure_presence_of - 
+    #since it may require the evaluation of child patterns of the context pattern to
+    #arbitray level) 
+    #
+    #In such cases, the possibilities are:
+    #
+    #1) make a depth-first evaluation from the context pattern until the needed ancestor
+    #   pattern is evaluated. This can mess things up, since if any ancestor node uses
+    #   the sinks of predecessor(s) other than the context node, those need to be evaluated
+    #   too, and we may run into a cyclyc dependency or at least a complicated recursion
+    #   
+    #2) Post processing - evaluate normally and throw out results which do not pass the 
+    #   constraint
+    #
+    #2b) Do it on the XML level - most probably this solution will be implemented
+    
+    # Different constraint types
+    CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ANCESTOR_PATTERN = 0
+    CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ANCESTOR_PATTERN = 1
+    CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ATTRIBUTE = 2
+    CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ATTRIBUTE = 3
+    CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ANCESTOR_NODE = 4
+    CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ANCESTOR_NODE = 5
+    
+    
+    attr_reader :type, :target, :parent_filter
+    
+    #Add 'ensure presence of ancestor pattern' constraint
+    
+    #If this type of constraint is added to a pattern, it must have an ancestor pattern
+    #(child pattern, or child pattern of a child pattern, etc.) denoted by "ancestor"
+    #'Has an ancestor pattern' means that the ancestor pattern actually extracts something
+    #(just by looking at the wrapper model, the ancestor pattern is always present)
+    #ON result level!!!
+    def self.add_ensure_presence_of_ancestor_pattern(parent_filter, ancestor)
+      Constraint.new(parent_filter, ancestor, CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ANCESTOR_PATTERN)
+    end
+    
+    #Add 'ensure presence of ancestor pattern' constraint
+    
+    #If this type of constraint is added to a pattern, it must NOT have an ancestor pattern
+    #(child pattern, or child pattern of a child pattern, etc.) denoted by "ancestor"
+    #'Has an ancestor pattern' means that the ancestor pattern actually extracts something
+    #(just by looking at the wrapper model, the ancestor pattern is always present)
+    #ON result level!!!
+    def self.add_ensure_absence_of_ancestor_pattern(parent_filter, ancestor)
+      Constraint.new(parent_filter, ancestor, CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ANCESTOR_PATTERN)
+    end  
+    
+    #Add 'ensure absence of attribute' constraint
+  
+    #If this type of constraint is added to a pattern, the HTML node it targets
+    #must NOT have an attribute named "attribute_name" with the value "attribute_value"
+    def self.add_ensure_absence_of_attribute(parent_filter, attribute_hash)
+      Constraint.new(parent_filter, 
+                     attribute_hash, 
+                     CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ATTRIBUTE)
+    end
+    
+    #Add 'ensure presence of attribute' constraint
+    
+    #If this type of constraint is added to a pattern, the HTML node it targets
+    #must have an attribute named "attribute_name" with the value "attribute_value"
+    def self.add_ensure_presence_of_attribute(parent_filter, attribute_hash)
+      Constraint.new(parent_filter, 
+                     attribute_hash, 
+                     CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ATTRIBUTE)
+    end
+    
+    #Add 'ensure absence of ancestor node' constraint  
+    
+    #If this type of constraint is added to a pattern, the HTML node extracted by the pattern
+    #must NOT contain a HTML ancestor node called 'node_name' with the attribute set 'attributes'.
+    #
+    #"attributes" is an array of hashes, for example
+    #[{'font' => 'red'}, {'href' => 'http://www.google.com'}]
+    #in the case that more values have to be checked with the same key (e.g. 'class' => 'small' and '
+    #class' => 'wide' it has to be written as [{'class' => ['small','wide']}]
+    #
+    #"attributes" can be empty - in this case just the 'node_name' is checked
+    def self.add_ensure_absence_of_ancestor_node(parent_filter, node_name, attributes)
+      Constraint.new(parent_filter, 
+                     [node_name, attributes],
+                     CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ANCESTOR_NODE)                   
+    end
+    
+    #Add 'ensure presence of ancestor node' constraint  
+    
+    #If this type of constraint is added to a pattern, the HTML node extracted by the pattern
+    #must NOT contain a HTML ancestor node called 'node_name' with the attribute set 'attributes'.
+    #
+    #"attributes" is an array of hashes, for example
+    #[{'font' => 'red'}, {'href' => 'http://www.google.com'}]
+    #in the case that more values have to be checked with the same key (e.g. 'class' => 'small' and '
+    #class' => 'wide' it has to be written as [{'class' => ['small','wide']}]
+    #
+    #"attributes" can be empty - in this case just the 'node_name' is checked
+    def self.add_ensure_presence_of_ancestor_node(parent_filter, node_name, attributes)
+      Constraint.new(parent_filter, 
+                     [node_name, attributes],
+                     CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ANCESTOR_NODE)                   
+    end
+    
+    #Evaluate the constraint; if this function returns true,
+    #it means that the constraint passed, i.e. its filter will be added to the exctracted
+    #content of the pattern
+    def check(result)
+      case @type
+        when CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ANCESTOR_PATTERN
+          puts "CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ANCESTOR_PATTERN"
+        when CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ANCESTOR_PATTERN
+          puts "CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ANCESTOR_PATTERN"
+        when CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ATTRIBUTE
+          attribute_present(result)
+        when CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ATTRIBUTE
+          !attribute_present(result)
+        when CONSTRAINT_TYPE_ENSURE_PRESENCE_OF_ANCESTOR_NODE          
+          ancestor_node_present(result)        
+        when CONSTRAINT_TYPE_ENSURE_ABSENCE_OF_ANCESTOR_NODE          
+          !ancestor_node_present(result)
+      end
+    end
+    
+  private
+    #We would not like these to be called from outside
+    def initialize(parent_filter, target, type)
+      @type = type
+      @parent_filter = parent_filter
+      @target = target
+    end  
+    
+    #Implementation of the ancestor node presence test
+    #Check the documentation of the add_ensure_presence_of_ancestor_node method
+    #for further information on the result parameter
+    def ancestor_node_present(result)
+      found = false
+      node_name = @target[0]
+      node_attributes = @target[1]
+      node_attributes.each do |pair|
+        return true if !result.search("//#{node_name}[@#{pair[0]}='#{pair[1]}']").empty?
+      end
+      if node_attributes.empty?
+        return true if !result.search("//#{node_name}").empty?
+      end
+      false
+    end
+    
+    def attribute_present(result)
+      match = true
+      #If v = nil, the value of the attribute can be arbitrary;
+      #Therefore, in this case we just have to make sure that the attribute is
+      #present (i.e. != nil), we don't care about the value
+      @target.each do |k,v|
+        if v == nil
+            match &&= (result.attributes[k.to_s] != nil) 
+          else
+            match &&= (result.attributes[k.to_s] == v.to_s) 
+        end        
+      end
+      match
+    end
+    
+  end #end of class
+end #end of module

data/lib/scrubyt/constraint_adder.rb

@@ -0,0 +1,86 @@
+module Scrubyt
+  ##
+  #=<tt>Utility class for adding constraints</tt>
+  #
+  #Originally methods of Pattern - but since Pattern was already too heavy (and after 
+  #all, adding a constraint (logically) does not belong to Pattern anyway) it was moved
+  #to this utility class. In pattern everything that begins with ensure_ 
+  #is automatically dispatched here.
+  #
+  #I will not document the functions since these are just forwarders; See the 'real'
+  #functions with their documentation in Scrubyt::Constraint.rb
+  class ConstraintAdder
+  
+    def self.ensure_presence_of_ancestor_pattern(pattern, ancestor_node_name)    
+      data = self.prepare_ensure_ancestor_pattern(pattern, sym_root, sym_ancestor)
+      pattern.filters[0].ensure_presence_of_ancestor_pattern(ancestor_node_name)
+      pattern #To make chaining possible
+    end
+    
+    def self.ensure_absence_of_ancestor_pattern(pattern, ancestor_node_name)
+      data = self.prepare_ensure_ancestor_pattern(pattern, sym_root, sym_ancestor)
+      pattern.filters[0].ensure_absence_of_ancestor_pattern(ancestor_node_name)
+      pattern #To make chaining possible
+    end
+    
+    def self.ensure_presence_of_ancestor_node(pattern, ancestor_node_name, attributes=[])
+       pattern.filters[0].ensure_presence_of_ancestor_node(ancestor_node_name, 
+                                                           prepare_attributes(attributes))
+       pattern #To make chaining possible
+    end
+    
+    def self.ensure_absence_of_ancestor_node(pattern, ancestor_node_name, attributes=[])
+      pattern.filters[0].ensure_absence_of_ancestor_node(ancestor_node_name, 
+                                                         prepare_attributes(attributes))
+      pattern #To make chaining possible
+    end
+    
+    def self.ensure_presence_of_attribute(pattern, attribute_hash)
+       pattern.filters[0].ensure_presence_of_attribute(attribute_hash)
+       pattern #To make chaining possible
+    end
+    
+    def self.ensure_absence_of_attribute(pattern, attribute_hash)
+       pattern.filters[0].ensure_absence_of_attribute(attribute_hash)
+       pattern #To make chaining possible
+    end        
+    
+private
+    def self.find_by_name(root_pattern, name)
+      @found_pattern = nil
+      find_by_name_recursive(root_pattern, name)
+      if (@found_pattern == nil)
+        #$Logger.error("Fatal: No pattern named #{name} exists!")
+	puts "Fatal: No pattern named #{name} exists!"
+      end
+      @found_pattern      
+    end
+    
+    def self.find_by_name_recursive(pattern, name)
+      if pattern.name == name
+        @found_pattern = pattern
+      else
+        pattern.children.each {|child| find_by_name_recursive(child, name)}
+      end
+    end
+    
+    def self.prepare_attributes(attributes)
+      attribute_pairs = []
+      attributes.each do |key, value|
+        if (value.instance_of? Array)
+          value.each {|val| attribute_pairs << [key,val]}          
+        else
+          attribute_pairs << [key, value]
+        end
+      end
+      return attribute_pairs
+    end    
+    
+    def self.prepare_ensure_ancestor_pattern(pattern, root, ancestor)
+      context_pattern = find_by_name(pattern.root_pattern, root)
+      target_pattern = find_by_name(pattern.root_pattern, ancestor)
+      return [context_pattern, target_pattern]    
+    end
+  
+  end #end of class ConstraintAddere
+end #end of module Scrubyt

data/lib/scrubyt/export.rb

@@ -0,0 +1,187 @@
+#require File.join(File.dirname(__FILE__), 'pattern.rb')
+
+module Scrubyt
+  # =<tt>exporting previously defined extractors</tt>
+  class Export
+    ##
+    #Exports the given extractor (specified by it's root pattern) from the given file
+    #
+    #_input_file_ - the full path of the file where the extractor was defined. This can
+    #be achieved by calling 
+    # 
+    #  pattern.export(__File__)
+    # 
+    #from the file of the extractor definition.
+    # 
+    #*parameters*
+    # 
+    #_pattern_ - the root pattern of the extractor. This is the variable 'something' in
+    #such a call:
+    # 
+    #  something = Scrubyt::Extractor.define ...
+    #  
+    #However, since the export method should not be called directly (pattern is calling 
+    #it), you will probably never need to care about this parameter.
+    #
+    #_output_file_name_ - the name of the file where the exported extractor should be 
+    #dumped; From default (i.e. if you don't specify this parameter) this is 
+    #"#{wrapper_name}_extractor_export.rb". You may override this setting if specifying
+    #this optional parameter.
+    #
+    #_extractor_result_file_name_ - the name of the file, where the result of the 
+    #*exported* extractor should be dumped - for example, if _output_file_name_ is "foo.rb"
+    #and _extractor_result_file_name_ is "bar.xml", the extractor is exported to a file named
+    #"foo.rb", and after running "foo.rb", the results will be dumped to the file "bar.xml"
+    #If this option is not specified, the result is dumped to standard output as XML.
+    #
+    #Examples:
+    #
+    #  camera_data = Scrubyt::Extractor.define do
+    #    Action.fetch File.join(File.dirname(__FILE__), "input.html")
+    #    
+    #    P.item_name "Canon EOS 20D SLR Digital Camera (Lens sold separately)"
+    #  end
+    #  
+    #  camera_data.export(__FILE__)
+    #  
+    #This will export this extractor to a file called "camera_data_extractor_export.rb". 
+    #If "camera_data_extractor_export.rb" will be executed, the result will be dumped
+    #to the standard output.
+    #  
+    #Note that the export method in the last line belongs to the class Scrubyt::Pattern
+    #and not to Scrubyt::Export (i.e. this class). Scrubyt::Pattern.export will call 
+    #Scrubyt::Export.export.
+    #
+    #  camera_data = Scrubyt::Extractor.define do
+    #    Action.fetch File.join(File.dirname(__FILE__), "input.html")
+    #    
+    #    P.item_name "Canon EOS 20D SLR Digital Camera (Lens sold separately)"
+    #  end
+    #  
+    #  camera_data.export(__FILE__, 'my_super_camera_extractor.rb', '/home/peter/stuff/result.xml')
+    #  
+    #This snippet will export the extractor to a file named 'my_super_camera_extractor.rb'.
+    #After running 'my_super_camera_extractor.rb', the result will be dumped to the file
+    #'/home/peter/stuff/result.xml'.
+    def self.export(input_file, pattern, output_file_name, extractor_result_file_name)
+      @result = ""
+      contents = open(input_file).read
+      wrapper_name = contents.scan(/\s+(.+)\s+=.*Extractor\.define.*/)
+      output_file = output_file_name == nil ? open("#{wrapper_name}_extractor_export.rb", 'w') :
+                                              open(output_file_name, 'w')
+      export_header(output_file)
+      export_extractor(contents, pattern, output_file)
+      export_footer(output_file, wrapper_name, extractor_result_file_name)
+      cleanup_result
+      output_file.write(@result)      
+      output_file.close
+      @result    
+    end
+
+private
+    def self.export_header(output_file)
+      @result += "require 'lib/extractor.rb'\n\n"
+    end
+    
+    def self.cleanup_result
+      @result.gsub!('P.') {}
+    end
+   
+    #OK, I have to admit: this function is powered by woodo magic. A lots of woodoo magic. 
+    #Piles of tons of heaps of woodoo magic :-)
+    #
+    #The only reason I can expect it to work is that it passes all the tests of the extractors 
+    #I have created so far. However at the same time  I know how to create one easily which 
+    #would break the exporting, so don't experiment with this too much...
+    #
+    #The other solutions include:
+    #- serialization (yaml, pstore etc) but that would mess the code terribly up - so 
+    #therefore I did not chose this solution.
+    #- defining the block as string - however, this introduces ugly %q{}s etc - all in all, 
+    #this is still a more viable solution that serialization IMHO
+    #- a lot of other tricks - however, all of these introduce a lot of noise which I don't
+    #like.
+    #
+    #Conclusion: If there will be no terrible, unrepairable, uncontrollable etc. problems 
+    #with this approach, it will be replaced (probably with constructing the extractor as
+    #a string). However, until that point, it will stay.    
+    def self.export_extractor(contents, pattern, output_file)
+      first_line = contents.scan(/.*Extractor\.define.*/)
+      #During wrapper construction, we count the number of blocks; add one occurrence of 
+      #end (to close the block of the extractor definition)
+      count = pattern.root_pattern.block_count + 1
+      #Construct the extractor definition matching regexp based on the number of ends
+      definition = contents.scan(/Extractor\.define(?:.*?(?:\}|end)){#{count.to_s}}/m)
+      #Since the regexp matching the extractor definition was multiline, get the first
+      #line separately and patch it in!
+      rows = definition[0].split("\n")
+      #Lord of the hacks :-) Originally, when we have used the class P as a pattern definer,
+      #patterns could be matched very easily from the extractor definition (because they begun
+      #with 'P.'). Now that P has been removed, mimick it! 
+      keywords = ['fetch', 'fill_textfield', 'submit', 'end', 'click_link']
+      rows.each do |row|       
+        #Do not prepend P. to comments and empty lines
+        next if (row.strip =~ /^#/ || row.strip == '')
+        #Do not prepend P. to any of the reserved keywords 
+        jump_to_next = false
+        keywords.each { |keyword| jump_to_next = true if row.strip =~ /^#{keyword}/ }
+        next if jump_to_next
+        #Prepend P.s - the hairy stuff with eval et al is there to preserve the whitespace
+        row.sub!(/\s+(.*)/) { "#{' ' * eval((row.size - row.lstrip.size ).to_s)} P.#{$1}" } 
+        #Don't forget also the stuff in parentheses!
+        row.gsub!(/\{\s+/) {"{P."}
+      end
+      rows[0] = first_line
+      #@full_definition holds the original definition (at this point, later on it will be
+      #gsub!bed and all)
+      @full_definition = rows.join("\n")
+      #This hash contains all the examples that need to be replaced with their XPath 
+      #counterparts;"P.#{name}"
+      #We are relying on the convention that if an example is definied, it is always
+      #the first parameter and it is always a string 
+      @name_to_xpath_map = {}
+      create_name_to_xpath_map(pattern)
+      #Replace the examples which are quoted with " and '
+      @name_to_xpath_map.each do |name, xpath| 
+        replace_example_with_xpath(name, xpath, %q{"})
+        replace_example_with_xpath(name, xpath, %q{'})
+      end
+      #Finally, add XPaths to pattern which had no example at the beginning (the XPath was
+      #generated from the child patterns
+      @name_to_xpath_map.each do |name, xpath|  
+        comma = @full_definition.scan(Regexp.new("P.#{name}(.+)$"))[0][0].sub('do'){}.strip == '' ? '' : ','
+        if (@full_definition.scan(Regexp.new("P.#{name}(.+)$"))[0][0]).include?('{')
+          @full_definition.sub!("P.#{name}") {"P.#{name}('#{xpath}')"}
+        else
+          @full_definition.sub!("P.#{name}") {"P.#{name} \"#{xpath}\"#{comma}"}
+        end      
+      end
+      @result += @full_definition
+    end    
+    
+    def self.export_footer(output_file, wrapper_name, extractor_result_file_name)
+      if extractor_result_file_name
+        @result += "\n\n#{wrapper_name}.to_xml.write(open('result_of_exported_extractor.xml', 'w'), 1)"
+      else
+        @result += "\n\n#{wrapper_name}.to_xml.write($stdout, 1)"
+      end
+    end
+
+    
+    def self.create_name_to_xpath_map(pattern)
+      @name_to_xpath_map[pattern.name] = pattern.filters[0].xpath if pattern.filters[0].xpath != nil
+      pattern.children.each {|child| create_name_to_xpath_map child}      
+    end
+    
+    def self.replace_example_with_xpath(name, xpath, left_delimiter, right_delimiter=left_delimiter)
+      replacing_xpath = (@full_definition.scan(Regexp.new("P.#{name}(.+)$"))[0][0]).include?('{') ? 
+              "P.#{name}('\"#{xpath}\"')" :
+              "P.#{name} \"#{xpath}\""
+      @full_definition.sub!(/P\.#{name}\s+#{left_delimiter}(.*)#{right_delimiter}/) do
+        @name_to_xpath_map.delete("#{name}")
+        replacing_xpath
+      end
+    end
+    
+  end
+end