rixby 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc379f400b5e2b6213b52f64b4cc87c30138fab3f3ced3a0935b1e13a6a133ae
-  data.tar.gz: b6d14233a8f412d5a8de2bd9daa284e0a96ef22dd2c59e741909abe513bb186a
+  metadata.gz: ef6d5cf45dabe8f0517070a8d17ec40d31ed2c16f995730cd525bcaf241ebc9d
+  data.tar.gz: 7e16d744d8e27d45dd14862a6b6ece2b0ff235666599ef0477852181da3e2c17
 SHA512:
-  metadata.gz: 761bea6040e72373f4a2d58591b8b4240c8678bfd1ba60cd2b7c545e268c89caefd16a25a92df2cccce002d52545d1c1f864bc0faa758ec9e9c4d6e166784f40
-  data.tar.gz: 6bddb361c92dd554440bed262f621d0fdeb1c0ccf423915dab7787cde2e484d69dd9b25e0ed2eb2b40c5b2fc54e38f99e4d866ac762b3f64d446db1f2c1aafd7
+  metadata.gz: 86d9731737f512720ff0d59e266acf398a21181a2564cfd241eaa23749d8ec50c3cadd24f7fa5135b1107ab466516b35f59b7e239c1e082861dd5954919a2ed3
+  data.tar.gz: 8cfb9f99b2373cb875ced2f399bc53f2aabf834759681e7be1e7adfdff3a79cefe1ab386b1dc2f4cafaeea35a3a203c73b136fdce277b53e3f52db5747186155

data/README.md

@@ -42,6 +42,8 @@ p unit_square
 
 </tr>
 
+</table>
+
 > [!TIP]
 > For a more complete example, see the `example` directory.
 > Start from `canvas.rb`.

data/lib/ixby.rb

@@ -1 +1,6 @@
 require 'rixby'
+
+# Back in the day, you had to activate RubyGems by passing `-rubygems`.
+# This was really `-r` (for `require`) on a gem called `ubygems`, which was an alias for `rubygems`.
+#
+# This is a similar hack!

data/lib/rixby/version.rb

@@ -1,3 +1,3 @@
 module Rixby
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

data/lib/rixby.rb

@@ -6,10 +6,29 @@ if Ruby::Box.current == Ruby::Box.main
   Ruby::Box.main.instance_variable_set(:@__rixby_boxes, {})
 end
 
+# Import items from a file.
+#
+# Requires a block in one of the following two forms:
+#
+#   1. Import particular items from the file (which must be `export`-ed):
+#      ```
+#      import { from 'file', :a, :b, :c }
+#      ```
+#
+#   2. Import everything which was `export`-ed from the file:
+#      ```
+#      import { all: 'file' }
+#      ```
+#
+# Imports are only visible to the current file.
+# Files which import this file will not see the same imports.
+#
 def import(&blk)
   unless block_given?
     raise 'you must pass a block to `import` describing the items to import'
   end
+
+  # The syntax uses a block specifically so that we can pinch the binding, and define new things in it
   block_binding = blk.binding
 
   import_desc = Rixby::ImportDsl.evaluate(&blk)
@@ -23,13 +42,16 @@ def import(&blk)
     absolute_filename += '.rb'
   end
 
+  # Only import each file into a box once.
+  # Otherwise we'll end up with a new definition of each class every time we import something, and
+  # they won't compare equally.
   imported_boxes = Ruby::Box.main.instance_variable_get(:@__rixby_boxes)
   if imported_boxes.has_key?(absolute_filename)
     box = imported_boxes[absolute_filename]
   else
     box = Ruby::Box.new
     box.instance_variable_set(:@__rixby_imported, true)
-    box.require(__FILE__)
+    box.require(__FILE__) # Enable `import`/`export` in that file too
     box.require(absolute_filename)
     imported_boxes[absolute_filename] = box
   end
@@ -44,6 +66,7 @@ def import(&blk)
     raise 'internal error: malformed import array'
   end
 
+  # Copy imports into the current scope.
   imports.each do |import|
     export = exports[import] or raise(KeyError, "no export named `#{import}`")
 
@@ -58,6 +81,20 @@ def import(&blk)
   end
 end
 
+# Export an item from this file, so it's visible to `import`.
+#
+# Call either on a method definition, or from within a class/module:
+#
+# ```
+# export def something
+#   # ...
+# end
+#
+# class Foobar export
+#   # ...
+# end
+# ```
+#
 def export(item)
   # If this file isn't being imported, we can ignore `export`.
   # This is relevant if you `export` from the main file, where `singleton_method` doesn't seem to be
@@ -86,8 +123,9 @@ def export(item)
   exports = box.instance_variable_get(:@__rixby_exports)
   exports[key] = value
 end
-EXPORT_METHOD = method(:export)
 
+# Enables `export` to be called from within a class or module to export that item
+EXPORT_METHOD = method(:export)
 Module.define_method(:export) do
   EXPORT_METHOD.(self)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rixby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Aaron Christiansen
@@ -17,7 +17,6 @@ extra_rdoc_files: []
 files:
 - ".tool-versions"
 - LICENSE
-- NOTES.md
 - README.md
 - example/assertion.rb
 - example/canvas.rb

data/NOTES.md

@@ -1,16 +0,0 @@
-explicit export is vital so you don't throw out all of your imports as exports
-
-the idea doesn't really work without this
-
-```ruby
-export def x
-
-end
-
-export class X
-
-end
-
-export 3, as: Something
-```
-