catlogic 0.0.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fcf6e7fcb655d416e5ab00d93212b490860e2632
-  data.tar.gz: b9b5d3856a9c181436aff598eb043589432c2cac
+  metadata.gz: 6312cc7710e89773cfc041b5affe729ba1b3b647
+  data.tar.gz: 5590b0ba2c25878ba794371fc6c0f0a762924c4e
 SHA512:
-  metadata.gz: 06e48a30aa87c2ddd027040ea4d08d7f97edf336b5bb9c81213c21729ac2a1928d4363131a2a48b25755d0e8d74c2b1fa9534cde1eb55b5a19c201e7ba79ea8b
-  data.tar.gz: 4bef72f6ee5103edd20c0e59b4024515cb321a381620563d08a4a04426ff030a2539b923549f89e41761ad06397610793aaa4cb30ee3fda7d64c1b643072c27e
+  metadata.gz: 679b421b4ce3c76b15de5246594833eb9782f27a32605b5ab6f8e0017b88d3409d71ba59ad4e4e6250990926e224c154acc8c10e1b35337eba1c57f20f75fdb9
+  data.tar.gz: 51ac946455ced01462986b901dcd46287d6a3d26584995b9d7057113e42ca663d251434e334019b667a1a59d8c14cfb295398a52696485bfcbb07be46b980af1

data/README.md

@@ -1,36 +1,231 @@
 # Catlogic
 
+This a library designed to construct, calculate, and investigate categorical propositions and syllogisms.
+
 ## Installation
 
+While such a library may at first be intimidating for the novice to use, it is not beyond you! 
+
+If you are using a Unix system (a Mac or Linux machine) you should be able to use this library quite easily with IRB, requiring little set up or programming knowledge.
+
+To install `catlogic`, run in your terminal
+
     gem install catlogic
+    
+To use in a script, simply require catlogic at the top of your file
+
+	require 'catlogic'
+	
+To use in `irb`, (the recommended way for a beginner to play around with the library), enter the irb shell by typing in the terminal: 
+
+	irb
+
+Now type at the prompt
+	
+	require 'catlogic'
+
+You are now ready to go. To quickly create a syllogism type:
 
+	syl = Catlogic::Form.new("AAA", 1).syllogism
+	
+Now you can test your syllogisms validity:
+
+	syl.validity
+	
+or generate a human readable output
+
+	syl.label
+	
+See below for a detailed discussion of the kinds of objects you can create.
+	
 ## Usage
 
-    require 'catlogic'
+To use the library, some knowledge of categorical logic, propositions, and syllogisms is required.
+
+I recommend taking a look at the relevant wikipedia pages: [http://en.wikipedia.org/wiki/Syllogism](http://en.wikipedia.org/wiki/Syllogism); [http://en.wikipedia.org/wiki/Syllogism](http://en.wikipedia.org/wiki/Syllogism), [http://en.wikipedia.org/wiki/Categorical_proposition](http://en.wikipedia.org/wiki/Categorical_proposition); [http://www.logicmuseum.com/wiki/Syllogism](http://www.logicmuseum.com/wiki/Syllogism); [http://en.wikipedia.org/wiki/Square_of_opposition](http://en.wikipedia.org/wiki/Square_of_opposition)
+
+Here I will just define the basic terms of categorical logic required to understand and use the `catlogic` library.
+
+### The Proposition
+Perhaps the most important unit of categorical logic is the categorical proposition.
+
+Thus, one of the central objects in this library is the Proposition object. A Proposition is not, however, the smallest conceptual unit, but is constructed from five other pieces of information: quantity, subject term, quality, predicate term, and a truth value. A Proposition objects is therefore constructed from four elemental level objects and one boolean, like so: 
+
+    proposition = Catlogic::Proposition.new(
+   		Catlogic::Quantity.new("universal"), 
+   		Catlogic::Term.new("Dogs"), 
+   		Catlogic::Quality.new("affirmative"), 
+   		Catlogic::Term.new("Mammals"), 
+   		true)
+   		
+Or this can be constructed in shorthand like so:
+
+    proposition = Catlogic::Proposition.new("universal", "Dogs", "affirmative", "Mammals", true)
+ 
+The truth value defaults to true, so you can choose to omit explicitly declaring that the proposition is true.
+   
+In either case, this construction corresponds to the human readable proposition: "All Dogs are Mammals," which can be retrieved using the label method.
 
-    # create a categorical proposition
-    proposition = Proposition.new(Quantity.new("Universal"), Term.new("Dogs), Catlogic::Quality.new("Affirmative"), Term.new("Mortal"), true)
+    proposition.label
     
-    # get the type of the proposition
+will produce the String:
+
+    "All Dogs are Mammals"
+    
+Besides the subject and predicate term and truth value, every categorical proposition has a quantity, either "universal" (All) or "particular" (Some). Likewise every proposition has a quality, either "affirmative" (are) or "negative" (are not). 
+
+The combination of Quality and Quantity data yields one of four unique proposition types, represented by A, E, I, and O, which can be retrieved from any constructed proposition like so: 
+
     proposition.type
     
-	#get a human readable form of the proposition
-	propostion.label
-	
-	#make immediate inferences
-	#obverse
-	proposition.obverse
+But likewise, it is also possible to construct generic propositions starting from a given proposition type. This can be constructed as follows:
+
+    propositiontype = Catlogic::PropositionType.new("A")
     
-    # Build a proposition from its type
-    proposition = PropositionType.new("I").proposition
+A generic proposition can be constructed from this by using the `proposition` method: 
+
+    proposition = propositiontype.proposition
     
-	# Build a syllogism
-	syllogism = Syllogism.new(majorproposition, minorproposition, conclusion)
+Calling the `proposition.label` method now returns `All S are P`.
+
+A number of immediate inferences can be made from a give proposition. These can be called as follows:
+
+	proposition.contradictory	
+	proposition.contrary
+	proposition.subcontrary
+	proposition.subaltern
+	proposition.converse
+	proposition.obverse
+	proposition.contrapolated
+
+
+### The Syllogism
+
+The next major unit is the Syllogism, which is itself an object constructed from three Proposition objects, a major proposition, a minor proposition, and the conclusion.
+
+It is constructed first by creating three propositions.
+
+    major = Catlogic:Proposition.new("universal", "Dogs", "affirmative", "Mammals")
     
-    # Test the validity of a syllogism
-    syllogism.validity
+	minor = Catlogic::Proposition.new("universal", "Cockapoos", "affirmative", "Dogs")
+	
+	conclusion = Catlogic::Proposition.new("universal", "Cockapoos", "affirmative", "Mammals")
+
+Note that I left off adding `true` at the end of these proposition constructions because, if not stated, the Proposition object defaults to true.
+
+The Syllogism object is then constructed from these propositions:
+
+    syllogism = Catlogic::Syllogism.new(major, minor, conclusion)
     
-    # Get form of syllogism
-    syllogism.form
+All of the different Proposition objects that make up the syllogism can be retrieved as follows:
+
+	syllogism.major
+	syllogism.minor
+	syllogism.conclusion
+	
+Each syllogism has a middle term. This middle term is the term repeated in the major and minor premises. It can be retrieved from a syllogism as follows.
+
+    syllogism.middle
+    
+This will return a Term object and, to get the human readable version of that term, simply ask for the label.
+
+   syllogism.middle.label
+   
+Which, in our case, is "Dogs". 
+
+Likewise each syllogism has a major term and a minor term. 
+
+The minor term is found in the subject position in the conclusion premise and the major term is found in the predicate position in the conclusion premise. The Term objects can be retrieved as follows:
+
+	syllogism.majorterm
+	syllogism.minorterm
+	
+A syllogism also has a unique Form, which is made up from a Mood object and Figure object. Each of these can be retrieved from a syllogism. The Mood is constituted by the three proposition types of the syllogism's three propositions. 
+
+	syllogism.mood
+
+returns a Mood object, itself constructed from three PropositionType objects. A human readable output can be retrieved by applying the method `.label` to the Mood object, like so:
+
+	syllogism.mood.label
+	
+This will return "AAA" because our syllogism is made up of three A proposition types. 
+
+The Form object is also constructed from a Figure object, which is determined by the position of the middle term in the major and minor premises. There are four possible figures, and a Figure object can be retrieved by applying the figure method to the syllogism.
+
+	syllogism.figure
+	syllogism.figure.label
+	
+The addition of the `.label` method returns the integer 1 because our sample syllogism is a figure one syllogism.
+
+Combining the Mood and the Figure objects constructs a Form object which can also be retrieved from a Syllogism object.
+
+	syllogism.form
+	syllogism.form.label # == "AAA1"
+	
+The Mood and Figure can also be retrieved directly from the Form object
+
+	form = syllogism.form
+	form.mood
+	form.figure
+	
+The Form object is also very useful because it allows us to very quickly construct a generic syllogism for any possible syllogism.
+
+The Form object can be constructed as follows.
+
+	form = Catlogic::Form.new("AAA", 1)
+	
+One can quickly create a syllogism from the given Form object by calling the syllogism method:
+
+	syllogism = form.syllogism
+	
+Besides retrieving information about a given syllogism, we can also test a syllogisms validity: 
+
+	syllogism.validity
+	
+If valid it will return `true`, if invalid it will return `false`. 
+
+The validity method tests against six separate tests, that reduce the 256 possible syllogisms to the 24 valid (unconditionally and conditionally) syllogisms. Each of these tests can be run separately.
+
+	syllogism.undistributed_middle_test
+	syllogism.illicit_major_test
+	syllogism.illicit_minor_test
+	syllogism.exclusive_premises_test
+	syllogism.affirm_from_neg_test
+	syllogism.neg_from_affirms_test
+	
+### Syllogism Pairs and Syllogism Collections	
+This is a more advanced use case, but it may happen that you have two or more premises and you actually want to compute possible syllogisms that can be constructed from this set and then test for validity.
+
+To do this you can create a PremisePair Object from two Proposition objects
+
+	preimsepair = Catlogic:PremisePari.new(major, minor)
+	
+On a PremisePair object you can request an array of possible conclusions. For any premise pair it will return the four possible conclusion combinations.
+
+There are enough resources at this point in the library to allow you to test the validity of those possible conclusions and determine if you can infer any new truths from the original set of known propositions.
+
+This can be written your self or done using the PremiseCollection object.
+
+The PremiseCollection object takes an array of two or more Proposition objects in any order, constructed like so:
+
+	collection = Catlogic::PremiseCollection.new([propostion1, proposition2, proposition3])
+	
+With this object constructed you can use the method `valid_syllogisms' to return an array of valid syllogisms that can be constructed from the input set.
+
+	collection.valid_syllogims
+	
+You can also search for just new inferred conclusions either with `inferred_truths_unique` or `inferred_truths_new`.
+
+	collection.inferred_truths_unique
+	collection.inferred_truths_new
+
+`.inferred_truths_unique` will return non duplicate truths inferred from the given set.
+
+`.inferred_truths_unique` will filter the above set excluding all inferred truths that were present in the original set.
+
+ 
+Please post issues and feature requests.
+
+Full documentation can be found at [http://www.rubydoc.info/gems/catlogic/](http://www.rubydoc.info/gems/catlogic/)
     
 

data/lib/catlogic/proposition.rb

@@ -3,7 +3,7 @@ module Catlogic
 
     attr_reader :quantity, :subject, :quality, :predicate, :truthvalue
 
-    def initialize(quantity, subject, quality, predicate, truthvalue)
+    def initialize(quantity, subject, quality, predicate, truthvalue=true)
       @quantity=quantity.to_quantity
       @subject=subject.to_term
       @quality=quality.to_quality
@@ -57,7 +57,8 @@ module Catlogic
 
     def contrary
       if @quantity.label  == "particular"
-        abort("There is no contrary for this type of propostion. Try subcontrary")
+        puts
+        return "There is no contrary for this type of propostion. Try subcontrary"
       end
       quality = @quality.opposite
 
@@ -73,7 +74,8 @@ module Catlogic
 
     def subcontrary
       if @quantity.label  == "universal"
-        abort("There is no subcontrary for this type of propostion. Try contrary.")
+        puts "There is no subcontrary for this type of propostion. Try contrary."
+        return
       end
 
       quality = @quality.opposite

data/lib/catlogic/version.rb

@@ -1,3 +1,3 @@
 module Catlogic
-  VERSION = "0.0.3"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: catlogic
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Jeffrey C. Witt
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-03 00:00:00.000000000 Z
+date: 2015-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler