win 0.0.2

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 arvicco
+
+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.rdoc

@@ -0,0 +1,149 @@
+= win
+
+    by: Arvicco
+    url: http://github.com/arvicco/win_gui
+
+== DESCRIPTION
+
+A collection of Windows functions predefined for you using FFI. In addition to
+straightforward (CamelCase) API wrappers, it also strives to provide more Ruby-like
+snake_case methods that take a minimum of arguments with sensible defaults and have
+sensible return values (false/true instead of 0/nonzero for test functions, etc).
+
+Windows functions are grouped by topics and defined in separate namespaces (modules),
+that also contain related constants and convenience methods. For example, win/dde.rb
+file contains functions related to DDE protocol, such as DdeInitialize() as well as
+constants such as DMLERR_NO_ERROR, APPCLASS_STANDARD, etc.
+
+It is still work in progress, only a small number of Windows API functions wrapped so far...
+
+== SUMMARY
+
+So you want to write a simple program that makes some Windows API function calls.
+You searched MSDN high and low and you now know exactly what functions you need.
+All you want is just putting those function calls into your Ruby code without too
+much pain. You'd love this to be more or less natural extension of your Ruby code,
+preferably not turning your code base into an ugly spaghetty of CamelCase calls,
+String/Array pack/unpack gymnastics, buffer/pointer allocations, extracting return
+values from [in/out] parameters and checking return codes for 0.
+
+You have several options at this point. You can use either 'win32-api' or 'ffi' libraries
+to connect your ruby code to Windows API and manually define wrapper methods for
+needed function calls. This is definitely a valid approach, even if it is a bit
+low-level one: you'll still have to handle (somewhat) gory details of callback
+announcement, argument preparation, mimicking pointers with Strings (or declaring
+pointers explicitly with FFI) and other stuff (like manually defining about a gazillion
+obscure Windows constants). As an example, consider the amount of code needed to complete
+a task as simple as getting unicode title text for the window that you already have handle
+for (using win32-api):
+
+  api = Win32::API.new( 'GetWindowTextW', ['L', 'P', 'I'], 'L', 'user32' )
+  buffer = "\x00" * 1024  # I just hope it will be enough...
+  num_chars = api.call(window_handle, buffer, buffer.size)
+  title = if num_chars == 0
+    nil
+  else
+     buffer.force_encoding('utf-16LE').encode('utf-8').rstrip
+  end
+
+This is how you achieve the same result with ffi:
+
+  extend FFI::Library
+  ffi_lib 'user32'
+  ffi_convention :stdcall
+  attach_function :GetWindowTextW, [ :long, :buffer_out, :int ], :long
+  buffer = FFI::Buffer.new 1024
+  buffer.put_string(0, "\x00" * 1024)
+  num_chars = GetWindowTextW(window_handle, buffer, 1024)
+  title = if num_chars == 0
+    nil
+  else
+     buffer.get_bytes(0, num_chars).force_encoding('utf-16LE').encode('utf-8').rstrip
+  end
+
+As an alternative, you can use 'windows-pr' (pure ruby) library that gives you lots of
+Windows functions pre-defined and sectioned into modules, declares Windows constants and
+adds some other niceties. Unfortunately this library works only with MRI (not JRuby or
+other Ruby implementations), and still lacks Ruby look-and-feel for declared functions.
+It helps you to cut some of the declaration slack:
+
+  num_chars = GetWindowTextW(window_handle, buffer ="\x00" * 1024 , buffer.size)
+  title = if num_chars == 0
+    nil
+  else
+     buffer.force_encoding('utf-16LE').encode('utf-8').rstrip
+  end
+
+But still, does not it look like TOO MUCH code for something that should (ideally) look like this:
+
+  title = window_text_w(window_handle)
+
+This is an idea behind this library - make Windows API functions easier to use and feel more
+natural inside Ruby code. Following the principle of least surprise, we define methods that:
+* Have Rubyesque names (minimized? instead of IsMinimized, etc)
+* Require minimum arguments with sensible defaults
+* Return appropriate values explicitly (several return values if necessary)
+* Have sensible returns (false/true instead of 0/nonzero for test functions, nil if find function fails, etc)
+* Accept blocks where callback is expected
+* Are partitioned into related namespaces, so that you can load only the modules you need
+
+Well, we even keep a backup solution for those diehard Win32 API longtimers who would rather
+allocate their buffer strings by hand and mess with obscure return codes. If you use original
+CamelCase method name instead of Rubyesque snake_case one, it will expect those standard
+parameters you know and love from MSDN, return your zeroes instead of nils and support no
+other enhancements.
+
+And if you do not see your favorite Windows API functions amoung those already defined, it is
+quite easy to define new ones with 'function' macro method from Win::Library class - it does a
+lot of heavy lifting for you and can be customized with options and code blocks to give you
+reusable API wrapper methods with the exact behavior you need.
+
+== REQUIREMENTS:
+
+Only works with Ruby 1.9 compatible implementations since it uses some of the most recent features
+(block arguments given to block, etc...)
+
+== FEATURES/PROBLEMS:
+
+This project is quite new, so it may be not suitable for production-quality systems yet.
+Contributors always welcome!
+
+== INSTALLATION
+
+  $ gem install win
+
+== SYNOPSIS
+
+  require 'win/window'
+
+  class Foo
+    include Win::Window
+
+    fg_window = foreground_window
+    puts window_text_w(fg_window)
+    show_window(fg_window) unless minimized?(fg_window)
+    hide_window(fg_window) if maximized?(fg_window)
+    ...
+  end
+
+== CREDITS:
+
+This library started as an extension of ideas and code described in excellent book
+"Scripted GUI Testing with Ruby" by Ian Dees. 'win32-api' and 'windows-pr' gems by
+Daniel J. Berger and Park Heesob provided both inspiration and an excellent source
+for code borrowing. 'ffi' gem serves as a solid basis for this library, allowing to
+use it for multiple Ruby implementations.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 arvicco. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "win"
+    gem.summary = %Q{A collection of Windows functions predefined for you using FFI}
+    gem.description = %Q{A collection of Windows functions predefined for you using FFI}
+    gem.email = "arvitallian@gmail.com"
+    gem.homepage = "http://github.com/arvicco/win"
+    gem.authors = ["arvicco"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "cucumber", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+
+  task :features => :check_dependencies
+rescue LoadError
+  task :features do
+    abort "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+  end
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "win #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.2

data/features/support/env.rb

@@ -0,0 +1,4 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+require 'win'
+
+require 'spec/expectations'

data/features/win.feature

@@ -0,0 +1,9 @@
+Feature: something something
+  In order to something something
+  A user something something
+  something something something
+
+  Scenario: something something
+    Given inspiration
+    When I create a sweet new gem
+    Then everyone should see how awesome I am

data/lib/win/extensions.rb

@@ -0,0 +1,24 @@
+class String
+  def snake_case
+    gsub(/([a-z])([A-Z0-9])/, '\1_\2' ).downcase
+  end
+  
+  def to_w
+    (self+"\x00").encode('utf-16LE')
+  end
+  
+  def to_vkeys
+    unless size == 1
+      raise "Can't convert but a single character: #{self}"
+    end
+    ascii = upcase.unpack('C')[0]
+    case self
+      when 'a'..'z', '0'..'9', ' '
+      [ascii]
+      when 'A'..'Z'
+      [0x10, ascii]    # Win.const_get(:VK_SHIFT) = 0x10 Bad coupling
+    else
+      raise "Can't convert unknown character: #{self}"
+    end
+  end
+end

data/lib/win/library.rb

@@ -0,0 +1,198 @@
+require 'ffi'
+require 'win/extensions'
+
+module Win
+
+  class NotFoundError < NameError
+    def initialize(name=nil, libs=nil)
+      super %Q[Function #{name ? "'#{name}' ": ""}not found#{libs ? " in #{libs}" : ""}"]
+    end
+  end
+
+  module Library
+
+    # Class Win::Library::API mimics Win32::API
+    class API
+
+      # The name of the DLL that exports the API function
+      attr_reader :dll_name
+
+      # Ruby (library) module to which this function is attached
+      attr_reader :lib_module
+
+      # The name of the function passed to the constructor
+      attr_reader :function_name
+
+      # The name of the actual function that is returned by the constructor.
+      # For example, if you passed 'GetUserName' to the constructor, then the
+      # effective function name would be either 'GetUserNameA' or 'GetUserNameW'.
+      attr_accessor :effective_function_name
+
+      # The prototype, returned as an array of FFI types
+      attr_reader :prototype
+
+      # The return type (:void for no return value)
+      attr_reader :return_type
+
+      def initialize( lib_module, function, effective_function_name, prototype, return_type )
+        @lib_module = lib_module
+        @function_name = function
+        @effective_function_name = effective_function_name
+        @prototype = prototype
+        @return_type = return_type
+      end
+
+      def call( *args )
+        @lib_module.send(@effective_function_name.to_sym, *args)
+      end
+    end
+
+    # Contains class methods (macros) to be used in Win::Libraries
+    module ClassMethods
+      TYPES = {
+              V: :void, # For functions that return nothing (return type void).
+              v: :void, # For functions that return nothing (return type void).
+              C: :uchar, #– 8-bit unsigned character (byte)
+              c: :char, # 8-bit character (byte)
+              # :int8 – 8-bit signed integer
+              # :uint8 – 8-bit unsigned integer
+              S: :ushort, # – 16-bit unsigned integer (Win32API: used for string)
+              s: :short, # – 16-bit signed integer
+              # :uint16 – 16-bit unsigned integer
+              # :int16 – 16-bit signed integer
+              I: :uint, # 32-bit unsigned integer
+              i: :int, # 32-bit signed integer
+              # :uint32 – 32-bit unsigned integer
+              # :int32 – 32-bit signed integer
+              L: :ulong, # unsigned long int – platform-specific size
+              l: :long, # long int – platform-specific size (http://groups.google.com/group/ruby-ffi/browse_thread/thread/4762fc77130339b1)
+              # :int64 – 64-bit signed integer
+              # :uint64 – 64-bit unsigned integer
+              # :long_long – 64-bit signed integer
+              # :ulong_long – 64-bit unsigned integer
+              F: :float, # 32-bit floating point
+              D: :double, # 64-bit floating point (double-precision)
+              P: :pointer, # pointer – platform-specific size
+              p: :string, # C-style (NULL-terminated) character string (Win32API: S)
+              B: :bool # (?? 1 byte in C++)
+              #For function argument type only:
+              # :buffer_in – Similar to :pointer, but optimized for Buffers that the function can only read (not write).
+              # :buffer_out – Similar to :pointer, but optimized for Buffers that the function can only write (not read).
+              # :buffer_inout – Similar to :pointer, but may be optimized for Buffers.
+              # :varargs – Variable arguments
+      }
+
+      ##
+      # Defines new method wrappers for Windows API function call:
+      #   - Defines method with original (CamelCase) API function name and original signature (matches MSDN description)
+      #   - Defines method with snake_case name (converted from CamelCase function name) with enhanced API signature
+      #       When the defined wrapper method is called, it checks the argument count, executes underlying API
+      #       function call and (optionally) transforms the result before returning it. If block is attached to
+      #       method invocation, raw result is yielded to this block before final transformations
+      #   - Defines aliases for enhanced method with more Rubyesque names for getters, setters and tests:
+      #       GetWindowText -> window_test, SetWindowText -> window_text=, IsZoomed -> zoomed?
+      #
+      # You may modify default behavior of defined method by providing optional &define_block to def_api.
+      #   If you do so, instead of directly calling API function, defined method just yields callable api
+      #   object, arguments and (optional) runtime block to your &define_block and returns result coming out of it.
+      #   So, &define_block should define all the behavior of defined method. You can use define_block to:
+      #   - Change original signature of API function, provide argument defaults, check argument types
+      #   - Pack arguments into strings for [in] or [in/out] parameters that expect a pointer
+      #   - Allocate string buffers for pointers required by API functions [out] parameters
+      #   - Unpack [out] and [in/out] parameters returned as pointers
+      #   - Explicitly return results of API call that are returned in [out] and [in/out] parameters
+      #   - Convert attached runtime blocks into callback functions and stuff them into [in] callback parameters
+      #
+      # Accepts following options:
+      #   :dll:: Use this dll instead of default 'user32'
+      #   :rename:: Use this name instead of standard (conventional) function name
+      #   :alias(es):: Provides additional alias(es) for defined method
+      #   :boolean:: Forces method to return true/false instead of nonzero/zero
+      #   :zeronil:: Forces method to return nil if function result is zero
+      #
+      def function(function, params, returns, options={}, &define_block)
+        method_name, effective_names, aliases = generate_names(function, options)
+        boolean = options[:boolean]
+        zeronil = options[:zeronil]
+        params = params.split(//) if params.respond_to?(:split) # Convert params string into array
+#puts "#{method_name}, #{effective_names}, #{aliases}"
+        params.map! {|param| TYPES[param.to_sym] || param} # Convert chars into FFI type symbols
+        returns = TYPES[returns.to_sym] || returns # Convert chars into FFI type symbols
+
+        effective = effective_names.inject(nil) do |func, ename|
+          func || begin
+#p ename, params, returns
+            attach_function(ename, params.dup, returns)
+            ename
+          rescue FFI::NotFoundError
+            nil
+          end
+        end
+
+        raise Win::NotFoundError.new(function, ffi_libraries.map(&:name)) unless effective
+
+        api = API.new(self, function, effective, params, returns)
+
+        define_method(function) {|*args| api.call(*args)} # define CamelCase method wrapper for api call
+
+        if define_block
+          define_method(method_name) do |*args, &runtime_block|
+            define_block[api, *args, &runtime_block]
+          end
+        else
+          define_method(method_name) do |*args, &runtime_block|    # define snake_case method with enhanced api
+            namespace.enforce_count(args, params)
+            result = api.call(*args)
+            result = runtime_block[result] if runtime_block
+            return result != 0 if boolean         # Boolean function returns true/false instead of nonzero/zero
+            return nil if zeronil && result == 0  # Zeronil function returns nil instead of zero
+            result
+          end
+        end
+        aliases.each {|ali| alias_method ali, method_name }        # define aliases
+        api  # return API object
+      end
+
+      # Generates possible effective names for function in Win32 dll (function+A/W),
+      # Rubyesque name and aliases for method(s) defined based on function name,
+      # sets boolean flag for test functions (Is...)
+      #
+      def generate_names(function, options={})
+        effective_names = [function]
+        effective_names += ["#{function}A", "#{function}W"] unless function =~ /[WA]$/
+        aliases = ([options[:alias]] + [options[:aliases]]).flatten.compact
+        method_name = options[:rename] || function.snake_case
+        case method_name
+          when /^is_/
+            aliases << method_name.sub(/^is_/, '') + '?'
+            options[:boolean] = true
+          when /^set_/
+            aliases << method_name.sub(/^set_/, '')+ '='
+          when /^get_/
+            aliases << method_name.sub(/^get_/, '')
+        end
+        [method_name, effective_names, aliases]
+      end
+
+      # Ensures that args count is equal to params count plus diff
+      #
+      def enforce_count(args, params, diff = 0)
+        num_args = args.size
+        num_params = params.size + diff #params == 'V' ? 0 : params.size + diff
+        if num_args != num_params
+          raise ArgumentError, "wrong number of arguments (#{num_args} for #{num_params})"
+        end
+      end
+    end
+
+    #extend ClassMethods
+
+    def self.included(klass)
+      klass.extend ClassMethods
+      klass.extend FFI::Library
+      klass.ffi_lib 'user32', 'kernel32'  # Default libraries
+      klass.ffi_convention :stdcall
+      klass.class_eval "def namespace; #{klass}; end"
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--color
+--format nested

data/spec/spec_helper.rb

@@ -0,0 +1,38 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'spec'
+require 'spec/autorun'
+
+# Customize RSpec with my own extensions
+module SpecMacros
+
+  # wrapper for it method that extracts description from example source code, such as:
+  # spec { use{    function(arg1 = 4, arg2 = 'string')  }}
+  def spec &block
+    it description_from(*block.source_location), &block
+  end
+
+  # reads description line from source file and drops external brackets (like its{}, use{}
+  def description_from(file, line)
+      File.open(file) do |f|
+        f.lines.to_a[line-1].gsub( /(spec.*?{)|(use.*?{)|}/, '' ).strip
+      end
+  end
+end
+
+Spec::Runner.configure { |config| config.extend(SpecMacros) }
+
+module WinTest
+
+  TEST_IMPOSSIBLE = 'Impossible'
+  TEST_CONVERSION_ERROR = /Can.t convert/
+
+  def use
+    lambda {yield}.should_not raise_error
+  end
+
+  def any_block
+    lambda {|*args| args}
+  end
+
+end

data/spec/win/extensions_spec.rb

@@ -0,0 +1,63 @@
+require File.join(File.dirname(__FILE__), ".." , "spec_helper" )
+require 'win/extensions'
+
+module WinTest
+
+  describe String do
+    context '#snake_case' do
+      it 'transforms CamelCase strings' do
+        'GetCharWidth32'.snake_case.should == 'get_char_width_32'
+      end
+      
+      it 'leaves snake_case strings intact' do
+        'keybd_event'.snake_case.should == 'keybd_event'
+      end
+    end
+
+    context '#to_w' do
+      it 'transcodes string to utf-16LE' do
+        'GetCharWidth32'.to_w.encoding.name.should == 'UTF-16LE'
+      end
+      
+      it 'ensures that encoded string is null-terminated' do
+        'GetCharWidth32'.to_w.bytes.to_a[-2..-1].should == [0, 0]
+      end
+    end
+    
+    context '#to_vkeys' do
+      it 'transforms number char into [equivalent key code]' do
+       ('0'..'9').each {|char| char.to_vkeys.should == char.unpack('C')}
+      end
+      
+      it 'transforms uppercase letters into [shift, equivalent key code]' do
+       ('A'..'Z').each {|char| char.to_vkeys.should == [0x10, *char.unpack('C')]}
+        # Win.const_get(:VK_SHIFT) = 0x10 Bad coupling
+      end
+      
+      it 'transforms lowercase letters into [(upcase) key code]' do
+       ('a'..'z').each {|char| char.to_vkeys.should == char.upcase.unpack('C')}
+      end
+      
+      it 'transforms space into [equivalent key code]' do 
+        " ".to_vkeys.should == " ".unpack('C')
+      end
+      
+      it 'raises error if char is not implemented punctuation' do
+       ('!'..'/').each {|char| lambda {char.to_vkeys}.should raise_error TEST_CONVERSION_ERROR }
+       (':'..'@').each {|char| lambda {char.to_vkeys}.should raise_error TEST_CONVERSION_ERROR }
+       ('['..'`').each {|char| lambda {char.to_vkeys}.should raise_error TEST_CONVERSION_ERROR }
+       ('{'..'~').each {|char| lambda {char.to_vkeys}.should raise_error TEST_CONVERSION_ERROR }
+      end
+      
+      it 'raises error if char is non-printable or non-ascii' do
+        lambda {1.chr.to_vkeys}.should raise_error TEST_CONVERSION_ERROR
+        lambda {230.chr.to_vkeys}.should raise_error TEST_CONVERSION_ERROR
+      end
+      
+      it 'raises error if string is multi-char' do
+        lambda {'hello'.to_vkeys}.should raise_error TEST_CONVERSION_ERROR
+        lambda {'23'.to_vkeys}.should raise_error TEST_CONVERSION_ERROR
+      end  
+    end
+  end
+end

data/spec/win/library_spec.rb

@@ -0,0 +1,370 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+require 'win/library'
+
+module WinTest
+
+  module MyLib # namespace for defined functions
+    include Win::Library
+  end
+  include MyLib
+
+  def should_be symbol, api
+    case symbol
+      when :find_window
+        #api.dll_name.should == 'user32' # The name of the DLL that exports the API function
+        api.effective_function_name.should == 'FindWindowA' # Actual function returned by the constructor: 'GetUserName' ->'GetUserNameA' or 'GetUserNameW'
+        api.function_name.should == 'FindWindow' # The name of the function passed to the constructor
+        api.prototype.should == [:pointer, :pointer] # The prototype, returned as an array of characters
+        api.return_type.should == :ulong # The prototype, returned as an array of characters
+    end
+  end
+
+  def should_count_args(*methods, rights, wrongs)
+    rights = [rights].flatten
+    wrongs = [wrongs].flatten
+    methods.each do |method|
+      (0..8).each do |n|
+        if n == rights.size
+          expect {send method, *rights}.to_not raise_error
+        else
+        args = (1..n).map {wrongs[rand(wrongs.size)]}
+        expect {send method, *args}.
+                to raise_error "wrong number of arguments (#{args.size} for #{rights.size})"
+        end
+      end
+    end
+  end
+
+  def any_handle
+    MyLib.function 'FindWindow', 'PP', 'L' unless respond_to? :find_window
+    find_window(nil, nil)
+  end
+
+  def not_a_handle
+    123
+  end
+
+  def redefined_methods
+    [:FindWindow, :IsWindow, :EnumWindows, :GetComputerName, :GetForegroundWindow]
+  end
+
+  def hide_method(*names) # hide original method(s) if it is defined
+    names.map(&:to_s).each do |name|
+      MyLib.module_eval do
+        aliases = generate_names(name).flatten + [name]
+        aliases.map(&:to_s).each do |ali|
+          if method_defined? ali
+            alias_method "original_#{ali}".to_sym, ali
+            remove_method ali
+          end
+        end
+      end
+    end
+  end
+
+  def restore_method(*names) # restore original method if it was hidden
+    names.map(&:to_s).each do |name|
+      MyLib.module_eval do
+        aliases = generate_names(name).flatten + [name]
+        aliases.map(&:to_s).each do |ali|
+          temp = "original_#{ali}".to_sym
+          if method_defined? temp
+            alias_method ali, temp
+            remove_method temp
+          end
+        end
+      end
+    end
+  end
+
+  describe Win::Library, ' defines wrappers for Win32::API functions' do
+
+    before(:each) { hide_method *redefined_methods } # hide original methods if  defined
+    after(:each) { restore_method *redefined_methods } # restore original methods if hidden
+
+    context 'defining enhanced API function method' do
+      spec{ use{ MyLib.function('FindWindow', 'PP', 'l', rename: nil, aliases: nil, boolean: nil, zeronil: nil, &any_block) }}
+
+      it 'defines new instance methods with appropriate names' do
+        MyLib.function 'FindWindow', 'PP', 'L'
+        respond_to?(:FindWindow).should be_true
+        respond_to?(:find_window).should be_true
+      end
+
+      it 'constructs argument prototype from uppercase string, enforces the args count' do
+        expect { MyLib.function 'FindWindow', 'PP', 'L' }.to_not raise_error
+        should_count_args :find_window, :FindWindow, [nil, nil], [nil, TEST_IMPOSSIBLE, 'cmd']
+      end
+
+      it 'constructs argument prototype from (mixed) array, enforces the args count' do
+        expect { MyLib.function 'FindWindow', [:pointer, 'P'], 'L' }.to_not raise_error
+        should_count_args :find_window, :FindWindow, [nil, nil], [nil, TEST_IMPOSSIBLE, 'cmd']
+      end
+
+      it 'with :rename option, overrides snake_case name for defined method but leaves CamelCase intact' do
+        MyLib.function 'FindWindow', 'PP', 'L', :rename=> 'my_own_find'
+        expect {find_window(nil, nil)}.to raise_error NoMethodError
+        expect {FindWindow(nil, nil)}.to_not raise_error
+        expect {my_own_find(nil, nil)}.to_not raise_error
+      end
+
+      it 'defined snake_case method returns expected value when called' do
+        MyLib.function 'FindWindow', 'PP', 'L'
+        find_window(nil, nil).should_not == 0
+        find_window(nil, TEST_IMPOSSIBLE).should == 0
+        find_window(TEST_IMPOSSIBLE, nil).should == 0
+        find_window(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE).should == 0
+      end
+
+      it 'defined CamelCase method returns expected value when called' do
+        MyLib.function 'FindWindow', 'PP', 'L'
+        FindWindow(nil, nil).should_not == 0
+        FindWindow(nil, TEST_IMPOSSIBLE).should == 0
+        FindWindow(TEST_IMPOSSIBLE, nil).should == 0
+        FindWindow(TEST_IMPOSSIBLE, TEST_IMPOSSIBLE).should == 0
+      end
+
+#      it 'returns underlying Win32::API object if defined method is called with (:api) argument ' do
+#        MyLib.function 'FindWindow', 'PP', 'L'
+#        expect {find_window(:api)}.to_not raise_error
+#        should_be :find_window, find_window(:api)
+#      end
+
+      it 'returns underlying Win32::API object' do
+        FWAPI = MyLib.function 'FindWindow', 'PP', 'L'
+        should_be :find_window, FWAPI
+      end
+    end
+
+    context 'defining aliases' do
+      it 'adds alias for defined method with :alias option' do
+        MyLib.function( 'FindWindow', 'PP', 'L', :alias => 'my_own_find')
+        expect {find_window(nil, nil)}.to_not raise_error
+        expect {my_own_find(nil, nil)}.to_not raise_error
+      end
+
+      it 'adds aliases for defined method with :aliases option' do
+        MyLib.function 'FindWindow', 'PP', 'L', :aliases => ['my_own_find', 'my_own_find1']
+        expect {find_window(nil, nil)}.to_not raise_error
+        expect {my_own_find(nil, nil)}.to_not raise_error
+        expect {my_own_find1(nil, nil)}.to_not raise_error
+      end
+
+      it 'adds Rubyesque alias to IsXxx API test function' do
+        MyLib.function 'IsWindow', 'L', 'B'
+        respond_to?(:window?).should be_true
+        respond_to?(:is_window).should be_true
+      end
+
+      it 'adds Rubyesque alias to GetXxx API getter function' do
+        MyLib.function 'GetComputerName', 'PP', 'I', :dll=> 'kernel32'
+        respond_to?(:get_computer_name).should be_true
+        respond_to?(:computer_name).should be_true
+      end
+    end
+
+    context 'auto-defining Ruby-like boolean methods if API function name starts with "Is_"' do
+      before(:each) {MyLib.function 'IsWindow', 'L', 'L'}
+
+      it 'defines new instance method name dropping Is_ and adding ?' do
+        respond_to?(:window?).should be_true
+        respond_to?(:is_window).should be_true
+        respond_to?(:IsWindow).should be_true
+      end
+
+      it 'defined CamelCase method returns zero/non-zero as expected' do
+        IsWindow(any_handle).should_not == true
+        IsWindow(any_handle).should_not == 0
+        IsWindow(not_a_handle).should == 0
+      end
+
+      it 'defined snake_case method returns false/true instead of zero/non-zero' do
+        window?(any_handle).should == true
+        window?(not_a_handle).should == false
+        is_window(any_handle).should == true
+        is_window(not_a_handle).should == false
+      end
+
+      it 'defined methods enforce the argument count' do
+        should_count_args :window?, :is_window, :IsWindow,  [not_a_handle], [nil, not_a_handle, any_handle]
+      end
+    end
+
+    context 'defining API with :boolean option converts result to boolean' do
+      before(:each) { MyLib.function 'FindWindow', 'PP', 'L', :boolean => true }
+
+      it 'defines new instance method' do
+        respond_to?(:find_window).should be_true
+        respond_to?(:FindWindow).should be_true
+      end
+
+      it 'defined snake_case method returns false/true instead of zero/non-zero' do
+        find_window(nil, nil).should == true
+        find_window(nil, TEST_IMPOSSIBLE).should == false
+      end
+
+      it 'defined CamelCase method still returns zero/non-zero' do
+        FindWindow(nil, nil).should_not == true
+        FindWindow(nil, nil).should_not == 0
+        FindWindow(nil, TEST_IMPOSSIBLE).should == 0
+      end
+
+      it 'defined methods enforce the argument count' do
+        should_count_args :find_window, :FindWindow, [nil, nil], [nil, TEST_IMPOSSIBLE, 'cmd']
+      end
+    end
+
+    context 'defining API with :zeronil option converts zero result to nil' do
+      before(:each) {MyLib.function 'FindWindow', 'PP', 'L', :zeronil => true}
+
+      it 'defines new instance method' do
+        respond_to?(:find_window).should be_true
+        respond_to?(:FindWindow).should be_true
+      end
+
+      it 'defined CamelCase method still returns zero/non-zero' do
+        FindWindow(nil, nil).should_not == true
+        FindWindow(nil, nil).should_not == 0
+        FindWindow(nil, TEST_IMPOSSIBLE).should == 0
+      end
+
+      it 'defined method returns nil (but NOT false) instead of zero' do
+        find_window(nil, TEST_IMPOSSIBLE).should_not == false
+        find_window(nil, TEST_IMPOSSIBLE).should == nil
+      end
+
+      it 'defined method does not return true when result is non-zero' do
+        find_window(nil, nil).should_not == true
+        find_window(nil, nil).should_not == 0
+      end
+
+      it 'defined methods enforce the argument count' do
+        should_count_args :find_window, :FindWindow, [nil, nil], [nil, TEST_IMPOSSIBLE, 'cmd']
+      end
+    end
+
+    context 'using DLL other than default user32 with :dll option' do
+      before(:each) {MyLib.function 'GetComputerName', 'PP', 'I', :dll=> 'kernel32'}
+
+      it 'defines new instance method with appropriate name' do
+        respond_to?(:GetComputerName).should be_true
+        respond_to?(:get_computer_name).should be_true
+        respond_to?(:computer_name).should be_true
+      end
+
+      it 'returns expected result' do
+        MyLib.function 'GetComputerName', ['P', 'P'], 'I', :dll=> 'kernel32'
+        hostname = `hostname`.strip.upcase
+        name = " " * 128
+        get_computer_name(name, "128")
+        name.unpack("A*").first.should == hostname
+      end
+    end
+
+    context 'trying to define an invalid API function' do
+      it 'raises error when trying to define function with a wrong function name' do
+        expect { MyLib.function 'FindWindowImpossible', 'PP', 'L' }.
+                to raise_error( /Function 'FindWindowImpossible' not found/ )
+      end
+    end
+
+    context 'defining API function using definition block' do
+      it 'defines new instance method' do
+        MyLib.function( 'FindWindow', 'PP', 'L' ){|api, *args|}
+        respond_to?(:find_window).should be_true
+        respond_to?(:FindWindow).should be_true
+      end
+
+      it 'does not enforce argument count outside of block' do
+        MyLib.function( 'FindWindow', 'PP', 'L' ){|api, *args|}
+        expect { find_window }.to_not raise_error
+        expect { find_window(nil) }.to_not raise_error
+        expect { find_window(nil, 'Str', 1) }.to_not raise_error
+      end
+
+      it 'returns block return value when defined method is called' do
+        MyLib.function( 'FindWindow', 'PP', 'L' ){|api, *args| 'Value'}
+        find_window(nil).should == 'Value'
+      end
+
+      it 'passes arguments and underlying Win32::API object to the block' do
+        MyLib.function( 'FindWindow', 'PP', 'L' ) do |api, *args|
+          @api = api
+          @args = args
+        end
+        expect {find_window(1, 2, 3) }.to_not raise_error
+        @args.should == [1, 2, 3]
+        should_be :find_window, @api
+      end
+
+      it ':rename option overrides standard name for defined method' do
+        MyLib.function( 'FindWindow', 'PP', 'L', :rename => 'my_own_find' ){|api, *args|}
+        expect {find_window(nil, nil, nil)}.to raise_error
+        expect {my_own_find(nil, nil)}.to_not raise_error
+      end
+
+      it 'adds alias for defined method with :alias option' do
+        MyLib.function( 'FindWindow', 'PP', 'L', :alias => 'my_own_find' ){|api, *args|}
+        expect {find_window(nil, nil)}.to_not raise_error
+        expect {my_own_find(nil, nil)}.to_not raise_error
+      end
+
+      it 'adds aliases for defined method with :aliases option' do
+        MyLib.function( 'FindWindow', 'PP', 'L', :aliases => ['my_own_find', 'my_own_find1'] ) {|api, *args|}
+        expect {find_window(nil, nil)}.to_not raise_error
+        expect {my_own_find(nil, nil)}.to_not raise_error
+        expect {my_own_find1(nil, nil)}.to_not raise_error
+      end
+    end
+
+    context 'calling defined methods with attached block to preprocess the API function results' do
+      it 'defined method yields raw result to block attached to its invocation' do
+        MyLib.function 'FindWindow', 'PP', 'L', zeronil: true
+        find_window(nil, TEST_IMPOSSIBLE) {|result| result.should == 0 }
+      end
+
+      it 'defined method returns result of block attached to its invocation' do
+        MyLib.function 'FindWindow', 'PP', 'L', zeronil: true
+        return_value = find_window(nil, TEST_IMPOSSIBLE) {|result| 'Value'}
+        return_value.should == 'Value'
+      end
+
+      it 'defined method transforms result of block before returning it' do
+        MyLib.function 'FindWindow', 'PP', 'L', zeronil: true
+        return_value = find_window(nil, TEST_IMPOSSIBLE) {|result| 0 }
+        return_value.should_not == 0
+        return_value.should == nil
+      end
+    end
+
+    context 'defining API function without arguments - f(VOID)' do
+      it 'should enforce argument count to 0, NOT 1' do
+        MyLib.function 'GetForegroundWindow', [], 'L', zeronil: true
+        should_count_args :GetForegroundWindow, :get_foreground_window, :foreground_window, [], [nil, 0, 123]
+      end
+   end
+
+    context 'working with API function callbacks' do
+      it '#callback method creates a valid callback object' do
+        pending 'What about callbacks?'
+        expect { @callback = WinGui.callback('LP', 'I') {|handle, message| true} }.to_not raise_error
+        @callback.should be_a_kind_of(Win32::API::Callback)
+      end
+
+      it 'created callback object can be used as a valid arg of API function expecting callback' do
+        pending 'What about callbacks?'
+        MyLib.function 'EnumWindows', 'KP', 'L'
+        @callback = WinGui.callback('LP', 'I'){|handle, message| true }
+        expect { enum_windows(@callback, 'Message') }.to_not raise_error
+      end
+
+      it 'defined API functions expecting callback convert given block into callback' do
+        pending 'What about callbacks?'
+        pending ' What about prototype!? API is not exactly clear atm (.with_callback method?)'
+        MyLib.function 'EnumWindows', 'KP', 'L'
+        expect { enum_windows('Message'){|handle, message| true } }.to_not raise_error
+      end
+    end
+
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: win
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- arvicco
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-08 00:00:00 +03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: cucumber
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A collection of Windows functions predefined for you using FFI
+email: arvitallian@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- features/step_definitions/win_steps.rb
+- features/support/env.rb
+- features/win.feature
+- lib/win/extensions.rb
+- lib/win/library.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/win/extensions_spec.rb
+- spec/win/library_spec.rb
+has_rdoc: true
+homepage: http://github.com/arvicco/win
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A collection of Windows functions predefined for you using FFI
+test_files: 
+- spec/spec_helper.rb
+- spec/win/extensions_spec.rb
+- spec/win/library_spec.rb