ruby-jing 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3d008f4db22a52baedf6f25339cd24ba6e9848ea
+  data.tar.gz: 3ac4428cf7a0d8c372a401e4585f2c13bc1d8ba9
+SHA512:
+  metadata.gz: d4d4a4682496576208a44f81ca98fdd712067f874d35747881f8a966f05061b59c9d62c3b643225bd19b115785b1f9a22279675fe4acad91c73ec6b7a255822b
+  data.tar.gz: bd73c441aa2ac74bca835316823624234fc1af79d2237847f4e4d4740f1393b915a33f23ee3f30c743f91bd60030d9dc37a1a64c0f92cacf2e139dbd2146eaa4

data/README.rdoc

@@ -0,0 +1,135 @@
+= Ruby Jing
+
+{<img src="https://secure.travis-ci.org/sshaw/ruby-jing.png"/>}[http://travis-ci.org/sshaw/ruby-jing]
+{<img src="https://codeclimate.com/github/sshaw/ruby-jing.png" />}[https://codeclimate.com/github/sshaw/ruby-jing]
+
+RELAX NG schema validation using the {Jing CLI}[http://www.thaiopensource.com/relaxng/jing.html]
+
+=== Overview
+
+  require "jing"
+
+  jing = Jing.new("schema.rng")
+  begin
+    errors = jing.validate("doc.xml")
+  rescue Jing::OptionError, Jing::ExecutionError => e
+    abort "what what what #{e}"
+  end
+
+  if errors.none?
+    puts "Valid!"
+  else
+    errors.each do |error|
+      puts "#{error[:message]} @ #{error[:line]}:#{error[:column]}"
+    end
+  end
+
+  # This can also raise errors
+  abort "Invalid!" unless jing.valid?("/path/to/doc.xml")
+
+=== Why use Java to validate instead of Ruby libraries like Nokorigi, REXML, libxml, etc..?
+
+Simple: good error messages. Let's look at the error messages provided by each of these libraries.
+
+ <!-- RNG schema -->
+ <element name="addressBook" xmlns="http://relaxng.org/ns/structure/1.0">
+   <zeroOrMore>
+     <element name="card">
+       <attribute name="version">
+         <choice>
+           <value>v1</value>
+           <value>v2</value>
+         </choice>
+       </attribute>
+       <element name="name">
+         <text/>
+       </element>
+     </element>
+   </zeroOrMore>
+ </element>
+
+ <!-- XML A -->
+ <addressBook>
+   <card></card>
+ </addressBook>
+
+ <!-- XML B -->
+ <addressBook>
+   <card verison="v100">    
+     <name>John Smith</name>
+     <oops>Doh!</oops>
+   </card>
+ </addressBook>
+
+==== Nokorigi/libxml
+
+  schema = Nokogiri::XML::RelaxNG(File.read(rng))
+  doc = Nokogiri::XML(File.read(xml))
+  errors = schema.validate(doc)  
+  errors.each { |e| puts e }
+
+Resulting errors:
+
+  # XML A
+  Element card failed to validate attributes
+  Expecting an element , got nothing
+
+  # XML B
+  Element card failed to validate attributes
+  Did not expect element oops there
+
+==== REXML
+
+  include REXML
+  doc = Document.new(File.read(xml))
+  validator = Validation::RelaxNG.new(File.read(rng))
+  validator.validate(doc)
+
+Fails for XML A and XML B --it treats the XML declaration as a validation error!
+
+  Validation error.  Expected: :start_element( addressBook ) from < S.1 #:start_element( addressBook ), < Z.2 #:start_element( card ), :start_attribute( version ), < C.3 :text( v1 ) or :text( v2 ) >, :end_attribute(  ), :start_element( name ), :text(  ), :end_element(  ), :start_element( email ), :text(  ), :end_element(  ), :end_element(  ) >, :end_element(  ), :end_document(  ) >  but got <?xml ... ?>( 
+   )
+
+==== Jing
+
+  jing = Jing.new(schema)
+  errors = jing.validate(xml)
+  errors.each { |e| puts e[:message] }
+
+Resulting errors:
+
+  # XML A
+  element "card" missing required attribute "version"
+  element "card" incomplete; missing required element "name"
+
+  # XML B
+  value of attribute "version" is invalid; must be equal to "v1" or "v2"
+  element "oops" not allowed anywhere; expected the element end-tag
+
+Better, don't ya think?
+
+=== More Info
+
+* {Docs}[http://rdoc.info/gems/ruby-jing/frames]
+* {Bugs}[http://github.com/sshaw/ruby-jing/issues]
+
+=== Author
+
+Skye Shaw [skye.shaw AT gmail.com]
+
+=== License
+
+Released under the MIT License: www.opensource.org/licenses/MIT
+
+=== Jing Copying Conditions
+
+Copyright (c) 2001-2003 Thai Open Source Software Center Ltd
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Neither the name of the Thai Open Source Software Center Ltd nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/lib/jing.rb

@@ -0,0 +1,139 @@
+require "optout"
+
+class Jing
+  VERSION = "0.0.1"
+  DEFAULT_JAR = File.join(File.dirname(__FILE__), "jing-20091111.jar")
+
+  Error = Class.new(StandardError)
+  ExecutionError = Class.new(Error)
+  OptionError = Class.new(Error)
+
+  @@option_builder = Optout.options do
+    on :java,     :required => true, :default => "java"
+    on :jar,      "-jar", Optout::File.exists, :default => DEFAULT_JAR
+    on :compact,  "-c",   Optout::Boolean
+    on :encoding, "-e",   String
+    on :id_check, "-i",   Optout::Boolean,     :default  => false
+    on :schema,           Optout::File.exists, :required => true
+    on :xmlfile,          Optout::File.exists, :required => true
+  end
+
+  ##
+  # Cretae an instance to validate against the given schema. The schema can be in the XML or compact syntax.
+  #
+  #  jing = Jing.new("schema.rng", options)
+  #
+  # === Arguments
+  #
+  # [schema (String)] Path to the schema
+  # [options (Hash)] Jing options, optional
+  #
+  # === Options
+  #
+  # [:java (String)] Name and/or location of the java executable. Defaults to <code>"java"</code>.
+  # [:jar (String)] Path to the Jing JAR file. Defaults to the bundled JAR.
+  # [:compact (Boolean)] Set to +true+ if the schema uses the RELAX NG compact syntax. Defaults to false, will be set to +true+ is the schema has a +.rnc+ extension.
+  # [:encoding (String)] Encoding of the XML document.
+  # [:id_check (Boolean)] Disable checking of ID/IDREF/IDREFS. Defaults to +false+
+
+  # === Errors
+  #
+  # [ArgumentError] If the options are not +nil+ or a +Hash+.
+
+  def initialize(schema, options = nil)
+    if options
+      raise ArgumentError, "options must be a Hash" unless Hash === options
+      @options = options.dup
+    end
+
+    @options ||= {}
+    @options[:schema] = schema
+    @options[:compact] = true if @options[:compact].nil? and @options[:schema] =~ /\.rnc\Z/i   # Don't override an explicit setting
+    # Optout quirk: true will *include* the switch, which means we *don't* want to check
+    @options[:id_check] = !@options[:id_check] if @options.include?(:id_check)
+  end
+
+  ##
+  # Validate an XML document against the schema.
+  #
+  #  errors = jing.validate("doc.xml")
+  #
+  # === Arguments
+  #
+  # [xml (String)] Path to the XML file
+  #
+  # === Errors
+  #
+  # [Jing::OptionError] A Jing option was invalid. Note that this <b>does not apply to an invalid <code>:java</code> option.</b>
+  # [Jing::ExecutionError] Problems were encountered trying to execute Jing.
+  #
+  # === Returns
+  #
+  # [Array] The errors, each element is a +Hash+. See Error Hash for more info.
+  #
+  # ==== Error Hash
+  #
+  # The error hash contains the following keys/values
+  #
+  # [:source (String)] File containing the error, can be the schema or the instance XML.
+  # [:line (Fixnum)] Line number
+  # [:column (Fixnum)] Column number
+  # [:message (String)] The problem
+
+  def validate(xml)
+    @options[:xmlfile] = xml
+
+    out = execute(@options)
+    return [] if $?.success? and out.empty?
+    errors = parse_output(out)
+    raise ExecutionError, out if errors.none? # There must have been a problem that was not schema related
+    errors
+  end
+
+  # Validate an XML document against the schema. To receive a list of vlidation errors use #validate.
+  #
+  #  puts "yay!" if jing.valid?("doc.xml")
+  #
+  # === Arguments
+  #
+  # [xml (String)] Path to the XML file
+  #
+  # === Errors
+  #
+  # Same as #validate
+  #
+  # === Returns
+  # 
+  # [Boolean] +true+ if valid, +false+ if invalid
+  #
+  
+  def valid?(xml)
+    errors = validate(xml)
+    errors.none?
+  end
+    
+  private
+  def execute(options)
+    cmd = @@option_builder.shell(options)
+    `#{cmd} 2>&1`
+  rescue SystemCallError => e
+    raise ExecutionError, "jing execution failed: #{e}"
+  rescue Optout::OptionError => e
+    raise OptionError, e.message
+  end
+
+  def parse_output(output)
+    errors = []
+    output.split("\n").map do |line|
+      if line =~ /\A(.+):(\d+):(\d+):\s+\w+:\s+(.+)\Z/
+	errors << {
+	  :source  => $1,
+	  :line    => $2.to_i,
+	  :column  => $3.to_i,
+	  :message => $4
+	}
+      end
+    end
+    errors
+  end
+end

data/test/test_jing.rb

@@ -0,0 +1,140 @@
+require "minitest/autorun"
+require "tempfile"
+require "jing"
+
+class TestJing < MiniTest::Unit::TestCase
+  root = File.join(File.expand_path(File.dirname(__FILE__)), "fixtures")
+
+  VALID_XML = File.join(root, "valid.xml")
+  INVALID_XML = File.join(root, "invalid.xml")
+  RNG_SCHEMA = File.join(root, "schema.rng")
+  RNC_SCHEMA = File.join(root, "schema.rnc")
+
+  def test_default_jar_file_used
+    cmd = fakeshell { Jing.new(RNG_SCHEMA).validate(VALID_XML) }
+    assert_match /\A'java'\s+ -jar\s+ '#{Jing::DEFAULT_JAR}' \s+/x, cmd
+  end
+
+  def test_jar_file_must_exist
+    assert_raises Jing::OptionError, /\bjar\b/ do
+      Jing.new(RNG_SCHEMA, :jar => "__oopsy__!").validate(VALID_XML)
+    end
+  end
+
+  def test_jar_option
+    jar = Tempfile.new "jar"
+    cmd = fakeshell { Jing.new(RNG_SCHEMA, :jar => jar.path).validate(VALID_XML) }
+    assert_match /\A'java'\s+ -jar\s+ '#{jar.path}' \s+/x, cmd
+  end
+
+  def test_java_option
+    java = "/usr/alt/java"
+    cmd = fakeshell { Jing.new(RNG_SCHEMA, :java => java).validate(VALID_XML) }
+    assert_match /\A'#{java}'\s+/, cmd
+  end
+
+  def test_java_must_exist
+    # This should be an OptionError!
+    assert_raises Jing::ExecutionError, /\bjava\b/ do
+      Jing.new(RNG_SCHEMA, :java => "__no_no_no__").validate(VALID_XML)
+    end
+  end
+
+  def test_encoding_option
+    enc = "iso-8859-1"
+    cmd = fakeshell { Jing.new(RNG_SCHEMA, :encoding => enc).validate(VALID_XML) }
+    assert_match /\A'java'\s+ -jar\s+ '#{Jing::DEFAULT_JAR}'\s+ -e\s+ '#{enc}'/x, cmd
+  end
+
+  def test_id_check_option
+    cmd = fakeshell { Jing.new(RNG_SCHEMA, :id_check => false).validate(VALID_XML) }
+    assert_match /\A'java'\s -jar\s+ '#{Jing::DEFAULT_JAR}'\s+ -i/x, cmd
+
+    cmd = fakeshell { Jing.new(RNG_SCHEMA, :id_check => true).validate(VALID_XML) }
+    refute_match /\b-i\b/x, cmd
+
+    cmd = fakeshell { Jing.new(RNG_SCHEMA).validate(VALID_XML) }
+    refute_match /\b-i\b/x, cmd
+  end
+
+  def test_compact_option
+    cmd = fakeshell { Jing.new(RNC_SCHEMA, :compact => true).validate(VALID_XML) }
+    assert_match /\A'java'\s -jar\s+ '#{Jing::DEFAULT_JAR}'\s+ -c/x, cmd
+
+    cmd = fakeshell { Jing.new(RNC_SCHEMA, :compact => false).validate(VALID_XML) }
+    refute_match /\b-c\b/, cmd
+  end
+
+  def test_compact_option_when_compact_schema_is_used
+    cmd = fakeshell { Jing.new(RNC_SCHEMA).validate(VALID_XML) }
+    assert_match /\A'java'\s+ -jar\s+ '#{Jing::DEFAULT_JAR}'\s+ -c/x, cmd
+  end
+
+  def test_relaxng_file_must_exist
+    assert_raises Jing::OptionError, /cannot read/ do
+      Jing.new("bad_file_name").validate(VALID_XML)
+    end
+  end
+
+  def test_instance_xml_file_must_exist
+    assert_raises Jing::OptionError, /cannot read/ do
+      Jing.new(VALID_XML).validate("bad_file_name")
+    end
+  end
+
+  def test_valid_instance_xml_returns_true
+    assert Jing.new(RNG_SCHEMA).valid?(VALID_XML)
+  end
+
+  def test_valid_instance_xml_returns_no_errors
+    errors = Jing.new(RNG_SCHEMA).validate(VALID_XML)
+    assert_equal 0, errors.size    
+  end
+
+  def test_invalid_instance_xml_returns_false
+    assert !Jing.new(RNG_SCHEMA).valid?(INVALID_XML)
+  end
+
+  def test_invalid_instance_xml_returns_errors
+    errors = Jing.new(RNG_SCHEMA).validate(INVALID_XML)
+    assert_equal 1, errors.size
+
+    err = errors[0]
+    assert_equal INVALID_XML, err[:source]
+    assert_equal 4, err[:line]
+    assert_match /\A\d\d?\z/, err[:column].to_s
+    assert_match /\bemail\b/, err[:message]
+  end
+
+  def test_successful_exit_status_with_unparsable_output_raises_an_exception
+    output = "something bad happened"
+    assert_raises Jing::ExecutionError, /#{output}/ do
+      fakeshell(:exit => 0, :output => output) { Jing.new(RNG_SCHEMA).validate(VALID_XML) }
+    end
+  end
+
+  private
+  def fakeshell(options = {})
+    output = options.delete(:output) || ""
+    exit_code = options.delete(:exit) || 0
+
+    cmd = nil
+    Object.class_eval do
+      alias_method "real_tick", "`"
+      define_method("`") do |arg|
+        cmd = arg
+        real_tick %{ruby -e"exit #{exit_code}"} # Just to set $?
+        output
+      end
+    end
+
+    yield
+    cmd.tr %{"}, %{'}  # replace Win quotes with *nix
+  ensure
+    Object.class_eval do
+      undef_method "`" #`
+      alias_method "`", "real_tick"
+      undef_method "real_tick"
+    end
+  end
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: ruby-jing
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Skye Shaw
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: optout
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: |2
+      RELAX NG schema validation using Jing, a Java based RELAX NG validator that emits clear,
+      detailed validation errors. ruby-jing validates XML documents by wrapping Jing's java
+      command-line user interface.
+email: skye.shaw@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+files:
+- lib/jing-20091111.jar
+- lib/jing.rb
+- test/test_jing.rb
+- README.rdoc
+homepage: http://github.com/sshaw/ruby-jing
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.6
+signing_key: 
+specification_version: 4
+summary: RELAX NG schema validation using the Jing CLI
+test_files:
+- test/test_jing.rb