[ANN] lazyscript 0.2.0

Discussion in 'Ruby' started by benny, Apr 2, 2006.

  1. benny

    benny Guest

    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:
     
    benny, Apr 2, 2006
    #1
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Mike Sampson [MSFT]

    [ANN]: NNTP Server slow downs.

    Mike Sampson [MSFT], Oct 7, 2003, in forum: ASP .Net
    Replies:
    0
    Views:
    417
    Mike Sampson [MSFT]
    Oct 7, 2003
  2. Mike Sampson [MSFT]

    [ANN]: NNTP Server slow downs.

    Mike Sampson [MSFT], Dec 6, 2003, in forum: ASP .Net
    Replies:
    0
    Views:
    502
    Mike Sampson [MSFT]
    Dec 6, 2003
  3. Richard Grimes [MVP]

    ANN: Free .NET Workshops

    Richard Grimes [MVP], Jul 4, 2005, in forum: ASP .Net
    Replies:
    0
    Views:
    506
    Richard Grimes [MVP]
    Jul 4, 2005
  4. Michael Livsey
    Replies:
    3
    Views:
    429
    Michael Livsey
    May 27, 2004
  5. benny

    [ANN] lazyscript 0.1.0

    benny, Mar 29, 2006, in forum: Ruby
    Replies:
    1
    Views:
    76
    benny
    Mar 29, 2006
Loading...

Share This Page