Benny is happy to announce the release of lazyscript.rb  0.2.0

WARNING: this release is slightly incompatible to the initial release 0.1.0
(see changelog below)

Dear rubyists, 
 
please give it a try and let me hear what you think about it.

 == Overview
 LazyScript offers an easy way to create text / ncurses based applications
that are dealing with several interdependant parts
 and that may require input from a user (bascially selection of options and
input).

 Don't waste your time in dealing with user interaction for text / ncurses
based applications. Easily create dialogs with complex dependancies
 that are translateable, maintainable and extendible within minutes. Focus
on what your application should actually do.

 Your application will be divided into several "screens" that are shown to
the user. Each "screen" has a corresponding class
 (a subclass of "Screen") and an entry in a YAML config file, where is
defined what is shown on this screen.
 The options shown on a screen point to methods of the corresponding class
or to other screens.

 For often needed methods like "add", "delete" and "select" there are
helpers (see the documentation of the screen class).

 The resolution of the dependancies between the different screen classes are
resolved easily and transparently.
 If you need a selection from another screen in the actual  screen, simply
call "from(AnotherScreenClass)" and you are done.
 The selection is only done once and cached then (lazy evaluation).
 You might easily reset it with "reset(AnotherScreenClass)".

 If you have the rubygem ncurses installed you even get ncurses based
dialogs for free.

 == Minimal Example
 === Application
  require 'rubygems'
  require_gem 'lazyscript'
  load_config("myconfig.yaml")
  # define your screen classes here
  class MyScreen < Screen
    def lazy
      say("do nothing")
    end
  end
  # run your screen dialogs
  run()
 === Config file
  ---
  screens:
    "Minimal":
      class: Menu
                 options:
                         "go to MyScreen": MyScreen
         "MyScreen Area":
                 class: MyScreen
                 options:
                         "try to be lazy": lazy

 == More / Better Examples
 === Application
  require 'rubygems'
  require_gem 'lazyscript'

  # loads the config file, it will be created for you, if it doesn't exist
  load_config("myscript.yaml")

  # define the screen Database
  class Database < Screen
    # the path shown in the status bar (where we are in the dialogs).
    # the name of a currently chosen database appended to this path
    def path
      "database/"
    end

    # defines a hash of keys shown to select a certain database. the values
are the result you get
    def select
      {"database1" => "a", "database2" => "b", "database3" => "c"}
    end
  end

  # define the screen Schema
  class Schema < Screen
    # from(Database) forces a database to selected before we could deal with
a schema
    # this results in a dialog popping up to select a database from the list
above (see Database#select)
    # and return to the schema screen after a database was chosen
    # then the name of the chosen database is shown in the path followed by
a dot and the name of the currently chosen schema
    # (if there is one chosen). since we use lazy evaluation (see
lazyvalue.rb) the database is one asked one and then cached
    def path
      "#{from(Database)}."
    end

    # a method that requires some other input
    def special_question
      # see the gem "highline" for more infos of the syntax of "say" and
"ask" (it even works with ncurses)
      say("I want to ask you some questions:")
      age = ask("How old are you?")
      gender = ask("Are you male / female?", [:male, :female])
    end
  end

  # defines the screen Table
  class Table < Screen
    # here first the selection of a database is forced and after that the
selection of a schema (see Schema#path)
    def path
      "#{from(Database)}.#{from(Schema)}."
    end

    # here we use from(Database) and from(Schema) again to get the selected
ones or force a selection if they haven't been selected before
    # if you want to know more about how you may define from(SomeThing) or
to(SomeThing) yourself look at the gem "FaceToFace"
    def select
      db = from(Database)
      schema = from(Schema)
      hsh= {"table1" => "", "table2" => "", "table3" => ""}
    end

    # here an example how to use the add method to add a table
    def add()
      # force to rechoose database and scheme, even if they already have
been chosen
      reset(Database)
      reset(Schema)

      # get the new choices
      db = from(Database)
      schema = from(Schema)

      # here Screen#add is called. in the block you place your normal code.
      # if block return true, the action is concidered to be successful, if
it returns false as unsuccessful
      super() do |name|
        # name is the name for the new table entered by the user
        #say "added #{db}.#{schema}.#{name}"
        true
      end
    end

    # here an example how to use the delete method to delete a table
    def delete()
      # force the selection of the table that should be deleted
      table = from(Table)

      # call Screen#delete to ask if the table should be deleted. if the
response is "yes" then the block will
      # be executed, otherwise the table screen will be shown
      # if the block returns true, the deletion will be considered as
successful, if false then unsuccessful
      super(table) do
        # delete it
        true
      end
    end
  end

  # Don't forget to call "run" at the end or it will do nothing!
  run()



 === Config file
  - 'Menu' is the first screen shown when you start the application
  - 'options' specifies options shown on the screen. key is the text that
will be shown and value is either a method of the class or another screen
class
  - 'class' is the screen class to which the screen belongs
  NOTE that YAML style requires indentation of 2 spaces - no tabs!

  ---
  screens:
    "\n\n#-- Welcome to our little Example --#\n":
      class: Menu
                 options:
                         "database menu name": Database
        "schema admin": Schema
         "Database admin":
                 class: Database
                 options:
                         "go to schema menu": Schema
                         "table menu": Table
        "add a new database": add
        "remove a database": delete
    "Schema admin area":
           class: Schema
                 options:
                         "go to tables": Table
        "add a new schema": add
        "remove a schema": delete
        "select a schema": select

 == How may I change the texts?
 Look at the config file, there you may overwrite all default messages.

 You may even create a subhash "messages" for a certain screen in the config
file where you can define deviating messages "per screen".

 This way you could easily build up a multilanguage application:
 Take the locale from the shell environment (e.g. $LANG) and include the
appropriate config file:
  load_config("myapp_#{ENV['LANG']}.yaml"))
 There you define the translated texts and you may define even self defined
messages as long as they don't conflict
 with existing ones (all existing config entries are in your config file if
it has been created for you by lazyscript)

 == Hint for usage of the ncurses front end
 A simple paging mechanism is implement, if you have more items returning
from you select method than fit  on the screen, you
 may go through the pages with PGUP and PGDOWN.

 == Changelog

 === 0.2 (2006-04-02)
 makes the usage of lazyscript even easier and more flexible:
  - now there are no "modes", we are always dealing with screens
  - all texts are configurable, even the ones for methods and other screens
  - config file is more consistent concerning naming and structure
  - you might redefine the default messages even on a "per screen" level
  - definition of 'hidden_methods()' is no longer needed
  - now every option on a screen has to appear explictely in the config
file, this makes it more verbose but easier to understand and more flexible
  - only drawback: config file and lib are incompatible with 0.1. to upgrade
your application:
    replace "Mode" with "Screen" in the application, backup your old config
file and let lazyscript generate a new one for you. modify that one to your
needs
 === 0.1 (2006-03-29)
   - initial release

 == Where may I find a complete example?
 have a look at examples/example.rb

 == Bugs / Limitations
  - sometimes you have to select several times "quit" to really quit the
application
  - mouse and shortcuts in ncurses currently not supported

 == Future
  - the ncurses dialogs will have to be further refined
  - add some cmdparse hacks to allow direct usage of the modes without
dialogs
  - maybe even implement the dialogs in a GUI lib (with fallback to
textmode) and as webrick dialogs
    this would enable us to write applications that may run with any
interface without having to care about the interface

Project Website: http://rubyforge.org/projects/lazyscript/ 
Contact: linux / marcrenearns.de