mixml 0.0.3 → 0.9

data/README.md

@@ -0,0 +1,169 @@
+# mixml
+
+[![Gem Version](https://badge.fury.io/rb/mixml.png)](http://badge.fury.io/rb/mixml)
+[![Build Status](https://travis-ci.org/jochenseeber/mixml.png?branch=master)](https://travis-ci.org/jochenseeber/mixml)
+[![Coverage Status](https://coveralls.io/repos/jochenseeber/mixml/badge.png?branch=master)](https://coveralls.io/r/jochenseeber/mixml?branch=master)
+
+Mixml is a small tool to greatly simplify the tedious task of changing multiple multiple XML files at once. Its main
+purpose is to spare me from having to use XSLT ever again. You can use mixml to change XML files in the following ways:
+
+  * Pretty print
+  * Remove nodes
+  * Add nodes
+  * Replace nodes
+  * Rename nodes
+  * Change node values
+
+For example, the following command will remove all attributes named `id` from the supplied XML files:
+
+    mixml remove --inplace --xpath '//@id' *.xml
+
+Mixml also supports a simple DSL to perform scripted changes. To perform the same as above using a script, save the
+following in `test.mixml`:
+
+    xpath '//@id' do
+        remove
+    end
+
+and then call:
+
+    mixml execute --script test.mixml *.xml
+
+You can also use mixml directly in your Ruby code:
+
+    require 'mixml'
+
+    tool = Mixml::Tool.new do |t|
+        t.save = true
+    end
+
+    tool.work('one.xml', 'two.xml') do
+        xpath '//@id' do
+            remove
+        end
+    end
+
+Mixml supports building replacement values using
+
+  * [Ruby string interpolation](http://en.wikibooks.org/wiki/Ruby_Programming/Syntax/Literals#Interpolation)
+  * [Erubis templates](http://www.kuwata-lab.com/erubis/)
+  * [Nokogiri's XML DSL](http://nokogiri.org/Nokogiri/XML/Builder.html)
+  * Plain Ruby
+
+You can find more usage examples [here](demo/tool.md).
+
+## Installation
+
+Install mixml:
+
+    $ gem install mixml
+
+## Usage
+
+Use the following command to get help:
+
+    mixml --help
+
+### Pretty print XML
+
+    mixml pretty *.xml
+
+### Remove nodes
+
+    mixml remove --xpath '//addresses' *.xml
+
+### Rename nodes
+
+    mixml rename --xpath '//addresses' --template 'addressbook' *.xml
+
+### Replace nodes
+
+    mixml replace --xpath '//addresses' --template '<addressbook/>' *.xml
+
+### Append nodes
+
+    mixml append --xpath '/list' --template '<addressbook/>' *.xml
+
+### Set node value
+
+    mixml value --xpath '//addresses/@name' --template 'default' *.xml
+
+### Execute a script
+
+Example script in `test.mixml`
+
+    xpath '//addresses[name="default"]' do
+        remove
+    end
+    xpath '//addresses' do
+        replace template '<addressbook/>'
+    end
+
+Use the following command to run the script
+
+    mixml execute --script test.mixml *.xml
+
+Script commands:
+
+    xpath 'xpath-expression' do
+        remove # Remove node
+        replace 'xml' # Replace node
+        append 'xml'
+        value 'text' # Set node value
+        rename 'text' # Rename node
+    end
+
+Instead of using strings for parameters, you can also use a template expression:
+
+    xpath 'xpath-expression' do
+        replace template 'special-{=node.name}' # Prefix nodes with 'special-''
+    end
+
+This works for all commands that take a string parameter. We use [Erubis](http://www.kuwata-lab.com/erubis) as
+templating engine, and `{` and `}` as delimiters.
+
+In addition, you can also use [Nokogiri](http://http://nokogiri.org/)'s
+[builder component](http://nokogiri.org/Nokogiri/XML/Builder.html) to create the XML that replaces an element:
+
+    xpath '//addresses' do
+        replace xml ->(node, xml) {
+            xml.addressbook(:name => node['name'])
+        }
+    end
+
+### Use CSS rules to select nodes
+
+You can also use CSS rules instead of XPath expressions to select the nodes to process:
+
+    css 'addresses:first-child', 'addresses:last-child' do
+        remove
+    end
+
+### Evaluate an expression
+
+You can also pass the script to execute directly to mixml:
+
+    mixml execute --expression 'xpath("//addresses") { remove }' *.xml
+
+### Write results
+
+The standard setting is to leave the input files unchanged and print the resulting files. You can replace the input
+files with the changed XML by using the `inplace` option:
+
+    mixml remove --inplace --xpath '//addresses' test.xml
+
+This will remove all elements named `group` from `test.xml`.
+
+### Pretty print results
+
+To pretty print the output, use the `pretty` option:
+
+    mixml remove --inplace --xpath '//addresses' --pretty test.xml
+
+## Contributing
+
+1. Fork the GitHub repository: [https://github.com/jochenseeber/mixml/fork](https://github.com/jochenseeber/mixml/fork)
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Commit your changes: `git commit -am 'Add some feature'`
+4. Push to the branch: `git push origin my-new-feature`
+5. Create a new Pull Request

data/demo/applique/test.rb

@@ -0,0 +1,84 @@
+require 'fileutils'
+require 'rspec/expectations'
+require 'rspec/collection_matchers'
+require 'equivalent-xml'
+require 'nokogiri'
+
+include RSpec::Matchers
+
+# File with test content
+class TestFile
+    include RSpec::Matchers
+
+    # @return [String] File name
+    attr_reader :file_name
+
+    # @param file_name [String] File name
+    def initialize(file_name)
+        @file_name = file_name
+    end
+
+    # Write text into file
+    #
+    # @param text [String] Text to write
+    # @return [void]
+    def <<(text)
+        File.open(@file_name, 'w') do |f|
+            f.write text
+        end
+    end
+
+    # Expect file to match content
+    #
+    # @param object [String, Nokogiri::XML::Document] Text or XML to match
+    # @return [void]
+    def matches(object)
+        content = File.read(@file_name)
+        if object.is_a?(Nokogiri::XML::Document) then
+            expect(content).to be_equivalent_to(object).respecting_element_order
+        else
+            expect(content).to be(object)
+        end
+    end
+end
+
+# Create a new test file
+def file(name)
+    FileUtils.mkpath(File.dirname(name))
+    TestFile.new(name)
+end
+
+# Create a new XML document
+def xml(text)
+    Nokogiri::XML(text)
+end
+
+# Redirect stdout and return output
+#
+# @yield Execute block with redirected stdout
+# @return [String] Output
+def redirect
+    begin
+        old_stdout = $stdout
+        $stdout = StringIO.new('', 'w')
+        yield
+        $stdout.string
+    ensure
+        $stdout = old_stdout
+    end
+end
+
+# Define a new matcher to compare text files ignoring empty lines as well as leading and trailing spaces.
+RSpec::Matchers.define :match_text do |expected|
+    # Remove empty lines and leading and trailing spaces from text
+    #
+    # @param text [String] Text to clean
+    # @return [String] cleaned text
+    def clean(text)
+        text.gsub(/\n+/, "\n").gsub(/^\s+|\s+$/, '')
+    end
+
+    match do |actual|
+        clean(actual) == clean(expected)
+    end
+end

data/demo/tool.md

@@ -0,0 +1,334 @@
+# Usage examples
+
+## Setup
+
+First we need to create a new Tool object and load an XML file. We create a Mixml tool object and use a
+[helper](applique/test.rb) to load the following XML for each example.
+
+    require 'mixml'
+
+    Before do
+        @tool = Mixml::Tool.new do |t|
+            # Pretty print output
+            t.pretty = true
+
+            # Save output after processing
+            t.save = true
+
+            # Don't print documents after processing
+            t.print = false
+        end
+
+        # Save test.xml
+        file('test.xml') << %{
+            <list>
+                <philosopher name="Hobbes"/>
+                <philosopher name="Rawls"/>
+            </list>
+        }
+
+        @tool.load('test.xml')
+    end
+
+## Remove nodes
+
+Select some nodes with an XPath expression and then remove them
+
+    @tool.execute do
+        xpath '//philosopher' do
+            remove
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list/>
+    }
+
+## Replace nodes
+
+Select some elements with an XPath expression and then change the element name.
+
+    @tool.execute do
+        xpath '//*[@name = "Hobbes"]' do
+            replace '<tiger name="Hobbes"/>'
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <tiger name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+## Replace nodes with string interpolation
+
+Ruby [string interpolation](http://en.wikibooks.org/wiki/Ruby_Programming/Syntax/Literals#Interpolation) is performed on
+string parameters, so you can also select some elements with an XPath expression and then change each element using a
+Ruby expression.
+
+    @tool.execute do
+        xpath '//*[@name = "Hobbes"]' do
+            replace '<tiger-and-#{node.name} name="Hobbes"/>'
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <tiger-and-philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+This works for all commands that take a string parameter.
+
+## Replace nodes with a template
+
+If you prefer, you can also use template expressions instead of string parameters. Mixml uses
+[Erubis](http://www.kuwata-lab.com/erubis) as templating engine, and `{` and `}` as delimiters. With this, you can
+select some elements with an XPath expression and then replace each element.
+
+    @tool.execute do
+        xpath '//*[@name = "Hobbes"]' do
+            replace template '<tiger-and-{=node.name} name="{=node["name"]}"/>'
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <tiger-and-philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+This works for all commands that take a string parameter.
+
+## Replace nodes with XML
+
+If you prefer, you can also use an XML builder to create values using the simple DSL provided by
+[Nokogiri](http://nokogiri.org/Nokogiri/XML/Builder.html). Using this, you can select some elements with an XPath
+expression and then replace each element.
+
+    @tool.execute do
+        xpath '//*[@name = "Hobbes"]' do
+            replace xml ->(node, xml) {
+                xml.send(:"tiger-and-philosopher", :name => node['name'])
+            }
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <tiger-and-philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+This works for all commands that take XML text as parameter (e.g. replace and append).
+
+## Replace nodes with Ruby
+
+If you prefer, you can also use plain Ruby code to create values. with this, you can select some elements with an XPath
+expression and then replace each element.
+
+    @tool.execute do
+        node xpath '//*[@name = "Hobbes"]' do |node|
+            node.name = "tiger-and-#{node.name}"
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <tiger-and-philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+Instead of processing each node individually, you can also process the selected node sets.
+
+    @tool.execute do
+        nodes xpath('//*[@name = "Hobbes"]') do |nodeset|
+            nodeset.each do |node|
+                node.name = "tiger-and-#{node.name}"
+            end
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <tiger-and-philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+This works for all commands that take XML text as parameter (e.g. replace and append).
+
+## Append nodes
+
+Select some elements with an XPath expression and then append children to them.
+
+    @tool.execute do
+        xpath '/list' do
+            append '<tiger name="Hobbes"/>'
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+            <tiger name="Hobbes"/>
+        </list>
+    }
+
+## Replace attribute values
+
+Select some attributes with an XPath expression and change their value.
+
+    @tool.execute do
+        xpath '//philosopher[1]/@name' do
+            value 'Thomas Hobbes'
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <philosopher name="Thomas Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+## Rename nodes
+
+Select some nodes with an XPath expression and change their name.
+
+    @tool.execute do
+        xpath '//philosopher[@name = "Hobbes"]' do
+            rename 'tiger-and-#{node.name}'
+        end
+    end
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <tiger-and-philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+## Evaluate a command string
+
+Evaluate a command string with mixml commands
+
+    @tool.execute("xpath('//philosopher') { remove }")
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list/>
+    }
+
+## Select nodes using CSS rules
+
+You can also use CSS rules to select the nodes to process
+
+    @tool.execute("css('philosopher:first-child') { remove }")
+    @tool.flush
+
+    file('test.xml').matches xml %{
+        <list>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+## Do everything in one step
+
+Load files, modify them and optionally save them again in one step using the `work` method.
+
+    tool = Mixml::Tool.new do |t|
+        t.pretty = true
+    end
+
+    @tool.work('test.xml') do
+        xpath '//philosopher' do
+            remove
+        end
+    end
+
+    expect(@tool.documents).to have(0).items
+
+    file('test.xml').matches xml %{
+        <list/>
+    }
+
+## Print modified documents without saving
+
+Print files whithout saving them.
+
+    @tool.save = false
+    @tool.print = true
+
+    text = redirect do
+        @tool.execute do
+            xpath '//philosopher' do
+                remove
+            end
+        end
+
+        @tool.flush
+    end
+
+    # Check output
+    expect(text).to match_text(%{
+        <?xml version="1.0"?>
+        <list/>
+    })
+
+    # Check if file still is unmodified
+    file('test.xml').matches xml %{
+        <list>
+            <philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+    }
+
+## Print headers when processing multiple documents
+
+    text = redirect do
+        file('more.xml') << %{
+            <list>
+                <philosopher name="Kant"/>
+                <philosopher name="Platon"/>
+            </list>
+        }
+
+        @tool.load('more.xml')
+        @tool.print_all
+    end
+
+    expect(text).to match_text(%{
+        --------
+        test.xml
+        --------
+        <?xml version="1.0"?>
+        <list>
+            <philosopher name="Hobbes"/>
+            <philosopher name="Rawls"/>
+        </list>
+        --------
+        more.xml
+        --------
+        <?xml version="1.0"?>
+        <list>
+            <philosopher name="Kant"/>
+            <philosopher name="Platon"/>
+        </list>
+    })