mini_term 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c3390b9651f5aeaf92e8492f85ef061675d70b0e
+  data.tar.gz: 83dafaec60ff3e9b117cd3e323b7c11b59123593
+SHA512:
+  metadata.gz: 5646e6678a067d6de0fdfe3236bfca2be7531ca35d9a286bbac96de1717b804403751f23d2e6a6344835088de073bb7c37efb9b85ce008b29cadf9edb7febbd4
+  data.tar.gz: 5542f74ac659a59b11cbb07c477d1fe5d3f9650a45a9e25810d036c56670ac53ce66ab340d9b6b7a68b5968362ea7b5245bcf7abb734c3f35c6833910fdd9964

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at peter.c.camilleri@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in mini_term.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 PeterCamilleri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,292 @@
+# MiniTerm
+
+The MiniTerm gem is a simple bit of code that seeks to smooth over the bumps
+and pot holes encountered when interacting with the console terminal to create
+console based CLI applications. More than most it also seeks to eliminate
+worries about the nasty cross-platform issues encountered between Windows,
+Linux, and MAC OS-X systems.
+
+This code started out its life buried deep within the code of the mini readline
+gem where it helped that gem do its job. A while ago it was realized that the
+services provided were invaluable for a much wider range of development. I was
+increasingly frustrated by my need to "go-around" mini readline to get at some
+of its lower level features. When that happens it is a clear sign that a gem is
+doing too much and has too many responsibilities.
+
+That's why the low level terminal functionality was split out into the mini
+term gem contained in this code repository. At the same time, the lessons
+learned from the earlier version of the code have been applied to make this
+code better and also not any more incompatible than needed. Since mini readline
+was the only "user" of the old code, moving out in some new directions should
+not pose a migration issue except for me.
+
+Finally, this gem would not be possible without the excellent insight into the
+gnarly world of win_32_api, dl, and fiddle I gained reading and copying the
+code in the [ConnorAtherton/rb-readline](https://github.com/ConnorAtherton/rb-readline)
+project and gem. *Thank You!*
+
+So, what hurdles do we expect the mini term gem to overcome? What cross-platform
+issues vex us? After all, it's not as if Ruby ignores the issue of low-level
+console access. It has the io/console and io/wait code libraries. They are
+supposed to give low level access right?
+
+And this is the point where the wheels start falling off.
+
+* The io/console library has truly awful documentation. Many methods lack any
+sort of description or meaningful parameter names. The developer is left to
+reverse engineering the behavior of the code. The programming process borders
+on the tribal. In this regard, io/wait is OK. Too bad it only plays a limited
+role.
+
+* The io/console library does not work correctly under Windows. And before we
+hear a chorus of "Switch to Linux", the anti-windows squad are reminded that
+this is a cross-platform tool, just like Ruby is supposed to be. The issue is
+that raw mode is not so raw under windows. In fact it's so cooked that it more
+resembles a chunk of charcoal! It just plain does not work. Fortunately there
+is an answer. Ruby has access to the various APIs though the 'fiddle' gem.
+This gem is used to emulate the deprecated 'win32api' gem.
+
+* Under JRuby, the situation is even worse. The io/console facility is
+incapable of manipulating the tty or console at all. A true non-starter. Only
+here's where things take a twist for the weird. Under Windows, JRuby *does*
+support the 'win32api' gem. It even works! I'm not at all sure how to support
+JRuby under Linux or Mac OS-X.
+
+* Working with Rubinius is perhaps the worst of all. Rubinius *still* does not
+run under Windows. Until such time as I am able to develop under a supported
+platform, or can collaborate with someone who can, this is a non-starter. Don't
+stay tuned, don't hold your breath; This problem is *not* going away any time
+soon.
+
+#### So! What do we have?
+
+This is a matrix of language versions and environments that have are tested or
+have been tested at one time or another.
+
+Ruby           | Win32   | Win64   | Cygwin  | Linux   | Mac
+---------------|---------|---------|---------|---------|---------
+ruby 2.1.6p336 | Yes?    | Yes??   | Yes??   | Yes??   | Yes??
+ruby 2.2.3p173 | Yes??   | Yes??   | Yes?    | Yes??   | Yes??
+ruby 2.3.3p222 | Yes??   | Yes     | Yes??   | Yes??   | Yes??
+jruby 9.1.5.0  | Yes?    | Yes??   | Maybe?  | Maybe?  | Maybe?
+
+This table will be updated as more information becomes available. Check the
+[github  repository](https://github.com/PeterCamilleri/mini_term) for the
+latest info.
+
+Notes:
+* Mini term uses keyword parameters so Ruby 2.0 or later is required. This is
+why older versions of Ruby have been removed from this table.
+* Yes? means that this combination was once tested with very similar code and
+should be OK, we hope. Testing would be nice.
+* Yes?? means that this combination *should* work but needs testing.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mini_term'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mini_term
+
+## Usage
+
+The mini term can be used in a project with:
+
+```ruby
+require 'mini_term'
+```
+
+### Interface Summary
+
+The following is a brief summary of the public interface of the MiniTerm module:
+
+**Constants**
+
+    VERSION       -- A version string of the form "9.9.9"
+    DESCRIPTION   -- A descriptive string.
+    VALID_OPTIONS -- An array of the supported option symbols.
+    TERM_TYPE     -- Either :windows or :ansi
+    TERM_PLATFORM -- One of :windows, :cygwin, :macosx, :linux, or :unix
+
+**Methods**
+
+    open(options), close, open?
+    term_info, width, height, ansi?, windows?, java?
+    set_posn(row: the_current_row, column:)
+    raw {}, raw?, begin_raw_input, end_raw_input
+    get_raw_char, has_raw_char? flush
+    get_mapped_char, add_map(type) {}, map_types
+    print(text), clear_screen
+
+
+*MiniTerm.open* - Before it can be used, the mini term should be opened. This
+is done with:
+
+```ruby
+MiniTerm.open(options)
+```
+
+The open method can take some optional arguments:
+
+    pass_ctrl_c: true   # The control+c character is passed through to the application.
+    pass_ctrl_c: false  # (Default) The control+c character is used by the OS.
+
+    pass_ctrl_s: true   # The control+s character is passed through to the application.
+    pass_ctrl_s: false  # (Default) The control+s character is used by the OS.
+
+    quiet: true         # Suppress various warning messages.
+    quiet: false        # (Default) Display warning message.
+
+    strict: true        # Invalid options raise an exception.
+    strict: false       # (Default) Invalid options cause no such fuss.
+
+
+If an unsupported or invalid option is detected, a warning message is displayed
+unless the quiet option is active. Alternatively, if the strict option is
+enabled, the MiniTermStrict exception is raised in that case.
+
+*MiniTerm.close* - The converse to open is close. It takes no arguments.
+
+```ruby
+MiniTerm.close
+```
+
+Rest assured that if your program should forget to close MiniTerm, the gem will
+close itself automatically when your program exits. This ensures that the
+terminal will not be left in a unworkable state. It will also tell you that it
+had to "Force MiniTerm.close" unless it was opened with the quiet: true option.
+
+*MiniTerm.terminfo, etc* - These methods return information about the current
+MiniTerm operating environment.
+
+```ruby
+MiniTerm.terminfo   # Returns the console's number of [rows, columns]
+MiniTerm.width      # Returns the console's number of columns.
+MiniTerm.height     # Returns the console's number of rows.
+MiniTerm.ansi?      # Is ANSI mode active?
+MiniTerm.windows?   # Is Windows mode active?
+MiniTerm.java?      # Is Java active?
+```
+
+*MiniTerm.set_posn* - This method is used to place the cursor anywhere on the
+screen or anywhere in the current line.
+
+```ruby
+set_posn(row: the_current_row, column:)
+```
+Note: If the row parameter is omitted, the row remains on the current row. The
+column parameter is always required.
+
+*MiniTerm.raw, etc* - These methods controll the use of raw console input, one
+of the major features provided by the MiniTerm gem. These methods are:
+
+```ruby
+MiniTerm.raw {|self|  }   # Execute the block with raw mode active.
+MiniTerm.raw?             # Is raw mode active now?
+```
+
+*MiniTerm.get_raw_char, etc* - These methods deal with the keyboard in a raw
+mode. They do not echo or wait for the user to press enter or any of those
+other cooked mode things. Keyboard data in the raw!
+
+```ruby
+MiniTerm.get_raw_char     # Wait for a keystroke in raw mode.
+MiniTerm.has_raw_char?    # Are there any keys waiting?
+MiniTerm.flush            # Flush any keys in the buffer.
+```
+
+Note that the get_raw_char method needs to be run with raw mode in effect. See
+the raw methods above for more on that. Also, in raw mode, some keys, especially
+extended keys may be composed of more than one byte. These methods only return
+one byte at a time.
+
+*MiniTerm.get_mapped_char, etc* - A mapped character is one or more raw
+characters that are mapped to an array containing a symbol and the characters
+that pathed the mapping to that sysmbol. For example:
+
+```ruby
+[:go_left, "\e[D"]
+```
+
+The conversion process from a stream of raw bytes to commands is done with a
+map. The method MiniTerm.add_map(type) {} takes one argument, the type, and a
+block. The type is currently one of the two terminal types: :windows or :ansi.
+The block also takes one argument, the newly created map. The code can then
+define entries in the map as follows:
+
+```ruby
+MiniTerm.add_map(:ansi) do |map|
+  map["\e[D"] = :go_left
+  # etc etc etc
+end
+```
+
+Now, the index for each entry represents a sort of path to the command. This
+path must not be ambiguous. For example, the following will generate an error:
+
+```ruby
+MiniTerm.add_map(:ansi) do |map|
+  map["\e"]   = :cancel
+  map["\e[D"] = :go_left
+  # etc etc etc
+end
+```
+
+To understand this, imagine that this map were allowed. The user presses the
+left arrow key. This generates the sequence "\e[D". The "\e" is received first
+and mapped to a :cancel command by the first rule. Then the "[D" characters are
+received and most likely inserted as these are printable characters. That is
+not what is wanted because the left arrow key was mapped to the wrong actions.
+This map is ambiguous mapping error is why MiniTerm signals a MiniTermKME error
+when the map is created.
+
+The method MiniTerm.map_types list the types for key maps that have been added.
+In most cases this will be [:ansi, :windows]. A map should be defined for each
+of the two term types, unless the application is only intended for one type.
+
+#### Exceptions:
+
+The mini term gem uses the following exception classes:
+
+    Exception              # From Ruby.
+      StandardError        # From Ruby.
+        MiniTermError      # The abstract base exception for mini term.
+          MiniTermKME      # A keyboard mapping error was detected.
+          MiniTermNoMap    # No map can be found for the current terminal type.
+          MiniTermNotRaw   # Raw mode is required for this operation.
+          MiniTermStrict   # An exception raised due to strictness.
+          MiniTermWTF      # An internal error happened. This shouldn't happen.
+
+## 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
+
+OR...
+
+* Make a suggestion by raising an
+ [issue](https://github.com/PeterCamilleri/mini_term/issues)
+. All ideas and comments are welcome.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](./LICENSE.txt).
+
+## Code of Conduct
+
+Everyone interacting in the mini_term project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
+[code of conduct](./CODE_OF_CONDUCT.md).

data/exe/README.md

@@ -0,0 +1,120 @@
+# MiniTerm - Utilities and Demos
+
+This section describes the simple utilities and demo programs that are included
+with the mini_term gem. The applications are designed to ease writing and
+testing of programs using mini_term. Then again, some are just for fun.
+
+## mapped_key_test
+
+The mapped_key_test program is designed demonstrate the mapped input system.
+The program comes with sample mappings for the supported systems and supports
+the use of alternate maps as well.
+
+If no arguments are given, the default maps are used.
+The following shows a sample run with an input of "1234567890 Enter UpArrow
+LeftArrow RightArrow DownArrow Tab Ctrl+z" with the default map under Windows.
+
+    42 mysh>mapped_key_test
+
+    Testing Mapped Keyboard input. Press Ctrl+z to quit.
+    Current maps = [:windows, :ansi]
+    Current term type = :windows
+
+    action = :insert_text, text = ["1"]
+    action = :insert_text, text = ["2"]
+    action = :insert_text, text = ["3"]
+    action = :insert_text, text = ["4"]
+    action = :insert_text, text = ["5"]
+    action = :insert_text, text = ["6"]
+    action = :insert_text, text = ["7"]
+    action = :insert_text, text = ["8"]
+    action = :insert_text, text = ["9"]
+    action = :insert_text, text = ["0"]
+    action = :enter, text = ["\r"]
+    action = :previous_history, text = ["\xE0", "H"]
+    action = :go_left, text = ["\xE0", "K"]
+    action = :go_right, text = ["\xE0", "M"]
+    action = :next_history, text = ["\xE0", "P"]
+    action = :auto_complete, text = ["\t"]
+    action = :end_of_input, text = ["\u001A"]
+
+Alternatively, the path(s) to a Ruby file(s) containing maps can be provided.
+One such file is provided at samples/test_map.rb. this trivial map shows a
+custom map in action.
+
+    43 mysh>mapped_key_test samples\test_map.rb
+    Requiring 'C:/Sites/mini_term/samples/test_map.rb'
+
+    Testing Mapped Keyboard input. Press Ctrl+z to quit.
+    Current maps = [:windows, :ansi]
+    Current term type = :windows
+
+    action = :unmapped, text = ["1"]
+    action = :unmapped, text = ["2"]
+    action = :unmapped, text = ["3"]
+    action = :unmapped, text = ["4"]
+    action = :unmapped, text = ["5"]
+    action = :unmapped, text = ["6"]
+    action = :unmapped, text = ["7"]
+    action = :unmapped, text = ["8"]
+    action = :unmapped, text = ["9"]
+    action = :unmapped, text = ["0"]
+    action = :unmapped, text = ["\t"]
+    action = :end_of_input, text = ["\u001A"]
+
+As mentioned before, this map doesn't do much but it does illustrate the basics
+of creating a custom map.
+
+## mini_term_code_points
+
+The purpose of the mini_term_code_points is to explore the glyphs associated
+with the code points of characters sent to the console. Let's see what plain
+old ASCII looks like:
+
+    16 mysh>mini_term_code_points 20 7F
+    Code points in the range: 20...7F
+       0                                       !"#$%&' ()*+,-./ 01234567 89:;<=>?
+      40  @ABCDEFG HIJKLMNO PQRSTUVW XYZ[\]^_ `abcdefg hijklmno pqrstuvw xyz{|}~
+
+While the other demo programs make direct use of the mini term gem, this one
+does not. It simply allows the programmer to explore the extent of Unicode
+support in the test environment.
+
+Note: By default, the mini_term_code_points displays the first 65536 code
+points which can take a while and will probably scroll away unless you pipe
+it into more (or less) or have a deep scroll back buffer.
+
+## raw_key_test
+
+This program is intended as a means to explore the key codes generated by the
+keyboard. This will help in the process of designing a MiniTerm map or the
+custom code to directly handle user input.
+
+The program works by taking raw data from the keyboard and simply displaying it
+in hex format. The program exits when the character "Q" is entered.
+
+A sample run of this program, under Windows is shown below. In this example the
+keys entered were "1234567890 *F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12* qQ"
+where *F1* through *F12* represent the keyboard's "F" keys and spaces are added
+only for clarity and where not entered.
+
+    77 mysh>raw_key_test
+    Testing Raw Keyboard input. Press Q to quit.
+    [31][32][33][34][35][36][37][38][39][30][00][3B][00][3C][00][3D][00][3E][00][3F]
+    [00][40][00][41][00][42][00][43][00][44][E0][85][E0][86][71][51]
+
+## mini_term_blizzard
+
+The other programs bundled with mini_term are serious practical utilities. They
+all serve a purpose. The mini_term_blizzard is none of those things! When run,
+it fills the console screen with _snow_.
+
+Yup!
+
+Snow!
+
+If run with no arguments, it uses the asterisk ("*") for the snowflakes. It can
+also take hex arguments that are the code point, or range of code points to be
+used. The following looks really nice on my test machine:
+
+    mini_term_blizzard 2740 2749