statemachine 1.2.0 → 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (141) hide show
  1. data/.gitignore +12 -0
  2. data/Gemfile +6 -0
  3. data/Gemfile.lock +12 -0
  4. data/Rakefile +21 -20
  5. data/doc/website/README +6 -0
  6. data/doc/website/config.yaml +2 -0
  7. data/doc/website/index.html +39 -0
  8. data/doc/website/src/default.css +110 -0
  9. data/doc/website/src/default.template +41 -0
  10. data/doc/website/src/documentation.page +45 -0
  11. data/doc/website/src/example.page +13 -0
  12. data/doc/website/src/example1.page +59 -0
  13. data/doc/website/src/example2.page +96 -0
  14. data/doc/website/src/example3.page +76 -0
  15. data/doc/website/src/example4.page +65 -0
  16. data/doc/website/src/images/8l_star.png +0 -0
  17. data/doc/website/src/images/bg.png +0 -0
  18. data/doc/website/src/images/bottom_border.png +0 -0
  19. data/doc/website/src/images/bottom_edge.png +0 -0
  20. data/doc/website/src/images/examples/vending_machine.png +0 -0
  21. data/doc/website/src/images/examples/vending_machine2.png +0 -0
  22. data/doc/website/src/images/examples/vending_machine3.png +0 -0
  23. data/doc/website/src/images/examples/vending_machine4a.png +0 -0
  24. data/doc/website/src/images/examples/vending_machine4b.png +0 -0
  25. data/doc/website/src/images/left_edge.png +0 -0
  26. data/doc/website/src/images/logo.png +0 -0
  27. data/doc/website/src/images/right_edge.png +0 -0
  28. data/doc/website/src/images/side_borders.png +0 -0
  29. data/doc/website/src/index.page +20 -0
  30. data/generate_tests/dot_graph/turnstile.rb +29 -0
  31. data/generate_tests/dot_graph/turnstile2.rb +48 -0
  32. data/generate_tests/java/turnstile.rb +54 -0
  33. data/generate_tests/java/turnstile2.rb +72 -0
  34. data/lib/statemachine/action_invokation.rb +0 -19
  35. data/lib/statemachine/version.rb +2 -2
  36. data/rails_plugin/README +183 -0
  37. data/rails_plugin/Rakefile +11 -0
  38. data/rails_plugin/app/controllers/admin_controller.rb +43 -0
  39. data/rails_plugin/app/controllers/application.rb +7 -0
  40. data/rails_plugin/app/controllers/main_controller.rb +34 -0
  41. data/rails_plugin/app/helpers/admin_helper.rb +2 -0
  42. data/rails_plugin/app/helpers/application_helper.rb +3 -0
  43. data/rails_plugin/app/helpers/main_helper.rb +7 -0
  44. data/rails_plugin/app/models/product.rb +21 -0
  45. data/rails_plugin/app/models/vending_machine.rb +36 -0
  46. data/rails_plugin/app/models/vending_machine_interface.rb +101 -0
  47. data/rails_plugin/app/models/vending_statemachine.rb +41 -0
  48. data/rails_plugin/app/views/admin/index.rhtml +45 -0
  49. data/rails_plugin/app/views/layouts/main.rhtml +12 -0
  50. data/rails_plugin/app/views/main/_info.rhtml +13 -0
  51. data/rails_plugin/app/views/main/event.rjs +27 -0
  52. data/rails_plugin/app/views/main/index.rhtml +38 -0
  53. data/rails_plugin/config/boot.rb +45 -0
  54. data/rails_plugin/config/database.yml +21 -0
  55. data/rails_plugin/config/environment.rb +60 -0
  56. data/rails_plugin/config/environments/development.rb +21 -0
  57. data/rails_plugin/config/environments/production.rb +18 -0
  58. data/rails_plugin/config/environments/test.rb +19 -0
  59. data/rails_plugin/config/routes.rb +23 -0
  60. data/rails_plugin/db/migrate/001_create_vending_machines.rb +12 -0
  61. data/rails_plugin/db/migrate/002_create_products.rb +14 -0
  62. data/rails_plugin/db/migrate/003_add_position_to_products.rb +9 -0
  63. data/rails_plugin/db/schema.rb +20 -0
  64. data/rails_plugin/doc/README_FOR_APP +2 -0
  65. data/rails_plugin/lib/tasks/base.rake +5 -0
  66. data/rails_plugin/public/.htaccess +40 -0
  67. data/rails_plugin/public/404.html +30 -0
  68. data/rails_plugin/public/500.html +30 -0
  69. data/rails_plugin/public/dispatch.cgi +10 -0
  70. data/rails_plugin/public/dispatch.fcgi +24 -0
  71. data/rails_plugin/public/dispatch.rb +10 -0
  72. data/rails_plugin/public/favicon.ico +0 -0
  73. data/rails_plugin/public/images/bricks.jpg +0 -0
  74. data/rails_plugin/public/images/cash_release_button.png +0 -0
  75. data/rails_plugin/public/images/change.png +0 -0
  76. data/rails_plugin/public/images/dime.png +0 -0
  77. data/rails_plugin/public/images/dollar.png +0 -0
  78. data/rails_plugin/public/images/money_panel.png +0 -0
  79. data/rails_plugin/public/images/nickel.png +0 -0
  80. data/rails_plugin/public/images/quarter.png +0 -0
  81. data/rails_plugin/public/images/rails.png +0 -0
  82. data/rails_plugin/public/images/vending_machine_body.png +0 -0
  83. data/rails_plugin/public/index.html +277 -0
  84. data/rails_plugin/public/javascripts/application.js +2 -0
  85. data/rails_plugin/public/javascripts/controls.js +833 -0
  86. data/rails_plugin/public/javascripts/dragdrop.js +942 -0
  87. data/rails_plugin/public/javascripts/effects.js +1088 -0
  88. data/rails_plugin/public/javascripts/prototype.js +2515 -0
  89. data/rails_plugin/public/robots.txt +1 -0
  90. data/rails_plugin/public/stylesheets/layout.css +163 -0
  91. data/rails_plugin/script/about +3 -0
  92. data/rails_plugin/script/breakpointer +3 -0
  93. data/rails_plugin/script/console +3 -0
  94. data/rails_plugin/script/destroy +3 -0
  95. data/rails_plugin/script/generate +3 -0
  96. data/rails_plugin/script/performance/benchmarker +3 -0
  97. data/rails_plugin/script/performance/profiler +3 -0
  98. data/rails_plugin/script/plugin +3 -0
  99. data/rails_plugin/script/process/inspector +3 -0
  100. data/rails_plugin/script/process/reaper +3 -0
  101. data/rails_plugin/script/process/spawner +3 -0
  102. data/rails_plugin/script/rails_spec +11 -0
  103. data/rails_plugin/script/rails_spec_server +43 -0
  104. data/rails_plugin/script/runner +3 -0
  105. data/rails_plugin/script/server +3 -0
  106. data/rails_plugin/spec/controllers/admin_controller_spec.rb +7 -0
  107. data/rails_plugin/spec/controllers/main_controller_spec.rb +38 -0
  108. data/rails_plugin/spec/fixtures/products.yml +2 -0
  109. data/rails_plugin/spec/fixtures/vending_machines.yml +2 -0
  110. data/rails_plugin/spec/helpers/admin_helper_spec.rb +5 -0
  111. data/rails_plugin/spec/helpers/main_helper_spec.rb +5 -0
  112. data/rails_plugin/spec/models/product_spec.rb +16 -0
  113. data/rails_plugin/spec/models/vending_machine_interface_spec.rb +168 -0
  114. data/rails_plugin/spec/models/vending_machine_spec.rb +30 -0
  115. data/rails_plugin/spec/models/vending_statemachine_spec.rb +130 -0
  116. data/rails_plugin/spec/plugins/context_support_spec.rb +28 -0
  117. data/rails_plugin/spec/plugins/controller_support_spec.rb +98 -0
  118. data/rails_plugin/spec/spec.opts +1 -0
  119. data/rails_plugin/spec/spec_helper.rb +28 -0
  120. data/rails_plugin/spec/views/main/event_spec.rb +61 -0
  121. data/rails_plugin/vendor/plugins/statemachine/README +4 -0
  122. data/rails_plugin/vendor/plugins/statemachine/Rakefile +22 -0
  123. data/rails_plugin/vendor/plugins/statemachine/init.rb +2 -0
  124. data/rails_plugin/vendor/plugins/statemachine/install.rb +1 -0
  125. data/rails_plugin/vendor/plugins/statemachine/lib/context_support.rb +22 -0
  126. data/rails_plugin/vendor/plugins/statemachine/lib/controller_support.rb +85 -0
  127. data/rails_plugin/vendor/plugins/statemachine/lib/statemachine_on_rails.rb +11 -0
  128. data/rails_plugin/vendor/plugins/statemachine/tasks/statemachine_tasks.rake +4 -0
  129. data/spec/action_invokation_spec.rb +1 -1
  130. data/spec/builder_spec.rb +1 -1
  131. data/spec/default_transition_spec.rb +1 -1
  132. data/spec/generate/dot_graph/dot_graph_stagemachine_spec.rb +1 -1
  133. data/spec/history_spec.rb +1 -1
  134. data/spec/sm_action_parameterization_spec.rb +1 -1
  135. data/spec/sm_entry_exit_actions_spec.rb +1 -1
  136. data/spec/sm_odds_n_ends_spec.rb +1 -1
  137. data/spec/sm_simple_spec.rb +1 -1
  138. data/spec/sm_super_state_spec.rb +1 -1
  139. data/spec/sm_turnstile_spec.rb +1 -1
  140. data/spec/transition_spec.rb +1 -1
  141. metadata +162 -46
@@ -0,0 +1,76 @@
1
+ ---
2
+ title: Statemachine Example 3
3
+ inMenu: true
4
+ directoryName:
5
+ ---
6
+ <h2>Conditional Logic</h2>
7
+
8
+ Out vending machine is a good example of when we may need conditional logic. When ever a coin is inserted, the invoked event will depend on whether the total amount of money inserted is sufficient to buy something. If enough money has been tendered, the display should suggest that the customer make a selection. If insufficient money has been inserted, the customer should be prompted to insert more.
9
+
10
+ Conditional logic can be accomplished by using <b>entry actions</b>. See the diagram below.
11
+
12
+ <img style="border: 1px solid black" src="images/examples/vending_machine3.png">
13
+ <br><b>State Diagram with Conditional Logic</b>
14
+
15
+ Starting in the Accept Money state, when a coin is inserted, the coin event is fired and the statemachine transitions into the Coin Inserted state. This is where it gets fun. Upon entering of the Coin Inserted state its entry event is invoked: count_amount_tendered. This method will count the money and invoke the not_paid_yet or paid event accordingly. This will cause the statemachine to transition into the appropriate state.
16
+
17
+ The Coin Inserted state is unique. You wouldn’t expect to find the statemachine in the Coin Inserted state for any reason except to make this decision. Once the decision is made, the state changes. States like this are called <b>Decision States</b>.
18
+
19
+ <h2>Code</h2>
20
+
21
+ <pre>require 'rubygems'
22
+ require 'statemachine'
23
+
24
+ class VendingMachineContext
25
+
26
+ attr_accessor :statemachine
27
+
28
+ def initialize
29
+ @amount_tendered = 0
30
+ end
31
+
32
+ def add_coin
33
+ @amount_tendered = @amount_tendered + 25
34
+ end
35
+
36
+ def count_amount_tendered
37
+ if @amount_tendered >= 100
38
+ @statemachine.paid
39
+ else
40
+ @statemachine.not_paid_yet
41
+ end
42
+ end
43
+
44
+ def prompt_money
45
+ puts "$.#{@amount_tendered}: more money please"
46
+ end
47
+
48
+ def prompt_selection
49
+ puts "please make a selection"
50
+ end
51
+ end
52
+
53
+ vending_machine = Statemachine.build do
54
+ trans :accept_money, :coin, :coin_inserted, :add_coin
55
+ state :coin_inserted do
56
+ event :not_paid_yet, :accept_money, :prompt_money
57
+ event :paid, :await_selection, :prompt_selection
58
+ on_entry :count_amount_tendered
59
+ end
60
+ context VendingMachineContext.new
61
+ end
62
+ vending_machine.context.statemachine = vending_machine
63
+
64
+ vending_machine.coin
65
+ vending_machine.coin
66
+ vending_machine.coin
67
+ vending_machine.coin</pre>
68
+
69
+ Output:
70
+
71
+ <pre>$.25: more money please
72
+ $.50: more money please
73
+ $.75: more money please
74
+ please make a selection</pre>
75
+
76
+ Moving on to <a href="example4.html">Example 4</a>, we will begin to deal with superstates.
@@ -0,0 +1,65 @@
1
+ ---
2
+ title: Statemachine Example 4
3
+ inMenu: true
4
+ directoryName:
5
+ ---
6
+ <h2>Superstates</h2>
7
+
8
+ Often in statemachines, duplication can arise. For example, the vending machine in our examples may need periodic repairs. It’s not certain which state the vending machine will be in when the repair man arrives. So all states should have a transition into the Repair Mode state.
9
+
10
+ <img style="border: 1px solid black" src="images/examples/vending_machine4b.png">
11
+ <br><b>Diagram 1 - Without Superstates</b>
12
+
13
+ In this diagram, both the Waiting and Paid states have a transition to the Repair Mode invoked by the repair event. Duplication! We can dry this up by using the <b>Superstate</b> construct. See below:
14
+
15
+ <img style="border: 1px solid black" src="images/examples/vending_machine4a.png">
16
+ <br><b>Diagram 2 - With Superstates</b>
17
+
18
+ Here we introduce the Operational superstate. Both the Waiting and Paid states are contained within the superstate which implies that they inherit all of the superstate’s transitions. That means we only need one transition into the Repair Mode state from the Operational superstate to achieve the same behavior as the solution in <i>diagram 1</i>.
19
+
20
+ One statemachine may have multiple superstates. And every superstate may contain other superstates. ie. Superstates can be nested.
21
+
22
+ <h2>History State</h2>
23
+
24
+ The solution in <i>diagram 2</i> has an advantage over <i>diagram 1</i>. In <i>diagram 1</i>, once the repair man is done he triggers the operate event and the vending machine transitions into the Waiting event. This is unfortunate. Even if the vending machine was in the Paid state before the repair man came along, it will be in the Waiting state after he leaves. Shouldn’t it go back into the Paid state?
25
+
26
+ This is where use of the history state is useful. You can see the history state being use in <i>diagram 2</i>. In this solution, the history state allows the vending machine to return from a repair session into the same state it was in before, as though nothing happened at all.
27
+
28
+ <h2>Code</h2>
29
+
30
+ The following code builds the statemachine in <i>diagram 2</i>. Watch out for the _H. This is how the history state is denoted. If you have a superstate named foo, then it’s history state will be named foo_H.
31
+
32
+ <pre>require 'rubygems'
33
+ require 'statemachine'
34
+
35
+ vending_machine = Statemachine.build do
36
+ superstate :operational do
37
+ trans :waiting, :dollar, :paid
38
+ trans :paid, :selection, :waiting
39
+ trans :waiting, :selection, :waiting
40
+ trans :paid, :dollar, :paid
41
+
42
+ event :repair, :repair_mode, Proc.new { puts "Entering Repair Mode" }
43
+ end
44
+
45
+ trans :repair_mode, :operate, :operational_H, Proc.new { puts "Exiting Repair Mode" }
46
+
47
+ on_entry_of :waiting, Proc.new { puts "Entering Waiting State" }
48
+ on_entry_of :paid, Proc.new { puts "Entering Paid State" }
49
+ end
50
+
51
+ vending_machine.repair
52
+ vending_machine.operate
53
+ vending_machine.dollar
54
+ vending_machine.repair
55
+ vending_machine.operate</pre>
56
+
57
+ Output:
58
+
59
+ <pre>Entering Repair Mode
60
+ Exiting Repair Mode
61
+ Entering Waiting State
62
+ Entering Paid State
63
+ Entering Repair Mode
64
+ Exiting Repair Mode
65
+ Entering Paid State</pre>
@@ -0,0 +1,20 @@
1
+ ---
2
+ title: Statemachine Overview
3
+ inMenu: true
4
+ directoryName:
5
+ ---
6
+ The Statemachine library is a simple yet full-featured Finite Statemachine framework. Define your statemachine in Ruby code and execute it in your system.
7
+
8
+ <h2>Download and Installation</h2>
9
+
10
+ To download the package or source code visit the Statemachine <a href="http://rubyforge.org/projects/statemachine/">project page.</a> For the Statemachine gem:
11
+
12
+ <pre> > sudo gem install statemachine</pre>
13
+ or just
14
+ <pre> > gem install statemachine</pre>
15
+
16
+ <h2>Documentation</h2>
17
+
18
+ * <a href="documentation.html">Full descriptive documentation</a>
19
+ * <a href="http://slagyr.github.com/statemachine/rdoc/index.html">RDoc API</a>
20
+ * <a href="http://blog.8thlight.com/articles/2006/11/17/understanding-statemachines-part-1-states-and-transitions">Helpful tutorial</a> describing what Statemachine are and how to implement them using the statemachine library.
@@ -0,0 +1,29 @@
1
+ $: << File.expand_path(File.dirname(__FILE__) + "/../../lib")
2
+ require 'statemachine'
3
+ require 'statemachine/generate/dot_graph'
4
+ @output = File.expand_path(File.dirname(__FILE__) + "/turnstile")
5
+
6
+ def clean
7
+ class_files = Dir.glob("#{@output}/*.dot")
8
+ class_files.each { |file| system "rm #{file}" }
9
+ end
10
+
11
+ def generate
12
+ @sm = Statemachine.build do
13
+ trans :locked, :coin, :unlocked, :unlock
14
+ trans :unlocked, :pass, :locked, :lock
15
+ trans :locked, :pass, :locked, :alarm
16
+ trans :unlocked, :coin, :locked, :thanks
17
+ end
18
+ @sm.to_dot(:output => @output)
19
+ end
20
+
21
+ def open
22
+ `open #{@output}/main.dot`
23
+ end
24
+
25
+ clean
26
+ generate
27
+ open
28
+
29
+
@@ -0,0 +1,48 @@
1
+ $: << File.expand_path(File.dirname(__FILE__) + "/../../lib")
2
+ require 'statemachine'
3
+ require 'statemachine/generate/dot_graph'
4
+ @output = File.expand_path(File.dirname(__FILE__) + "/turnstile2")
5
+
6
+ def clean
7
+ class_files = Dir.glob("#{@output}/*.dot")
8
+ class_files.each { |file| system "rm #{file}" }
9
+ end
10
+
11
+ def generate
12
+ @sm = Statemachine.build do
13
+ superstate :operational do
14
+ on_entry :operate
15
+ on_exit :beep
16
+ state :locked do
17
+ on_entry :lock
18
+ event :coin, :unlocked
19
+ event :pass, :locked, :alarm
20
+ end
21
+ state :unlocked do
22
+ on_entry :unlock
23
+ event :coin, :unlocked, :thanks
24
+ event :pass, :locked
25
+ end
26
+ event :diagnose, :diagnostics
27
+ end
28
+ state :diagnostics do
29
+ on_entry :disable
30
+ on_exit :beep
31
+ event :operate, :operational
32
+ end
33
+ stub_context :verbose => false
34
+ end
35
+
36
+ @sm.to_dot(:output => @output)
37
+ end
38
+
39
+ def open
40
+ `open #{@output}/main.dot`
41
+ end
42
+
43
+
44
+ clean
45
+ generate
46
+ open
47
+
48
+
@@ -0,0 +1,54 @@
1
+ $: << File.expand_path(File.dirname(__FILE__) + "/../../lib")
2
+ require 'statemachine'
3
+ require 'statemachine/generate/java'
4
+ @output = File.expand_path(File.dirname(__FILE__) + "/turnstile")
5
+
6
+ def clean
7
+ system "rm -rf #{@output}/java"
8
+ class_files = Dir.glob("#{@output}/*.class")
9
+ class_files.each { |file| system "rm #{file}" }
10
+ system "rm #{@output}/output.txt"
11
+ end
12
+
13
+ def generate
14
+ @sm = Statemachine.build do
15
+ trans :locked, :coin, :unlocked, :unlock
16
+ trans :unlocked, :pass, :locked, :lock
17
+ trans :locked, :pass, :locked, :alarm
18
+ trans :unlocked, :coin, :locked, :thanks
19
+ end
20
+ @sm.to_java(:output => @output, :name => "JavaTurnstile", :package => "thejava.turnstile")
21
+ end
22
+
23
+ def compile
24
+ java_files = Dir.glob("#{@output}/**/*.java")
25
+ command = "javac #{java_files.join(' ')}"
26
+ system command
27
+ end
28
+
29
+ def run
30
+ system "java -cp #{@output} TurnstileMain > #{@output}/output.txt"
31
+ end
32
+
33
+ def check
34
+ actual = IO.read("#{@output}/output.txt").strip.split("\n")
35
+ expected = %w{alarm unlock thanks unlock lock}
36
+
37
+ if actual == expected
38
+ puts "PASSED"
39
+ else
40
+ puts "FAILED"
41
+ puts "--------------- expected:"
42
+ puts expected
43
+ puts "--------------- actual:"
44
+ puts actual
45
+ end
46
+ end
47
+
48
+ clean
49
+ generate
50
+ compile
51
+ run
52
+ check
53
+
54
+
@@ -0,0 +1,72 @@
1
+ $: << File.expand_path(File.dirname(__FILE__) + "/../../lib")
2
+ require 'statemachine'
3
+ require 'statemachine/generate/java'
4
+ @output = File.expand_path(File.dirname(__FILE__) + "/turnstile2")
5
+
6
+ def clean
7
+ system "rm -rf #{@output}/java"
8
+ class_files = Dir.glob("#{@output}/*.class")
9
+ class_files.each { |file| system "rm #{file}" }
10
+ system "rm #{@output}/output.txt"
11
+ end
12
+
13
+ def generate
14
+ @sm = Statemachine.build do
15
+ superstate :operational do
16
+ on_entry :operate
17
+ on_exit :beep
18
+ state :locked do
19
+ on_entry :lock
20
+ event :coin, :unlocked
21
+ event :pass, :locked, :alarm
22
+ end
23
+ state :unlocked do
24
+ on_entry :unlock
25
+ event :coin, :unlocked, :thanks
26
+ event :pass, :locked
27
+ end
28
+ event :diagnose, :diagnostics
29
+ end
30
+ state :diagnostics do
31
+ on_entry :disable
32
+ on_exit :beep
33
+ event :operate, :operational
34
+ end
35
+ stub_context :verbose => false
36
+ end
37
+
38
+ @sm.to_java(:output => @output, :name => "JavaTurnstile", :package => "thejava.turnstile")
39
+ end
40
+
41
+ def compile
42
+ java_files = Dir.glob("#{@output}/**/*.java")
43
+ command = "javac #{java_files.join(' ')}"
44
+ system command
45
+ end
46
+
47
+ def run
48
+ system "java -cp #{@output} Turnstile2Main > #{@output}/output.txt"
49
+ end
50
+
51
+ def check
52
+ actual = IO.read("#{@output}/output.txt").strip.split("\n")
53
+ expected = %w{operate lock alarm unlock thanks lock beep disable beep operate lock unlock lock}
54
+
55
+ if actual == expected
56
+ puts "PASSED"
57
+ else
58
+ puts "FAILED"
59
+ puts "--------------- expected:"
60
+ puts expected
61
+ puts "--------------- actual:"
62
+ puts actual
63
+ end
64
+ end
65
+
66
+ clean
67
+ generate
68
+ compile
69
+ run
70
+ check
71
+
72
+
@@ -43,22 +43,3 @@ module Statemachine
43
43
  end
44
44
 
45
45
  end
46
-
47
- class Object
48
-
49
- module InstanceExecHelper; end
50
-
51
- include InstanceExecHelper
52
-
53
- def instance_exec(*args, &block) # !> method redefined; discarding old instance_exec
54
- mname = "__instance_exec_#{Thread.current.object_id.abs}_#{object_id.abs}"
55
- InstanceExecHelper.module_eval{ define_method(mname, &block) }
56
- begin
57
- ret = send(mname, *args)
58
- ensure
59
- InstanceExecHelper.module_eval{ undef_method(mname) } rescue nil
60
- end
61
- ret
62
- end
63
-
64
- end
@@ -1,8 +1,8 @@
1
1
  module Statemachine
2
2
  module VERSION #:nodoc:
3
3
  unless defined? MAJOR
4
- MAJOR = 1
5
- MINOR = 2
4
+ MAJOR = 2
5
+ MINOR = 0
6
6
  TINY = 0
7
7
 
8
8
  STRING = [MAJOR, MINOR, TINY].join('.')
@@ -0,0 +1,183 @@
1
+ == Welcome to Rails
2
+
3
+ Rails is a web-application and persistence framework that includes everything
4
+ needed to create database-backed web-applications according to the
5
+ Model-View-Control pattern of separation. This pattern splits the view (also
6
+ called the presentation) into "dumb" templates that are primarily responsible
7
+ for inserting pre-built data in between HTML tags. The model contains the
8
+ "smart" domain objects (such as Account, Product, Person, Post) that holds all
9
+ the business logic and knows how to persist themselves to a database. The
10
+ controller handles the incoming requests (such as Save New Account, Update
11
+ Product, Show Post) by manipulating the model and directing data to the view.
12
+
13
+ In Rails, the model is handled by what's called an object-relational mapping
14
+ layer entitled Active Record. This layer allows you to present the data from
15
+ database rows as objects and embellish these data objects with business logic
16
+ methods. You can read more about Active Record in
17
+ link:files/vendor/rails/activerecord/README.html.
18
+
19
+ The controller and view are handled by the Action Pack, which handles both
20
+ layers by its two parts: Action View and Action Controller. These two layers
21
+ are bundled in a single package due to their heavy interdependence. This is
22
+ unlike the relationship between the Active Record and Action Pack that is much
23
+ more separate. Each of these packages can be used independently outside of
24
+ Rails. You can read more about Action Pack in
25
+ link:files/vendor/rails/actionpack/README.html.
26
+
27
+
28
+ == Getting started
29
+
30
+ 1. Start the web server: <tt>ruby script/server</tt> (run with --help for options)
31
+ 2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
32
+ 3. Follow the guidelines to start developing your application
33
+
34
+
35
+ == Web servers
36
+
37
+ Rails uses the built-in web server in Ruby called WEBrick by default, so you don't
38
+ have to install or configure anything to play around.
39
+
40
+ If you have lighttpd installed, though, it'll be used instead when running script/server.
41
+ It's considerably faster than WEBrick and suited for production use, but requires additional
42
+ installation and currently only works well on OS X/Unix (Windows users are encouraged
43
+ to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from
44
+ http://www.lighttpd.net.
45
+
46
+ If you want something that's halfway between WEBrick and lighttpd, we heartily recommend
47
+ Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that
48
+ also works very well with Windows. See more at http://mongrel.rubyforge.org/.
49
+
50
+ But of course its also possible to run Rails with the premiere open source web server Apache.
51
+ To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want
52
+ to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid.
53
+
54
+ See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI.
55
+
56
+ == Example for Apache conf
57
+
58
+ <VirtualHost *:80>
59
+ ServerName rails
60
+ DocumentRoot /path/application/public/
61
+ ErrorLog /path/application/log/server.log
62
+
63
+ <Directory /path/application/public/>
64
+ Options ExecCGI FollowSymLinks
65
+ AllowOverride all
66
+ Allow from all
67
+ Order allow,deny
68
+ </Directory>
69
+ </VirtualHost>
70
+
71
+ NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI
72
+ should be on and ".cgi" should respond. All requests from 127.0.0.1 go
73
+ through CGI, so no Apache restart is necessary for changes. All other requests
74
+ go through FCGI (or mod_ruby), which requires a restart to show changes.
75
+
76
+
77
+ == Debugging Rails
78
+
79
+ Have "tail -f" commands running on both the server.log, production.log, and
80
+ test.log files. Rails will automatically display debugging and runtime
81
+ information to these files. Debugging info will also be shown in the browser
82
+ on requests from 127.0.0.1.
83
+
84
+
85
+ == Breakpoints
86
+
87
+ Breakpoint support is available through the script/breakpointer client. This
88
+ means that you can break out of execution at any point in the code, investigate
89
+ and change the model, AND then resume execution! Example:
90
+
91
+ class WeblogController < ActionController::Base
92
+ def index
93
+ @posts = Post.find_all
94
+ breakpoint "Breaking out from the list"
95
+ end
96
+ end
97
+
98
+ So the controller will accept the action, run the first line, then present you
99
+ with a IRB prompt in the breakpointer window. Here you can do things like:
100
+
101
+ Executing breakpoint "Breaking out from the list" at .../webrick_server.rb:16 in 'breakpoint'
102
+
103
+ >> @posts.inspect
104
+ => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>,
105
+ #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
106
+ >> @posts.first.title = "hello from a breakpoint"
107
+ => "hello from a breakpoint"
108
+
109
+ ...and even better is that you can examine how your runtime objects actually work:
110
+
111
+ >> f = @posts.first
112
+ => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
113
+ >> f.
114
+ Display all 152 possibilities? (y or n)
115
+
116
+ Finally, when you're ready to resume execution, you press CTRL-D
117
+
118
+
119
+ == Console
120
+
121
+ You can interact with the domain model by starting the console through script/console.
122
+ Here you'll have all parts of the application configured, just like it is when the
123
+ application is running. You can inspect domain models, change values, and save to the
124
+ database. Starting the script without arguments will launch it in the development environment.
125
+ Passing an argument will specify a different environment, like <tt>script/console production</tt>.
126
+
127
+ To reload your controllers and models after launching the console run <tt>reload!</tt>
128
+
129
+
130
+
131
+ == Description of contents
132
+
133
+ app
134
+ Holds all the code that's specific to this particular application.
135
+
136
+ app/controllers
137
+ Holds controllers that should be named like weblog_controller.rb for
138
+ automated URL mapping. All controllers should descend from
139
+ ActionController::Base.
140
+
141
+ app/models
142
+ Holds models that should be named like post.rb.
143
+ Most models will descend from ActiveRecord::Base.
144
+
145
+ app/views
146
+ Holds the template files for the view that should be named like
147
+ weblog/index.rhtml for the WeblogController#index action. All views use eRuby
148
+ syntax. This directory can also be used to keep stylesheets, images, and so on
149
+ that can be symlinked to public.
150
+
151
+ app/helpers
152
+ Holds view helpers that should be named like weblog_helper.rb.
153
+
154
+ app/apis
155
+ Holds API classes for web services.
156
+
157
+ config
158
+ Configuration files for the Rails environment, the routing map, the database, and other dependencies.
159
+
160
+ components
161
+ Self-contained mini-applications that can bundle together controllers, models, and views.
162
+
163
+ db
164
+ Contains the database schema in schema.rb. db/migrate contains all
165
+ the sequence of Migrations for your schema.
166
+
167
+ lib
168
+ Application specific libraries. Basically, any kind of custom code that doesn't
169
+ belong under controllers, models, or helpers. This directory is in the load path.
170
+
171
+ public
172
+ The directory available for the web server. Contains subdirectories for images, stylesheets,
173
+ and javascripts. Also contains the dispatchers and the default HTML files.
174
+
175
+ script
176
+ Helper scripts for automation and generation.
177
+
178
+ test
179
+ Unit and functional tests along with fixtures.
180
+
181
+ vendor
182
+ External libraries that the application depends on. Also includes the plugins subdirectory.
183
+ This directory is in the load path.