fae 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: f0f89598b59524e013062bb117f47fcd1889716a
-  data.tar.gz: b9a9397367d130f47918553a63344e7e73fb4fa1
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OTQ4YmUyNTU0ODY2YjViODVkNjFkY2FmMzY4ZDM0NmVhZTUyMGFlYQ==
+  data.tar.gz: !binary |-
+    ZDVmMDY1NTE0ZTRiZTFlMzc2YzUyYTViYmI3NDAzYmUxZDM1OTg0MQ==
 SHA512:
-  metadata.gz: ed9dff23f912d6156c0bd0d81e220ab95da5a44361883303ed56d1f5d009169b332ff3662b8b40b2285d45406302e65d7a6fba052a9249280d6b21f8c85e49b7
-  data.tar.gz: 2d20b2843097ee222bd03a73288fcba66f240a4b76324299efad7144979f8816fa77b14fa9c9efe2152b9c7bacb9d4299fc237ea69623b9b4525ab94917969af
+  metadata.gz: !binary |-
+    OThiOTUyNTk5MDc2NzBkNzkyZjk3ZGM2M2VkNWJmOTkxNDEyZWI0MTZjNzkz
+    ZjFlMzIzMzk5YmRjNDkzOWMxMzM2ZWVmMjIwZGEyZjRjYTY1MGQxYzkwMWRi
+    MTY4NzdlOTQ3ZDAwZDVlMmEyMWYyZmM5ZTRmZGIzNzAxMmVkMmY=
+  data.tar.gz: !binary |-
+    MjA0NmJiZTFmYWQ3Njk0OTc0YzRlM2ZlM2YxNDljYjM2NGIyOTA0MDM4MzIy
+    OTA1OTNjMzhhNmZiNDI5NzRkYTA1OGNkYTYxY2YyMGM4NTU0YjhhMjNlYTQy
+    ZjEwZmZhYjE5NTIwNTM2OGQ1OWU5YzJiZTliMzIyNDA5NjQwNjg=

data/README.md

@@ -1,28 +1,152 @@
 # Fae
 
-TODO: Write a gem description
+[![Gem Version](https://badge.fury.io/rb/fae.svg)](http://badge.fury.io/rb/fae)
+
+This is a small Ruby gem that evaluates a Finite Automata State Diagram for validity.
+
+## Dependencies
+
+* Ruby 1.9.3 or greater
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Install the gem by running the following command:
 
-    gem 'fae'
+```bash
+gem install fae
+```
 
-And then execute:
+## Usage
 
-    $ bundle
+The gem comes with an executable, `fae`, and can be run in two different modes, interactive or file.
 
-Or install it yourself as:
+### File Mode
 
-    $ gem install fae
+You can load a finite automata state diagram from a file, by creating it in the following format:
 
-## Usage
+```yaml
+- description: the language with an odd number of a's
+  # Comma-separated list of letters in your language
+  language: a
+  states:
+    # This is the state name, then the paths each letter would take you.
+    # This should be in "letter -> State, letter -> State" format.
+    A: a -> B
+    # If the state is accepting, you should add accepting to the end
+    B: a -> A, accepting
+  # Strings to evaluate when checking the state diagram
+  strings:
+    # In the format "name: valid or invalid"
+    a: valid
+    aa: invalid
+    aaa: valid
+    aaaa: invalid
+```
+
+Then run the executable with the `-f` flag:
+
+```bash
+fae -f diagram.yml
+```
+
+For example, take the following state diagram, which is the language `a,b` and described by `the language of all strings in which the number of a's is even`:
+
+![Example State Diagram](https://raw.githubusercontent.com/caseyscarborough/fae/master/etc/example_state_diagram.png)
+
+The data file for this diagram would look like this (`example.yml`):
+
+```yaml
+- description: the language of all strings in which the number of a's is even
+  language: a, b
+  states:
+    A: a -> B, b -> A, accepting
+    B: a -> A, b -> B
+  strings:
+    a: invalid
+    aa: valid
+    aaa: invalid
+    baba: valid
+    bababa: invalid
+    bab: invalid
+    # As many other string combinations you'd like to test
+```
+
+You can then run:
+
+```bash
+fae -f example.yml
+```
+
+And the output would be the following:
+
+![Example Output](https://raw.githubusercontent.com/caseyscarborough/fae/master/etc/example_file_mode_output.png)
+
+## Interactive Mode
+
+Interactive mode is exactly what it sounds like, in which it will ask you questions about your diagram and evaluate it for you. This method is convenient, but if you'd like to check it again you will have to go back through the entire process.
+
+You can start interactive mode by executing:
+
+```bash
+fae -i
+```
+
+Here is an example output:
+
+![Example Output](https://raw.githubusercontent.com/caseyscarborough/fae/master/etc/example_interactive_mode_output.png)
+
+## Using the API
+
+You can also use the library directly if you'd rather run your own scripts. Here is an example usage:
+
+```rb
+require 'fae'
+
+characters = ['a', 'b']
+language = Fae::Language.new(characters)
+
+# A Finite Automata is created with a language and description.
+fa = Fae::FiniteAutomata.new(language, "The language of all strings containing at least two a's")
+
+fa.add_states([
+  # A new state is created with a name, a Hash of paths,
+  # and whether or not it is accepting. The hash of paths
+  # takes the letter as a key, and the next state as its value.
+  Fae::State.new('A', { :a => 'B', :b => 'A' }, false),
+  Fae::State.new('B', { :a => 'C', :b => 'B' }, false),
+  Fae::State.new('C', { :a => 'C', :b => 'C' }, true)
+])
+
+fa.add_strings([
+  # Strings are added with their value, and whether or
+  # not they should be valid for this Finite Automata.
+  String.new("a", false),
+  String.new("aa", true),
+  String.new("ba", false),
+  # ... as many strings as you'd like to test
+])
+
+# Run the evaluation
+fa.evaluate!
+```
+
+## When Your State Diagram is Incorrect
+
+If your state diagram is incorrect, the program will give you feedback about your diagram:
+
+![](https://raw.githubusercontent.com/caseyscarborough/fae/master/etc/example_failed_output.png)
+
+This can help you figure out where your diagram is going wrong.
+
+## Examples
+
+An example data file and direct API usage can be seen in the [examples directory](https://github.com/caseyscarborough/fae/tree/master/examples).
 
-TODO: Write usage instructions here
+The examples in the data file are taken from the Chapter 2 exercises in [Introduction to Languages and the Theory of Computation](http://www.amazon.com/Introduction-Languages-Theory-Computation-Martin/dp/0073191469).
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/fae/fork )
+1. Fork it ( https://github.com/caseyscarborough/fae/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/bin/fae

@@ -7,7 +7,12 @@ options = {}
 OptionParser.new do |opt|
   opt.banner = "Usage: fae [options]"
 
-  opt.on('-h', '--help', 'View this help menu') { puts opt; exit 0 }
+  help = lambda do |code|
+    puts opt
+    exit code
+  end
+
+  opt.on('-h', '--help', 'View this help menu') { help.call(0) }
   opt.on('-f FILENAME', '--file FILENAME', 'Evaluate a data file') { |o| options[:file] = o }
   opt.on('-v', '--version', 'Display the version number') { puts Fae::VERSION; exit 0 }
   opt.on('-i', '--interactive', 'Start interactive check') { options[:interactive] = true }
@@ -16,17 +21,20 @@ OptionParser.new do |opt|
     opt.parse!
   rescue OptionParser::InvalidOption => e
     puts e.message
-    puts opt
-    exit 1
+    help.call(1)
   rescue OptionParser::MissingArgument => e
     puts e.message
-    puts opt
-    exit 1
+    help.call(1)
+  end
+
+  if (!options[:file] && !options[:interactive])
+    puts "You must specify an argument."
+    help.call(1)
   end
 end
 
 if (options[:file])
-  Fae.load_file(options[:file])
-else
-  Fae.interactive
+  Fae.file_mode(options[:file])
+elsif (options[:interactive])
+  Fae.interactive_mode
 end

data/examples/diagrams.yml

@@ -0,0 +1,47 @@
+- description: 2.1d - the language of all strings that begin or end with "aa" or "bb"
+  language: a, b
+  states:
+    A: a -> B, b -> D
+    B: a -> C, b -> G
+    C: a -> C, b -> C, accepting
+    D: a -> F, b -> E
+    E: a -> E, b -> E, accepting
+    F: a -> H, b -> G
+    G: a -> F, b -> I
+    H: b -> G, a -> H, accepting
+    I: a -> F, b -> I, accepting
+  strings:
+    a: invalid
+    aa: valid
+    aaa: valid
+    aaabbbbbba: valid
+    aabbabba: valid
+    bbabba: valid
+    babbbab: invalid
+    babbbabb: valid
+    abbabbba: invalid
+- description: 2.1f - the language of all strings with an even number of a's
+  language: a, b
+  states:
+    A: a -> B, b -> A, accepting
+    B: a -> A, b -> B
+  strings:
+    a: invalid
+    aa: valid
+    aaa: invalid
+    aaabbbbbbbba: valid
+- description: 2.1h - the language of all strings containing no more than one occurrence of the string "aa"
+  language: a, b
+  states:
+    A: a -> B, b -> A, accepting
+    B: a -> C, b -> A, accepting
+    C: a -> E, b -> D, accepting
+    D: a -> F, b -> D, accepting
+    E: a -> E, b -> E
+    F: a -> E, b -> D, accepting
+  strings:
+    a: valid
+    aa: valid
+    aaa: invalid
+    aaabbbbbbbba: invalid
+    aabbabbba: valid

data/examples/example.rb

@@ -0,0 +1,28 @@
+require_relative '../lib/fae'
+
+characters = ['a', 'b']
+language = Fae::Language.new(characters)
+
+# A Finite Automata is created with a language and description.
+fa = Fae::FiniteAutomata.new(language, "The language of all strings containing at least two a's")
+
+fa.add_states([
+  # A new state is created with a name, a Hash of paths,
+  # and whether or not it is accepting. The hash of paths
+  # takes the letter as a key, and the next state as its value.
+  Fae::State.new('A', { :a => 'B', :b => 'A' }, false),
+  Fae::State.new('B', { :a => 'C', :b => 'B' }, false),
+  Fae::State.new('C', { :a => 'C', :b => 'C' }, true)
+])
+
+fa.add_strings([
+  # Strings are added with their value, and whether or
+  # not they should be valid for this Finite Automata.
+  String.new("a", false),
+  String.new("aa", true),
+  String.new("ba", false),
+  # ... as many strings as you'd like to test
+])
+
+# Run the evaluation
+fa.evaluate!

data/fae.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["caseyscarborough@gmail.com"]
   spec.summary       = %q{Evaluates Finite Automata State Diagrams for correctness.}
   spec.description   = %q{}
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/caseyscarborough/fae"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/lib/fae.rb

@@ -10,8 +10,7 @@ require_relative 'fae/version'
 module Fae
 
   class << self
-
-    def load_file(filename)
+    def file_mode(filename)
       diagrams = nil
       begin
         diagrams = YAML.load_file(filename)
@@ -55,7 +54,7 @@ module Fae
       end
     end
 
-    def interactive
+    def interactive_mode
       states  = []
       strings = []
 

data/lib/fae/finite_automata.rb

@@ -1,5 +1,15 @@
 module Fae
+
+  # The main class that drives the Finite Automata evaluation.
+  #
+  # Takes in a language, states, and strings, and checks them
+  # to validate a state diagram.
   class FiniteAutomata
+    
+    # Initializes a new instance of the FiniteAutomata.
+    #
+    # @param language [Language] a language instance
+    # @param description [String] the description of the finite automata  
     def initialize(language, description)
       @states = []
       @strings = []
@@ -8,18 +18,27 @@ module Fae
       @description = description
     end
 
+    # Adds strings to check against when evaluating.
+    #
+    # @param strings [Array] an array of strings
     def add_strings(strings)
       strings.each do |string|
         @strings << string
       end
     end
 
+    # Adds strings to check against when evaluating.
+    #
+    # @param states [Array] an array of states
     def add_states(states)
       states.each do |state|
         add_state(state)
       end
     end
 
+    # Retrieves a state from this finite automata by name.
+    #
+    # @param name [String] the name of the state to find
     def get_state(name)
       retrieved_state = nil
       @states.each do |state|
@@ -34,6 +53,7 @@ module Fae
       return retrieved_state
     end
 
+    # Runs the evaluation on the finite automata.
     def evaluate!
       @invalids = []
       if (@states.length == 0)

data/lib/fae/language.rb

@@ -1,12 +1,20 @@
 module Fae
+
+  # A language described by any number of characters
   class Language
     attr_accessor :characters
 
+    # Creates a new language instance.
+    #
+    # @param characters [Array] an array of characters
     def initialize(characters)
       @characters = []
       @characters = characters.uniq
     end
 
+    # Checks if a string is valid for this language.
+    #
+    # @param string [String] the string to check
     def string_is_valid(string)
       # Use lookahead to check for valid string
       regex = "^(?=.*\\D)[#{@characters.join('|')}]+$"
@@ -17,6 +25,9 @@ module Fae
       return false
     end
 
+    # Adds a character to the language.
+    #
+    # @param char [String] the character to add
     def add_character(char)
       @characters << char
     end

data/lib/fae/state.rb

@@ -1,18 +1,31 @@
 module Fae
+
+  # A state in the state diagram.
   class State
     attr_accessor :name, :next_states, :valid
 
+    # Creates a new state instance.
+    #
+    # @param name [String] the state name, i.e.: "A"
+    # @param next_states [Hash] a hash of next states from this state
+    # @param valid [Boolean] whether or not this is an accepting state
+    # @example
+    #   State.new('A', { :a => 'B', :b => 'A' }, true)
     def initialize(name, next_states, valid)
       @name = name
       @next_states = next_states
       @valid = valid
     end
 
+    # Evaluates a string at this state, and passes it to the next state.
+    #
+    # @param string [String] the string to evaluate
+    # @param fa [FiniteAutomata] the finite automata that this state belongs to
     def evaluate(string, fa)
       if (string.first.empty?)
-        output = valid ? "valid".colorize(:green) : "invalid".colorize(:red)
+        output = @valid ? "valid".colorize(:green) : "invalid".colorize(:red)
         print "#{@name} (#{output}) "
-        return { :output => output, :valid => valid }
+        return { :output => output, :valid => @valid }
       end
       print "#{@name} #{'->'.colorize(:light_black)} "
       fa.get_state(next_states[string.first.to_sym]).evaluate(string.shift_left, fa)

data/lib/fae/version.rb

@@ -1,3 +1,3 @@
 module Fae
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fae
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Casey Scarborough
@@ -14,42 +14,42 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ~>
       - !ruby/object:Gem::Version
         version: '1.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: colorize
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: ''
@@ -60,12 +60,18 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
+- .gitignore
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - bin/fae
+- etc/example_failed_output.png
+- etc/example_file_mode_output.png
+- etc/example_interactive_mode_output.png
+- etc/example_state_diagram.png
+- examples/diagrams.yml
+- examples/example.rb
 - fae.gemspec
 - lib/fae.rb
 - lib/fae/finite_automata.rb
@@ -73,7 +79,7 @@ files:
 - lib/fae/state.rb
 - lib/fae/version.rb
 - lib/string.rb
-homepage: ''
+homepage: https://github.com/caseyscarborough/fae
 licenses:
 - MIT
 metadata: {}
@@ -83,12 +89,12 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []