console 0.1

data/ext/console/console.c

@@ -0,0 +1,203 @@
+/*
+ * console.c -- unit tests for ruby Console library
+ * Author:     William Morgan (mailto: wmorgan-ruby-console@masanjin.net)
+ * Copyright:  Copyright 2010 William Morgan
+ * License:    same terms as Ruby itself
+ */
+
+#define _XOPEN_SOURCE
+#include <wchar.h>
+#include <stdlib.h>
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+/*
+ * call-seq: display_width(string)
+ * 
+ * Returns the display width of <code>string</code>, that is, the number of
+ * columns that the string will take up when printed to screen. Note that this
+ * is different from the number of characters (some characters take up one
+ * column, some (e.g. Chinese characters) take up two columns), and the number
+ * of bytes (e.g. UTF-8 is a multibyte encoding) in a string.
+ *
+ * For Ruby 1.8, the string is assumed to be in the current locale's encoding.
+ * If not, terrible things will happen.
+ *
+ * For Ruby 1.9, the string will be magically converted from whatever encoding
+ * it is in, into the current locale's encoding, for processing. This may fail.
+ */
+static VALUE display_width(VALUE v_self, VALUE v_string) {
+  Check_Type(v_string, T_STRING);
+
+  /* for ruby 1.8, we assume the string is in your locale's CTYPE encoding
+   * already. if not, terrible things will happen.
+   *
+   * for ruby 1.9, we explicitly convert it to the locale's CTYPE encoding,
+   * like this:
+   */
+#ifdef HAVE_RUBY_ENCODING_H
+  v_string = rb_str_encode(v_string, rb_enc_from_encoding(rb_locale_encoding()), 0, Qnil);
+#endif
+  char* string = RSTRING_PTR(v_string);
+
+  mbstate_t mbs; memset(&mbs, 0, sizeof(mbs));
+  long display_width = 0;
+  long remaining_bytes = RSTRING_LEN(v_string);
+  while(remaining_bytes > 0) {
+    wchar_t wc;
+    size_t num_bytes = mbrtowc(&wc, string, remaining_bytes, &mbs);
+    if(num_bytes == 0) rb_raise(rb_eArgError, "malformed string: NULL byte at position %ld", RSTRING_LEN(v_string) - remaining_bytes);
+
+    int width = wcwidth(wc);
+    if(width == 0) rb_raise(rb_eArgError, "bad string: non-printable character");
+
+    display_width += width;
+    remaining_bytes -= num_bytes;
+    string += num_bytes; // advance string pointer
+  }
+
+  return LONG2NUM(display_width);
+}
+
+static const char* default_pad_string = " ";
+
+/*
+ * call-seq:
+ *   slice(string, start_offset, display_width=1, pad_string=" ")
+ *
+ * Returns a slice of a string based on display width, rather than character or
+ * bytes. I.e, the <code>start_offset</code> and <code>display_width</code>
+ * offsets index the columns required to display the string, and not individual
+ * characters or bytes.
+ *
+ * This is useful if you want to display a part of a string on screen, as you
+ * can pull out a specific portion by its display size.
+ *
+ * Padding: slicing can truncate multi-column characters. If the slice
+ * truncates a character, the string will be padded with
+ * <code>pad_string</code>, on the left side, right side, or both, as
+ * necessary. If <code>pad_string</code> is <code>nil</code> then no padding
+ * will be done. <code>pad_string</code> should be a single-column
+ * string for this to make sense.
+ *
+ * For Ruby 1.8, the string is assumed to be in the current locale's encoding.
+ * If not, terrible things will happen.
+ *
+ * For Ruby 1.9, the string will be magically converted from whatever encoding
+ * it is in, into the current locale's encoding, for processing. This may fail.
+ *
+ * The returned string WILL be in the current locale encoding, regardless of the
+ * encoding of the original string.
+ */
+static VALUE slice(int argc, VALUE *argv, VALUE v_self) {
+  VALUE v_string, v_display_start, v_display_width, v_pad_string;
+  rb_scan_args(argc, argv, "22", &v_string, &v_display_start, &v_display_width, &v_pad_string);
+  Check_Type(v_string, T_STRING);
+
+  /* try and mimic String#slice's argument handling as much as possible */
+  int display_start = NUM2INT(v_display_start);
+  if(display_start < 0) display_start = NUM2LONG(display_width(v_self, v_string)) + display_start; // negative start means from the end of the string
+  if(display_start < 0) return Qnil; // but if you go too far, you fail
+
+  int display_width;
+  if(argc < 3) display_width = 1; // default value just like String#slice (although it makes slightly less sense)
+  else display_width = NUM2INT(v_display_width);
+  if(display_width < 0) return Qnil; // you fail
+
+  char* pad_string;
+  if(argc < 4) pad_string = default_pad_string; // only fill in default if unspecified; nil is a valid value
+  else if(v_pad_string == Qnil) pad_string = "";
+  else pad_string = RSTRING_PTR(v_pad_string);
+
+  /* see comments in display_width() */
+#ifdef HAVE_RUBY_ENCODING_H
+  v_string = rb_str_encode(v_string, rb_enc_from_encoding(rb_locale_encoding()), 0, Qnil);
+#endif
+  char* string = RSTRING_PTR(v_string);
+
+  mbstate_t mbs; memset(&mbs, 0, sizeof(mbs));
+  long remaining_bytes = RSTRING_LEN(v_string);
+
+  // first, advance the string pointer so that we've seen display_start width characters
+  long current_width = 0;
+  while((remaining_bytes > 0) && (current_width < display_start)) {
+    wchar_t wc;
+    size_t num_bytes = mbrtowc(&wc, string, remaining_bytes, &mbs);
+    if(num_bytes == 0) rb_raise(rb_eArgError, "malformed string: NULL byte at position %ld", RSTRING_LEN(v_string) - remaining_bytes);
+
+    int width = wcwidth(wc);
+    if(width == 0) rb_raise(rb_eArgError, "bad string: non-printable character");
+
+    current_width += width;
+    remaining_bytes -= num_bytes;
+    string += num_bytes; // advance string pointer
+  }
+
+  /* here's a weird behavior (to me!) of String#slice that we emulate:
+   * if the start point is the string length itself, you get an empty
+   * string back; if the start point is greater than that, you get nil.
+   */
+  if((current_width < display_start)) return Qnil;
+
+  /* determine left padding */
+  char* pad_left = "";
+  if((current_width > display_start) && (display_width > 0)) pad_left = pad_string;
+
+  // now, advance the string_end pointer so that we've seen an additional display_width width characters
+  char* string_end = string;
+  current_width -= display_start;
+  while((remaining_bytes > 0) && (current_width < display_width)) {
+    wchar_t wc;
+    size_t num_bytes = mbrtowc(&wc, string_end, remaining_bytes, &mbs);
+    if(num_bytes == 0) rb_raise(rb_eArgError, "malformed string: NULL byte at position %ld", RSTRING_LEN(v_string) - remaining_bytes);
+
+    int width = wcwidth(wc);
+    if(width == 0) rb_raise(rb_eArgError, "bad string: non-printable character");
+
+    if((current_width + width) > display_width) break; // have to stop here
+
+    current_width += width;
+    remaining_bytes -= num_bytes;
+    string_end += num_bytes; // advance string pointer
+  }
+
+  /* determine right padding */
+  char* pad_right = "";
+  if((current_width < display_width) && (remaining_bytes > 0)) pad_right = pad_string;
+
+  // finally, construct a new string
+  int bytesize = string_end - string;
+  int leftsize = strlen(pad_left);
+  int rightsize = strlen(pad_right);
+
+  char* new_string = calloc(bytesize + leftsize + rightsize + 1, sizeof(char));
+  if(leftsize > 0) strcpy(new_string, pad_left);
+  if(bytesize > 0) memcpy(new_string + leftsize, string, bytesize * sizeof(char));
+  if(rightsize > 0) strcpy(new_string + leftsize + bytesize, pad_right);
+
+  (new_string + bytesize + leftsize + rightsize)[0] = 0; 
+
+  return rb_enc_str_new(new_string, bytesize + leftsize + rightsize, rb_enc_get(v_string));
+}
+
+/*
+ * A helper class for console-based programs that need to deal with non-ASCII
+ * code. If you are writing a curses/ncurses program, or otherwise care about
+ * the number of characters on the screen, this is crucial stuff.
+ *
+ * Provides:
+ *
+ * Console.display_width: get the number of display columns used by a string.
+ *
+ * Console.slice: get a substrig by display column offset and size.
+ *
+ */
+
+void Init_console() {
+  VALUE cConsole;
+
+  cConsole = rb_define_class("Console", rb_cObject);
+  rb_define_module_function(cConsole, "display_width", display_width, 1);
+  rb_define_module_function(cConsole, "slice", slice, -1);
+}
+

data/ext/console/extconf.rb

@@ -0,0 +1,2 @@
+require 'mkmf'
+create_makefile("console")

data/test/console.rb

@@ -0,0 +1,122 @@
+# encoding: utf-8
+
+## test/console.rb -- unit tests for ruby Console library
+## Author:     William Morgan (mailto: wmorgan-ruby-console@masanjin.net)
+## Copyright:  Copyright 2010 William Morgan
+## License:    same terms as Ruby itself
+
+require 'test/unit'
+require 'console'
+
+class ConsoleTest < ::Test::Unit::TestCase
+  def setup
+    @s = "能吞aê"
+  end
+
+  def test_slice_of_zero_width_is_empty_string
+    assert_equal "", Console.slice(@s, 0, 0)
+    assert_equal "", Console.slice(@s, 1, 0)
+  end
+
+  def test_slice_out_of_bounds_is_nil
+    assert_equal nil, Console.slice(@s, 100, 3)
+    assert_equal nil, Console.slice(@s, -100, 3)
+  end
+
+  def test_slice_with_negative_offset
+    assert_equal "ê", Console.slice(@s, -1, 1)
+    assert_equal "aê", Console.slice(@s, -2, 2)
+    assert_equal "a", Console.slice(@s, -2, 1)
+  end
+
+  def test_slice_width_argument_defaults_to_1
+    assert_equal "ê", Console.slice(@s, -1)
+    assert_equal "a", Console.slice(@s, -2)
+  end
+
+  def test_slice_works_on_chinese_characters
+    assert_equal "能", Console.slice(@s, 0, 2);
+    assert_equal "能吞", Console.slice(@s, 0, 4);
+    assert_equal "能吞a", Console.slice(@s, 0, 5);
+    assert_equal "能吞aê", Console.slice(@s, 0, 6);
+  end
+
+  def test_slice_with_excessive_width_is_still_cool
+    assert_equal "能吞aê", Console.slice(@s, 0, 100);
+    assert_equal "吞aê", Console.slice(@s, 2, 100);
+    assert_equal "aê", Console.slice(@s, 4, 100);
+    assert_equal "ê", Console.slice(@s, 5, 100);
+    assert_equal "", Console.slice(@s, 6, 100); # yep, we get a non-nil at this value
+    assert_equal nil, Console.slice(@s, 7, 100);
+  end
+
+  def test_slice_with_the_biggest_valid_start_offset_behaves_like_String_slice_does
+    assert_equal "", Console.slice(@s, 6, 100);
+    assert_equal "", Console.slice(@s, 6, 0);
+    assert_equal nil, Console.slice(@s, 6, -1);
+  end
+
+  def test_slice_misaligned_start_offsets_get_padded
+    s = "能吞aê"
+
+    assert_equal "", Console.slice(@s, 0, 0)
+    assert_equal " ", Console.slice(@s, 0, 1)
+    assert_equal "能", Console.slice(@s, 0, 2)
+    assert_equal "能 ", Console.slice(@s, 0, 3)
+
+    assert_equal "", Console.slice(@s, 1, 0)
+    assert_equal " ", Console.slice(@s, 1, 1)
+    assert_equal "  ", Console.slice(@s, 1, 2)
+    assert_equal " 吞", Console.slice(@s, 1, 3)
+
+    assert_equal "", Console.slice(@s, 3, 0);
+    assert_equal " ", Console.slice(@s, 3, 1);
+    assert_equal " a", Console.slice(@s, 3, 2);
+    assert_equal " aê", Console.slice(@s, 3, 3);
+  end
+
+  def test_slice_misaligned_start_offsets_get_padded_with_specified_character
+    assert_equal "", Console.slice(@s, 0, 0, "X")
+    assert_equal "X", Console.slice(@s, 0, 1, "X")
+    assert_equal "XX", Console.slice(@s, 1, 2, "X")
+  end
+
+  def test_slice_fails_on_nonstrings
+    assert_raises(TypeError) { Console.slice :potato, 1, 1 }
+    assert_raises(TypeError) { Console.slice 3, 1, 1 }
+  end
+
+  def test_display_width_empty_string_is_zero
+    assert_equal 0, Console.display_width("")
+  end
+
+  def test_display_width_works_on_ASCII_strings
+    assert_equal 1, Console.display_width("a")
+    assert_equal 1, Console.display_width(" ")
+    assert_equal 6, Console.display_width("potato")
+  end
+
+  def test_display_width_works_on_accented_characters
+    assert_equal 1, Console.display_width("ê")
+    assert_equal 4, Console.display_width("êêêê")
+  end
+
+  def test_display_width_works_on_chinese_characters
+    assert_equal 2, Console.display_width("能")
+    assert_equal 4, Console.display_width("能吞")
+  end
+
+  def test_display_width_works_on_mixed_stuff
+    assert_equal 2, Console.display_width("aê")
+    assert_equal 5, Console.display_width("能吞a")
+    assert_equal 6, Console.display_width("能吞aê")
+    assert_equal 6, Console.display_width("aê能吞")
+    assert_equal 6, Console.display_width("a能ê吞")
+    assert_equal 6, Console.display_width("能aê吞")
+  end
+
+  def test_display_width_fails_on_nonstrings
+    assert_raises(TypeError) { Console.display_width :potato }
+    assert_raises(TypeError) { Console.display_width 3 }
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: console
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  version: "0.1"
+platform: ruby
+authors: 
+- William Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-10 21:59:22 -04:00
+default_executable: 
+dependencies: []
+
+description: Console is a hlper for displaying super-ASCII strings on the console. It turns out that all these funny foreign characters not only take up strange numbers of bytes, they also take up strange numbers of columns on the screen when you print them. Console procides utility methods for determining the display width of a string, and for taking a substring in a display-width-centric manner.
+email: wmorgan-console@masanjin.net
+executables: []
+
+extensions: 
+- ext/console/extconf.rb
+extra_rdoc_files: []
+
+files: 
+- ext/console/extconf.rb
+- ext/console/console.c
+- test/console.rb
+has_rdoc: true
+homepage: http://console.rubyforge.org
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Console is a helper for displaying super-ASCII strings on the console.
+test_files: []
+