yowl 0.4.pre

data/CHANGES

@@ -0,0 +1,15 @@
+
+0.4
+
+- Rename to YOWL
+
+0.3
+
+- Now also finds dowl/introduction.html
+- When rdfs:label is missing the short name is used
+- Generates SVG graphics: 
+  - a Class Diagram with all Classes found in a schema
+  - A Diagram per Class with its direct associations
+  - A Diagram per Individual with its direct associations
+  - At the index page: a Diagram with all Ontologies and their import relationships
+ 

data/INSTALL-MACOSX.md

@@ -0,0 +1,107 @@
+# Installation on Mac OS X
+
+Unfortunately, its not trivial to get YOWL to run on Mac OS X.
+
+You can either use MacPorts or Brew to install some of the components that YOWL needs.
+
+## MacPorts
+
+You first have to download and install MacPorts: http://www.macports.org/install.php
+
+Then use MacPorts to install GraphViz (which is used to generate the graphics) and wget:
+
+```
+sudo port install graphviz wget
+```
+
+## HomeBrew
+
+As an alternative to MacPorts, you can install Brew and use that to install Graphviz,
+for installation instructions of Brew look here: https://github.com/mxcl/homebrew/wiki/Installation
+
+Once Brew is installed, install Graphviz and wget:
+
+```
+sudo brew install graphviz wget
+```
+
+## Raptor 1
+
+YOWL depends on the Ruby package "ruby-rdf" which in turn depends on a C library called "raptor".
+Unfortunately, MacPorts recently dropped support for the older version of Raptor (version 1) that
+is used by ruby-rdf, so MacPorts can only install version 2, which is not compatible with ruby-rdf,
+so don't bother to install it.
+Another well known package manager for Mac OS X, HomeBrew, also can only install version 2
+of libraptor.
+
+There are two solutions available at this point (unless you have a better idea):
+
+### Building libraptor version 1 from source
+
+```
+mkdir -p ~/Work/build
+cd ~/Work/build
+wget http://download.librdf.org/source/raptor-1.4.21.tar.gz
+tar xvf raptor-1.4.21.tar.gz 
+cd raptor-1.4.21
+./configure "CPPFLAGS=-I/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.7.sdk/usr/include"
+make
+sudo make install
+```
+
+As you can see in the configure line above, the build procedure assumes that you have Xcode installed, where it tries to find "curl/types.h".
+If you have this file installed elsewhere then change that location on the configure line. 
+One way to find "curl/types.h" is:
+
+```
+sudo locate types.h | grep curl
+```
+
+Or
+
+```
+sudo find /usr /opt /sw /Applications -name 'types.h' | grep curl
+```
+
+### Installing libraptor version 1 with Fink
+
+Besides MacPorts and HomeBrew, there's also Fink. Go to the Fink website, download
+and install Fink and then type:
+
+```
+sudo fink selfupdate
+sudo fink install raptor-bin
+```
+
+This will fail on Mac OS X Mountain Lion (10.8.x or later) because the raptor package
+as defined by Fink is dependent on an older version of curl, which does no longer have
+the "curl/types.h" file, which is needed by raptor, unless you configure it a bit
+differently:
+
+Open the Fink package file for raptor:
+
+```
+sudo vi /sw/fink/10.7/stable/main/finkinfo/libs/libraptor1-shlibs.info
+```
+
+Find the line that starts with "ConfigureParams:" and add the option --with-www=xml so
+that it looks as follows:
+```
+ConfigureParams: --enable-dependency-tracking --disable-static --enable-gtk-doc --with-www=xml
+```
+
+Then save the file and execute the following:
+
+```
+sudo fink rebuildpackage raptor-bin
+sudo fink install raptor-bin
+sudo ln -s /sw/lib/libraptor.1.dylib /usr/lib/libraptor.dylib
+```
+
+## Gems
+
+YOWL depends on various "ruby gems" that can be installed as follows:
+
+```
+sudo gem install ffi rdf rdf-raptor rdf-json rdf-trix sxp sparql ruby-graphviz
+```

data/README.md

@@ -0,0 +1,92 @@
+# YOWL
+
+Yet another OWL documentor. YOWL is a command line utility that can read a number of
+RDFS/OWL files, called the repository, and generate a documentation website from it,
+with visualisations like Class Diagrams (as SVG), Individuals Diagrams and Import Diagrams.
+
+It also detects annotations from the following public ontologies:
+
+  - Dublin Core
+  - [Term-centric Semantic Web Vocabulary Annotations](http://www.w3.org/2003/06/sw-vocab-status/note)
+  - [VANN](http://vocab.org/vann/.html)
+  - SKOS
+  - FOAF
+  
+This is a fork of the original DOWL project at https://github.com/ldodds/dowl.
+
+# INSTALLATION
+
+## Installation on Mac OS X:
+
+[Installation on Mac OS X](/jgeluk/yowl/blob/master/INSTALL-MACOSX.md)
+
+## Installation on Ubuntu
+
+```bash
+apt-get install ruby rake gem
+```
+
+## General
+
+Install all libraries used by YOWL:
+
+```bash
+[sudo] gem install ffi rdf rdf-raptor rdf-json rdf-trix sxp sparql ruby-graphviz
+```
+
+This version of YOWL is not yet available as a "gem" itself so it needs to be downloaded from Github:
+
+```bash
+mkdir ~/downloads
+cd ~/downloads
+wget http://github.com/jgeluk/yowl/tarball/master -O yowl.tar.gz
+tar xvf yowl.tar.gz
+#
+# Remember the name of the root directory of the unpacked tarball
+# which looks like jgeluk-yowl-5ba77f5
+#
+sudo rm -rf /opt/yowl
+sudo mv ~/downloads/jgeluk-yowl-5ba77f5 /opt/yowl
+cd /opt/yowl
+sudo rake install
+```
+
+Or get it with git:
+
+```bash
+rm -rf /opt/yowl
+cd /opt
+git clone git@github.com:jgeluk/yowl.git
+cd /opt/yowl
+sudo rake install
+```
+
+# Usage
+
+Execute bin/yowl to see usage options:
+
+```bash
+user@host:/opt/yowl# /opt/yowl/bin/yowl 
+Output will be generated in this directory: /opt/yowl
+Usage: YOWL [<options>]
+
+Specific options:
+    -i, --ontology FILES             Read input FILES
+    -o, --output DIR                 Write HTML output to DIR
+    -t, --template DIR               Use ERB templates in DIR
+        --no-vann                    Skip looking for vann:preferedNamespacePrefix
+
+Common options:
+    -?, -h, --help                   Show this message
+    -V, --version                    Show version
+    -v, --verbose                    Show verbose logging
+```
+
+For example, to generate a site for the PROV ontology,
+download the prov owl file and run YOWL as follows:
+
+```bash
+/opt/yowl/bin/yowl -i /root/downloads/prov/*.owl -o /var/www/prov
+```
+
+

data/Rakefile

@@ -0,0 +1,76 @@
+require 'rake'
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rdoc/task'
+require 'rake/testtask'
+require 'rake/clean'
+
+NAME = "yowl"
+VER = "0.4.pre"
+
+RDOC_OPTS = ['--quiet', '--title', 'yowl reference', '--main', 'README.md']
+
+PKG_FILES = %w(README.md INSTALL-MACOSX.md Rakefile CHANGES) + 
+  Dir.glob("{bin,test,examples,lib}/**/*")
+
+CLEAN.include ['*.gem', 'pkg']
+
+SPEC = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.summary = 'OWL visualization and documentation generator'
+  s.description = <<-EOF
+    Yet another OWL documentor. YOWL is a command line utility that can read a number of RDFS/OWL files, 
+    called the repository, and generate a documentation website from it, with visualisations like
+    Class Diagrams (as SVG), Individuals Diagrams and Import Diagrams.
+  EOF
+  s.name = NAME
+  s.version = VER
+  s.required_ruby_version = ">= 1.8.7"    
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README.md", "INSTALL-MACOSX.md", "CHANGES"]
+  s.rdoc_options = RDOC_OPTS
+  s.authors = ['Leigh Dodds', 'Jacobus Geluk']
+  s.email = ['leigh.dodds@talis.com', 'jacobus.geluk@gmail.com']
+  s.homepage = 'http://github.com/jgeluk/yowl'
+  s.files = PKG_FILES
+  s.require_path = "lib" 
+  s.bindir = "bin"
+  s.executables = ["yowl"]
+  s.test_file = "test/test_yowl.rb"
+  s.add_dependency("rdf-raptor", ">= 0.4.0")
+  s.add_dependency("ffi", ">= 1.1.5")
+  s.add_dependency("rdf", ">= 0.3.8")
+  s.add_dependency("rdf-raptor", ">= 0.4.2")
+  s.add_dependency("rdf-json", ">= 0.3.0")
+  s.add_dependency("rdf-trix", ">= 0.3.0")
+  s.add_dependency("sxp", ">= 0.0.14")
+  s.add_dependency("sparql", ">= 0.3.1")
+  s.add_dependency("ruby-graphviz", ">= 1.0.8")
+  s.rubyforge_project = 'nowarning'
+end
+      
+Gem::PackageTask.new(SPEC) do |pkg|
+    pkg.need_tar = true
+end
+
+RDoc::Task.new do |rdoc|
+    rdoc.rdoc_dir = 'doc/rdoc'
+    rdoc.options += RDOC_OPTS
+    rdoc.rdoc_files.include("README.md", "INSTALL-MACOSX.md", "CHANGES", "lib/**/*.rb")
+    rdoc.main = "README.md"
+end
+
+Rake::TestTask.new do |test|
+  test.verbose = true
+end
+
+desc "Install from a locally built copy of the gem"
+task :install do
+  sh %{rake package}
+  sh %{sudo gem install pkg/#{NAME}-#{VER}}
+end
+
+desc "Uninstall the gem"
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{NAME}}
+end

data/bin/yowl

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+$:.unshift File.join(File.dirname(__FILE__), "..", "lib")
+require 'rubygems'
+require 'getoptlong'
+require 'yowl'
+require 'erb'
+
+PROGRAM = File::basename $0
+
+options = YOWL::OptionsParser.parse(ARGV)
+if options
+  repository = YOWL::Repository.new(options)
+  YOWL::Generator.new(repository, options).run()
+end

data/examples/introduction.html

@@ -0,0 +1,5 @@
+<h2>Introduction</h2>
+
+<p>
+Contents of introduction.html in the same directory is automatically included.
+</p>

data/lib/yowl/association.rb

@@ -0,0 +1,66 @@
+module YOWL
+  class Association < YOWL::LabelledDocObject
+
+    attr_reader :domainClass
+    attr_reader :rangeClass
+    attr_reader :property
+    attr_reader :key
+    def initialize(resource, schema, domainClass, rangeClass)
+      super(resource, schema)
+      @domainClass = domainClass
+      @rangeClass = rangeClass
+
+      @key = "#{@domainClass.uri},#{@rangeClass.uri},#{label}".hash
+    end
+
+    def label
+      return short_name
+    end
+
+    def hash
+      return key
+    end
+
+    def eql?(other)
+      @key.eql? other.key
+    end
+
+    #
+    # Add the current Association as an edge to the given GraphViz graph,
+    # but check whether the Association refers to a Domain and Range class in
+    # the current schema and whether the Association has already been added
+    # to the graph (by checking the given edges collection).
+    #
+    def addAsGraphVizEdge(graph_, nodes_, edges_)
+
+      if not nodes_.has_key?(@domainClass.uri)
+        return nodes_, edges_
+      end
+      if not nodes_.has_key?(@rangeClass.uri)
+        return nodes_, edges_
+      end
+      if edges_.has_key?(@key)
+        return nodes_, edges_
+      end
+
+      domainClassNode = nodes_[@domainClass.uri]
+      rangeClassNode = nodes_[@rangeClass.uri]
+
+      edges_[@key] = Association.newGraphVizEdge(graph_, domainClassNode, rangeClassNode, label)
+
+      return nodes_, edges_
+    end
+
+    def Association.newGraphVizEdge(graph_, domainNode_, rangeNode_, label_, constraint_ = true)
+      return graph_.add_edges(
+        domainNode_,
+        rangeNode_,
+        :label => label_, 
+        :arrowhead => :open, 
+        :arrowsize => 0.5,
+        :penwidth => 0.5,
+        :constraint => constraint_
+      )
+    end
+  end
+end

data/lib/yowl/class.rb

@@ -0,0 +1,296 @@
+module YOWL
+
+  class Class < YOWL::LabelledDocObject
+    
+    include Comparable
+
+    attr_reader :resource
+    attr_reader :subClasses
+    attr_reader :associations
+
+    private
+    def initialize(resource, schema)
+      super(resource, schema)
+      @super_classes = nil
+      @subClasses = nil
+      @associations = nil
+    end
+
+    public
+    def Class.withUri(resource, schema)
+      if resource.anonymous?
+        warn "WARNING: Ignoring class with uri #{resource.to_s}"
+        return
+      end
+      klass = schema.classes[resource.to_s]
+      if klass
+        return klass
+      end
+      klass = Class.new(resource, schema)
+      schema.classes[resource.to_s] = klass
+      if schema.options.verbose
+        puts "Created class #{klass.short_name}"
+      end
+      return klass
+    end
+
+    public
+    def short_name()
+      sn = super()
+      if sn[0,7] == "http://" or sn[0,8] == "https://"
+        if sn.include?('#')
+          ns = sn.slice(/.*#/)
+        else
+          ns = sn.slice(/.*\//)
+        end
+        return sn[ns.length..-1]
+      end
+      return sn
+    end
+
+    public
+    def super_classes()
+      if not @super_classes.nil?
+        return @super_classes
+      end
+
+      @super_classes = []
+
+      @schema.model.query(
+        RDF::Query::Pattern.new(@resource, YOWL::Namespaces::RDFS.subClassOf)
+      ) do |statement|
+        #
+        # Only look at statements like these:
+        #
+        # <rdfs:subClassOf rdf:resource="<uri>"/>
+        #
+        # And ignore statements like these:
+        #
+        # <rdfs:subClassOf>
+        #   <owl:Restriction>
+        #     <owl:onProperty rdf:resource="<uri>"/>
+        #     <owl:allValuesFrom rdf:resource="<uri>"/>
+        #   </owl:Restriction>
+        # </rdfs:subClassOf>
+        #
+        if statement.object.uri?
+          superClass = Class.withUri(statement.object, @schema)
+          if superClass
+            if superClass != self
+              @super_classes << superClass
+            end
+          else
+            warn "WARNING: Could not find super class #{statement.object.to_s}"
+          end
+        end
+      end
+      return @super_classes
+    end
+
+    public
+    def hasSuperClasses?
+      return ! super_classes.empty?()
+    end
+
+    public
+    def hasSuperClassesInSchema?
+      super_classes.each() do |klass|
+        if @schema.classes.include?(klass.uri)
+          return true
+        end
+      end
+      return false
+    end
+
+    public
+    def subClasses()
+      if @subClasses
+        return @subClasses
+      end
+      @subClasses = Set.new
+
+      @schema.model.query(
+        RDF::Query::Pattern.new(nil, YOWL::Namespaces::RDFS.subClassOf, @resource)
+      ) do |statement|
+        subClass = Class.withUri(statement.subject, @schema)
+        if subClass
+          if subClass != self
+            @subClasses << subClass
+          end
+        else
+          warn "WARNING: Could not find sub class of #{short_name} with uri #{statement.subject.to_s}"
+        end
+      end
+      #@subClasses.sort! { |x,y| x <=> y }
+      return @subClasses
+    end
+
+    public
+    def hasSubClasses?
+      return ! subClasses.empty?()
+    end
+
+    public
+    #
+    # Return a collection of Associations representing ObjectProperties
+    # where the current class is one of the Domain classes.
+    #
+    def associations()
+      if not @associations.nil?
+        return @associations
+      end
+      @associations = Set.new
+
+      if @schema.options.verbose
+        puts "Searching for associations of class #{short_name}"
+      end
+
+      query = RDF::Query.new({
+        :property => {
+          YOWL::Namespaces::RDFS.domain => @resource,
+          RDF.type => YOWL::Namespaces::OWL.ObjectProperty,
+          YOWL::Namespaces::RDFS.range => :range
+        }
+      })
+        
+      solutions = query.execute(@schema.model)
+      if @schema.options.verbose
+        puts " - Found #{solutions.count} solutions"
+      end
+      solutions.distinct!
+      if @schema.options.verbose
+        puts " - Found #{solutions.count} distinct solutions"
+      end
+
+      solutions.each do |solution|
+        property = solution[:property]
+        range = solution[:range]
+        if @schema.options.verbose
+          puts " - Found Association from #{short_name} to #{@schema.prefixedUri(range)}: #{@schema.prefixedUri(property.to_s)}"
+        end
+        rangeClass = Class.withUri(range, @schema)
+        if @schema.options.verbose
+          puts "   - Found this class for it: #{rangeClass}"
+        end
+        if rangeClass
+          @associations << Association.new(property, @schema, self, rangeClass)
+        end
+      end
+      if @schema.options.verbose
+        puts " - Returning #{@associations.size} associations for class #{short_name}"
+      end
+      return @associations
+    end
+    
+    public
+    #
+    # Add the current class as a GraphViz node to the given collection of nodes
+    # and to the given graph. Return the collection of nodes.
+    #    
+    def addAsGraphvizNode (graph_, nodes_, edges_)
+      name = short_name
+      if @schema.options.verbose
+        puts "- Processing class #{name}"
+      end
+      #
+      # No need to add a node twice
+      #
+      if nodes_.has_key? uri
+        return nodes_, edges_
+      end
+      node = graph_.add_nodes(escaped_uri)
+      node.URL = "#class_#{short_name}"
+      
+      prefix = nil
+      if name.include?(':')
+        prefix = name.sub(/:\s*(.*)/, "")
+        name = name.sub(/(.*)\s*:/, "")
+      end
+      name = name.split(/(?=[A-Z])/).join(' ')
+      if prefix
+        #
+        # Can't get HTML labels to work
+        #
+        #name = "<TABLE BORDER=\"0\" CELLBORDER=\"1\" CELLSPACING=\"0\"><TR><TD>#{name}</TD></TR><TR><TD><I>(#{prefix})</I></TD></TR></TABLE>"
+        name = "#{name}\n(#{prefix})"
+      end
+      node.label = name
+      
+      if hasComment?
+        node.tooltip = comment
+      else 
+        if hasDefinition?
+          node.tooltip = definition
+        end
+      end
+      nodes_[uri] = node
+      return nodes_, edges_
+    end
+    
+    public
+    #
+    # Generate a diagram for each class, the "per class diagram"
+    #
+    def perClassDiagramAsSvg
+      #if @schema.options.verbose
+      #  puts "Generating SVG Per Class Diagram for #{short_name}"
+      #end
+    
+      g = GraphvizUtility.setDefaults(GraphViz.new(:G, :type => :digraph))
+      g[:rankdir] = "LR"
+      g.node[:fixedsize] = false
+      
+      nodes = Hash.new
+      edges = Hash.new
+      nodes, edges = addAsGraphvizNode(g, nodes, edges)
+      
+      #
+      # Do the "outbound" associations first
+      #
+      associations.each do |association|
+        nodes, edges = association.rangeClass.addAsGraphvizNode(g, nodes, edges)
+        nodes, edges = association.addAsGraphVizEdge(g, nodes, edges)
+      end
+      
+      #
+      # Then do the "inbound" associations
+      #
+      @schema.classes.values.to_set.each do |klass|
+        klass.associations.each do |association|
+          if self == association.rangeClass
+            nodes, edges = association.rangeClass.addAsGraphvizNode(g, nodes, edges)
+            nodes, edges = association.addAsGraphVizEdge(g, nodes, edges)
+          end
+        end
+      end
+      
+      return GraphvizUtility.embeddableSvg(g)
+    end
+    
+    #
+    # Create the GraphVis Edge for all "is a" (rdf:type) associations from a node
+    # (representing a Class or Individual) to another node (always representing a Class)
+    #
+    def Class.newGraphVizEdge(graph_, domainNode_, rangeNode_, constraint_ = true)
+      options = {
+        :arrowhead => :empty,
+        :arrowsize => 0.5,  
+        :dir => :back,
+        :label => "is a", 
+        :labeldistance => 2,
+        :penwidth => 0.5,
+        :constraint => constraint_
+      }
+      if not constraint_
+        options[:style] = :dashed
+      end
+      return graph_.add_edges(
+        rangeNode_,
+        domainNode_,
+        options
+      )
+    end
+
+  end
+
+end