rsence-pre 2.1.0.1.pre

data/conf/rsence_command_strings.yaml

@@ -0,0 +1,444 @@
+# Strings for various methods
+:messages:
+  :invalid_option_expected_number: |+
+    Invalid option for <%%= option_name.to_s %>:
+      Expected number, got: <%%= arg.inspect %>.
+    
+    Type 'rsence help <%%= @cmd.to_s %>' for usage.
+  :no_such_configuration_file: |+
+    No such configuration file:
+      <%%= arg.inspect %>
+    
+    Type 'rsence help <%%= @cmd.to_s %>' for usage.
+  :no_value_for_option: |+
+    No value for option:
+      <%%= option_name.to_s.inspect %>
+    
+    Type 'rsence help <%%= @cmd.to_s %> for usage."
+  :no_such_directory: |
+    No such directory:
+      <%%= path.inspect %>
+  :not_a_directory: |
+    Not a directory:
+      <%%= path.inspect %>
+  :missing_conf_directory: |
+    Missing conf directory:
+      <%%= conf_path.inspect %>
+  :invalid_conf_directory: |
+    Not a conf directory:
+      <%%= conf_path.inspect %>
+  :missing_conf_file: |
+    Missing conf file:
+      <%%= conf_file.inspect %>
+  :invalid_conf_file_not_file: |
+    Invalid conf file, not a file:
+      <%%= conf_file.inspect %>
+  :warn_no_plugin_directory_in_project: |
+    Warning! No plugin directory in project, expected:
+      <%%= plugin_path.inspect %>
+  :plugin_directory_not_a_directory: |
+    Plugin directory not a directory, expected:
+      <%%= plugin_path.inspect %>
+  :warn_no_plugin_directory_in_project: |
+    Warning! No <%%= dir_name %> directory in project, creating:
+      <%%= dir_path.inspect %>
+  :invalid_environment: |
+    Invalid environment: <%%= env_path.inspect %>
+    
+    Type 'rsence help <%%= @cmd.to_s %>' for usage."
+    Type 'rsence help initenv' for environment initialization usage."
+  :invalid_option_chr: |
+    Invalid option character for option character block <%%= arg.inspect %>:
+      <%%= chr.inspect %>
+    
+    Type 'rsence help <%%= @cmd.to_s %>' for usage."
+  :invalid_option: |
+    Invalid option:
+      <%%= arg.inspect %>.
+    
+    Type 'rsence help <%%= @cmd.to_s %>' for usage."
+  :no_pid: |
+    No PID, unable to check process status.
+  :no_pid_file: |
+    No PID file, unable to check process status.
+  :no_pid_support: |
+    No PID support, unable to check process status.
+  :no_process_running_but_something_responds: |
+    No process running, but something responds on <%%= addr %>:<%%= port %>.
+  :no_process_running_and_nothing_responds: |
+    No process running, and nothing responds on <%%= addr %>:<%%= port %>.
+  :process_running_and_responds: |
+    Process ID <%%= pid %> is running and responds on <%%= addr %>:<%%= port %>.
+  :process_running_but_nothing_responds: |
+    Process ID <%%= pid %> is running, but does not respond on <%%= addr %>:<%%= port %>.
+  :saving_message: <
+    Saving session data...
+  :no_pid_unable_to_save: |
+    No PID, unable to signal the save command to the process.
+  :no_process_running: |
+    No process running.
+  :session_data_saved: |
+    Session data saved.
+# Strings for the initenv command
+:initenv:
+  :env_already_initialized: |
+    Environment already initialized.
+  :env_not_empty: |
+    Environment directory <%%= @args[:env_path] %> is not empty.
+  :creating_env: |+
+    
+    Creating a new RSence environment at <%%= @args[:env_path] %>
+    
+    RSence will first ask a few questions about your environment
+    in order to initialize and prepare the project configuration.
+    
+    You may abort this command at any time by pressing CTRL-C
+    Nothing will be written until you have answered all the questions.
+    
+    Pressing the ENTER (or RETURN) key at each prompt will choose the
+    default option shown.
+    If you are not sure about how to answer a question, press
+    the ENTER (or RETURN) key to continue.
+    
+  :enter_title: |+
+    
+     Please enter the title of your project.
+     This title will be used in the default page title.
+     
+  :project_title: Project Title
+  :enter_db_url: |+
+    
+    
+    
+     Please specify the connection string for the session database to use.
+     By default, a local SQLite database is created in the 'db' subdirectory
+     of the environment directory. Any database supported by Sequel is supported
+     by RSence.
+    
+     For further information about database connection strings, read the Sequel
+     documentation at:
+     http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html
+    
+     You will also need the appropriate ruby driver for the database selected. If
+     none is installed, RSence will not be able to store persistent session data
+     between server restarts.
+    
+  :db_url: Session database connection string
+  :enter_http_port: |+
+    
+    
+    
+     Please enter a HTTP port for the server to listen to. This port must not be a
+     TCP port already in use.
+     
+  :http_port: HTTP Port
+  :enter_tcp_ip: |+
+    
+    
+     Please enter a TCP/IP address for the HTTP server to listen to. This address 
+     must be an address configured by a network interface of this computer.
+    
+     The address 0.0.0.0 matches any interfaces.
+     The address 127.0.0.1 matches only the localhost address, this address is
+     not accessible from any other computer.
+     
+  :tcp_ip: Interface TCP/IP address
+  :enter_root_dir: |+
+    
+    
+     Please enter a root directory for RSence to respond in.
+     By default this is the root directory of the server: /
+     
+  :root_dir: URI Prefix
+  :config_summary: |+
+    
+    Configuration Summary
+    
+     Please verify that the configuration is correct.
+     This configuration will be written into the configuration file:
+       <%%= conf_file %>
+    
+    Title:       <%%= config[:index_html][:title] %>
+    
+    Database:    <%%= config[:database][:ses_db] %>
+    
+    HTTP Server:
+      Address:    <%%= config[:http_server][:bind_address] %>
+      Port:       <%%= config[:http_server][:port] %>
+      URI Prefix: <%%= config[:base_url] %>
+      
+      This means the URL will be <%%= test_url %>
+    
+  :confirm_config: "Is the configuration correct, "
+  :creating_dirs: "Creating directories..."
+  :installing_welcome_plugin: |+
+      Installing the welcome plugin. To remove it, just delete this folder:
+        <%%= welcome_plugin_dst %>
+  :creating_files: "Creating files..."
+  :congratulations: |+
+    
+    <%= '-='*39 %>-
+    
+    RSence project environment for '<%%= config[:index_html][:title] %>' created.
+    
+    You may configure the environment by editing the file:
+    
+      <%%= conf_file %>
+    
+    If you would like to test this environment now, start the RSence server:
+    
+      rsence run <%%= env_dir %>
+    
+    Then point your browser to:
+    
+      <%%= test_url %>
+    
+    The latest documentation and further information is available at the
+    RSence website:
+    
+      http://rsence.org/
+    
+    
+    Congratulations!
+    
+  :readme: |
+    This directory contains a RSence environment titled '<%%= config[:index_html][:title] %>'.
+    Visit http://rsence.org/ for further information.
+# Help for the 'rsence' command line tool.
+:help:
+  :head: |+
+    RSence command-line tool, version <%= @@version %>
+  
+  :tail: |+
+    RSence is a self-contained rich internet application client-server framework.
+    For further information, see http://rsence.org/
+  :unknown: >
+    Unknown command: 
+
+  :help_help: >
+    Type 'rsence help' for usage.
+
+  :help_main: |+
+    usage: rsence <command> [options] [args]
+  
+    Type 'rsence help <command>' for help on a specific command.
+  
+    Available commands:
+       <%= help_avail_cmds %>
+  
+  :path: |+
+    The [PATH] is the RSence environment to use.
+    The [PATH] defaults to the current working directory.
+  
+  :options: |+
+    Available options:
+  
+      --conf <file.yaml>      Use additional config file. You can give this option
+                              several times. The <file.yaml> is the configuration
+                              file to load.
+  
+      --debug (-d)            Debug mode. Shortcut for several options useful for
+                              developers. Not the preferred mode for production.
+  
+      --verbose (-v)          More verbose output. Also enabled by --debug
+  
+      --log-fg (-f)           Directs the output of the log messages to stdout
+                              instead of the log files. Useful for development.
+  
+      --trace-js              Logs all js/json going through the msg object.
+  
+      --trace-delegate        Logs all plugin delegate calls.
+  
+      --port <number>         The port number the http server listens to.
+  
+      --addr <ip address>     The IP address or net mask the http server listens to.
+                              '0.0.0.0' matches all interfaces.
+                              '127.0.0.1' matches the local loopback interface.
+  
+      --server <handler>      The Rack handler to use. Defaults to mongrel
+  
+      --reset-sessions (-r)   Resets all active sessions.
+  
+      --auto-update (-a)      Automatically checks for changes in installed plugin
+                              and component bundles. Rebuilds changed component
+                              bundles and reload changed plugin bundles.
+                              Useful for development purposes.
+                              Also enabled by --debug
+  
+      --latency <number>      Sleeps <number> amount of milliseconds on every
+                              request. Useful for testing slow connections.
+  
+      --say (-S)              Uses speech synthesis via the 'say' command to
+                              provide audible feedback, when --auto-update is
+                              enabled. Says 'Autobuild complete.',
+                              'Loaded [plugin name].', 'Unloaded [plugin name].',
+                              'Reloaded [plugin name].', 'Reloading plugins.' and
+                              'Plugins reloaded.'
+                              Only available on Mac OS X and other systems with a
+                              'say' command installed.
+  
+  :initenv: |+
+    usage: 'rsence initenv [options] [PATH]'
+  
+    The 'initenv' command creates a new RSence environment. 
+  
+    The expected structure of a project environment (where 'project_directory'
+    is the directory of your project) is:
+  
+     [d]  project_name       :  The name of your project.
+       [d]  conf             :  The directory of config files.
+         [f]  config.yaml    :  The config file to load by default.
+       [d]  db               :  Directory containing database files.
+       [d]  log              :  Directory containing log files.
+       [d]  plugins          :  Directory containing installed plugins.
+       [d]  run              :  Directory containing runtime pid files.
+       [f]  README           :  Description of the environment directory.
+       [f]  VERSION          :  RSence version the environment was created with
+  
+    The 'config.yaml' file contains patches specific to your project.
+  
+    The configuration files are loaded and applied in this order:
+      1:  [rsence_install_path]/conf/default_conf.yaml
+      2:  [rsence_install_path]/conf/local_conf.yaml
+      3:  /etc/rsence/config.yaml
+      4:  ~/.rsence/config.yaml
+      5:  [project_directory]/conf/config.yaml
+      6:  Any files given using --conf parameters, in order of occurrence.
+  
+    The plugins directory contains the plugins that are run in the project.
+  
+  
+    Available options:
+  
+      --port <number>         The port number the http server listens to.
+  
+      --addr <ip address>     The IP address or net mask the http server listens to.
+                              '0.0.0.0' matches all interfaces.
+                              '127.0.0.1' matches the local loopback interface.
+                              Defaults to 0.0.0.0
+  
+      --server <handler>      The Rack handler to use. Defaults to mongrel
+  
+      --title <title>         The title of the index page.
+  
+      --database <conn_str>   Use the Sequel connection string to configure the
+                              default session database.
+  
+      --uri-prefix <path>     Configure RSence to use this http "directory" as
+                              the prefix. It defaults to the root directory: /
+  
+      --blank                 Doesn't install the Welcome -plugin.
+  
+      --non-interactive (-q)  Doesn't ask anything, just creates the environment
+                              with the options supplied.
+                            
+    For further configuration, edit the config.yaml file.
+  
+  :run: |+
+    usage: 'rsence run [options] [PATH]'
+  
+    The 'run' command starts RSence in foreground (no daemon). Exit with CTRL-C.
+  
+  :start: |+
+    usage: 'rsence start [options] [PATH]'
+  
+    The 'start' command starts RSence in the background (as a daemon).
+  
+    Use the 'stop' command to stop RSence.
+  
+    Use the 'restart' command to restart RSence in the background.
+  
+    Use the 'status' command to see if RSence is running.
+  
+  :stop: |+
+    usage: 'rsence stop [options] [PATH]'
+  
+    The 'stop' command stops RSence running in the background (as a daemon).
+  
+    Use the 'status' command to see if RSence is running.
+  
+  :restart: |+
+    usage: 'rsence restart [options] [PATH]'
+  
+    The 'restart' command restarts RSence in the background (as a daemon).
+    If RSence wasn't running before the 'restart' command was issued, the
+    effect is the same as 'start'.
+  
+    Use the 'stop' command to stop RSence.
+  
+    Use the 'status' command to see if RSence is running.
+  
+  :status: |+
+    usage: 'rsence status [options] [PATH]'
+  
+    The 'status' command checks if RSence is running.
+    If started with the 'start', 'run' or 'restart' command, a PID file is written.
+    Status checks if the PID file exists, if the RSence process responds and if
+    the configured TCP port responds in the configured IP address.
+  
+    Available options:
+  
+      --conf <file.yaml>      Use additional config file. You can give this option
+                              several times. The <file.yaml> is the configuration
+                              file to load.
+    
+      --debug (-d)            Debug mode. Shortcut for several options useful for
+                              developers. Not the preferred mode for production.
+    
+      --verbose (-v)          More verbose output. Also enabled by --debug
+    
+      --port <number>         The port number the http server listens to.
+    
+      --addr <ip address>     The IP address or net mask the http server listens to.
+  
+  :save: |+
+    usage: 'rsence save [options] [PATH]'
+  
+    The 'save' command signals the RSence process to tell the plugins to save their
+    data and the session manager to save its session database.
+  
+    Available options:
+  
+      --conf <file.yaml>      Use additional config file. You can give this option
+                              several times. The <file.yaml> is the configuration
+                              file to load.
+    
+      --debug (-d)            Debug mode. Shortcut for several options useful for
+                              developers. Not the preferred mode for production.
+    
+      --verbose (-v)          More verbose output. Also enabled by --debug
+  
+  :version: |+
+    usage: 'rsence version'
+  
+    The 'version' command simply outputs the version number of RSence.
+  
+    RSence follows the standard four-numbered sequence-based version identification
+    scheme. The scheme is defined like: major.minor[.maintenance[.package]][.pre]
+  
+    The major number designates major changes in functionality, sometimes limiting
+    backwards compatibility with software written for previous versions.
+  
+    The minor number designates minor changes in functionality, like minor or
+    moderate changes in functionality that usually don't impact backwards
+    compatibilty of software written for a previous release with the same major
+    version.
+  
+    The maintenance number designates bug fixes and other minimal changes to
+    the release. In a maintenance number change, no new features are introduced.
+  
+    The package number is a sequence used for the package release. Rubygems
+    requires an unique version for each gem released, so pre-releases usually
+    occupy the first package numbers of any release.
+  
+    The '.pre' suffix signifies a pre-release, like "Alpha" or "Beta". To
+    install a prerelease version, gem requires the '--pre' command line argument.
+    Release versions never have the '.pre' suffix. There are usually several
+    package number increments of a new release.
+  
+    Version number conventions in written text should include both major and
+    minor version numbers prefixed with 'RSence'. The maintennance number
+    is usally not mentioned unless an issue is fix or such is discussed.
+  
+    For instance: "RSence 2.0 has undergone some major refactoring since 1.2.1"
+  

data/docs/ExampleGuiPlugin.rdoc

@@ -0,0 +1,193 @@
+= Example: The "welcome" GUIPlugin bundle
+
+This bundle is installed by default for each new RSence project environment, when created by the +rsence initenv+ command. It displays a simple user interface that contains a congratulatory message of a successful setup. Feel free to experiment with the plugin in your project environment.
+
+=== File / directory structure
+This is just an example, the meaning of gui/
+  !!!plain
+  |-- info.yaml
+  |-- values.yaml
+  |-- text
+  |   `-- welcome.html
+  |-- gui
+  |   `-- welcome.yaml
+  `-- welcome.rb
+
+=== The +info.yaml+ file of the "welcome" bundle
+This file defines the meta-information used by RSence to decide the loading order, dependencies and such. This bundle doesn't have any dependencies, so it's just using the default +depends_on: :system+, which means its loaded and called in order after the built-in plugins of RSence.
+
+The human-readable product name of the bundle
+  !!!yaml
+  title: Welcome message
+
+The human-readable version of the bundle
+  !!!yaml
+  version: 1.0.0
+
+A brief description of the package
+  !!!yaml
+  description: |
+    This is a simple welcome message plugin. It's installed in new project
+    environments, when the rsence initenv in executed.
+    You may safely remove this plugin bundle.
+
+System version requirements. In this case "RSence 2.0.0 or newer"
+  !!!yaml
+  sys_version: '>= 2.0.0'
+
+=== The +values.yaml+ file of the "welcome" bundle
+Only two values are used by the "welcome" plugin bundle. One to signal the server the "Close" button is clicked and the other to signal that the "Don't show again" check box is checked.
+
+The checkbox uses Boolean values and it doesn't need a responder so none is bound. Its default value is false.
+  !!!yaml
+  :dont_show_again:
+    :value: false
+
+The button (and sheet) in the gui are bound to this value, which defaults to 0 and has the +close_button+ method defined as the responder, which called when the value is changed in the client by clicking the "Close" button.
+  !!!yaml
+  :close:
+    :value: 0
+    :responders:
+    - { :method: close_button }
+
+=== The +welcome.rb+ source code file of the "welcome" bundle.
+The code in this file not only define the type and features of the plugin bundle, but also defines a few methods that are triggered.
+
+The class definition itself, just subclass {RSence::Plugins::GUIPlugin__ GUIPlugin}.
+  class WelcomePlugin < GUIPlugin
+  
+The +gui_params+ method is called by the {RSence::Plugins::GUIParser GUIParser} just before processing the GUITree data. In this case, it's extended to provide not only the values (delivered by the superclass), but also a custom entry, the +:text+ hash with the +:welcome+ member, which is the contents of the +welcome.html+ file inside the +text+ directory of the bundle. The params is accessed using dot notation in Symbol form in the GUITree yaml file.
+    def gui_params( msg )
+      params = super
+      params[:text] = {
+        :welcome => file_read('text/welcome.html')
+      }
+      return params
+    end
+
+The +close_button+ method is defined as a responder for the +:close+ value defined in the +values.yaml+. It's called when the "Close" button is clicked in the client. If the other value; +:dont_show_again+, has the data value +true+ ("Don't show again" -checkbox is checked), also calls the +disable_self+ method. Finally returns +true+, because the data doesn't need further validation and is good as-is.
+    def close_button( msg, value )
+      dont_show_again = get_ses(msg)[:dont_show_again]
+      if (value.data == 1) and (dont_show_again.data == true)
+        disable_self
+      end
+      return true
+    end
+
+The +disable_self+ method just disables the "welcome" plugin and tells RSence to unload itself. The "disabled" file means the bundle won't be loaded as long as the file is in place.
+    def disable_self
+      file_write( 'disabled', '' )
+      @plugins.unload_bundle( @name )
+    end
+
+Ends the class block:
+  end
+
+
+
+=== The +gui/welcome.yaml+ file of the "welcome" bundle
+This file has the user interface description encoded in YAML[http://yaml.org/]. It's converted by a {RSence::Plugins::GUIParser GUIParser} instance automatically set up by the {RSence::Plugins::GUIPlugin__ GUIPlugin} class instance, when the RSence web page is loaded (and reloaded) by the user.
+
+By convention, place the type and version of the GUITree specification first. This is used by the system to interpret the contents accordingly.
+  !!!yaml
+  type: GUITree
+  version: 0.6
+
+By convention, place the dependencies next. These are the javascript packages to load by the client before rendering the GUITree.
+  !!!yaml
+  dependencies:
+    - default_theme
+    - controls
+
+Next, the root class of the user interface tree is defined. This is usually an instance of +HApplication+, in this case the +RSence.GUIApp+ is used, because it's a customized extension of +HApplication+ designed for GUITree usage and supports options like +title+ and +priority+ by default.
+  !!!yaml
+  class: RSence.GUIApp
+  options:
+    title: Welcome App
+    priority: 20
+
+To have the +RSence.GUIApp+ instance titled "Welcome App" contain any views, we define the +subviews+ for it:
+  !!!yaml
+  subviews:
+
+The first subview is an instance of the +HSheet+ component, which is a component that self-centers, dims the background and its visibility controlled by its value.
+  !!!yaml
+    - class: HSheet
+
+All components use a +rect+ item to define their geometry, this is usually in form of an Array with at exactly +4+ or +6+ coordinates. In this case, with the offset of +0+ units from the left edge of its parent and +0+ units from the top edge of its parent. It has a size of +600+ units wide and +500+ units tall. Each unit at the default (100%) zoom level is exactly 1 pixel.
+  !!!yaml
+      rect: [ 0, 0, 600, 500 ]
+
+There is also a {RSence::HValue +HValue+} named +close+ defined in the +values.yaml+. This binds the +HSheet+ instance to the value and vice versa.
+  !!!yaml
+      bind: :values.close
+
+We also extend the component to kill its application (the +RSence.GUIApp+ defined above), which in effect destructs all the views defined by this GUITree when the data of the value becomes 1.
+  !!!yaml
+      extend:
+        refreshValue: |
+
+Custom Javascript extensions can be written inline like this. Functions are identified as text blocks that begin with 'function('. Other types are mapped as-is and converted to JSON structures.
+  !!!js
+          function(){
+            this.base();
+            if ( this.value==1 ) {
+              this.app.die();
+            }
+          }
+
+Then, we define the first subview of the +HSheet+ instance as a +HScrollView+, which is a view that has scroll bars. Its +rect+ is defined with stretching content filling entirely the area of its parent (the +HSheet+) except for the +42+ units at the bottom of its parent (the +HSheet+). Its minimum size is defined as +550+ units wide and +300+ units tall. Its options define that it displays horizontal scroll bars if the content doesn't fit and a white background with a black border at the bottom.
+  !!!yaml
+        - class: HScrollView
+          rect: [ 0, 0, 550, 300, 0, 42 ]
+          options:
+            scrollX: false
+            scrollY: auto
+            style:
+              - [ 'background-color', 'white' ]
+              - [ 'border-bottom', '1px solid black' ]
+
+Then, a few few items are defined as its subviews. An HImageView displaying the RSence logo, a +HView+ displaying a link to rsence.org and a +HInlineView+ displaying the contents of the +text/welcome.html+ file.
+  !!!yaml
+            - class: HImageView
+              rect: [ 18, 10, 559, 110 ]
+              options:
+                value: http://rsence.org/rsence_org_logo.gif
+            - class: HView
+              rect: [ null, 95, 310, 25, 35, null ]
+              options:
+                html: |
+                  <i style="font-family:Helvetica,Arial,sans-serif;font-size:16px;">
+                    <a style="color:#28c;font-weight:bold" href="http://rsence.org/">http://www.rsence.org/</a>
+                  </i>
+                style:
+                  - - text-align
+                    - right
+            - class: HInlineView
+              rect: [ 0, 0, null, null, 0, 0 ]
+              options:
+                html: :text.welcome
+                style:
+                  - - font-family
+                    - 'Helvetica, Arial, sans-serif'
+                  - - font-size
+                    - 16px
+                  - - line-height
+                    - 20px
+
+Finally, we define a +HClickValueButton+ (a button with the click event triggering a change of its value to +1+), which is bound to the same value as the +HSheet+, causing the +HSheet+ and the application including all child views to be destructed. The value change is also synchronized to the server-side responder method +close_button+ in the +welcome.rb+ file.
+  !!!yaml
+        - class: HClickValueButton
+          rect: [ null, null, 60, 24, 8, 8 ]
+          bind: :values.close
+          options:
+            label: Close
+
+We also define a +HCheckbox+ with another value bound, the +:dont_show_again+. This causes the plugin to be disabled  when the close button is clicked.
+  !!!yaml
+        - class: HCheckbox
+          rect: [ null, null, 130, 24, 74, 8 ]
+          bind: :values.dont_show_again
+          options:
+            label: Don't show again
+