viva 0.42.1337

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a01b0d14ea32240f6880c8f285b4ffc5d1ef16fc
+  data.tar.gz: af40b3a31343a9d7088d153ccdabb660f89a10d5
+SHA512:
+  metadata.gz: 48c2b43fefcee481edae7284894ccf1a7efd2c1230df3347476bfb17994ceca0e0aebbfce159371fe5614ffb9b7b16f5cf963d6d6cc69743cd1bb8c80ca055a1
+  data.tar.gz: ecf62bfa07e1830d2341550931c24be0d78071013525efee13d374760b8a407746eb65af7faaa21c4df1840aa13dee388a18c48c26a1bc1893e8be094e75467a

data/CODE_OF_CONDUCT

@@ -0,0 +1,9 @@
+,---.    ,---.-./`) ,---.   .--.   ____       .-'''-. .--.      .--.   ____   ,---.   .--.
+|    \  /    \ .-.')|    \  |  | .'  __ `.   / _     \|  |_     |  | .'  __ `.|    \  |  |
+|  ,  \/  ,  / `-' \|  ,  \ |  |/   '  \  \ (`' )/`--'| _( )_   |  |/   '  \  \  ,  \ |  |
+|  |\_   /|  |`-'`"`|  |\_ \|  ||___|  /  |(_ o _).   |(_ o _)  |  ||___|  /  |  |\_ \|  |
+|  _( )_/ |  |.---. |  _( )_\  |   _.-`   | (_,_). '. | (_,_) \ |  |   _.-`   |  _( )_\  |
+| (_ o _) |  ||   | | (_ o _)  |.'   _    |.---.  \  :|  |/    \|  |.'   _    | (_ o _)  |
+|  (_,_)  |  ||   | |  (_,_)\  ||  _( )_  |\    `-'  ||  '  /\  `  ||  _( )_  |  (_,_)\  |
+|  |      |  ||   | |  |    |  |\ (_ o _) / \       / |    /  \    |\ (_ o _) /  |    |  |
+'--'      '--''---' '--'    '--' '.(_,_).'   `-...-'  `---'    `---` '.(_,_).''--'    '--'

data/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION, AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

data/README.md

@@ -0,0 +1,135 @@
+<p align="center">
+  <img src="http://i.imgur.com/OzCBizi.png" />
+</p>
+
+## What's this?
+
+**Viva** is a little C extension that exposes the **vi**rtual **va**riable API to Ruby land for science and the lulz.
+
+### What's that?
+
+Contrary to popular misconception, many of Ruby's global variables are in fact not. Consider the case of `$~` (known to [`English`](http://ruby-doc.org/stdlib-2.3.0/libdoc/English/rdoc/English.html) speakers as `$LAST_MATCH_INFO`):
+
+```ruby
+def foo
+  'foo'.match /\w+/ and p $~
+end
+
+'bar'.match /\w+/
+
+p $~ # "bar" from the current scope
+foo  # "foo" from #foo's scope
+p $~ # "bar" again
+```
+
+It's evident that something tricksy is going on here; if this allegedly "global" variable doesn't maintain its value across scopes, whence does it come? I'll spare you the gory details: it's defined in terms of [a pair of C functions](https://git.io/vzwAN). Referring to `$~` will invoke `match_getter()` to obtain a value and *assigning to `$~`* will cause the provided `MatchData` instance to be used for `$~` and all of its descendants (of which there are [potentially thousands](https://git.io/vzwxR)).
+
+#### Cool story, bro.
+
+That's all well and good, yeah? "vvars" are scoped and pretty much do The Right Thing™. What's more, there's nothing stopping you from digging in and defining your own. But who wants to write C? [Bestest](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=4&cad=rja&uact=8&ved=0ahUKEwjqlvHc4L_KAhVF4iYKHRAZAxMQFggzMAM&url=http%3A%2F%2Fwww.merriam-webster.com%2Fdictionary%2Fbestest&usg=AFQjCNF5NASit_I0DsFXBB2l4baH0n7nFQ&bvm=bv.112454388,d.eWE) of all would be if we could define virtual getters and setters with Ruby callables, and so I've made that a thing.
+
+### La raison d'être
+
+There's an old shell variable in Zsh—I know it's in Bash, it's probably in Zsh—called `RANDOM`, and the tin's not lying:
+
+```bash
+$ echo $RANDOM $RANDOM $RANDOM
+8784 15644 1499
+```
+
+[How neat is that?](http://i.imgur.com/SCRFkTZ.png) Let's give Ruby a `$RANDOM` that's neater still:
+
+```ruby
+require 'viva'
+
+max = 32768 # Be like Bash... for now.
+getter = -> { rand max }
+setter = -> spec { max = spec }
+
+Viva.define :RANDOM, getter, setter
+
+p Array.new(4) { $RANDOM }
+# => [31791, 5045, 21337, 14134]
+
+$RANDOM = 1..6
+
+p Array.new(4) { $RANDOM }
+# => [3, 5, 6, 2]
+```
+
+Bash's offering looks positively static in comparison. ¡Viva la Rubylución!
+
+## Usage
+
+`Viva.define` is the primary interface. It accepts exactly three arguments: a name for the virtual variable to be defined and two callables (instances of `Method` or `Proc`) to be used as the getter and setter thereof, respectively.
+
+The name is coerced via `Kernel#String`; preceded with a `'$'`; and subjected to the rules for global identifiers, with the additional stipulation that numeric names may only be between `-9` and `0`, inclusively. This constraint is informed by the parser rather than enforced by the virtual variable API: `$-10` and below are outright syntax errors, and assignment to the positives is explicitly forbidden. We can *refer* to them just fine, but they're "super-virtual" and will, at present, simply ignore any efforts to tailor their behavior to one's wily whim. I consider the inability to use them to be a :bug: in **Viva**.
+
+**TL;DR;SMAT**:
+
+ valid |invalid
+:-----:|:-----:
+`0`    |`1`
+`-4`   |`-10`
+`"$"`  |`" "`
+`"-_"` |`"_-"`
+`Viva` |`nil`
+`:*`   |`:^`
+
+The getter can be defined to take an argument, which will be the "actual" value of the requested variable. Likewise, the setter receives the value that was assigned. The point, of course, is that you're free to do with these values what you will.
+
+Invoking `Viva.define` with a falsy value instead of a callable will undefine it and restore that operation to its regularly scheduled programming (bog-standard retrieval and assignment); regrettably, this holds true for variables which previously had some special meaning (pretty much everything in `English`). This is another :bug:.
+
+`define_getter` and `define_setter` are convenience methods that take blocks and leave their better halves in place:
+
+```ruby
+Viva.define_setter('$') do |pid|
+  p "Someone wanted our PID to be #{pid}."
+end
+
+%w[$ PID PROCESS_ID].each do |name|
+  Viva.define_getter(name) { 1337 }
+end
+
+$$ = 42 # => "Someone wanted our PID to be 42."
+p $$    # => 1337
+```
+
+Just for laughs, **Viva** provides a bit of syntactic sugalt for defining both accessors simultaneously using "two blocks":
+
+```ruby
+Viva(:MoL).--> v { v * 2 } { |v| v * 7 }
+
+$MoL = 3
+p $MoL # => 42
+```
+
+That you have to put the parameter in different places makes it look pretty silly, which I argue is a feature.
+
+Finally, there's `undef_getter` and `undef_setter` which, while perfectly self-explanatory, go a long way toward revealing what's actually going on here:
+
+```ruby
+def undef_getter var
+  Getters.delete "$#{var}"
+end
+```
+
+No effort has been made to conceal the internals from the user. This one's for you, [`FrozenCore`](https://youtu.be/SBdqCYKWISU?t=463).
+
+### FQAs
+
+* Is this real life?
+
+Likelier than not, but perhaps one of the solipsists has the right of it.
+
+* Why is this happening?
+
+Some men just want to watch the world-writable variables burn with the glory of a thousand suns. <sup><sup>If only I could be so grossly incandescent...</sup></sup>
+
+* Should I use this?
+
+I'm inclined to think [_why would've liked it](http://favstar.fm/users/_why/status/1231698950); your team are liable to [respond less positively](https://www.youtube.com/watch?v=H07zYvkNYL8). Horses for courses and the like.
+
+### Contributing
+
+You are strongly but gently advised to reconsider. If you simply won't be deterred, may the fork be with you.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rake/testtask'
+
+Rake::TestTask.new :spec do |t|
+  t.test_files = ['spec/viva_spec.rb']
+end
+
+task :default do
+  IO.new(0).puts <<JOKE
+
+rm: it is dangerous to operate recursively on '/'
+rm: use --no-preserve-root to override this failsafe
+
+JOKE
+end

data/examples/counter.rb

@@ -0,0 +1,8 @@
+require 'viva'
+
+c = -1
+Viva(:COUNTER).--> { c += 1 } { |v| c = v }
+
+p Array.new(3) { $COUNTER } # => [0, 1, 2]
+$COUNTER = 10
+p Array.new(3) { $COUNTER } # => [11, 12, 13]

data/examples/mol.rb

@@ -0,0 +1,6 @@
+require 'viva'
+
+Viva(:MoL).--> v { v * 2 } { |v| v * 7 }
+
+$MoL = 3
+p $MoL # => 42

data/examples/pid.rb

@@ -0,0 +1,12 @@
+require 'viva'
+
+Viva.define_setter('$') do |pid|
+  p "Someone wanted our PID to be #{pid}."
+end
+
+%w[$ PID PROCESS_ID].each do |name|
+  Viva.define_getter(name) { 1337 }
+end
+
+$$ = 42 # => "Someone wanted our PID to be 42."
+p $$    # => 1337

data/examples/random.rb

@@ -0,0 +1,11 @@
+require 'viva'
+
+max = 32768
+getter = -> { rand max }
+setter = -> spec { max = spec }
+
+Viva.define :RANDOM, getter, setter
+
+p Array.new(4) { $RANDOM }
+$RANDOM = 1..6
+p Array.new(4) { $RANDOM }

data/ext/viva/core.c

@@ -0,0 +1,60 @@
+#include <ruby.h>
+
+static VALUE mViva, getters, setters;
+static ID id_call;
+
+/* `struct rb_global_variable` doesn't get exported from variable.c, but this
+ * should suffice to have everything in the right place when we go looking. */
+struct gvar { int _, __; void *val; };
+
+static VALUE
+viva_getter(ID id, void *data)
+{
+  VALUE getter = rb_hash_aref(getters, rb_id2str(id));
+  VALUE val = data ? data : Qnil; /* the old value, if any */
+
+  if (RTEST(getter))
+    return rb_funcall(getter, id_call, abs(rb_proc_arity(getter)), val);
+  return val;
+}
+
+static void
+viva_setter(VALUE val, ID id, void *_, struct gvar *var)
+{
+  VALUE setter = rb_hash_aref(setters, rb_id2str(id));
+
+  var->val = RTEST(setter) ? rb_funcall(setter, id_call, 1, val) : val;
+}
+
+#define error_msg "`%s`is not allowed as a virtual variable name"
+
+static VALUE
+viva_define(VALUE self, VALUE var, VALUE getter, VALUE setter)
+{
+  char *str;
+  var = rb_String(var);
+  rb_str_update(var, 0, 0, rb_str_new("$", 1));
+  str = StringValueCStr(var);
+
+  /* Reject invalid global identifiers and fully digital ones other than $0,
+   * since the former would be syntax errors and the latter inaccessible. */
+  if (!rb_is_global_id(rb_intern(str)) || atoi(str + 1) > 0)
+    rb_raise(rb_eNameError, error_msg, str);
+
+  rb_hash_aset(getters, var, getter);
+  rb_hash_aset(setters, var, setter);
+  rb_define_virtual_variable(str, viva_getter, viva_setter);
+
+  return rb_str_intern(var);
+}
+
+void
+Init_core()
+{
+  mViva = rb_define_module("Viva");
+  id_call = rb_intern("call");
+
+  rb_define_const(mViva, "Getters", getters = rb_hash_new());
+  rb_define_const(mViva, "Setters", setters = rb_hash_new());
+  rb_define_singleton_method(mViva, "define", viva_define, 3);
+}

data/ext/viva/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+
+create_makefile 'viva/core'

data/lib/viva.rb

@@ -0,0 +1,31 @@
+require 'viva/core'
+
+module Viva
+  module_function
+
+  def define_getter var
+    define var, proc, Setters["$#{var}"]
+  end
+
+  def define_setter var
+    define var, Getters["$#{var}"], proc
+  end
+
+  def undef_getter var
+    Getters.delete "$#{var}"
+  end
+
+  def undef_setter var
+    Setters.delete "$#{var}"
+  end
+
+  def - getter, &setter
+    define @var, getter, setter
+  end
+end
+
+module Kernel
+  module_function def Viva var
+    Viva.tap { |v| v.instance_variable_set :@var, var }
+  end
+end

data/lib/viva/version.rb

@@ -0,0 +1,3 @@
+module Viva
+  VERSION = '0.42.1337'
+end

data/spec/viva_spec.rb

@@ -0,0 +1,50 @@
+require 'minitest/autorun'
+require 'minitest/pride'
+require 'viva'
+
+describe Viva do
+  describe '.define' do
+    describe 'when given a valid virtual variable name' do
+      it 'should return its name as a globalized Symbol' do
+        [0, -4, '$', '-_', Viva, :*].each do |name|
+          expected = :"$#{name}"
+          Viva.define(name, nil, nil).must_equal expected
+        end
+      end
+    end
+
+    describe 'when given an invalid virtual variable name' do
+      it 'should complain and refrain (inaccessible < useless)' do
+        [1, -10, ' ', '_-', nil, :^,].each do |name|
+          -> { Viva.define name, nil, nil }.must_raise NameError
+        end
+      end
+    end
+
+    # NOTE: These next two specs are essentially identical.
+    # How does one verify that nonexistent code didn't run?
+
+    it 'should be able to create a getter with no setter' do
+      Viva.define :a, -> actual { actual * 2 }, nil
+      $a = 21
+      $a.must_equal 42
+    end
+
+    it 'should be able to create a setter with no getter' do
+      Viva.define :b, nil, -> actual { actual * 2 }
+      $b = 21
+      $b.must_equal 42
+    end
+  end
+
+  # This more or less runs the thing through its paces, so let's stop here.
+
+  it "should be able to emulate GCC's __COUNTER__ (with bonus reset)" do
+    c = -1
+    Viva(:COUNTER).--> { c += 1 } { |v| c = v }
+
+    Array.new(3) { $COUNTER }.must_equal [0, 1, 2]
+    $COUNTER = 10
+    Array.new(3) { $COUNTER }.must_equal [11, 12, 13]
+  end
+end

data/viva.gemspec

@@ -0,0 +1,16 @@
+$:.unshift File.expand_path '../lib', __FILE__
+require 'viva/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'viva'
+  s.version     = Viva::VERSION
+  s.author      = 'D.E. Akers'
+  s.email       = '0x0dea@gmail.com'
+
+  s.summary     = 'Viva exposes the virtual variable API to Ruby land.'
+  s.homepage    = 'https://github.com/0x0dea/viva'
+  s.license     = 'WTFPL'
+
+  s.files       = `git ls-files`.split
+  s.extensions  = %w[ext/viva/extconf.rb Rakefile]
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: viva
+version: !ruby/object:Gem::Version
+  version: 0.42.1337
+platform: ruby
+authors:
+- D.E. Akers
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-01-25 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: 0x0dea@gmail.com
+executables: []
+extensions:
+- ext/viva/extconf.rb
+- Rakefile
+extra_rdoc_files: []
+files:
+- CODE_OF_CONDUCT
+- LICENSE
+- README.md
+- Rakefile
+- examples/counter.rb
+- examples/mol.rb
+- examples/pid.rb
+- examples/random.rb
+- ext/viva/core.c
+- ext/viva/extconf.rb
+- lib/viva.rb
+- lib/viva/version.rb
+- spec/viva_spec.rb
+- viva.gemspec
+homepage: https://github.com/0x0dea/viva
+licenses:
+- WTFPL
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Viva exposes the virtual variable API to Ruby land.
+test_files: []