hubris 0.0.3 → 0.0.4

data/README.markdown

@@ -0,0 +1,107 @@
+# Hubris
+
+## Description
+
+Hubris is a bridge between Ruby and Haskell, between love and bondage,
+between slothful indolence and raw, blazing speed. Hubris will wash
+your car, lie to your boss, and salvage your love life. If you are 
+very, very lucky, it might also let you get some functional goodness 
+into your ruby programs through the back door.
+
+I probably don't have to say this, but patches are very much
+welcome. If you have trouble installing it, tell me, and help me
+improve the docs.
+
+## Synopsis
+
+The best docs, as ever, are in the tests, but as a quick precis, you
+can use it a little like this:
+
+    require 'hubris' # best line ever
+
+    class Target
+      hubris :inline =>"triple::Int->Int; triple n = 3*n"
+    end
+
+    t = Target.new
+    puts t.triple(10)
+       => 30
+
+There are a few restrictions. All functions take one argument and
+return one value: this shouldn't be a major problem because you can
+pass arrays of arguments in if you need more. Hubris can currently
+handle numbers, strings, basic types (like nil, true and false),
+arrays and hashes. There will probably be some Ruby structures
+(modules, regular expressions, etc) that won't ever be handled
+natively unless someone can convince me it's a sensible thing to do.
+
+Hubris will refuse to compile Haskell code that produces any
+warnings. You can suppress this admittedly fairly strict behaviour by
+passing the ":no_strict => true" flag, but in your heart of hearts
+you'll know you've done the wrong thing.
+
+There are also two other modes:
+
+      hubris :source => "MyCoolModule.hs"
+
+which loads a source file on disk (in the same directory as your ruby),
+and
+
+      hubris :module => "Data.ByteString", :packages => ["bytestring"]
+
+which will load the Data.ByteString module which is installed on the
+system. In this case, we also need to let the Haskell side know that
+we'll be using the "bytestring" package, so we pass that too: You may
+need to load extra packages with :inline and :source as well, and
+that's supported.
+
+
+## Requirements
+
+* ghc 6.10 (to bootstrap 6.12) and cabal-install. This comes with the
+  Haskell Platform
+* ruby 1.8.6 or higher (most heavily tested on 1.9.1)
+* Linux or Mac. See
+  <http://www.shimweasel.com/2009/09/14/unprincipled-skulduggery-with-ghc-6-12-dylibs-on-mac-os-x>
+  and the following entry for more info on the Mac build.
+* zsh or bash
+* git
+
+## Install
+
+Better instructions for [Linux](http://wiki.github.com/mwotton/Hubris/installation-of-ghc-6121-on-ubuntu-910) and [Mac](http://wiki.github.com/mwotton/Hubris/installation-of-ghc-6121-on-mac-os-x)
+
+## Contributors
+
+* Mark Wotton
+* James Britt
+* Josh Price
+* Tatsuhiro Ujihisa
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2009 Mark Wotton
+
+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.
+
+
+[haskell_platform]: http://hackage.haskell.org/platform/

data/Rakefile

@@ -1,51 +1,54 @@
-require 'rubygems'
-#gem 'hoe', '>= 2.1.0'
-#require 'hoe'
+
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+require 'rake'
 require 'fileutils'
-require './lib/hubris'
-
-# Hoe.plugin :newgem
-# Hoe.plugin :website
-# Hoe.plugin :cucumberfeatures
-
-# Generate all the Rake tasks
-# Run 'rake -T' to see list of generated tasks (from gem root directory)
-#$hoe = Hoe.spec 'hubris' do
-#  self.developer 'Mark Wotton', 'mwotton@gmail.com'
-#  self.rubyforge_name = "hubris"
-#  self.summary = 'tool to help build .so files from haskell code for use in Ruby via dl'
-#  self.post_install_message = 'PostInstall.txt'
-#  self.readme_file = "README.markdown"
-#  self.history_file = "HISTORY.markdown"
-#end
-
-#require 'newgem/tasks'
-# Dir['tasks/**/*.rake'].each { |t| load t }
-
-
-#file "lib/RubyMap.hs" => ["lib/RubyMap.chs"] do
-#  str = "c2hs -v --cppopts='-I" + Hubris::RubyHeader + "' --cpp=gcc --cppopts=-E --cppopts=-xc lib/RubyMap.chs"
-#  # print str
-#  system(str)
-#end
-
-require 'spec'
-require 'spec/rake/spectask'
-
-# desc "Run the specs under spec/"
-# all_examples = Spec::Rake::SpecTask.new do |t|
-#   t.spec_opts = ['--options', "spec/spec.opts"]
-#   t.spec_files = FileList['spec/*.rb']
+
+# require 'rake-compiler'
+require 'rake/extensiontask'
+# require 'rake/extensiontesttask'
+
+
+# task "build:native" => [:no_extconf, :native, :build] do
+#     file = "pkg/stub-#{`cat VERSION`.chomp}.gem"
+#     mv file, "#{file.ext}-i686-linux.gem"
 # end
 
-# task :spec => ["lib/RubyMap.hs"]
+
+Rake::ExtensionTask.new('stub')
+
+# intended to be called by the gem builder
+task :haskell_compile => [:compile] do
+  ghc_version='/usr/local/bin/ghc' # FIXME, should be able to pick
+  # this out from somewhere
+  # write the Includes file
+  pwd =`pwd`.strip
+  arch_headers = "#{RbConfig::CONFIG['rubyhdrdir']}/#{RbConfig::CONFIG['arch']}"
+  lib_dir = RbConfig::CONFIG['libdir']
+  headers = RbConfig::CONFIG['rubyhdrdir']
+  File.open("#{pwd}/Haskell/Language/Ruby/Hubris/Includes.hs","w") do |file|
+    file.write "module Language.Ruby.Hubris.Includes where
+extraIncludeDirs = [\"#{headers}\", \"#{arch_headers}\"]"
+  end
+#  command="cd Haskell; cabal update; cabal install
+  #  --extra-include-dirs=#{RbConfig::CONFIG['rubyhdrdir']}
+  #  --extra-include-dirs=#{RbConfig::CONFIG['rubyhdrdir']}/#{RbConfig::CONFIG['arch']} --extra-lib-dirs=#{RbConfig::CONFIG['libdir']} --user  --enable-shared  --with-ghc=#{ghc_version}"
+  command="cd Haskell; cabal install --extra-include-dirs=#{arch_headers} --extra-include-dirs=#{headers} --extra-lib-dirs=#{lib_dir} --user  --enable-shared  --with-ghc=#{ghc_version}"
+  result=%x{#{command}}
+  raise "ERROR: ran #{command}, got #{result}" unless $?.success? 
+end
+
+task :no_extconf do
+    $gemspec.extensions = []
+end
+
+task :default => :haskell_compile
 
 task :clean do
   FileList[File.expand_path("~/.hubris_cache/*"),
-           'lib*.so', 'lib/*.o', 'libfoo_*.bundle' ].each do |f|
-    begin
-        File.delete(f)
-    rescue
-    end
+           'lib*.so', 'lib/*.o' ].each do |f|
+    File.delete(f) rescue nil
   end
 end
+

data/VERSION

@@ -0,0 +1 @@
+0.0.3

data/doc/CommonErrors.txt

@@ -0,0 +1,18 @@
+this is a quick guide to diagnosing what could be wrong.
+
+This:
+"""
+/var/folders/Dz/Dz5WpFSZGUaFLA8jp8kT5E+++TM/-Tmp-/working_source.hs:7:7:
+    Could not find module `Foreign':
+      Perhaps you haven't installed the "dyn" libraries for package
+      `base'?
+"""
+
+indicates that GHC HEAD was not installed correctly. Run something
+like "find /usr/local -iname '*dyn_hi'" to check that the GHC you are
+using has all its dynamic library header files installed. If it
+doesn't, you probably didn't build GHC the right way: check
+http://www.shimweasel.com/2009/09/16/another-awful-hack-to-ghc-6-11
+and
+http://www.shimweasel.com/2009/09/14/unprincipled-skulduggery-with-ghc-6-12-dylibs-on-mac-os-x
+for more info.

data/doc/CommonErrors.txt~HEAD

@@ -0,0 +1,18 @@
+this is a quick guide to diagnosing what could be wrong.
+
+This:
+"""
+/var/folders/Dz/Dz5WpFSZGUaFLA8jp8kT5E+++TM/-Tmp-/working_source.hs:7:7:
+    Could not find module `Foreign':
+      Perhaps you haven't installed the "dyn" libraries for package
+      `base'?
+"""
+
+indicates that GHC HEAD was not installed correctly. Run something
+like "find /usr/local -iname '*dyn_hi'" to check that the GHC you are
+using has all its dynamic library header files installed. If it
+doesn't, you probably didn't build GHC the right way: check
+http://www.shimweasel.com/2009/09/16/another-awful-hack-to-ghc-6-11
+and
+http://www.shimweasel.com/2009/09/14/unprincipled-skulduggery-with-ghc-6-12-dylibs-on-mac-os-x
+for more info.

data/doc/don_feedback.txt

@@ -0,0 +1,25 @@
+   ------------------------------------------------------------------------
+
+   Hubris
+    Ruby calling Haskell
+       - inline, dynamically compiled Haskell
+       - call precompiled stuff
+
+   Dream
+     Haskell to code would be Cabal package.
+       Ruby would be application.
+
+     FFI preprocessor:
+       Does Haskell foreign export
+       Generates marshalling boilerplate
+
+     Haskell code in Ruby
+
+   ------------------------------------------------------------------------
+
+   Grammar, parsing, type-driven.
+
+   Killer demo:
+       - Rails site,
+           - super clever/ fast/ multicore Haskell code
+

data/doc/haskell-hubris.tex

@@ -0,0 +1,242 @@
+% Local Variables:
+% compile-command: "/opt/local/bin/pdflatex fp-syd.tex && open fp-syd.pdf"
+% End:
+
+\documentclass{beamer}
+\usepackage{listings}
+\usepackage{beamerthemesplit}
+
+\title{Hubris}
+\subtitle{A Trojan Horse for Haskell}
+\author{Mark Wotton \textless mwotton@shimweasel.com\textgreater}
+\date{\today}
+
+\begin{document}
+\lstset{language=Haskell}
+\section{Two cultures}
+\frame{\titlepage}
+
+% \subsection
+\begin{frame}
+  \frametitle{I \ding{170} Ruby}
+  \begin{itemize}
+  \item concise and flexible
+  \item Big web community, many libraries
+  \item Fun
+  \end{itemize}
+\end{frame}
+
+\begin{frame} 
+  \frametitle{I \ding{170} Haskell}
+  \begin{itemize}
+  \item<1-> Fast (optimised native code, multicore, etc)
+  \item<2-> Expressive - type systems don't have to suck.
+  \item<3-> Provably safe at compile time
+  \end{itemize}
+\end{frame}
+
+
+\begin{frame}
+  \frametitle{So, why do I care?}
+  \begin{itemize}
+  \item<1-> Make it easier to slap up a quick web interface to cool
+    haskell code.
+  \item<2-> Get more web-savvy devs into the Haskell community
+  \end{itemize}
+\end{frame}
+
+\subsection{problems with Haskell}
+\begin{frame}
+\frametitle{heresies}
+\setlength\parskip{0.1in}
+
+Haskell web frameworks are still niche.
+
+It's an engineering problem, and pretty boring.
+
+Haskell devs aren't exactly hard to find, but they don't seem to be
+web guys.
+
+\end{frame}
+
+\subsection{problems with Ruby}
+\begin{frame}
+  \frametitle{lies, damn lies, benchmarks}
+  \center{JRuby vs GHC}
+  \begin{tabular}{l l l l} 
+    Program &	        Time	&Memory &	Source Size\\ \hline
+    reverse-complement	&5	&1	&1/4\\
+    regex-dna	        &7	&3	&1/5\\	
+    binary-trees	        &8	&7	&1	\\	
+    k-nucleotide	        &10	&1	&1/7	\\	
+    pidigits	        &18	&18	&2	\\	
+    n-body	        &26	&53	&1	\\	
+    chameneos-redux	&30	&24	&1	\\	
+    fasta	                &31	&142	&1	\\	
+    fannkuch	        &45	&22	&1/4	\\	
+    spectral-norm	        &227	&56	&1/3	\\	
+    mandelbrot	        &319	&3	&1/2\\	
+  \end{tabular}
+\end{frame}
+
+
+
+\section{Hubris}
+\begin{frame}
+\frametitle{Peanut butter, meet chocolate}
+Ruby has a heap of web frameworks, convenience libraries, well-tested
+integration with javascript + CSS.
+
+\setlength\parskip{0.25in}
+
+Haskell is smoking fast with rock solid type safety but a relatively tiny
+community
+
+Hubris is my bridge between the two
+\end{frame}
+
+\begin{frame}
+\frametitle{Again, WHY?}
+There are seventy bazillion ways of talking between languages.
+ \begin{itemize}
+  \item Web services
+  \item text over pipes
+  \item Protocol buffers, Thrift
+  \item COM, HOC, etc (binary interfaces)
+ \end{itemize}
+
+Reasons to do it this way:
+ \begin{itemize}
+   \item it's fun (for me, anyway)
+   \item low fuss - no explicit mapping of function interfaces
+   \item easy to explore a library
+   \item few dependencies
+ \end{itemize}
+\end{frame}
+
+\lstset{language=Haskell}
+\subsection{Haskell example}
+\begin{frame}[fragile]
+  \frametitle{lazy, statically typed, and pure}
+  Collatz.hs
+  \begin{lstlisting}
+module Collatz where
+clMax lim = maximumBy (comparing snd) (assocs arr)
+  where arr = listArray (1,lim) 
+                       (0:(map depth [2..]))
+        step x = if even x 
+                   then div x 2 
+                   else 3 * x + 1
+        depth x = 1 + if n <= lim 
+                        then arr ! n 
+                        else depth n
+          where n = step x    
+  \end{lstlisting}
+  Hubrify Collatz collatz.dylib Collatz.hs
+
+\end{frame}
+
+\subsection{wrap it in Ruby}
+\begin{frame}[fragile]
+  \frametitle{actually using it}
+  \lstset{language=Ruby}
+  \begin{lstlisting}
+    require Hubris           # my favourite line
+    module Collatz
+      hubris :module => 'collatz'
+    end
+    puts Collatz.clMax(1000000)
+    >> 837799
+  \end{lstlisting}
+\end{frame}
+
+\subsection{beneath the covers}
+\begin{frame}[fragile]
+  \frametitle{on the Haskell side}
+  Hubrify loads the given source files and attempts to find the
+  passed-in module using the GHC API.
+\lstset{language=Haskell}
+\begin{lstlisting}
+data RValue = T_NIL | T_FIXNUM Int | ...
+type Value = CULong -- imported from Ruby
+class Haskellable a where
+  toHaskell :: RValue -> Maybe a
+
+class Rubyable a where
+  toRuby :: a -> RValue
+
+wrap :: (Haskellable a, Rubyable b) -> 
+        (a -> b) -> (Value -> Value)
+\end{lstlisting}
+\end{frame}
+
+\begin{frame}[fragile]
+  \frametitle{blah}
+  For each top level definition f, we then typecheck. 
+\begin{lstlisting}
+(wrap f) T_NIL == T_NIL 
+\end{lstlisting}
+if it fits, it's exportable.
+
+  create a Haskell file exporting each valid function, add a top level
+  manifest, and compile into a self-contained dylib.
+
+\end{frame}
+
+\begin{frame}
+ \frametitle{On the ruby side}
+ No Haskell-specific information at all.
+
+ We have a manifest function we need to call to find the names of
+ wrapped functions. (Also gives us a convenient point to initialise
+ the Haskell runtime)
+
+ attach all passed functions as methods on the surrounding module
+
+\end{frame}
+
+
+% \frametitle{Predictive}
+\section{Making it less sucky}
+\begin{frame}
+\setlength\parskip{0.1in}
+\frametitle{What's been done}
+  caching of Haskell binaries
+
+  transparent mapping - no boilerplate
+
+  separation of concerns - no compiler on server
+
+  ported to GHC
+\end{frame}
+
+\begin{frame}
+\frametitle{Still to do}
+  one-way bridge, no callbacks to Ruby
+
+  autoconf support to find ruby libs and includes
+
+  more serious hammering to find bugs - is it legitimate to dlopen
+  multiple haskell dylibs?
+
+  performance testing
+
+\end{frame}
+
+
+\begin{frame}
+\frametitle{Try it out!}
+  install GHC 6.12 release candidate
+
+  git clone git://github.com/mwotton/HaskellHubris.git 
+
+  git clone git://github.com/mwotton/Hubris.git     
+
+  follow the README
+
+  tell me what's missing
+
+  patches very much welcome (thanks to Josh Price, James Britt and Tatsuhiro Ujihisa)
+\end{frame}
+
+\end{document}

data/doc/new_interface.rb

@@ -0,0 +1,74 @@
+# IDEAS for new interface
+
+# option 1 (implicit method name from haskell function)
+class MyClass
+  include Hubris
+  def_haskell(code) 
+end
+
+# option 2 (explicit method name)
+class MyClass
+  def_haskell(method_name,code) 
+end
+
+# option 3 ()
+class Module
+  include Hubris
+end
+
+class MyClass
+  inline_haskell "haskell function"
+end
+
+# option 4 (more humourous)
+class Module
+  include Hubris
+end
+
+class MyClass
+  hubris "haskell function"
+end
+
+#-----------------------------------------
+# include at the module or package level
+#=========================================
+# does importing as_class make sense? no, just include the module
+# when interpreting Haskell module names replace . with ::
+
+# importing std module as a ruby module/class
+hubris :package => "containers", :module => "Data.Map", :as => "Data::Map"
+
+# importing your own module (defaults to module)
+hubris :package => "mypackage", :module => "MyModule" [, :as => "MyModule"] 
+
+# implicit package handling (haskell file in my directory)
+hubris :module => "haskell/shit/MyModule"
+
+# simpler to implement option, allows more flexibility in Ruby land
+module MyRubyModule
+  # :packages is optional, just brings in external packages.
+  hubris :module => "Data.Map", :packages => ["containers","foo"]
+  # or
+  hubris :source => "MyHaskellCode.hs" # , :packages => [ ... ]
+  # or
+  hubris :inline => "foo x = x * 2"
+end
+
+
+# alternative
+
+Hubris.import :package => "containers", :module => "Data.Map"
+
+module MyRubyModule
+  include Hubris::Data::Map
+end
+
+# alternative2
+
+module MyRubyModule
+  hubris :package => "containers", :module => "Data.Map"
+end
+
+
+6:34:58 PM Josh Price: class Module; def hubris; self.class_eval { def self.h;"hubrified!";end };end;end
+6:35:10 PM Josh Price: class B;hubris;end