asobi 0.1.0

data/lib/asobi/pure.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# The core of asobi, without touching Ruby itself: no to_art on Integer,
+# no shape words on Object. Write Asobi.circle(...) and Asobi.art(8).
+require_relative "version"
+require_relative "messages"
+require_relative "geometry"
+require_relative "color"
+require_relative "random"
+require_relative "shapes"
+require_relative "art"
+require_relative "nodes"
+require_relative "many"
+require_relative "svg"
+
+# Parts that live in their own files: pictures in motion, and the reel a
+# browser plays. Neither touches Ruby's own classes.
+%w[motion reel].each do |part|
+  path = File.join(__dir__, "#{part}.rb")
+  require path if File.exist?(path)
+end

data/lib/asobi/random.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Asobi
+  # Randomness with a memory.
+  #
+  # Without seed:, every run of a sketch looks different. But within one run
+  # the picture stays put: the live view re-evaluates the sketch on every
+  # save, and the dots must not jump around each time.
+  #
+  # So one "session seed" is picked when the program starts. Each evaluation
+  # of a sketch begins with reset_calls!, and the n-th seedless random word
+  # in that evaluation gets a seed made from (session seed, n).
+  module Random
+    MASK = (1 << 64) - 1
+    MIX = 0x9E3779B97F4A7C15 # odd constant, spreads consecutive counts apart
+
+    @session_seed = ::Random.new_seed & MASK
+    @calls = 0
+
+    class << self
+      attr_reader :session_seed, :calls
+
+      # Fix the session seed (for tests, or to reproduce a run).
+      def session_seed=(seed)
+        @session_seed = Integer(seed) & MASK
+        @calls = 0
+      end
+
+      # Start counting from zero again; called before each sketch evaluation.
+      def reset_calls!
+        @calls = 0
+      end
+
+      # The seed for the next seedless call.
+      def next_seed
+        seed = (@session_seed ^ ((@calls + 1) * MIX)) & MASK
+        @calls += 1
+        seed
+      end
+
+      # A generator: from the explicit seed when there is one, otherwise
+      # from the session seed and the call count.
+      def generator(seed = nil)
+        return ::Random.new(next_seed) if seed.nil?
+        raise Messages.error(ArgumentError, :bad_seed, got: seed.inspect) unless seed.is_a?(Integer)
+
+        ::Random.new(seed)
+      end
+    end
+  end
+end

data/lib/asobi/reel.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Asobi
+  # The reel is what the browser plays (DESIGN.md section 9): a list of SVG
+  # fragments, how fast to play them, the viewBox, the background colour and
+  # (for the live view) the code and any error.
+  #
+  # Pure Ruby on purpose: no sockets, threads or file watching, so it also
+  # runs inside ruby.wasm.
+  module Reel
+    MAX_FRAMES = 900
+    PLAYER = File.join(__dir__, "web", "player.js")
+
+    module_function
+
+    # A Hash that JSON.generate turns into the Reel contract.
+    #
+    #   Reel.of(flower)                         one frame, fps 1
+    #   Reel.of(flower.spin(every: 4), fps: 30) 120 frames
+    #   Reel.of(flower, grain: true)            fine grain on every frame
+    #
+    # Grain is a small constant fragment (a noise filter and one rectangle
+    # over the view) added to the end of every frame, so the player needs
+    # nothing new and the grain stays still while the picture moves.
+    def of(thing, fps: 30, on: :white, paper: nil, code: nil, grain: nil)
+      background = Color.css(on)
+      strength = SVG.grain_strength(grain)
+      if motion?(thing)
+        frames, fps = motion_frames(thing, fps)
+        boxes = frames.map { |art| art.box(IDENTITY) }
+        svgs = frames.map(&:svg)
+        box = Box.union(boxes)
+      else
+        art = Asobi.art(thing)
+        svgs = [art.svg]
+        fps = 1
+        box = art.box(IDENTITY)
+      end
+      view = SVG.view(box, paper:).map { _1.to_f.round(3) }
+      if strength
+        noise = SVG.grain(view, strength)
+        svgs = svgs.map { _1 + noise }
+      end
+      { "frames" => svgs, "fps" => fps, "view" => view, "background" => background, "code" => code, "error" => nil }
+    end
+
+    # What the screen shows when the sketch is broken.
+    def error(message, code: nil) = { "error" => message.to_s, "code" => code }
+
+    # A complete page that plays the reel by itself, full window.
+    def html(thing, title: "asobi", **options)
+      reel = thing.is_a?(Hash) && thing.key?("frames") ? thing : of(thing, **options)
+      page(reel, title)
+    end
+
+    def save(thing, path, **options)
+      File.write(path.to_s, html(thing, **options), encoding: "UTF-8")
+      path
+    end
+
+    # The player program, safe to put between <script> tags.
+    def player_js = File.read(PLAYER, encoding: "UTF-8").gsub("</script", "<\\/script")
+
+    # JSON that can sit inside a <script> tag: "<" never appears raw.
+    def script_json(data) = JSON.generate(data).gsub("<", "\\u003c")
+
+    def motion?(thing) = thing.respond_to?(:at) && thing.respond_to?(:every)
+
+    # One loop of a motion: [pictures, fps]. The pictures are spread evenly
+    # over exactly one loop (frame i is at every * i / count seconds, as in
+    # Motion#frames), so the last frame leads straight back to the first.
+    # The fps reported is count / every: an Integer when it is whole, else a
+    # Float. Never more than MAX_FRAMES; a longer loop gets a lower fps.
+    def motion_frames(motion, fps)
+      fps = Check.whole(fps, word: :save, name: :fps, example: "save(\"flower.html\", fps: 30)", min: 1)
+      every = Check.number(motion.every, word: :every, name: :every, example: "spin(every: 4)", min: 0)
+      return [[Asobi.art(motion.at(0))], 1] unless every.positive?
+
+      count = ((every * fps).round).clamp(1, MAX_FRAMES)
+      frames = Array.new(count) { |i| Asobi.art(motion.at(every * i / count)) }
+      rate = count / every
+      [frames, (rate - rate.round).abs < 1e-9 ? rate.round : rate]
+    end
+
+    def page(reel, title)
+      <<~HTML
+        <!doctype html>
+        <html>
+        <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>#{Asobi.escape(title)}</title>
+        <style>
+          html, body { margin: 0; height: 100%; overflow: hidden; }
+          #stage { position: fixed; inset: 0; }
+        </style>
+        </head>
+        <body>
+        <div id="stage"></div>
+        <script>#{player_js}</script>
+        <script>
+          AsobiPlayer.mount(document.getElementById("stage")).update(#{script_json(reel)});
+        </script>
+        </body>
+        </html>
+      HTML
+    end
+  end
+
+  Art::SAVERS[".html"] = ->(art, path, **options) { Reel.save(art, path, **options) }
+end

data/lib/asobi/shapes.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+
+module Asobi
+  # The words that make shapes. Each answers a picture centred on the
+  # origin; none of them draws anything. Every number may be left out, and
+  # the first one may be given without its name:
+  #
+  #   circle                  radius 10
+  #   circle(radius: 12)      or, once you know it,  circle(12)
+  #
+  # With require "asobi" they work everywhere, like puts. With
+  # require "asobi/pure" write Asobi.circle(...).
+  module Shapes
+    def circle(radius_ = nil, radius: radius_ || 10)
+      Circle.new(Shapes.size(radius, :circle, :radius, "circle(radius: 10)"))
+    end
+
+    def ellipse(width_ = nil, height_ = nil, width: width_ || 30, height: height_ || 20)
+      w = Shapes.size(width, :ellipse, :width, "ellipse(width: 30, height: 20)")
+      h = Shapes.size(height, :ellipse, :height, "ellipse(width: 30, height: 20)")
+      Ellipse.new(w / 2.0, h / 2.0)
+    end
+
+    def rect(width_ = nil, height_ = nil, width: width_ || 30, height: height_ || 20)
+      w = Shapes.size(width, :rect, :width, "rect(width: 30, height: 20)")
+      h = Shapes.size(height, :rect, :height, "rect(width: 30, height: 20)")
+      Rect.new(w, h)
+    end
+
+    def square(size_ = nil, size: size_ || 20)
+      s = Shapes.size(size, :square, :size, "square(size: 20)")
+      Rect.new(s, s)
+    end
+
+    # Equilateral, pointing up; +size+ is the length of a side. Centred on
+    # its bounding box, so it lines up with other shapes.
+    def triangle(size_ = nil, size: size_ || 20)
+      s = Shapes.size(size, :triangle, :size, "triangle(size: 20)")
+      h = s * Math.sqrt(3) / 2
+      Path.polyline([[0.0, -h / 2], [s / 2.0, h / 2], [-s / 2.0, h / 2]], closed: true)
+    end
+
+    # +sides+ equal sides, one corner pointing straight up.
+    def polygon(sides_ = nil, radius_ = nil, sides: sides_ || 6, radius: radius_ || 10)
+      n = Check.whole(sides, word: :polygon, name: :sides, example: "polygon(sides: 6)", min: 3)
+      r = Shapes.size(radius, :polygon, :radius, "polygon(sides: 6, radius: 10)")
+      Path.polyline(Array.new(n) { |i| Geometry.polar(r, i * 360.0 / n) }, closed: true)
+    end
+
+    def star(points_ = nil, radius_ = nil, points: points_ || 5, radius: radius_ || 10, inner: nil)
+      n = Check.whole(points, word: :star, name: :points, example: "star(points: 5)", min: 2)
+      r = Shapes.size(radius, :star, :radius, "star(points: 5, radius: 10)")
+      inner = Shapes.size(inner || r * 0.45, :star, :inner, "star(radius: 10, inner: 4)")
+      corners = Array.new(n * 2) { |i| Geometry.polar(i.even? ? r : inner, i * 180.0 / n) }
+      Path.polyline(corners, closed: true)
+    end
+
+    # A straight black line lying flat.
+    def line(length_ = nil, length: length_ || 20)
+      l = Shapes.size(length, :line, :length, "line(length: 20)")
+      Path.polyline([[-l / 2, 0.0], [l / 2, 0.0]]).outlined(:black, width: 1)
+    end
+
+    def text(string = "asobi", size: 16, font: nil)
+      Text.new(string.to_s, Shapes.size(size, :text, :size, "text(\"ruby\", size: 16)"), font)
+    end
+
+    # Joins the points in order, centred on the origin.
+    #   path([0, 0], [40, -30], [80, 0])                 an open line
+    #   path([0, 0], [40, -30], [80, 0], closed: true)   a filled shape
+    #   path(..., smooth: true)                          a smooth curve
+    def path(*points, closed: false, smooth: false)
+      points = points.first if points.size == 1 && points.first.is_a?(Array) && points.first.first.is_a?(Array)
+      points = [[0, 0], [40, -30], [80, 0]] if points.empty?
+      points = Shapes.points(points)
+      cx = (points.map(&:first).minmax.sum) / 2.0
+      cy = (points.map(&:last).minmax.sum) / 2.0
+      points = points.map { |x, y| [x - cx, y - cy] }
+      shape = smooth ? Path.smooth(points, closed:) : Path.polyline(points, closed:)
+      closed ? shape : shape.outlined(:black, width: 1)
+    end
+
+    # A piece of a circle, drawn as a line. Angles are in degrees: 0 is
+    # straight up, and they grow clockwise, so 0 to 180 is the right half.
+    # Centred on the middle of its circle, so arcs of one circle line up.
+    #   arc                          the right half of a circle
+    #   arc(30, from: 90, to: 360)   three quarters
+    #   arc(from: 0, to: 360)        a whole circle (as a line)
+    def arc(radius_ = nil, radius: radius_ || 20, from: 0, to: 180)
+      r = Shapes.size(radius, :arc, :radius, "arc(radius: 20, from: 0, to: 180)")
+      a = Check.number(from, word: :arc, name: :from, example: "arc(from: 0, to: 180)")
+      b = Check.number(to, word: :arc, name: :to, example: "arc(from: 0, to: 180)")
+      Path.build do |pen|
+        pen.move(*Geometry.polar(r, a))
+        Shapes.arc_to(pen, 0.0, 0.0, r, a, b)
+      end.outlined(:black, width: 1)
+    end
+
+    # A smooth line lying flat: +waves+ full ups and downs across +length+,
+    # +height+ from the top of a crest to the bottom of a trough.
+    def wave(length_ = nil, height_ = nil, waves_ = nil,
+             length: length_ || 100, height: height_ || 10, waves: waves_ || 3)
+      example = "wave(length: 100, height: 10, waves: 3)"
+      l = Shapes.size(length, :wave, :length, example)
+      h = Shapes.size(height, :wave, :height, example)
+      w = Check.number(waves, word: :wave, name: :waves, example:, min: 0)
+      halves = [(w * 2).round, 1].max
+      step = l / halves
+      amp = h / 2.0
+      Path.build do |pen|
+        pen.move(-l / 2, 0.0)
+        halves.times do |i|
+          x0 = -l / 2 + i * step
+          y = (i.even? ? -1 : 1) * amp * 4.0 / 3
+          pen.curve(x0 + step * 0.4244, y, x0 + step * 0.5756, y, x0 + step, 0.0)
+        end
+      end.outlined(:black, width: 1)
+    end
+
+    # A doughnut; the hole really is a hole, so what is behind shows through.
+    def ring(radius_ = nil, thickness_ = nil, radius: radius_ || 20, thickness: thickness_ || 4)
+      example = "ring(radius: 20, thickness: 4)"
+      r = Shapes.size(radius, :ring, :radius, example)
+      t = Shapes.size(thickness, :ring, :thickness, example)
+      return Circle.new(r) if t >= r
+
+      Path.build(fill_rule: :evenodd) do |pen|
+        [r, r - t].each do |radius_here|
+          pen.move(0.0, -radius_here)
+          Shapes.arc_to(pen, 0.0, 0.0, radius_here, 0, 360)
+          pen.close
+        end
+      end
+    end
+
+    # +size+ is the width of the whole heart.
+    def heart(size_ = nil, size: size_ || 20)
+      s = Shapes.size(size, :heart, :size, "heart(size: 20)")
+      half = [
+        [0.0, 0.95], [-0.2, 0.75, -1.0, 0.25, -1.0, -0.28],
+        [-1.0, -0.72, -0.68, -0.95, -0.38, -0.95],
+        [-0.18, -0.95, -0.05, -0.82, 0.0, -0.62]
+      ]
+      Shapes.fit(Shapes.mirrored(half), width: s)
+    end
+
+    # A leaf that starts at the origin and grows straight up, so
+    # petal.repeat(8).in_fan is already a flower.
+    def petal(length_ = nil, width_ = nil, length: length_ || 20, width: width_ || 10)
+      example = "petal(length: 20, width: 10)"
+      l = Shapes.size(length, :petal, :length, example)
+      w = Shapes.size(width, :petal, :width, example)
+      raw = Path.build do |pen|
+        pen.move(0.0, 0.0)
+        pen.curve(-1.0, -0.15, -0.8, -0.75, 0.0, -1.0)
+        pen.curve(0.8, -0.75, 1.0, -0.15, 0.0, 0.0)
+        pen.close
+      end
+      box = raw.box(IDENTITY)
+      Shapes.map_path(raw) { |x, y| [x * w / box.width, y * l] }
+    end
+
+    # A crescent opening to the right; +size+ is its height.
+    def moon(size_ = nil, size: size_ || 20)
+      s = Shapes.size(size, :moon, :size, "moon(size: 20)")
+      d = 0.45
+      inner = 0.8
+      x = (d * d + 1 - inner * inner) / (2 * d) # where the two circles cross
+      tip = Math.asin(x) * 180 / Math::PI
+      back = Math.asin((x - d) / inner) * 180 / Math::PI
+      raw = Path.build do |pen|
+        pen.move(*Geometry.polar(1.0, tip))
+        Shapes.arc_to(pen, 0.0, 0.0, 1.0, tip, -180 - tip)
+        Shapes.arc_to(pen, d, 0.0, inner, 180 - back, 360 + back)
+        pen.close
+      end
+      Shapes.fit(raw.commands, height: s)
+    end
+
+    # A water drop, point up; +size+ is its height.
+    def drop(size_ = nil, size: size_ || 20)
+      s = Shapes.size(size, :drop, :size, "drop(size: 20)")
+      raw = Path.build do |pen|
+        pen.move(0.0, -1.0)
+        pen.curve(0.1, -0.65, 0.7, -0.3, 0.7, 0.3)
+        Shapes.arc_to(pen, 0.0, 0.3, 0.7, 90, 270)
+        pen.curve(-0.7, -0.3, -0.1, -0.65, 0.0, -1.0)
+        pen.close
+      end
+      Shapes.fit(raw.commands, height: s)
+    end
+
+    # One outline of soft bumps over a flat bottom; +size+ is its width.
+    def cloud(size_ = nil, size: size_ || 30)
+      s = Shapes.size(size, :cloud, :size, "cloud(size: 30)")
+      Shapes.fit(Shapes.cloud_outline(Shapes::CLOUD_BUMPS), width: s)
+    end
+
+    # Invisible, but takes up room.
+    def space(width_ = nil, height_ = nil, width: width_ || 10, height: height_ || width)
+      w = Shapes.size(width, :space, :width, "space(width: 10)")
+      h = Shapes.size(height, :space, :height, "space(width: 10, height: 20)")
+      Space.new(w, h)
+    end
+
+    # The empty picture.
+    def nothing = Many.new([])
+
+    # hue in degrees (0..360), saturation and lightness 0..100.
+    def hsl(hue = 0, saturation = 70, lightness = 50) = Color.hsl(hue, saturation, lightness)
+
+    # 0 is black, 100 is white.
+    def gray(lightness = 50) = Color.gray(lightness)
+
+    WORDS = instance_methods(false).freeze
+
+    # Circles [x, y, radius] for cloud, left to right, all resting on y = 0.
+    CLOUD_BUMPS = [[-0.62, -0.3, 0.3], [-0.2, -0.45, 0.45], [0.3, -0.38, 0.38], [0.68, -0.28, 0.28]].freeze
+
+    # Adds the arc of a circle (centre cx, cy) from one angle to another as
+    # cubic curves of at most 90 degrees each. The pen must already be at
+    # the start.
+    def self.arc_to(pen, cx, cy, r, from, to)
+      span = (to - from).to_f
+      pieces = [(span.abs / 90.0 - 1e-9).ceil, 1].max
+      theta = span / pieces * Math::PI / 180
+      k = 4.0 / 3 * Math.tan(theta / 4)
+      pieces.times do |i|
+        a0 = (from + span / pieces * i) * Math::PI / 180
+        a1 = a0 + theta
+        pen.curve(cx + r * (Math.sin(a0) + k * Math.cos(a0)), cy + r * (-Math.cos(a0) + k * Math.sin(a0)),
+                  cx + r * (Math.sin(a1) - k * Math.cos(a1)), cy + r * (-Math.cos(a1) - k * Math.sin(a1)),
+                  cx + r * Math.sin(a1), cy - r * Math.cos(a1))
+      end
+    end
+
+    # The left half of a symmetric outline, given as [x, y] (move) and
+    # [c1x, c1y, c2x, c2y, x, y] (curve) from the bottom up to the middle
+    # top, becomes the whole outline.
+    def self.mirrored(half)
+      move, *curves = half
+      [[:move, *move]] + curves.map { [:cubic, *_1] } + mirror_tail(curves, move) + [[:close]]
+    end
+
+    def self.mirror_tail(curves, move)
+      pts = [move, *curves.map { _1[-2, 2] }]
+      curves.each_index.reverse_each.map do |i|
+        c = curves[i]
+        [:cubic, -c[2], c[3], -c[0], c[1], -pts[i][0], pts[i][1]]
+      end
+    end
+
+    # Scales commands evenly to the given width or height and centres them
+    # on the origin.
+    def self.fit(commands, width: nil, height: nil)
+      raw = Path.new(commands:, fill_rule: :nonzero)
+      box = raw.box(IDENTITY)
+      k = width ? width / box.width : height / box.height
+      map_path(raw) { |x, y| [(x - box.cx) * k, (y - box.cy) * k] }
+    end
+
+    def self.map_path(path)
+      commands = path.commands.map do |name, *n|
+        [name, *n.each_slice(2).flat_map { |x, y| yield(x, y) }]
+      end
+      Path.new(commands:, fill_rule: path.fill_rule)
+    end
+
+    def self.cloud_outline(bumps)
+      pen = Path::Pen.new
+      cuts = bumps.each_cons(2).map { |a, b| upper_crossing(a, b) }
+      bumps.each_with_index do |(cx, cy, r), i|
+        from = i.zero? ? 180.0 : angle(cx, cy, *cuts[i - 1])
+        to = i == bumps.size - 1 ? 180.0 : angle(cx, cy, *cuts[i])
+        to += 360 while to <= from
+        pen.move(*Geometry.polar(r, from).then { |x, y| [cx + x, cy + y] }) if i.zero?
+        arc_to(pen, cx, cy, r, from, to)
+      end
+      pen.close
+      pen.commands
+    end
+
+    def self.angle(cx, cy, x, y) = Math.atan2(x - cx, cy - y) * 180 / Math::PI
+
+    def self.upper_crossing(a, b)
+      dx = b[0] - a[0]
+      dy = b[1] - a[1]
+      d = Math.hypot(dx, dy)
+      along = (a[2]**2 - b[2]**2 + d * d) / (2 * d)
+      h = Math.sqrt([a[2]**2 - along**2, 0].max)
+      [a[0] + (along * dx - h * dy) / d, a[1] + (along * dy + h * dx) / d].then do |p1|
+        q = [a[0] + (along * dx + h * dy) / d, a[1] + (along * dy - h * dx) / d]
+        p1[1] < q[1] ? p1 : q
+      end
+    end
+
+    def self.size(value, word, name, example) = Check.number(value, word:, name:, example:, min: 0)
+
+    def self.points(list)
+      clean = list.map do |point|
+        ok = point.is_a?(Array) && point.size == 2 && point.all? { Check.number?(_1) }
+        raise Messages.error(ArgumentError, :bad_point, got: point.inspect) unless ok
+
+        point.map(&:to_f)
+      end
+      raise Messages.error(ArgumentError, :few_points, got: clean.size) if clean.size < 2
+
+      clean
+    end
+  end
+
+  # Asobi.circle(...) and friends, for require "asobi/pure".
+  extend Shapes
+end