@@ -65,6 +65,7 @@ overview you can consult for future reference: * coder.rb - Used by script/generate to write out Ruby code * ctcp.rb - CTCP support library * daemon.rb - Provides support for different kinds of IRC servers + * datamapper_hacks.rb - Some hacks to help DataMapper work with Autumn * foliater.rb - Instantiates and manages stems and leaves * formatting.rb - Provides support for different kinds of IRC client text formatting and colorization @@ -84,6 +85,7 @@ overview you can consult for future reference: * Rakefile - Contains the rake tasks used to control Autumn (see the "Tasks" section) * README - This file +* README.textile - Textile-formatted readme * resources/ - Data files used by Autumn * daemons/ - Data files describing different IRC server types * script/ - Helper scripts for controlling Autumn @@ -546,18 +548,21 @@ connection looks like: password: pass database: database_name +or, in a smaller syntax: + + connection_name: mysql://root@pass:localhost/database_name + If you are using the "sqlite3" adapter, the +database+ option is the path to the file where the data should be written (example: data/my_database.db). You can name your connection however you want, but you _should_ name it after either your leaf or your leaf subclass. (More on this below.) -You should also create <tt>DataMapper::Base</tt> subclasses for each of your -model objects. You can place them within your leaf's support directory. This -works almost exactly the same as the app/models directory in Rails. +You should also create DataMapper model classes for each of your model objects. +You can place them within your leaf's models directory. This works almost +exactly the same as the app/models directory in Rails. Once your database, data models, and leaves have been configured, you can use -the <tt>rake db:create</tt> and <tt>rake db:populate</tt> tasks to automatically -set up your database. +the <tt>rake db:migrate</tt> task to automatically populate your database. Now, unlike Rails, Autumn supports multiple database connections. Two leaves can use two different database connections, or share the same database connection. @@ -591,7 +596,7 @@ And you have a database connection for that leaf, named after the leaf's class: fortune_leaf: adapter: sqlite3 - database: data/fortune.db + database: leaves/fortune_leaf/data/development.db Let's further assume you have a simple DataMapper object: @@ -610,7 +615,7 @@ this: end Autumn automatically knows to execute this DataMapper code in the correct -database context. It knows this because your leaf's name is FortuneLeaf, and +database context. It knows this because your leaf's name is +FortuneLeaf+, and your database context is named the same. But what if you wanted to use that connection for other leaves too, so you named @@ -643,7 +648,7 @@ method like so: This will break -- why? Because the +ctcp_version_request+ method is in the realm of the Autumn::CTCP class, _not_ the Autumn::Leaf class. (You can see this by investigating the CTCP class docs; it shows you what methods you can -implement for CTCP support.) Basically, the CTCP class calls your method +implement for CTCP support.) Basically, the +CTCP+ class calls your method directly, giving the Autumn::Leaf class no chance to set up the database first. So to fix it, make a call to +database+ first: @@ -663,7 +668,7 @@ them will use some sort of DataMapper resource named +Channel+, or something similar. You can't define the class +Channel+ twice in two different ways, so how do you deal with this? -The answer is: it's already dealt with for you. Go ahead and define the class +The answer is: It's already dealt with for you. Go ahead and define the class twice. Or three times. The longer explanation is: Secretly, behind the scenes, all your leaf code is @@ -688,7 +693,7 @@ For instance, if your leaf's name is "Fortune", and you needed two helpers, a database helper and a network helper, you could create two modules named +DatabaseHelper+ and +NetworkHelper+. Any modules named in this fashion and placed in the helpers subdirectory will be loaded and appended to the -Fortune controller and its views automatically. +controller and its views automatically. === Debugging Your Leaf @@ -919,11 +924,8 @@ Application tasks: Database tasks: -* LEAF=[leaf name] rake db:create - Creates an empty database for the - leaf. -* LEAF=[leaf name] rake db:drop - Drops a leaf's database. -* LEAF=[leaf name] rake db:populate - Creates all the tables for a leaf, - as specified by the leaf's model objects (in its support directory). +* LEAF=[leaf name] rake db:migrate - Creates all the tables for a leaf, + as specified by the leaf's model objects. Documentation tasks: README @@ -63,6 +63,7 @@ overview you can consult for future reference: ** coder.rb - Used by script/generate to write out Ruby code ** ctcp.rb - CTCP support library ** daemon.rb - Provides support for different kinds of IRC servers +** datamapper_hacks.rb - Some hacks to help DataMapper work with Autumn ** foliater.rb - Instantiates and manages stems and leaves ** formatting.rb - Provides support for different kinds of IRC client text formatting and colorization @@ -81,7 +82,8 @@ overview you can consult for future reference: section) * Rakefile - Contains the rake tasks used to control Autumn (see the *Tasks* section) -* README - This file +* README - RDoc-formatted readme +* README.textile - This file * *resources/* - Data files used by Autumn ** *daemons/* - Data files describing different IRC server types * *script/* - Helper scripts for controlling Autumn @@ -162,10 +164,10 @@ def fortune_command(stem, sender, reply_to, msg) end </code></pre> -The @at_rand@ method is provided by Facets, so you'll need to add a @require -'facets/random'@ line at the top of your file. Our method returns a fortune at -random, which is automatically transmitted to the channel or nick where the -command was received. +The @at_rand@ method is provided by Facets, so you'll need to add a +<code>require 'facets/random'</code> line at the top of your file. Our method +returns a fortune at random, which is automatically transmitted to the channel +or nick where the command was received. Of course, any self-respecting fortune bot announces its presence when it starts up, so, in your @Controller@ class, override the @Autumn::Leaf#did_start_up@ @@ -558,18 +560,21 @@ connection_name: database: database_name </code></pre> +or, in a smaller syntax: + +<code>connection_name: mysql://root@pass:localhost/database_name</code> + If you are using the "sqlite3" adapter, the @database@ option is the path to the file where the data should be written (example: @data/my_database.db@). You can name your connection however you want, but you _should_ name it after either your leaf or your leaf subclass. (More on this below.) -You should also create @DataMapper::Base@ subclasses for each of your model -objects. You can place them within your leaf's <tt>support</tt> directory. This -works almost exactly the same as the <tt>app/models</tt> directory in Rails. +You should also create DataMapper model classes for each of your model objects. +You can place them within your leaf's <tt>models</tt> directory. This works +almost exactly the same as the <tt>app/models</tt> directory in Rails. Once your database, data models, and leaves have been configured, you can use -the @rake db:create@ and @rake db:populate@ tasks to automatically set up your -database. +the @rake db:migrate@ task to automatically populate your database. Now, unlike Rails, Autumn supports multiple database connections. Two leaves can use two different database connections, or share the same database connection. @@ -606,7 +611,7 @@ And you have a database connection for that leaf, named after the leaf's class: <pre><code> fortune_leaf: adapter: sqlite3 - database: data/fortune.db + database: leaves/fortune_leaf/data/development.db </code></pre> Let's further assume you have a simple DataMapper object: @@ -630,7 +635,7 @@ end </code></pre> Autumn automatically knows to execute this DataMapper code in the correct -database context. It knows this because your leaf's name is FortuneLeaf, and +database context. It knows this because your leaf's name is @FortuneLeaf@, and your database context is named the same. But what if you wanted to use that connection for other leaves too, so you named @@ -669,7 +674,7 @@ end This will break -- why? Because the @ctcp_version_request@ method is in the realm of the @Autumn::CTCP@ class, _not_ the @Autumn::Leaf@ class. (You can see this by investigating the CTCP class docs; it shows you what methods you can -implement for CTCP support.) Basically, the CTCP class calls your method +implement for CTCP support.) Basically, the @CTCP@ class calls your method directly, giving the @Autumn::Leaf@ class no chance to set up the database first. So to fix it, make a call to @database@ first: @@ -691,15 +696,15 @@ them will use some sort of DataMapper resource named @Channel@, or something similar. You can't define the class @Channel@ twice in two different ways, so how do you deal with this? -The answer is: it's already dealt with for you. Go ahead and define the class +The answer is: It's already dealt with for you. Go ahead and define the class twice. Or three times. The longer explanation is: Secretly, behind the scenes, *all your leaf code is being cleverly loaded into a module named after your leaf*. So, when, in your <tt>controller.rb</tt> code, it says @class Controller < Autumn::Leaf@, you should read it as @class MyLeafName::Controller < Autumn::Leaf@. When you define -your model with @class Channel@, it's really read as @class -MyLeafName::Channel@. +your model with @class Channel@, it's really read as <code>class +MyLeafName::Channel</code>. Don't worry about table names or associations or anything, either. Just go ahead and use it as if it weren't in a module. The <tt>libs/datamapper_hacks.rb</tt> @@ -716,7 +721,7 @@ For instance, if your leaf's name is "Fortune", and you needed two helpers, a database helper and a network helper, you could create two modules named @DatabaseHelper@ and @NetworkHelper@. Any modules named in this fashion and placed in the <tt>helpers</tt> subdirectory will be loaded and appended to the -Fortune controller and its views automatically. +controller and its views automatically. h3. Debugging Your Leaf @@ -964,9 +969,7 @@ Application tasks: Database tasks: -| @LEAF=[leaf name] rake db:create@ | Creates an empty database for the leaf. | -| @LEAF=[leaf name] rake db:drop@ | Drops a leaf's database. | -| @LEAF=[leaf name] rake db:populate@ | Creates all the tables for a leaf, as specified by the leaf's model objects (in its <tt>support</tt> directory). | +| @LEAF=[leaf name] rake db:migrate@ | Creates all the tables for a leaf, as specified by the leaf's model objects | Documentation tasks: README.textile @@ -629,7 +629,6 @@ module Autumn end logger.info "Reloaded" - return 0 #TODO end def leaf_name libs/leaf.rb 1bf60b404917d246f6e0a367938d9abe2fa9b54e Tim Morgan riscfuture@gmail.com http://github.com/RISCfuture/autumn/commit/0d2d62f194636961a1c7502eddf3ccb18c413795 0d2d62f194636961a1c7502eddf3ccb18c413795

2008-07-05T01:41:02-07:00

More documentation updates for Autumn 3 29421673e66910de460160a54719796c3f391347 Tim Morgan riscfuture@gmail.com