automatic 12.3.0 → 12.3.1

data/doc/README

@@ -0,0 +1,488 @@
+automaticruby
+
+Name
+ Automatic Ruby - Ruby General Automation Framework
+
+Syntax
+$ automatic
+
+Specify the start of any recipe
+$ automatic -c <recipe>
+
+To view the version number
+$ automatic -v
+
+Description
+ This is a general-purpose automatic processing
+ruby framework which can extend the functionality
+by plug-ins.
+
+
+============
+Installation
+============
+
+[Stable]
+$ gem install automatic
+
+[Development]
+$ git clone git://github.com/id774/automaticruby.git
+
+
+ If the ruby 1.9, put following command.
+$ script/bootstrap
+
+ If the ruby 1.8, necessary to manually install the gems in the Gemfile.
+
+
+===========
+Get Started
+===========
+
+ To create of any recipe (see below).
+$ automatic -c your_recipe.yml
+
+ -c option to run with the manual. If there is no problem
+to automate, register it to cron.
+
+
+ This is the easy recipe to simply output blog's feed to
+only console. It can be used to check the operation of
+this software.
+$ automatic -c config/feed2console.yml
+
+
+=======
+Recipes
+=======
+
+ Automatic Ruby parses configuration file that was written
+in the form of YAML which including variety of information
+of associated plug-ins.
+
+ This YAML file is called "Recipe".
+
+ When you start automatic ruby without argument -c option,
+the config/default.yml is called. You can use -c option for
+specify a file name.
+
+[Example]
+$ automatic -c ~/recipes/your_recipe.yml
+
+
+=====================
+How to write a Recipe
+=====================
+
+ The Recipe has an implicit naming convention.
+
+[Syntax]
+
+plugins:
+  - module: MODULE_NAME
+    config:
+      VARIABLES
+
+
+ The following is a example.
+
+plugins:
+  - module: SubscriptionFeed
+    config:
+      feeds:
+        - http://reretlet.tumblr.com/rss
+
+  - module: StorePermalink
+    config:
+      db: tumblr.db
+
+  - module: FilterImage
+
+  - module: FilterTumblrResize
+
+  - module: StoreTargetLink
+    config:
+      path: /Users/yourname/Desktop/
+      interval: 1
+
+In the case of sample this recipe.
+1. Subscribe to RSS feeds of Tumblr by SubScriptionFeed.
+2. Save permalink to database by StorePermalink.
+3. Specify the URL of the image by FilterImage and FilterTumblrResize.
+4. Downloading image file of Tumblr by StoreTargetLink.
+
+
+Showing another example as follows.
+
+plugins:
+  - module: SubscriptionFeed
+    config:
+      feeds:
+        - http://example.com/rss2
+        - http://hogefuga.com/feed
+
+  - module: FilterIgnore
+    config:
+      link:
+        - hoge
+        - fuga
+
+  - module: StorePermalink
+    config:
+      db: permalink.db
+
+  - module: PublishHatenaBookmark
+    config:
+      username: your_hatena_id
+      password: your_password
+      interval: 5
+
+In the case of sample this recipe.
+1. Subscribe to 2 RSS feeds by SubScriptionFeed.
+2. Feed ignore the keyword by FilterIgnore.
+3. Save permalink to database by StorePermalink.
+4. Social Bookmarking by PublishHatenaBookmark.
+
+(Hatena Bookmark is a most popular social bookmark service
+in Japan.)
+
+
+These have been realized by a combination of plug-ins
+a series of processes.
+
+In this way, by simply writing to the recipe and
+configuration information for plug-ins, free processing can
+be achieved by a combination of multiple plug-ins.
+
+The possibility of infinite depending on the combination
+of plug-ins can be realized.
+
+All depending on whether you make a plug-in looks like!
+
+
+=======
+Plug-in
+=======
+
+Plug-ins from the plugins directory (see below) will be loaded.
+
+If ~ /.automatic/plugins exists, is loaded into them as well.
+
+Put your own plug-ins in your home directory.
+(How to make the plug-in will be described later.)
+
+You can automatically generate a sub-directory for your own plug-ins
+with the following command.
+
+$ automatic-config scaffold
+(For a description of automatic-config will be described later.)
+
+
+============================
+Directory and file structure
+============================
+.
+|
++-+ bin
+| |
+| +-- automatic
+| | The main file for run.
+| |
+| +-- automatic-config
+|   The tool for the auxiliary.
+|
++-+ config
+| |
+| +-- default.yml
+|   To describe the recipe information in the form of yaml.
+|   They called in the argument -c option of Automatic Ruby.
+|   If you write a new recipe, locate it in the config directory.
+|
+|
++-+ plugins
+| |
+| +-- subscription
+| | Plug-ins to subscribe to feeds.
+| |
+| +-- customfeed
+| | Plug-ins to generate a custom feed.
+| |
+| +-- filter
+| | Plug-ins to filter the information.
+| |
+| +-- store
+| | Plug-ins to store the information to internally.
+| |
+| +-- notify
+| | Plug-ins to notify the information.
+| |
+| +-- publish
+|   Plug-ins to send information to external.
+|
+| If you write a new plug-in, locate it in the plugins directory.
+|
+|
++-+ lib
+| |
+| +-- automatic.rb
+| | To the definition of automatic module.
+| |
+| +-+ automatic
+| | |
+| | +-- environment.rb
+| | | Read the environmental information.
+| | |
+| | +-- pipeline.rb
+| | | To use an object called a pipeline
+| | | sequentially processing plug-ins in recipes.
+| | |
+| | +-- feed_parser.rb
+| | | To parse the feed.
+| | |
+| | +-- log.rb
+| | | To output logs.
+| | |
+| | +-- recipe.rb
+| |   Read a recipes.
+| |
+| +-- config
+|
++-+ db
+| |
+| +-- permalink.db
+|   Have been collected in the plug-in Store::Permalink.
+|
++-+ script
+| |
+| +-- bootstrap
+|   To set the environment, such as bundle install.
+|   (Only more than ruby 1.9)
+|
++-- spec
+|   Directory for unit tests (Use RSpec).
+|
++-+ test
+| |
+| +-- integration
+|   Directory for the Integration Test.
+|
++-+ vendor
+| |
+| +-- gems
+|   Bundle installed gem packages.
+|
++---+ doc
+    |
+    +-- COPYING
+    | The license for this software.
+    |
+    +-- PLUGINS
+    | Documentation for plug-ins.
+    |
+    +-- README
+      This document.
+
+
+
+===========
+Development
+===========
+
+Repository
+https://github.com/id774/automaticruby
+
+Issues
+https://github.com/id774/automaticruby/issues
+
+RubyForge
+http://rubyforge.org/projects/automatic/
+
+CI
+http://id774.net/jenkins/
+
+
+===========
+How to Join
+===========
+
+1. Fork the repository.
+2. Write new plugin or existing code improvement.
+3. Send pull request!
+
+After that, we will give you the right to commit for a quick fix finely.
+
+
+===========
+Coding Rule
+===========
+
+2 tabs (Soft Tabs).
+Remove trailing spaces.
+Namespace and conventions, see the existing code.
+{} is recommended than do end (To avoid end end end,,).
+RDoc Header is written by creator of the file.
+Write tests with RSPec.
+Aim at 100% coverage.
+
+
+===================
+Automatic::Pipeline
+===================
+
+ This framework sequentially analyze a plug-ins on yaml recipe.
+At this time, pipeline passed instantance as an argument. And then,
+pipeline backs again as the return value.
+
+ Code is as follows.
+
+ pipeline = []
+ recipe.each_plugin { |plugin|
+   load_plugin(plugin.module)
+   klass = Automatic::Plugin.const_get(plugin.module)
+   pipeline = klass.new(plugin.config, pipeline).run
+ }
+
+ In this iteration, sequential processing can be realized.
+
+ This mechanism called "Automatic::Pipeline".
+
+
+
+=============================
+Implementation of the plug-in
+=============================
+
+ Plug-in is loaded by the constructor of YAML.load
+Class is recieved the array of hashes as the instance
+variable of pipelines object.
+
+Example implementation of the constructor that is recommended
+is as follows.
+
+def initialize(config, pipeline=[])
+  @config = config
+  @pipeline = pipeline
+end
+
+Run an instance method is called automatically. The return value
+is on the instance variable @pipeline. And then, be handed over
+to the next plug-in in the recipe.
+
+
+=========
+Unit Test
+=========
+
+Unit testing is performed in RSpec.
+
+Test of the plug-in, pass the pipeline which will be the argument,
+to check the return value.
+
+
+============
+Binding Test
+============
+
+To combine more than one recipe under the test/integration.
+Put the recipe for the binding test.
+
+Before you check-in to the repository, run following
+command with ruby 1.9.
+$ script/build
+
+By this, all RSpec tests and binding tests will be conducted.
+You can check-in to the repository after all test successed.
+Otherwise, CI will fail.
+
+
+======================
+Continuous Integration
+======================
+
+CI is performed in Jenkins.
+http://id774.net/jenkins/
+
+
+===========================
+Description of the plug-ins
+===========================
+
+See doc/PLUGINS.
+
+
+
+================
+automatic-config
+================
+
+automatic-config is the auxiliary tool.
+
+[Syntax]
+$ automatic-config
+ To view a list of sub-command.
+
+$ automatic-config scaffold
+ To generate a ~/.automatic directory in your home directory.
+
+$ automatic-config autodiscovery <url>
+ Return the URL of the feed of target detected by auto discovery.
+(ex.)
+$ automatic-config autodiscovery http://id774.net/blog
+["http://id774.net/blog/feed/", "http://id774.net/blog/comments/feed/"]
+
+$ automatic-config opmlparser <opml path>
+ To output the URLs to parse the OPML file.
+(ex.)
+$ automatic-config opmlparser opml.xml > feeds.txt
+
+$ automatic-config feedparser <url>
+ Return the contents to parse the feed.
+
+$ automatic-config log <level> <message>
+ To output log messages in the form of Automatic Ruby.
+
+
+
+==============
+Update History
+==============
+
+ See doc/ChangeLog.
+
+
+====
+TODO
+====
+
+ Refer to the issues of github
+ https://github.com/id774/automaticruby/issues
+
+
+===========
+Environment
+===========
+
+ ruby 1.8 or later
+
+
+The following packages depend on the gem.
+
+sqlite3
+activesupport
+hashie
+activerecord
+gcalapi
+xml-simple
+feedbag
+
+For more information, see Gemfile.
+
+
+=====
+Notes
+=====
+
+To avoid excessive scraping, use in the bounds of common sense.
+This software licensed under the GNU GENERAL PUBLIC LICENSE, Version 3.0.
+
+