acook / remedy

Remedy is a console interaction framework along the lines of Curses written in pure Ruby.

Remedy

Remedy is a console interaction framework along the lines of Curses written in pure Ruby. It is modular, making it easy to use what you need and ignore the rest.

If you have any suggestions or find any bugs, drop them in GitHub/issues so I can keep track of them. Thanks!

Installation

Add this line to your application's Gemfile:

  gem 'remedy'

If you're only going to use part of Remedy, you can tell Bundler to not automatically require the whole thing:

  gem 'remedy', require: false

And then execute:

$ bundle

Or install it yourself as:

$ gem install remedy

Usage

Remedy makes a few different classes and modules available to allow straight forward half-duplex communication with users via the console.

There are objects for input as well as output, including low level console keystroke reads and screen drawing.

Interaction

The Interaction object wraps raw keyboard reads and streamlines some aspects of accepting keyboard input.

For instance to get a keypress from the terminal and display it:

  include Remedy
  user_input = Interaction.new

  user_input.loop do |key|
    puts key
  end

Viewport

Viewport is the object that draws on your screen, you can give it any compatible Remedy::Partial object, or something that responds like one.

  include Remedy
  joke = Content.new
  joke << "Q: What's the difference between a duck?"
  joke << "A: Purple, because ice cream has no bones!"

  screen = Viewport.new
  screen.draw joke

Content in Remedy::Partials will be truncated as needed to accommodate the header and footer and the dimensions of the console. You can also specify the cursor/scroll position of the content being drawn, and when specifying headers or footers, you must.

  include Remedy
  title = Partial.new
  title << "Someone Said These Were Good"

  jokes = Content.new
  jokes << %q{1. A woman gets on a bus with her baby. The bus driver says: 'Ugh, that's the ugliest baby I've ever seen!' The woman walks to the rear of the bus and sits down, fuming. She says to a man next to her: 'The driver just insulted me!' The man says: 'You go up there and tell him off. Go on, I'll hold your monkey for you.'}
  jokes << %q{2. I went to the zoo the other day, there was only one dog in it, it was a shitzu.}

  disclaimer = Partial.new
  disclaimer << "According to a survey they were funny. I didn't make them."

  screen = Viewport.new
  screen.draw jokes, Size.new(0,0), title, disclaimer

Console

If you want easy access to some lower level console commands, you can use Console.

The most interesting function in my opinion is the callback that gets triggered when the user resizes the console window.

  include Remedy

  screen = Viewport.new

  Console.set_console_resized_hook! do |size|
    notice = Partial.new
    notice << "You just resized your screen!\n\nNew size:"
    notice << size
    screen.draw notice
  end

Remedy in the Wild

Remedy was originally written for my own console-based game. Remedy was extracted from it and open-sourced and it has lived on.

Here are some projects that use Remedy:

• A screenreader-friendly code editor for blind and visually impaired programmers: Viper
• The Official ElasticSearch Ruby Connector
• A multiplayer Yahtzee for web and console: YahtzeeGame
• Twitter/RSS/Facebook reader: noizee

Check them out!

Examples

The examples directory has a couple of running implementations to get you started!

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

remedy's Issues

Remove `Remedy::Partial` subclasses

The following subclasses contain no logic and seem to exist for naming semantics only:

Remedy::Content
Remedy::Header
Remedy::Footer

These should be removed and instead, Remedy::Partial should be supplied by the lib and the examples should reference only it. Currently, the README and menu example mentions Remedy::Partial in a comment and one must go digging to find out that all three of the above classes implement no behavior. These might be better left to the end user to implement if they so choose.

Design opinion: taking this concept a step further, the Remedy::View class could be made more useful by generalizing it into a collection of Partials rather than the semantic collection it is constrained to now: body, header, footer.

usage question

Hi, thanks for the library!

I was looking for something easier to use than curses, but more control than (the awesome) TTY libraries, and so far, this looks very promising!

I've been playing around with it, and am enjoying the combination of simplicity and effectiveness so far, it really works! :) Thank you for the library. A couple of questions/requests:

• I was wondering if you had any examples or docs on how to do multiple viewports on the screen at once, if that's a possible way to use it? e.g. a split pane interface. The Size still has me confused. can I specify an area with that? My random jabs at it have been unsuccessful so far.
• How would you do a "popup modal"? I tried using a new viewport, and an existing viewport with a different Partial, and those cleared the screen. I'd like to have the existing viewport below, and when the modal is done, be able to restore the dirty areas.

Thanks!

Rename `master` branch to `main`

https://github.com/github/renaming

Add Specs

This is a useful library. The examples are good. A test suite (RSpec preferred), including unit tests for each class, would be an excellent addition.

Problem running example

Hello,

I was looking for a ruby gem to allow me to detect key presses and found Remedy.

However I tried the example:

require 'remedy'
include Remedy

user_input = Interaction.new
user_input.loop do |key|
  puts key
end

And had problems with $log:

ruby remedy-test.rb 
/Users/humfrn01/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/gems/remedy-0.0.4/lib/remedy/keyboard.rb:27:in `parse': undefined method `debug' for nil:NilClass (NoMethodError)
        from /Users/humfrn01/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/gems/remedy-0.0.4/lib/remedy/keyboard.rb:9:in `get'
        from /Users/humfrn01/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/gems/remedy-0.0.4/lib/remedy/interaction.rb:53:in `block in loop'
        from /Users/humfrn01/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/gems/remedy-0.0.4/lib/remedy/interaction.rb:49:in `loop'
        from /Users/humfrn01/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/gems/remedy-0.0.4/lib/remedy/interaction.rb:49:in `loop'
        from remedy-test.rb:5:in `<main>'

Is there something I am missing?

nick.

Character typo

Hi
Thanks for gem - found a typo though:

        '[' => :left_bracket,
        ']' => :right_bracked,

link

Bad file descriptor on Windows while running the example

First I get some garbage:

�[?25l

When I press a key, I get Bad file descriptor

tweaks

There are a number of printable characters that report back as "unknown" (e.g., @, #, $, %, &, *, =, +, <, and >). Might you be interested in having a patch to add these? Also, what about an option to allow printable characters to pass through without any mapping?

-r

Unknown method coords

Hi
remedy is looking promising!
However the viewport example fails with unknown method coords for Remedy::Size:(0x0) with gem 0.1.0

viewport.rb:26:in range_find': undefined method coords' for #Remedy::Size:(0x0) (NoMethodError)

include Remedy
  joke = Content.new
  joke << "Q: What's the difference between a duck?"
  joke << "A: Purple, because ice cream has no bones!"

  screen = Viewport.new
  screen.draw joke