ontology-united 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ef0bf5863b23a554f1dc5a86bd0be1d4307a1de3
-  data.tar.gz: 5220f4ed1b6c8515344fe4484eba00cdd525891b
+  metadata.gz: ab561ca8455f27d70cbdd4cb9c20351da04f6a4e
+  data.tar.gz: ff6f3bb6c32f3cb2b9fd3862e10cc2b140ab9269
 SHA512:
-  metadata.gz: b6a60f8c8ed792e131f0197af0220292a136db44e5d148e36f6caeb4445052f36f94d3f77b5bfd90c666cb545e909038fd1b45912e30775e6410a4448ce23866
-  data.tar.gz: ba969589d3eda647f2ecc4b48a2030072082183d75435203c8ee94d6c9f66c4f40c57ecdded28fd8cfd07f1dd5e8799f3088519b67c31f673a1de8e81f8a9d83
+  metadata.gz: 758a5eac126d84d58d6a46901b43299ec9040e7b4f4f1166c3c2e8e6333cbb389caef40a7ce4e017c065ba71eef119a8dc62877c967e49c441901844f9d03aec
+  data.tar.gz: 6890fcda4eccbfc2b0d89aac0b8448e94bcd040d3fbdf0faa70c5fccb462b739e4749395a0a36d10c8975088c403f87a588f4368e515ef473d09c0a20ff32090

data/README.md

@@ -31,3 +31,157 @@ Or install it yourself as:
 
     $ gem install ontology-united
 
+## Usage
+
+First you'll need to require the gem (unless you are using bundler):
+```ruby
+require 'ontology-united'
+```
+
+After doing this you'll be able to create an ontology in two different ways.
+Either by explicitly using the defined method:
+```ruby
+OntologyUnited::DSL::OntologyDSL.define('MyOntologyName') do
+end
+```
+
+or by including the convience module, which will give you a more
+useful/shorter method call:
+```ruby
+# you'll only need to do this once per namespace
+include OntologyUnited::Convience
+
+define_ontology('MyOntologyName') do
+end
+```
+
+### Building your ontology
+
+Usually there is more than one way to building your ontology, i will
+elaborate on the benefits and drawbacks of each method.  However i will now
+use the convenience method of building an ontology.
+
+#### Prefix
+
+In order to benefit from ontology-united you'll first need to create a
+prefix. As the block passed to `define_ontology` is `instance_eval`ed on the
+ontology, self will be the current ontology. So you can create a prefix
+which points to the current ontology.
+```ruby
+define_ontology('MyOntologyName') do
+  this = prefix('thisOntology', self)
+end
+```
+
+However technically you can also pass an IRI (internationalized resource
+identifier) instead of `self`. But then you're pretty much on your own.
+You'll need to handle iri-management yourself.
+```ruby
+# Handling iri-management yourself:
+define_ontology('MyOntologyName') do
+  this = prefix('thisOntology', 'http://example.com/MyOntologyName#')
+end
+```
+
+#### Class (OWL)
+
+```ruby
+define_ontology('MyOntologyName') do
+  this = prefix('thisOntology', self)
+  this.class('ASampleClass')
+end
+```
+
+The `.class` method on a prefix, will create a prefixed class inside of the
+current ontology. If you do not want to rely on prefixes you can also use
+`ontology_class()` but then the argument has to be an IRI instead of a name.
+And again (as with prefixes) your currently on your own for
+iri-management.
+
+
+```ruby
+# Handling iri-management yourself:
+define_ontology('MyOntologyName') do
+  ontology_class('http://example.com/MyOntology#ASampleClass')
+end
+```
+
+By the way, you do not need to store ontology classes inside variables in
+order to use them again (i.e. in sentences). You can just *define* them
+again. The system will figure out by itself, that you actually meant the
+same class.
+
+#### Sentence
+
+Currently ontology-united only supports `sub_class_of` sentences.  This will
+be extended in the future, but it *has* to be enough for now.
+
+```ruby
+define_ontology('MyOntologyName') do
+  this = prefix('thisOntology', self)
+  this.class('ASampleClass').sub_class_of this.class('AParentClass')
+end
+```
+
+#### Imports
+
+You can define ontologies inside of other ontologies, through the inner
+`define`-method, which works exactly as the standard `define` method (also
+called `define_ontology` in convenience mode).
+
+```ruby
+define_ontology('Foo') do
+  this = prefix('this', self)
+  define('Bar') do
+    rr = prefix('rr', self)
+    rr.class('SomeBar')
+  end
+  this.class('Bar').sub_class_of this.class('Foo')
+  this.class('something')
+  this.class('something').sub_class_of this.class('Foo')
+end
+```
+
+As you might've guessed this is pretty useful when using imports, as this
+would allow you to import an ontology which you just defined *in-place*.
+Let's take a look at this:
+
+```ruby
+define_ontology('Foo') do
+  import define('Bar') do
+    rr = prefix('rr', self)
+    rr.class('SomeBar')
+  end
+  this.class('Bar').sub_class_of this.class('Foo')
+end
+```
+
+The `import` method is key, and that is basically it.
+
+
+### Serialization
+
+Let's assume we have an ontology:
+
+```ruby
+ontology = define_ontology('Foo') do
+  rr = prefix('rr', self)
+  imports define('Bar') do
+    rr = prefix('rr', self)
+    rr.class('SomeBar')
+  end
+  rr.class('Bar').sub_class_of rr.class('Foo')
+  rr.class('something')
+  rr.class('something').sub_class_of rr.class('Foo')
+end
+```
+
+If we want to work with it, we can query it for its IRI like this:
+`ontology.iri`, which will return a `file://`-schema IRI.
+
+If we want access to the `Tempfile` (which ontology-united uses internally),
+we can call `ontology.file`.
+
+Both methods will ensure that the corresponding file is created and
+serialized, including all imported ontologies.
+

data/lib/ontology-united/dsl/ontology.rb

@@ -4,6 +4,7 @@ require 'set'
 module OntologyUnited
   module DSL
     class Ontology < BaseDSL
+      DEFAULT_EXTENSION = :owl
 
       attr_reader_with_default :the_classes, :the_imports,
         :the_sentences, :the_prefixes, default: Set
@@ -39,10 +40,14 @@ module OntologyUnited
         OntologyDSL.define(*args, &block)
       end
 
+      def redefine(ontology = self, &block)
+        OntologyDSL.redefine(ontology, &block)
+      end
+
       def imports(arg, &block)
-        if block || arg.is_a?(Ontology)
+        if block && arg.is_a?(Ontology)
           ontology = arg
-          arg = define(ontology.name, &block)
+          arg = redefine(&block)
         end
         the_import = OntologyImport.new(arg)
         the_imports << the_import
@@ -71,14 +76,21 @@ module OntologyUnited
       end
 
       def file
-        @file ||= create_tempfile
+        create_tempfile if @file.nil?
+        @file
+      end
+
+      def extension
+        ".#{DEFAULT_EXTENSION}"
       end
 
       def create_tempfile
-        filename = name.match(%r(([^/]+)\.\w+$))[1]
-        file = Tempfile.new([filename, '.owl'])
+        filename = name
+        file = Tempfile.new([filename, extension])
         @iri = "file://#{file.path}"
+        @file = file
         file.write(self.to_s)
+        file.flush
         file.rewind
         file
       end

data/lib/ontology-united/dsl/ontology_dsl.rb

@@ -4,6 +4,10 @@ module OntologyUnited
 
       def self.define(name, &block)
         ontology = Ontology.new(name)
+        redefine(ontology, &block)
+      end
+
+      def self.redefine(ontology, &block)
         stack.push(ontology)
         if block
           if block.arity == 1

data/lib/ontology-united/serializer/owl/manchester.rb

@@ -46,11 +46,11 @@ module OntologyUnited::Serializer
 
       def class_definition?(ontology_class)
         # if no parent is set
-        parent_current.nil? ||
+        parent.nil? ||
           # or the parent is an ontology itself
-          ontology?(parent_current) ||
+          ontology?(parent) ||
           # or it is the first symbol of a sentence
-          sentence?(parent_current) && parent_current.sentence.first == ontology_class
+          sentence?(parent) && parent.sentence.first == ontology_class
       end
 
     end

data/lib/ontology-united/serializer/serializer_base.rb

@@ -1,25 +1,36 @@
 module OntologyUnited
   module Serializer
     class SerializerBase
-      attr_accessor :current, :parent_current
 
       def initialize(current: nil)
-        self.current = current
-        self.parent_current = nil
+        stack.push(current) if current
       end
 
       def process(subject, &block)
-        previous_parent = mark!(subject)
+        mark!(subject)
         result = block.call
-        mark!(parent_current, previous_parent)
+        unmark!
         result
       end
 
-      def mark!(subject, parent=nil)
-        previous_parent = parent_current
-        parent_current = parent || current
-        current = subject
-        previous_parent
+      def mark!(subject)
+        stack.push(subject)
+      end
+
+      def unmark!
+        stack.pop
+      end
+
+      def stack
+        @stack ||= []
+      end
+
+      def current
+        stack[-1]
+      end
+
+      def parent
+        stack[-2]
       end
 
       def join(elements, sep)
@@ -38,7 +49,7 @@ module OntologyUnited
         subject.is_a?(OntologyUnited::DSL::OntologyClass)
       end
 
-      def class?(subject)
+      def sentence?(subject)
         subject.is_a?(OntologyUnited::DSL::OntologySentence)
       end
 

data/lib/ontology-united/version.rb

@@ -1,3 +1,3 @@
 module OntologyUnited
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/ontology-united/ontology-united_spec.rb

@@ -9,9 +9,9 @@ describe OntologyUnited do
 
   context 'when issueing a standard definition' do
     let(:ontology) do
-      OntologyUnited::DSL::OntologyDSL.define('Foo.owl') do
+      OntologyUnited::DSL::OntologyDSL.define('Foo') do
         rr = prefix('rr', self)
-        imports define('Bar.owl') do
+        imports define('Bar') do
           rr = prefix('rr', self)
           rr.class('SomeBar')
         end

data/spec/ontology-united/serializer/owl/manchester_spec.rb

@@ -5,7 +5,7 @@ describe OntologyUnited::Serializer::OWL::Manchester do
   let(:name) { 'OntologyName' }
   let(:list) do
     the_prefix, ontology_class, sentence = nil
-    o = OntologyUnited::DSL::OntologyDSL.define("#{name}.owl") do
+    o = OntologyUnited::DSL::OntologyDSL.define(name) do
       the_prefix = prefix('some', self)
       ontology_class = the_prefix.class('Foobar')
       sentence = ontology_class.sub_class_of the_prefix.class('NoBar')
@@ -53,8 +53,36 @@ describe OntologyUnited::Serializer::OWL::Manchester do
     let(:serialized) { sentence.to_s(serializer: manchester.new) }
 
     it 'should be a valid manchester syntax sentence definition' do
-      expect(serialized).to eq("Class: some:Foobar SubClassOf: Class: some:NoBar")
+      expect(serialized).to eq("Class: some:Foobar SubClassOf: some:NoBar")
     end
   end
 
+  context 'when serializing ontologies with imports' do
+    let(:manchester) { OntologyUnited::Serializer::OWL::Manchester }
+    let(:name) { 'OntologyName' }
+    let(:list) do
+      referenced, the_import = nil
+      o = OntologyUnited::DSL::OntologyDSL.define(name) do
+        referenced = define('OtherOne') do
+          ontohub = prefix('ontohub', self)
+          ontohub.class('some_class')
+        end
+        the_import = imports referenced
+      end
+      [o, referenced, the_import]
+    end
+    let(:ontology) { list[0] }
+    let(:referenced) { list[1] }
+    let(:import) { list[2] }
+
+    context 'when serializing an import' do
+      let!(:serialized) { import.to_s(serializer: manchester.new) }
+
+      it 'should be a valid manchester syntax import definition' do
+        expect(serialized).to eq("Import: <#{referenced.iri}>")
+      end
+    end
+
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ontology-united
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Tim Reddehase
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-24 00:00:00.000000000 Z
+date: 2014-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler