wontomedia 0.0.1

data/doc/customization.markdown

@@ -0,0 +1,93 @@
+Copyright (C) 2010 - Glen E. Ivey
+  (see the end of this file for copyright/licensing information)
+
+Mechanism for Per-Instalation WontoMedia Customization
+======================================================
+
+WontoMedia is a web application intended to be installed in a large
+number and in a wide variety of systems.  For many of these systems,
+some of the included text or functionality may not be appropriate.  We
+have tried to separate portions of WontoMedia that may need to be
+customized (replaced) for different installations into separate files
+from the core application.
+
+To make things easier for those WontoMedia users who are also
+developers, we have segregated the instances of those files particular
+to a given WontoMedia installation from the core application files.
+Unfortunately, the conventions used by Ruby-on-Rails make things
+significantly easier if all files are located together based on
+function.  If we included customization files in the standard Rails
+directory hierarchy, then changes to them might inadvertently be
+included in commit's to the Git repositories for WontoMedia, or other
+people's changes to the sample version of the customization files
+might accidentally be applied to the custom versions for a particular
+installation.
+
+We have reconciled these conflicting needs as follows:
+
+ * customization files are kept in one or more "customization
+   directories" separate from any of the standard Rails directories
+
+ * within a customization directory is a sub-directory hierarchy
+   that mirrors the standard Rails directory structure
+
+ * a set of customization files, that can be viewed as examples and be
+   used as-is to get a new WontoMedia installation going, is located
+   in:
+
+    wontomedia/default-custom
+
+ * a rake task is provided that will create symbolic links to all
+   files found under all customization directories from the matching
+   point in the WontoMedia root directory hierarchy.  This allows
+   files "outside" of the normal directory structure (for version
+   control purposes) to appear "inside" where Rails expects them
+   during execution.
+
+ * a script is executed by rake (first step in "rake test:policies")
+   that finds all symbolic links in the project directory, and
+   replaces the file $GIT_DIR/info/exclude with a list of them.  In a
+   different type of project, where keeping symbolic links under
+   version control was important, this would be a problem.  However,
+   we have chosen the convention that symbolic links will be used in
+   the WontoMedia directory structure only for installation
+   customization.  This step prevents any symbolic links from being
+   committed to Git, and therefore any individual installations
+   configuration of cusomization files from being incorporated into
+   any updates to WontoMedia.
+
+   The "exclude" file is used, rather than .gitignore, so that an
+   individual site's extensions can include files above and beyond the
+   minimal set of entry points that the WontoMedia core expects.  If
+   .gitignore were used, then people would still have to manually
+   prevent customization files they added to their system from being
+   listed in Git commits they share with others.
+
+ * a script is executed by rake (run as part of "rake test:policies")
+   that recurses through the "default-custom" directory and fails that
+   a symbolic link exists in the application directory hierarchy for
+   each file under default-custom.  In this way, the content of
+   default-custom not only provides a sample of customization files,
+   but serves as the definition for all of the files referenced from
+   portions of the core application.
+
+The "customize" rake task is documented in
+
+    wontomedia/doc/script/rake-customize.markdown
+
+and its use in creating a new, *uncustomized* WontoMedia installation
+is mentioned in the WontoMedia wiki at:
+
+    http://wiki.wontology.org/InstallFromScratch
+    http://wiki.wontology.org/SettingUpYourDevelopmentEnvironment
+
+----------------------------------------------------------------
+
+    Permission is granted to copy, distribute and/or modify this
+    document under the terms of the GNU Free Documentation License,
+    Version 1.3, published by the Free Software Foundation; with no
+    Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+
+    You should have received a copy of the GNU Free Documentation
+    License along with document in the file COPYING.DOCUMENTATION.  If
+    not, see <http://www.gnu.org/licenses/>.

data/doc/scripts/rake-customize.markdown

@@ -0,0 +1,83 @@
+Copyright (C) 2010 - Glen E. Ivey
+  (see the end of this file for copyright/licensing information)
+
+# rake customize[directory-path:directory-path]
+
+This rake task operates recursively through each directory provided,
+and creates symbolic links to the files in that directory from
+matching, same-named points in the main wontomedia installation
+directory.  It is intended to merge installation-specific
+customization files maintained in separate directories (and version
+control repositories) from the core of the WontoMedia web application.
+
+As many directories as desired can be specified on the command line
+(one minimum).  The directory name list must be enclosed in square
+brackets, and placed immediately after the task name "customize" (no
+space).  Each directory is separated from the next by a colon (like a
+UNIX PATH).  Recall that rake always operates relative to the top
+directory of your project, regardless of your working directory when
+you execute the rake command.  Therefore, any relative paths you
+include are evaluated relative to the root of the wontomedia
+installation directory.
+
+Depending on your shell and the content of your directory names, you
+may need to include quotation marks or escape characters in the
+command line you type in order for rake to receive a command line
+formatted as shown.  In particular, the entire parameterized task,
+from the task name ("customize") through the closing square-bracket
+must be parsed by the shell and passed to rake as a single
+command-line argument.
+
+As an example of the "customize" task's operation, the command
+
+    rake customize[~/myWontology]
+
+will recursively find all files and directories under your
+"myWontology" directory, and make it appear as though they've been
+copied into your WontoMedia directory (in which the rake command was
+executed).  Assuming the following directory structure/content:
+
+    ~/myWontology/app/views/items/_home_introductory_text.html.erb
+
+this rake task will do the equivalent of:
+
+    ln -s ~/myWontology/app/views/items/_home_introductory_text.html.erb [wontomedia-root]/app/views/items
+
+However, the rake task uses absolute paths, so it will have to be
+re-executed if you later move either the WontoMedia directory or one
+of the customization directories in your file system.
+
+In this example, there was only one argument directory and only one
+file, so only one link was created.  This task will also create any
+directories needed to hold the created links, although this was not
+needed for the example above because a standard Ruby-on-Rails
+directory was used.
+
+When more than one directory is specified on the command line, this
+task processes them in the order provided.  If multiple directory
+arguments are provided, and two or more of them contain a file with
+the same relative path and name, only the link from the last
+(right-most) directory will remain when the task is complete.  This
+allows installation customizations to be derived from each other.  For
+example, running the following command from the root of your
+WontoMedia directory:
+
+    rake customize[default-custom:~/myWontology]
+
+will first create links to the minimum set of required customization
+files under the "default-custom" directory, and then create links to
+the files in your "myWontology" directory.  Your myWontology could
+then contain as little as a single file (with the correct,
+Rails-matching relative path) that replaced only a single link
+pointing into the default-custom directory.
+
+----------------------------------------------------------------
+
+    Permission is granted to copy, distribute and/or modify this
+    document under the terms of the GNU Free Documentation License,
+    Version 1.3, published by the Free Software Foundation; with no
+    Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+
+    You should have received a copy of the GNU Free Documentation
+    License along with document in the file COPYING.DOCUMENTATION.  If
+    not, see <http://www.gnu.org/licenses/>.

data/lib/helpers/connection_helper.rb

@@ -0,0 +1,41 @@
+#--
+# WontoMedia - a wontology web application
+# Copyright (C) 2010 - Glen E. Ivey
+#    www.wontology.com
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License version
+# 3 as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program in the file COPYING and/or LICENSE.  If not,
+# see <http://www.gnu.org/licenses/>.
+#++
+
+
+# This module provides a container for methods that manipulate or
+# transform Connection objects.
+module ConnectionHelper
+
+  # This method renders a multi-line string in the 'n3' format (aka
+  # 'Notation3' standardized by the W3C, see
+  # http://en.wikipedia.org/wiki/Notation3 for an introduction) from
+  # an array of Connection models.
+  #
+  # This is currently a trivial but correct implementation.  It supports
+  # our current data model, but will need a significant upgrade when
+  # WontoMedia begins to support reiffied edges (blank nodes), etc.
+  def self.connection_array_to_n3(connections)
+    result = ""
+    connections.each do |connection|
+      result << "<##{connection.subject.name}> <##{connection.predicate.name}> "
+      result << "<##{connection.obj.name}> .\n"
+    end
+    result
+  end
+end

data/lib/helpers/item_helper.rb

@@ -0,0 +1,141 @@
+#--
+# WontoMedia - a wontology web application
+# Copyright (C) 2010 - Glen E. Ivey
+#    www.wontology.com
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License version
+# 3 as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program in the file COPYING and/or LICENSE.  If not,
+# see <http://www.gnu.org/licenses/>.
+#++
+
+
+# This module provides a container for methods that manipulate or
+# transform Item objects, and constants related to Item objects.  The
+# constants are related to the single-table-inheritance structure
+# between Item and its specialized child classes, and don't fit into
+# any of the individual model classes themselves.
+module ItemHelper
+
+  ITEM_CLASS_NAME            = "Item"
+  ITEM_CATEGORY_CLASS_NAME   = "CategoryItem"
+  ITEM_INDIVIDUAL_CLASS_NAME = "IndividualItem"
+  ITEM_PROPERTY_CLASS_NAME   = "PropertyItem"
+  ITEM_QUALIFIED_CLASS_NAME  = "QualifiedItem"
+
+  ITEM_SUBTYPES_FROM_TEXT = {
+    "item"                 => Item,           "Item"           => Item,
+    "category"             => CategoryItem,   "CategoryItem"   => CategoryItem,
+    "individual"           => IndividualItem,
+      "IndividualItem" => IndividualItem,
+    "property"             => PropertyItem,   "PropertyItem"   => PropertyItem,
+    "qualified-connection" => QualifiedItem,  "QualifiedItem"  => QualifiedItem
+  }
+  ITEM_CLASSNAME_TO_SUBTYPE_SHORT = {
+    "CategoryItem" => 'category', "IndividualItem" => 'individual',
+    "PropertyItem" => 'property', "QualifiedItem" => 'qualified'
+  }
+  ITEM_SUBTYPES_TO_HUMAN = {
+    'CategoryItem' => 'Category',
+    'IndividualItem' => 'Individual',
+    'PropertyItem' => 'Property Type',
+    'QualifiedItem' => 'Qualified Connection'
+  }
+
+
+  # This method is a wrapper for Rails' Item.find(), except that it
+  # checks the sti_type of the item found, then creates and returns an
+  # instance of the correct Item child class.
+  def self.find_typed_item(*args)
+    n = Item.find(*args)
+    if n.nil?                                  ||
+       n.sti_type.nil?                         ||
+       ITEM_SUBTYPES_FROM_TEXT[n.sti_type].nil?
+      return nil
+    end
+
+# I think that this statement:
+#    ITEM_SUBTYPES_FROM_TEXT[n.sti_type].find(*args)
+# ought to work.  But it doesn't.  So instead, we do the following:
+    class_of_item_to_find = case n.sti_type
+            when "Item"                 then Item
+            when "item"                 then Item
+            when "CategoryItem"         then CategoryItem
+            when "category"             then CategoryItem
+            when "IndividualItem"       then IndividualItem
+            when "individual"           then IndividualItem
+            when "PropertyItem"         then PropertyItem
+            when "property"             then PropertyItem
+            when "QualifiedItem"        then QualifiedItem
+            when "qualified-connection" then QualifiedItem
+            end
+    class_of_item_to_find.find(*args)
+  end
+
+  # Use this method in place of <tt>new Item</tt> in order to create
+  # an Item child class (STI) instance matching a type string you have
+  # available.  (Note: if you know when writing a piece of code what
+  # item subtype you're trying to create, simply create that directly
+  # rather than using this method.  _E.g._, <tt>new
+  # PropertyItem</tt>.)
+  def self.new_typed_item(type_string, *args)
+    if type_string.nil?
+      return nil
+    end
+    if ITEM_SUBTYPES_FROM_TEXT[type_string].nil?
+      type_string = type_string.singularize
+      if ITEM_SUBTYPES_FROM_TEXT[type_string].nil?
+        return nil
+      end
+    end
+
+# absolutely no idea why this ugly thing works, but simply hash lookup
+# below causes failure deep in Rails' guts during new()
+    class_of_item_to_create = case type_string
+            when "Item"                 then Item
+            when "item"                 then Item
+            when "CategoryItem"         then CategoryItem
+            when "category"             then CategoryItem
+            when "IndividualItem"       then IndividualItem
+            when "individual"           then IndividualItem
+            when "PropertyItem"         then PropertyItem
+            when "property"             then PropertyItem
+            when "QualifiedItem"        then QualifiedItem
+            when "qualified-connection" then QualifiedItem
+            end
+#    class_of_item_to_create = ITEM_SUBTYPES_FROM_TEXT[type_string]
+    new_item = class_of_item_to_create.new(*args)
+    new_item.flags = 0
+    new_item
+  end
+
+  # Takes an Item object, +n+, and returns a symbol-indexed hash
+  # containing each of the Item's data fields.
+  def self.item_to_hash(n)
+# Really ought to be doing this programatically from the schema....
+    { :id => n.id, :name => n.name, :title => n.title, :flags => n.flags,
+      :description => n.description, :sti_type => n.sti_type }
+  end
+
+
+  # This method is equivalent to Rails' Item.all(), except that it
+  # only finds/returns "noun"-type items (Category and Individual
+  # items, but not Property or Qualified items).
+  def self.nouns
+    CategoryItem.all + IndividualItem.all
+  end
+
+  # This method is equivalent to Rails' Item.all(), except that it
+  # only finds/returns Items with an sti_type other than Qualified.
+  def self.not_qualified
+    CategoryItem.all + IndividualItem.all + PropertyItem.all
+  end
+end

data/lib/helpers/tripple_navigation.rb

@@ -0,0 +1,158 @@
+#--
+# WontoMedia - a wontology web application
+# Copyright (C) 2010 - Glen E. Ivey
+#    www.wontology.com
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License version
+# 3 as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program in the file COPYING and/or LICENSE.  If not,
+# see <http://www.gnu.org/licenses/>.
+#++
+
+
+# This module contains methods for navigating through (walking) the
+# inheritence hierarchy between the properties of connections.  They
+# allow callers to make queries about a property, and receive answers
+# that take into account the 'sub_property_of' relationships between
+# the immediately queried property and the property inheritance tree.
+module TrippleNavigation
+
+  # This method finds all existing PropertyItem's that are super
+  # properties of the PropertyItem identified by +predicate_id+.  The
+  # immediate super properties of an item are the objects of any
+  # connection of the form "item sub_property_of object".  The set of
+  # super properties found by this method includes immediate super
+  # properties and all of _their_ super properties.  This method
+  # accepts a block, and iteratively yields _its original argument_
+  # and the _IDs_ of the argument property's super properties to that
+  # block.
+  def self.relation_and_all_superproperties(predicate_id, &block)
+    yield predicate_id
+
+    spo_id = Item.find_by_name("sub_property_of").id
+    connections = Connection.all( :conditions => [
+      "subject_id = ? AND predicate_id = ?", predicate_id, spo_id ])
+    connections.each do |e|
+      relation_and_all_superproperties(e.obj_id, &block)
+    end
+  end
+
+  # This method finds all existing PropertyItem's that are sub
+  # properties of the PropertyItem identified by +predicate_id+.  The
+  # immediate sub properties of an item are the subjects of any
+  # connection of the form "subject sub_property_of item".  The set of
+  # sub properties found by this method includes immediate sub
+  # properties and all of _their_ sub properties.  This method accepts
+  # a block, and iteratively yields _its original argument_ and the
+  # _IDs_ of the argument property's sub properties to that block.
+  def self.relation_and_all_subproperties(predicate_id, &block)
+    yield predicate_id
+
+    spo_id = Item.find_by_name("sub_property_of").id
+    connections = Connection.all( :conditions => [
+      "predicate_id = ? AND obj_id = ?", spo_id, predicate_id ])
+    connections.each do |e|
+      relation_and_all_subproperties(e.subject_id, &block)
+    end
+  end
+
+  # This method tests for chains of relationships between
+  # PropertyItem's.  Its parameters are packaged in a single hash
+  # argument.  The value of each entry in the hash is the _ID_ of an
+  # Item in the database.  It returns a boolean that answers the
+  # "question" phrased in the parameter hash.
+  #
+  # Currently, there are two supported combinations of argument
+  # symbols:
+  #
+  # * <tt>:does</tt> xxxx <tt>:inherit_from</tt> xxxx <tt>:via</tt> xxxx
+  # * <tt>:does</tt> xxxx <tt>:link_to</tt> xxxx <tt>:through_children_of</tt> xxxx
+  #
+  # Both of these combinations form a question, the answer to which is
+  # in the boolean returned by this method (+true+ for yes).  The
+  # symbols used to index the argument hash are:
+  #
+  # [:does] The value in the hash associated with <tt>:does</tt> is the ID of the Item for which the caller is querying the connections stored in the database.
+  # [:inherit_from] The value in the hash associated with <tt>:inherit_from</tt> is the ID of a PropertyItem (different from the <tt>:does</tt> Item) in the database.  check_properties() will test for the presence of specific connections between this PropertyItem and the one specified by <tt>:does</tt>.
+  # [:via] The value in the hash associated with <tt>:via</tt> is the ID of the PropertyItem that must be present as the predicate of a connection for that connection to "count" toward establishing a chain of connections from the <tt>:does</tt> item to the <tt>:inherit_from</tt> item.  Note that <tt>:via</tt> is directional:  When <tt>:inherit_from</tt> is used, only connections where the <tt>:does</tt> item is the subject, the <tt>:inherit_from</tt> is the object, and all intervening connections "point" in that same direction will be tested, and this method will return <tt>true</tt> only when a chain of connections using the <tt>:via</tt> PropertyItem as their predicates can be found.
+  # [:link_to] The value in the hash associated with <tt>:link_to</tt> is the ID of another Item, to which check_properties will try to find a chain of connections from the <tt>:does</tt> Item.  Note that unlike calls to check_properties using <tt>:inherit_from</tt>, when <tt>:link_to</tt> is used the starting and ending items can be of any type, not just PropertyItems.
+  # [:through_children_of] The value in the hash associated with <tt>:through_children_of</tt> is the ID of a PropertyItem.  check_properties attempts to find a chain of connections between the other two Item parameters (in either direction) where the connections use the <tt>:through_children_of</tt> PropertyItem _or_ any PropertyItem that is a _child_ of the specified PropertyItem through the built-in <tt>sub_property_of</tt> relationship.  Unlike calls using <tt>:inherit_from</tt>, when checking <tt>:link_to</tt> connections present in either direction between the items found in a chain can produce a <tt>true</tt> result.
+  def self.check_properties(hash_of_params)
+    unless hash_of_params.has_key?(:does)
+      raise ArgumentError, "Expected :does in input hash"
+    end
+
+    if hash_of_params.has_key?(:inherit_from)
+      # TODO: ':via' is *almost* always a reference to
+      # sub_property_of.  Change this method and refactor callers so
+      # that when :via isn't present, it defaults to s_p_o.  (If we
+      # keep asking ActiveRecord to find_by_name(s_p_o), will it be
+      # cached or a huge performance hit?  Experiment and if
+      # A.R. really goes to the database each time, have a static
+      # variable here so that we only have to fetch from the db the
+      # first time.)
+      unless hash_of_params.has_key?(:via)
+        raise ArgumentError, "Expected :via in input hash"
+      end
+
+      child_id = hash_of_params[:does]
+      parent_id = hash_of_params[:inherit_from]
+      via_property_id = hash_of_params[:via]
+      # treat "self" as a form of inheritence
+      if child_id == parent_id
+        return true
+      end
+
+      connections = Connection.all( :conditions => [
+        "subject_id = ? AND predicate_id = ?", child_id, via_property_id ])
+      connections.each do |e|
+        if check_properties(
+            :does         => e.obj_id,
+            :inherit_from => parent_id,
+            :via          => via_property_id )
+          return true
+        end
+      end
+    elsif hash_of_params.has_key?(:link_to)
+      unless hash_of_params.has_key?(:through_children_of)
+        raise ArgumentError, "Expected :through_children_of in input hash"
+      end
+
+      from_item_id = hash_of_params[:does]
+      to_item_id   = hash_of_params[:link_to]
+      kind_of_path = hash_of_params[:through_children_of]
+      spo_id       = Item.find_by_name("sub_property_of").id
+
+      connections = Connection.all( :conditions =>
+        [ "subject_id = ?", from_item_id ])
+      connections.each do |e|
+        if check_properties(
+            :does         => e.predicate_id,
+            :inherit_from => kind_of_path,
+            :via          => spo_id )
+          if e.obj_id == to_item_id
+            return true
+          else
+            if check_properties(
+                :does                => e.obj_id,
+                :link_to             => to_item_id,
+                :through_children_of => kind_of_path )
+              return true
+            end
+          end
+        end
+      end
+    else
+      raise ArgumentError, "Expected :inherit_from or :link_to in input hash"
+    end
+    return false
+  end
+end