logic_tools 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 68b786dcea5db0011ebf3b7c4c8452ce7b1fd689
-  data.tar.gz: 8685d8a03576b28ba0601ca57a3a3dc22d3b5b9f
+  metadata.gz: a2329d237d7038309287c2907d60d5a383760642
+  data.tar.gz: d24b42399dcc9f835856e7ede9a539414f703dc1
 SHA512:
-  metadata.gz: e77ca46d2725b382528d08d9b180ea1864c3247c5c9114f4215be309333262dce348ba0d00b982034e5b26d9b1db96406991627c361bf05115c0815b0c049c5a
-  data.tar.gz: db8fa9b7b684f0597a9c50097c53893cfa8904cededad976f871c8b22d08dd6a197cd2fbca1a8b1a0ff53d04edd74ea6d0a96f72cbe8a928a4efc2762d523075
+  metadata.gz: 34433d985130bf65444113bc969347925f65d427b8400613f1daa0a2598a62158467abcd87c9c4fc67143faf2698dc5dbdb7c35d385222e906ec8ceeb0780c0b
+  data.tar.gz: ac8e94c8d5ebd78c7cffa01c14dbd7fa626cd88a4af95be1a2cfebcbd26fa9ff3a8b058fb940495a177ed845b8348d72e5c474e00252a4581c5a56bf6600595c

data/README.md

@@ -2,14 +2,12 @@
 
 LogicTools is a set of command-line tools for processing logic expressions.
 The tools include:
- * simplify\_qm:  for simplifying a logic expression.
- * std\_conj:  for computing the conjunctive normal form of a logic expression.
- * std\_dij:   for computing the disjunctive normal form a of logic expression.
- * truth\_tbl: for generating the truth table of a logic expression.
 
-## Disclaimer
+ * __simplify\_qm__:  for simplifying a logic expression.
+ * __std\_conj__:  for computing the conjunctive normal form of a logic expression.
+ * __std\_dij__:   for computing the disjunctive normal form a of logic expression.
+ * __truth\_tbl__: for generating the truth table of a logic expression.
 
-There is still a nasty bug in the logic simplifying tool (simplify_qm) which makes it give a wrong result. Fortunately, it seems to happen in some rare cases only.
 
 ## Installation
 
@@ -29,10 +27,16 @@ Or install it yourself as:
 
 ## Usage
 
-LogicTools is a command line-based set of tool. Each tool is used as follows:
-tool\_name "logical expression"
+LogicTools is a command line-based set of tool. Each tool is used as follows for processing a single expression:
+
+    $ tool_name "single logical expression"
+
+Multiple expressions stored into a file can also be processed as follows:
+
+    $ tool_name -f <filename>
 
 The logical expression is an expression where:
+
 * a logical variable is represented by a single alphabetical character (hence there is in total 56 possible variables);
 * a logical OR is represented by a '+' character;
 * a logical AND is represented by a '.' character (but it can be omitted);
@@ -40,32 +44,41 @@ The logical expression is an expression where:
 * opening and closing parenthesis are represented by, respectively, '(' and ')' characters.
 
 Important notice: 
+
 * the priority among logical operators is as follows: NOT > AND > OR
 * logical expressions must be put between quotes (the '"' character).
 
 For instance the followings are valid logical expression using the a,b and c variables:
-"ab+ac"
-"a.b.c"
-"a+b+!c"
-"a~(b+~c)"
+
+    "ab+ac"
+    "a.b.c"
+    "a+b+!c"
+    "a~(b+~c)"
 
 Finally, here are a few examples of LogicTool usage:
+
 * simplifying the expression a+ab:
-simplify\_qm "a+ab"
--> a
+
+        $ simplify_qm "a+ab"
+        -> a
 * compute the conjunctive normal form of the expression a+ab:
-std\_conj "a+ab"
--> ab+a~b
+
+        $ std_conj "a+ab"
+        -> ab+a~b
+
 * compute the disjunctive normal form of the expression a+ab:
-std\_dij "a+ab"
--> (a+b)(a+~b)
+
+        $ std_dij "a+ab"
+        -> (a+b)(a+~b)
+
 * compute the truth table of the expression a+ab:
-truth\_tbl "a+ab"
--> a b
-   0 0 0
-   0 1 0
-   1 0 1
-   1 1 1
+
+        $ truth_tbl "a+ab"
+        -> a b
+           0 0 0
+           0 1 0
+           1 0 1
+           1 1 1
 
 ## Development
 
@@ -84,12 +97,6 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 
 ## To do
-### High priority
-* Fix the bug that makes simplify\_qm produce sometimes a wrong result. 
-* Downgrade the user interface: actually the interface can do much more than what is described in the documentation, but this is not really useful, so it should better to remove these features.
-
-### Low priority
-
 * Add a more efficient alternative command to simplify_qm, based on the Espresso algorithm for example.
 
 

data/lib/logic_tools.rb

@@ -1,5 +1,12 @@
 require "logic_tools/version"
 
+######################################################################
+#                                                                    
+# == LogicTools
+# This module includes all the classes and methods used
+# by the *logic_tools* set of tools.
+#                                                                    
+######################################################################
+
 module LogicTools
-  # Your code goes here...
 end

data/lib/logic_tools/logicinput.rb

@@ -0,0 +1,43 @@
+
+module LogicTools
+
+
+#########################################################################
+#           Common command line interface for all Logic Tools           
+#########################################################################
+
+
+    ## Displays a short help message.
+    def help_short
+        name = File.basename($0)
+        puts "Usage: #{name} <\"logic expression\">"
+        puts "   or: #{name} -f <file name>"
+    end
+
+    ## Gets an iterator over the input expression
+    #  (obtained either through options or a through file).
+    def each_input
+        # No block? Return an enumerator
+        return enum_for(:each_input) unless block_given?
+        # A block? Interrate with it
+        # Process the arguments
+        if ($*.empty?) then
+            # No arguments, shows the help and end.
+            help_short
+            exit(1)
+        end
+        if $*[0] == "-f" or $*[0] == "--file" then
+            # Work from a file, iterate on each line
+            exprs = File.read($*[1])
+            exprs.gsub!(/\r\n?/, "\n")
+            exprs.each_line do |line|
+                yield(line)
+            end
+        elsif $*[0] == "-h" or $*[0] == "--help" then
+            help_short
+        else
+            # Work directly on the arguments as an expression
+            yield($*.join)
+        end
+    end
+end

data/lib/logic_tools/logicparse.rb

@@ -1,6 +1,6 @@
-##########################
-# Truth table generator  #
-##########################
+########################################################
+#     Parse a string and convert to a logic tree       #
+########################################################
 
 # For parsing the inputs
 require 'parslet'
@@ -11,24 +11,25 @@ require "logic_tools/logictree.rb"
 
 
 
-########################################################
-# Parse a string and convert to a logic tree
 
 
 module LogicTools
 
-    ## The parser of logic expressions
+    ## The parser of logic expressions.
     class Parser < Parslet::Parser
 
         # True / false
         rule(:tru) { str("1") }
         rule(:fal) { str("0") }
         # Variable
-        rule(:var) { match('[A-Za-uw-z]') }
+        # rule(:var) { match('[A-Za-uw-z]') }
+        rule(:var) { match('[A-Za-z]') }
         # And operator
-        rule(:andop) { str("&&") | match('[&\.\*^]') }
+        # rule(:andop) { str("&&") | match('[&\.\*^]') }
+        rule(:andop) { str(".") }
         # Or operator
-        rule(:orop) { match('[+|v]') }
+        # rule(:orop) { match('[+|v]') }
+        rule(:orop) { str("+") }
         # Not operator
         rule(:notop) { match('[~!]') }
 
@@ -43,7 +44,7 @@ module LogicTools
     end
 
 
-    ## The logic tree generator from the syntax tree
+    ## The logic tree generator from the syntax tree.
     class Transform < Parslet::Transform
 
         # Terminal rules
@@ -77,10 +78,8 @@ module LogicTools
     end
 
 
-    ## The parser/gerator main fuction: converts a string to a logic tree
-    #  Param:
-    #  +str+:: the string to parse
-    #  Return: the resulting logic tree
+    ## The parser/gerator main fuction: converts the text in +str+ to a 
+    #  logic tree.
     def string2logic(str)
         # Remove the spaces
         str = str.gsub(/\s+/, "")

data/lib/logic_tools/logicsimplify.rb

@@ -10,8 +10,8 @@ require 'set'
 module LogicTools
 
 
-    ## Converts an array of variable to bit vector according to their value
-    #  @param vars the array of variables to convert
+    ## Converts the array of variables +var+ to a bit vector according to
+    #  their values
     def vars2int(vars)
         res = ""
         vars.each_with_index do |var,i|
@@ -24,24 +24,33 @@ module LogicTools
 
 
 
-    # Class describing an implicant
+    ##
+    # Represents a logic implicant
     class Implicant
         include Enumerable
-        attr_reader :mask,   # The positions of the x 
-                    :bits,   # The bit vector of the implicant
-                    :count,  # The number of 1 of the implicant
-                    :covers, # The bit values covered by the implicant
-                    :prime   # Tell if the implicant is prime or not
-        attr_accessor :var   # The variable associated with the implicant
-                             # Do not interfer at all with the class, so
-                             # public and fully accessible
+
+        ## The positions of the *X* in the implicant.
+        attr_reader :mask
+        ## The bit vector of the implicant.
+        attr_reader :bits
+        ## The number of *1* of the implicant.
+        attr_reader :count
+        ## The bit values covered by the implicant.
+        attr_reader :covers
+        ## Tell if the implicant is prime or not.
+        attr_reader :prime   
+        ## The variable associated with the implicant
+        #  Do not interfer at all with the class, so
+        #  public and fully accessible
+        attr_accessor :var    
+        
         protected
         attr_writer :covers
         public
 
-        ## Create an implicant
-        #  @param base if Implicant: copy constructor <br>
-        #              otherwise: creat a new implicant from a bit string
+        ## Creates a new implicant from +base+.
+        #
+        #  Argument +base+ can be either another implicant or a bit string.
         def initialize(base)
             if base.is_a?(Implicant)
                 @covers = base.covers.dup
@@ -51,7 +60,7 @@ module LogicTools
             else
                 @bits = base.to_s
                 unless @bits.match(/^[01]*$/)
-                    raise "Invalid bit string for an initial implicant: " + @bits
+                    raise "Invalid bit string for an initial implicant: "+ @bits
                 end
                 @mask = " " * @bits.size
                 @count = @bits.count("1")
@@ -60,50 +69,44 @@ module LogicTools
             @prime = true # By default assumed prime
         end
 
-        ## Convert to a string
-        def to_s
+        ## Converts to a string
+        def to_s # :nodoc:
             @bits
         end
 
-        ## inspect
-        def inspect
+        def inspect #:nodoc:
             @bits.dup
         end
 
-        ## Set the prime status
-        #  @param st the new status (true or false)
+        ## Sets the prime status to +st+ (true or false).
         def prime=(st)
             @prime = st ? true : false
         end
 
-        ## Iterate overs the bits of the implicant
+        ## Iterates over the bits of the implicant.
         def each(&blk)
             @bits.each_char(&blk)
         end
 
-        # Compare implicants
-        # @param imp the implicant (or simply bit string) to compare with
-        def ==(imp)
-            @bits == imp.to_s
+        ## Compares with +implicant+
+        def ==(implicant) # :nodoc:
+            @bits == implicant.to_s
         end
-        def <=>(imp)
-            @bits <=> imp.to_s
+        def <=>(implicant) #:nodoc:
+            @bits <=> implicant.to_s
         end
 
-        # duplicates the implicant
-        def dup
+        ## duplicates the implicant.
+        def dup # :nodoc:
             Implicant.new(self)
         end
 
-        ## Get a bit by index
-        #  @param i the index in the bit string of the implicant
+        ## Gets the value of bit +i+.
         def [](i)
             @bits[i]
         end
 
-        ## Set a bit by index
-        #  @param i the index in the bit string of the implicant
-        #  @param b the bit to set
+        ## Sets the value of bit +i+ to +b+.
         def []=(i,b)
             raise "Invalid bit value: #{b}" unless ["0","1","x"].include?(b)
             return if @bits[i] == b # Already set
@@ -117,16 +120,14 @@ module LogicTools
         end
 
 
-        ## Merge with another implicant
-        #  @param imp the implicant to merge with
-        #  @return the resulting implicant
-        def merge(imp)
-            # Has imp the same mask?
-            return nil unless imp.mask == @mask
+        ## Creates a new implicant merging current implicant with +imp+.
+        def merge(implicant)
+            # Has implicant the same mask?
+            return nil unless implicant.mask == @mask
             # First look for a 1-0 or 0-1 difference
             found = nil
             @bits.each_char.with_index do |b0,i|
-                b1 = imp.bits[i]
+                b1 = implicant.bits[i]
                 # Bits are different
                 if (b0 != b1) then
                     # Stop if there where already a difference
@@ -146,7 +147,7 @@ module LogicTools
                 # And update its x
                 merged[found] = "x"
                 # Finally update its covers
-                merged.covers = @covers | imp.covers
+                merged.covers = @covers | implicant.covers
                 return merged
             end
             # No merge
@@ -154,67 +155,72 @@ module LogicTools
         end
     end
 
-    # Class describing a group of implicants with only singletons, sortable
-    # by number of ones
+
+    ##
+    # Represents a group of implicants with only singletons, sortable
+    # by number of ones.
     class SameXImplicants
         include Enumerable
 
-        ## Default constructor
+        ## Creates a group of implicants.
         def initialize
             @implicants = []
             @singletons =  Set.new # Set used for ensuring each implicant is
                                    # present only once in the group
         end
 
-        ## Ge the size of the group
+        ## Gets the number of implicants of the group.
         def size
             @implicants.size
         end
 
-        ## Iterate of the implicants
+        ## Iterates over the implicants of the group.
         def each(&blk)
             @implicants.each(&blk)
         end
 
-        ## Access by index
-        #  @param i the index
+        ## Gets implicant +i+.
         def [](i)
             @implicants[i]
         end
 
-        ## Add an implicant
-        #  @param imp the implicant to add
-        def add(imp)
-            return if @singletons.include?(imp.bits) # Implicant already present
-            @implicants << imp
-            @singletons.add(imp.bits.dup)
+        ## Adds +implicant+ to the group.
+        def add(implicant)
+            # Nothing to do if +implicant+ is already present.
+            return if @singletons.include?(implicant.bits)
+            @implicants << implicant
+            @singletons.add(implicant.bits.dup)
         end
+
         alias :<< :add
 
-        # Sort the implicants by number of ones
+        ## Sort the implicants by number of ones.
         def sort!
-            @implicants.sort_by! {|imp| imp.count }
+            @implicants.sort_by! {|implicant| implicant.count }
         end
 
-        # Convert to a string
-        def to_s
+        ## Converts to a string
+        def to_s # :nodoc:
             @implicants.to_s
         end
-        def inspect
+
+        def inspect # :nodoc:
             to_s
         end
     end
 
-    ## Class describing a pseudo variable associated to an implicant
+    ## 
+    #  Describes a pseudo variable associated to an implicant.
+    #
     #  Used for the Petrick's method
     class VarImp < Variable
         @@base = 0 # The index of the VarImp for building the variable names
 
+        ## The implicant the pseudo variable is associated to.
         attr_reader :implicant
 
-        ## Create the variable
-        #  @param imp the implicant to create the variable from
-        def initialize(imp)
+        ## Creates a pseudo variable assoctiated to an +implicant+.
+        def initialize(implicant)
             # Create the name of the variable
             name = nil
             begin
@@ -224,19 +230,20 @@ module LogicTools
             # Create the variable
             super(name)
             # Associate it with the implicant
-            @implicant = imp
-            imp.var = self
+            @implicant = implicant
+            implicant.var = self
         end
     end
 
 
 
-    # Enhance the Node class with expression simplifying
+    ## Enhances the Node class with expression simplifying.
     class Node
         
         ## Generates an equivalent but simplified representation of the
-        #  function.<br>
-        #  Uses the Quine-Mc Cluskey method
+        #  expression represented by the tree rooted by the current node.
+        #
+        #  Uses the Quine-Mc Cluskey method.
         def simplify
             # Step 1: get the generators
             
@@ -254,8 +261,8 @@ module LogicTools
 
             # Convert the minterms to implicants without x
             minterms.each do |term|
-                imp = Implicant.new(term)
-                implicants[imp.mask] << imp
+                implicant = Implicant.new(term)
+                implicants[implicant.mask] << implicant
             end
 
             # print "implicants = #{implicants}\n"
@@ -272,17 +279,18 @@ module LogicTools
                     group.sort! # Sort by number of one
                     size = group.size
                     # print "size = #{size}\n"
-                    group.each_with_index do |imp0,i0|
-                        # print "imp0 = #{imp0}, i0=#{i0}\n"
+                    group.each_with_index do |implicant0,i0|
+                        # print "implicant0 = #{implicant0}, i0=#{i0}\n"
                         ((i0+1)..(size-1)).each do |i1|
                             # Get the next implicant
-                            imp1 = group[i1]
-                            # print "imp1 = #{imp1}, i1=#{i1}\n"
-                            # No need to look further if the number of 1 of imp1
-                            # is more than one larger than imp0's
-                            break if imp1.count > imp0.count+1
+                            implicant1 = group[i1]
+                            # print "implicant1 = #{implicant1}, i1=#{i1}\n"
+                            # No need to look further if the number of 1 of 
+                            # implicant1 is more than one larger than 
+                            # implicant0's
+                            break if implicant1.count > implicant0.count+1
                             # Try to merge
-                            mrg = imp0.merge(imp1)
+                            mrg = implicant0.merge(implicant1)
                             # print "mrg = #{mrg}\n"
                             # Can merge
                             if mrg then
@@ -290,14 +298,14 @@ module LogicTools
                                 # Indicate than a merged happend
                                 has_merged = true
                                 # Mark the initial generators as not prime
-                                imp0.prime = imp1.prime = false
+                                implicant0.prime = implicant1.prime = false
                             end
                         end 
                         # Is the term prime?
-                        if imp0.prime then
-                            # print "imp0 is prime\n"
+                        if implicant0.prime then
+                            # print "implicant0 is prime\n"
                             # Yes add it to the generators
-                            generators << imp0
+                            generators << implicant0
                         end
                     end
                 end
@@ -359,7 +367,7 @@ module LogicTools
             end
 
             # Sort by variable order
-            selected.sort_by! { |imp| imp.bits }
+            selected.sort_by! { |implicant| implicant.bits }
 
             # print "Selected prime implicants are: #{selected}\n"
             # Generate the resulting tree