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: [email protected]