malachite 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 73c222a1089089b9c0b127a5cd17f2bd071a5d81
-  data.tar.gz: 18a92267b8d4d60d73a582c62fddefd7ee124f72
+  metadata.gz: 15a0bee07fc12cc4a174e49741cbe6cbc5b247d5
+  data.tar.gz: 55611fa07c4f2465e419f188af6213b108036813
 SHA512:
-  metadata.gz: b29d404e2a0c6644372bd27ecc3c822596bad20d7ebe14c9f52c7d33c12b067f4e28bf273ad6b639a33480252419f6e5351e3f2cf83dc9e0b2c6ab50f5ca1f75
-  data.tar.gz: 726df1464886ee70ce8fba545593ec88790b404293e88bbb7b46fb2783afa39727ed9b55c21b31618e39b0c8e6b808374aa98b7bdfabe9c78fa7df6360cac4ae
+  metadata.gz: 9f99bffb3e811b277ca753d006678d1a84ecd00d9ab8e32b6a3aaa6cff736df55bb9de4c6eebd9b10bc170ca1c1acf9cb8f4d602c0f4e30e0c685c4c107104a5
+  data.tar.gz: 08e4d4d7aa44e7d3460c4707a74341066546ebafc33262450279f16c31707b21ce483e1622616a51f316324ce3df14d05febb94d91d325f23d29555345543b22

data/.gitignore

@@ -0,0 +1,11 @@
+Gemfile.lock
+.rvmrc
+.ruby-version
+tags
+*.swp
+dump.db
+.rbx
+coverage/
+vendor/
+.bundle/
+tmp/

data/README.md

@@ -0,0 +1,128 @@
+### Malachite
+
+A RubyGem which enables calling Go code from Rails.
+
+### Installation
+
+Install [Go 1.5 or later](https://golang.org/doc/install) on relevant machines.
+
+Add this to your Gemfile:
+
+```ruby
+gem 'malachite', github: 'zhubert/malachite'
+```
+
+Make a subdirectory of "app" called "go".
+
+### Write Some Go Functions
+
+Everything in "app/go" will get compiled into one namespace, so to get it to work with
+Malachite, you need to:
+
+* name the methods you want exported like: "HandleFoo"
+* the Handle methods can only take one argument (use structs for more complexity)
+
+For instance, if you wanted to upcase strings more quickly in your Rails app, you'd put the following in the file "app/go/upcase.go":
+
+```go
+package main
+
+import (
+	"strings"
+)
+
+func HandleUpcase(things []string) (upperCased []string) {
+	for _, thing := range things {
+		upperCased = append(upperCased, strings.ToUpper(thing))
+	}
+	return
+}
+```
+
+Then use your function from Rails:
+
+```ruby
+Malachite::Client.upcase(["foo","bar"])
+=> ["FOO", "BAR"]
+```
+
+Or if you have more interesting data organize it with a struct:
+
+```go
+package main
+
+import "strings"
+
+type Person struct {
+	Name string `json:"name"`
+	Age  string `json:"age"`
+}
+
+func HandleStructured(people []Person) (upperCasedPeople []Person) {
+	for _, person := range people {
+		upCase := Person{strings.ToUpper(person.Name), person.Age}
+		upperCasedPeople = append(upperCasedPeople, upCase)
+	}
+	return
+}
+```
+
+```ruby
+peeps = [{name: 'Peter', age: '27'},{name: 'Tim', age: '30'}]
+Malachite::Client.structured(peeps)
+=> [{"name"=>"PETER", "age"=>"27"}, {"name"=>"TIM", "age"=>"30"}]
+```
+
+Or even something totally arbitrary:
+
+```go
+package main
+
+import "strings"
+
+type Person struct {
+	Name string `json:"name"`
+}
+
+type Foo struct {
+	Friends []Person `json:"friends"`
+	Enemies []Person `json:"enemies"`
+}
+
+func HandleFrenemies(foo Foo) (frenemies []Person) {
+	for _, friend := range foo.Friends {
+		for _, enemy := range foo.Enemies {
+			if friend.Name == enemy.Name {
+				frenemies = append(frenemies, friend)
+			}
+		}
+	}
+	return
+}
+```
+
+```ruby
+friends = [{name: 'Peter'},{name: 'Tim'}]
+enemies = [{name: 'Peter'},{name: 'Zeb'}]
+Malachite::Client.frenemies({friends: friends, enemies: enemies})
+=> [{"name"=>"Peter"}]
+```
+
+### How Does it Work?
+
+Some code trickery, quite honestly.
+
+* The first time the function is called, Malachite will build a shared library from all the Go code in your "app/go" folder
+* It then uses Ruby's Fiddle to call the shared library
+* Arguments are passed back and forth via JSON
+
+Because of the JSON step, you'll only see real performance gains on computationally difficult tasks. Ruby's JSON conversion is a large tax.
+
+### Ruby 2.2.4+
+
+It's strongly recommended to use the [newest release of Ruby](https://www.ruby-lang.org/en/news/2015/12/16/unsafe-tainted-string-usage-in-fiddle-and-dl-cve-2015-7551/) as there was a security issue with older versions of Fiddle.
+
+### TODO
+
+* Error handling
+* Benchmark performance...roughly

data/lib/malachite/exporter.go.tmpl

@@ -0,0 +1,9 @@
+//export callXXXXXX
+func callXXXXXX(data *C.char) *C.char {
+	things := YYYYYY
+	err := Unmarshal(C.GoString(data), &things)
+	if err != nil {
+		return C.CString(err.Error())
+	}
+	return C.CString(Marshal(HandleXXXXXX(things)))
+}

data/lib/malachite/main.go.tmpl

@@ -0,0 +1,18 @@
+package main
+import "encoding/json"
+import "C"
+
+func main() {}
+
+func Unmarshal(data string, v interface{}) error {
+	err := json.Unmarshal([]byte(data), &v)
+	return err
+}
+
+func Marshal(v interface{}) string {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return "{}"
+	}
+	return string(b)
+}

data/lib/malachite/tasks/malachite.rake

@@ -0,0 +1,7 @@
+namespace :malachite do
+  desc 'run Go tests'
+  task :test do
+    test_files = Dir["#{Rails.root.join('app', 'go')}/*.go"]
+    system('go', 'test', *test_files)
+  end
+end

data/lib/malachite/version.rb

@@ -1,3 +1,3 @@
 module Malachite
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/malachite.gemspec

@@ -0,0 +1,21 @@
+# encoding: utf-8
+require File.expand_path('../lib/malachite/version', __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.authors       = ['Zack Hubert']
+  spec.email         = ['zhubert@gmail.com']
+  spec.summary       = 'A RubyGem which enables calling Go code from Ruby'
+  spec.description       = 'A RubyGem which enables calling Go code from Ruby.'
+  spec.homepage      = 'http://www.zhubert.com'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split("\n")
+  spec.name          = 'malachite'
+  spec.require_paths = ['lib']
+  spec.version       = Malachite::VERSION
+
+
+  spec.add_dependency 'json', '~> 1.0'
+  spec.add_development_dependency 'bundler', '~> 1.9'
+  spec.add_development_dependency 'rake', '~> 10.0'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: malachite
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Zack Hubert
@@ -59,15 +59,21 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
 - Gemfile
+- README.md
 - Rakefile
 - lib/malachite.rb
 - lib/malachite/client.rb
 - lib/malachite/compiler.rb
 - lib/malachite/errors.rb
+- lib/malachite/exporter.go.tmpl
+- lib/malachite/main.go.tmpl
 - lib/malachite/railtie.rb
 - lib/malachite/tasks.rb
+- lib/malachite/tasks/malachite.rake
 - lib/malachite/version.rb
+- malachite.gemspec
 homepage: http://www.zhubert.com
 licenses:
 - MIT
@@ -91,5 +97,5 @@ rubyforge_project:
 rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
-summary: A RubyGem which enables calling Go code from Ruby.
+summary: A RubyGem which enables calling Go code from Ruby
 test_files: []