asterism 0.8.0 → 0.9.0

data/lib/asterism/cli/nouns.rb

@@ -0,0 +1,396 @@
+# The noun-verb commands of the command line (node, app, object, status:
+# lib/asterism/cli.rb's NOUNS), `completion` and the hidden `__complete`
+# (lib/asterism/cli/complete.rb).
+module Asterism
+  class CLI
+    # ------------------------------------------------------------ node
+
+    def cmd_node_list(_rest)
+      connect do |_net, sv|
+        names = sv.nodes
+        structured? ? emit(names) : names.each { @out.puts paint(_1, :node) }
+      end
+      0
+    end
+
+    def cmd_node_info(rest)
+      node = rest.shift
+      raise ArgumentError, "node info: which node? (asterism node info NODE)" unless node && !node.empty?
+      raise ArgumentError, "node info: NODE is a node's name (no /)" if node.include?("/")
+      code = 0
+      connect do |_net, sv|
+        entry = sv.tree(node: node).first
+        if entry.nil?
+          @err.puts "asterism: no node #{node} is visible"
+          code = 1
+        elsif structured?
+          emit(entry)
+        else
+          @out.puts paint(entry["node"], :node)
+          if entry["profile"]
+            pr = entry["profile"].except("icon")
+            Text.wrap(pr.map { |k, v| Text.pair(k, v) }, style.width, first: "  #{paint('profile:', :note)} ",
+                                                                       rest: "    ", break_long: false)
+                .each { @out.puts _1 }
+          end
+          entry["apps"].each { |a| app_block(a["app"], a, 2) }
+        end
+      end
+      code
+    end
+
+    # ------------------------------------------------------------ app
+
+    def cmd_app_list(_rest)
+      connect do |_net, sv|
+        names = sv.apps
+        structured? ? emit(names) : names.each { @out.puts paint_path(_1) }
+      end
+      0
+    end
+
+    def cmd_app_info(rest)
+      node, app = app_path!(rest, "app info").split("/")
+      code = 0
+      connect do |_net, sv|
+        a = sv.tree(node: node, app: app).first&.dig("apps")&.find { _1["app"] == app }
+        if a.nil?
+          @err.puts "asterism: no application #{node}/#{app} is visible"
+          code = 1
+        elsif structured?
+          emit({ "node" => node }.merge(a))
+        else
+          app_block("#{node}/#{app}", a, 0)
+        end
+      end
+      code
+    end
+
+    # ------------------------------------------------------------ object
+
+    def cmd_object_list(rest)
+      pattern = rest.shift || "**"
+      connect do |_net, sv|
+        paths = sv.objects(pattern)
+        structured? ? emit(paths) : paths.each { @out.puts paint_path(_1) }
+      end
+      0
+    end
+
+    def cmd_object_info(rest)
+      path = rest.shift
+      unless path && path.split("/", -1).size == 3 && path.split("/").none? { _1.empty? || _1.include?("*") }
+        raise ArgumentError, "object info: PATH is node/app/object (a pattern: asterism object list PATTERN)"
+      end
+      code = 0
+      connect do |_net, sv|
+        if sv.objects(path).empty?
+          @err.puts "asterism: no object #{path} is visible"
+          code = 1
+          next
+        end
+        methods = sv.metas([path])[path]
+        if structured?
+          h = { "path" => path, "methods" => methods }
+          h["doc"] = sv.object_doc(path) if sv.object_doc(path)
+          emit(h)
+        else
+          object_entry(path, methods, sv.object_doc(path))
+        end
+      end
+      code
+    end
+
+    def cmd_object_find(rest)
+      want = rest.shift
+      raise ArgumentError, "object find: which method? (asterism object find METHOD; * as a wildcard)" unless want
+      found = []
+      connect do |_net, sv|
+        paths = sv.objects
+        metas = sv.metas(paths)
+        paths.each do |p|
+          ms = (metas[p] || []).select { File.fnmatch?(want, _1["name"]) }
+          found << { "path" => p, "methods" => ms } unless ms.empty?
+        end
+        structured? ? emit(found) : found.each { @out.puts paint_path(_1["path"]) }
+      end
+      0
+    end
+
+    # ------------------------------------------------------------ status
+
+    def cmd_status_get(rest)
+      path = app_path!(rest, "status get")
+      code = 0
+      connect do |_net, sv|
+        st = sv.statuses([path])[path]
+        if st.nil?
+          @err.puts no_status(path)
+          code = 1
+        elsif structured?
+          emit(json_safe(st))
+        else
+          Text.status_lines(json_safe(st), style.width).each { @out.puts _1 }
+        end
+      end
+      code
+    end
+
+    # The status, then each change as it comes (the text: what changed, as
+    # watch tells it); --once: the status now, once.
+    def cmd_status_echo(rest)
+      path = app_path!(rest, "status echo")
+      code = 0
+      connect do |net, sv|
+        q = Queue.new
+        subscribe_status(net, path) { |st| q << [Time.now, st] } unless @opts[:once]
+        st = sv.statuses([path])[path]
+        if st
+          echo_event(Time.now, path, st, true)
+        elsif @opts[:once]
+          @err.puts no_status(path)
+          code = 1
+        end
+        next if @opts[:once]
+
+        until_stopped(net) do |left|
+          got = q.pop(timeout: [left || 0.2, 0.2].min)
+          echo_event(got[0], path, got[1], false) if got
+        end
+      end
+      code
+    end
+
+    # How often the status changes: every --period, when a change came, the
+    # average rate and the intervals (Hz).
+    def cmd_status_hz(rest)
+      path = app_path!(rest, "status hz")
+      raise ArgumentError, "--window: 1 or more" unless @opts[:window].positive?
+      raise ArgumentError, "--period: more than 0" unless @opts[:period].positive?
+      connect do |net, sv|
+        hz = Hz.new(window: @opts[:window])
+        lock = Mutex.new
+        subscribe_status(net, path) { |st| lock.synchronize { hz.put(st) } }
+        st = sv.statuses([path])[path]
+        lock.synchronize { hz.seed(st) } if st
+        @err.puts "asterism: #{path}: counting the status's changes (Ctrl-C to stop)" unless structured?
+        nxt = now + @opts[:period]
+        until_stopped(net) do |_left|
+          sleep 0.05
+          next if now < nxt
+          nxt += @opts[:period]
+          s = lock.synchronize { hz.report }
+          next unless s
+          if structured?
+            emit_line({ "t" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"), "path" => path }.merge(s))
+          else
+            Hz.text(s).each { @out.puts _1 }
+          end
+          @out.flush
+        end
+      end
+      0
+    end
+
+    # ------------------------------------------------------------ completion
+
+    def cmd_completion(rest)
+      case rest.shift
+      when "bash" then @out.write(Complete::BASH)
+      when "zsh" then @out.write(Complete::ZSH)
+      else raise ArgumentError, "completion: bash or zsh (source <(asterism completion bash))"
+      end
+      0
+    end
+
+    # The candidates for the word being completed, one a line. The words
+    # come as arguments (the last one the word being completed), after
+    # "--"; or (--bash LINE) as bash's line up to the cursor.
+    def cmd_complete(argv)
+      bash = argv.first == "--bash"
+      words = if bash
+                Complete.split_line(argv[1].to_s)
+              else
+                argv.first == "--" ? argv.drop(1) : argv
+              end
+      words = [""] if words.empty?
+      @complete_words = words
+      cands = Complete.new(self, CompleteSource.new(self, words)).candidates(words)
+      cands = Complete.bash_trim(cands, words.last) if bash && cands != [Complete::FILES]
+      cands.each { @out.puts _1 }
+      @out.flush
+      # A connection still trying past the budget is left behind: the
+      # process ends without waiting for it.
+      Process.exit!(0) if @complete_abandoned
+      0
+    end
+
+    # What __complete asks the network for, through the cache: the names
+    # (the tokens) and an object's methods (its meta).
+    class CompleteSource
+      def initialize(cli, words)
+        @cli = cli
+        @words = words
+      end
+
+      def names
+        cached("names") do
+          @cli.complete_fetch { |sv| { "apps" => sv.apps, "objects" => sv.objects } }
+        end
+      end
+
+      def methods(path)
+        cached("methods #{path}") do
+          @cli.complete_fetch { |sv| sv.metas([path])[path]&.map { _1["name"] } }
+        end
+      end
+
+      def all_methods
+        cached("methods") do
+          @cli.complete_fetch { |sv| sv.metas(sv.objects).values.flatten.map { _1["name"] }.uniq.sort }
+        end
+      end
+
+      private
+
+      def cached(entry, &blk)
+        net = @cli.complete_network(@words)
+        return nil if net.none?
+        dir = Complete::Cache.dir(@cli.env)
+        return blk.call unless dir
+        Complete::Cache.new(dir: dir, network: net).fetch(entry, &blk)
+      end
+    end
+
+    attr_reader :env
+
+    # Where the network is for __complete: the options among the words,
+    # else the environment (network). [router, credentials (its full path),
+    # peer]
+    def complete_network(words)
+      words.each_cons(2) do |a, b|
+        case a
+        when "--router" then @opts[:router] = b
+        when "--credentials" then @opts[:credentials] = b
+        when "--peer" then @opts[:peer] = b
+        end
+      end
+      r, c, pr = network
+      [r, c && File.expand_path(c), pr]
+    end
+
+    # Connects for at most Complete::BUDGET seconds and yields the Survey;
+    # the block's value, or nil when the network did not answer in time.
+    def complete_fetch
+      @opts[:settle] = 0.6
+      @opts[:timeout] = 0.6
+      out = Queue.new
+      th = Thread.new do
+        err = @err
+        @err = File.open(File::NULL, "w")
+        begin
+          connect { |_net, sv| out << yield(sv) }
+        rescue StandardError, ScriptError
+          out << nil
+        ensure
+          @err = err
+        end
+      end
+      v = out.pop(timeout: Complete::BUDGET)
+      if v.nil? && th.alive?
+        @complete_abandoned = true
+        return nil
+      end
+      th.join(0.5) || (@complete_abandoned = true)
+      v
+    end
+
+    # ------------------------------------------------------------ helpers
+
+    def app_path!(rest, what)
+      path = rest.shift
+      ok = path && path.split("/", -1).size == 2 && path.split("/").none? { _1.empty? || _1.include?("*") }
+      raise ArgumentError, "#{what}: which application? (asterism #{what} NODE/APP)" unless ok
+      path
+    end
+
+    def no_status(path)
+      "asterism: no status from #{path} (not there, no status, or no answer in time)"
+    end
+
+    # node/app[/object] painted part by part.
+    def paint_path(path)
+      parts = path.split("/")
+      roles = %i[node app object]
+      parts.each_with_index.map { |p, i| paint(p, roles[i] || :object) }.join(paint("/", :note))
+    end
+
+    # An application (a tree's entry) under its name: its status and its
+    # objects (how many methods, and the object's description).
+    def app_block(name, a, indent)
+      pad = " " * indent
+      @out.puts "#{pad}#{paint(name, :app)}"
+      status_block(a, indent + 2)
+      return if a["objects"].empty?
+      @out.puts "#{pad}  #{paint('objects:', :note)}"
+      a["objects"].each do |o|
+        ms = o["methods"]
+        @out.puts "#{pad}    #{paint(o['name'], :object)}  #{paint(ms ? count(ms.size, 'method') : '(no meta)', :note)}"
+        Text.wrap_text(o["doc"], style.width, first: "#{pad}      ").each { @out.puts _1 } if o["doc"]
+      end
+    end
+
+    # The status's puts of one application, cleaned (Status.parse).
+    def subscribe_status(net, path)
+      net.session.subscribe("asterism/#{path}/@status") do |sample|
+        got = ::Asterism::Status.parse(sample.key, sample.payload)
+        yield got[2] if got
+      end
+    end
+
+    # Yields until Ctrl-C, --duration or a lost connection (the seconds
+    # left of --duration, or nil).
+    def until_stopped(net)
+      deadline = @opts[:duration] && (now + @opts[:duration])
+      loop do
+        left = deadline && (deadline - now)
+        break if left && left <= 0
+        break unless net.connected?
+        yield left
+      end
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # One record of status echo: JSON / YAML, or the text (the status whole
+    # the first time, then a line for each change).
+    def echo_event(t, path, status, first)
+      status = json_safe(status)
+      if structured?
+        h = { "t" => t.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"), "path" => path, "status" => status }
+        h["now"] = true if first
+        emit_line(h)
+      else
+        text = echo_text(t, path, status, first)
+        @out.puts text if text
+      end
+      @out.flush
+    end
+
+    # The text of one record of status echo (nil: no change).
+    def echo_text(t, path, status, first)
+      head = "#{paint(t.strftime('%H:%M:%S.%L'), :time)} "
+      old = @echo_last
+      @echo_last = status
+      if first || !old.is_a?(Hash) || !status.is_a?(Hash)
+        lines = Text.status_lines(status, style.width, Text.width(head))
+        return "#{head}#{paint(path, :app)}#{paint(' (now)', :note) if first}\n#{lines.join("\n")}"
+      end
+      changes = Text.status_diff(old, status)
+      return nil if changes.empty?
+      changes.map { |c| "#{head}#{change_text(c)}" }.join("\n")
+    end
+  end
+end

data/lib/asterism/cli/survey.rb

@@ -115,10 +115,12 @@ module Asterism
 
       # The tree: [{"node", "profile", "apps" => [{"app", "status",
       # "objects" => [{"name", "methods"}]}]}]. meta: false leaves the
-      # methods out (no meta gets).
-      def tree(meta: true)
-        objs = objects
-        app_list = apps
+      # methods out (no meta gets); node: (and app:) narrow it to one node
+      # (one application).
+      def tree(meta: true, node: nil, app: nil)
+        scope = node && "#{node}/#{app || '*'}"
+        objs = scope ? objects("#{scope}/*") : objects
+        app_list = scope ? apps(scope) : apps
         threads = []
         node_list = (app_list.map { _1.split("/")[0] } + objs.map { _1.split("/")[0] }).uniq
         threads << Thread.new { profiles(node_list) }

data/lib/asterism/cli/text.rb

@@ -0,0 +1,256 @@
+# How the command line's text looks (not --json, which stays as it is):
+# colours and the terminal's width when the output is a terminal, plain
+# text 80 columns wide (or COLUMNS) otherwise; NO_COLOR turns the colours
+# off. Statuses are laid out as indented key=value lines, the methods and
+# the descriptions are wrapped to the width, and watch tells what changed
+# in a status. The standard library only (io/console for the width).
+require "json"
+
+module Asterism
+  class CLI
+    # Colours and width for one output.
+    class Style
+      CODES = { bold: 1, dim: 2, red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36 }.freeze
+      # What each kind of thing is painted with.
+      ROLES = {
+        node: %i[bold blue], app: [:cyan], object: [:green], method: [:bold], note: [:dim], time: [:dim],
+        join: [:green], leave: [:red], status: [:yellow], profile: [:magenta]
+      }.freeze
+      MIN_WIDTH = 20
+
+      attr_reader :width
+
+      def initialize(io, env = ENV)
+        tty = io.respond_to?(:tty?) && io.tty?
+        @color = tty && env["NO_COLOR"].to_s.empty?
+        w = (tty && terminal_width(io)) || env["COLUMNS"].to_i
+        @width = w.positive? ? [w, MIN_WIDTH].max : 80
+      end
+
+      def color?
+        @color
+      end
+
+      # text painted as role (a ROLES key) or with the CODES given.
+      def paint(text, *styles)
+        text = text.to_s
+        return text unless @color
+        codes = styles.flat_map { ROLES.fetch(_1, [_1]) }.map { CODES.fetch(_1) }
+        codes.empty? ? text : "\e[#{codes.join(';')}m#{text}\e[0m"
+      end
+
+      private
+
+      def terminal_width(io)
+        require "io/console"
+        w = io.winsize[1]
+        w.positive? ? w : nil
+      rescue StandardError, LoadError
+        nil
+      end
+    end
+
+    # Laying text out: display widths (East Asian wide characters take two
+    # columns), word wrapping, statuses and their differences.
+    module Text
+      module_function
+
+      ANSI = /\e\[[0-9;]*m/
+      # Code points that take two columns on a terminal (East Asian Wide and
+      # Fullwidth, roughly).
+      WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦\u{1F300}-\u{1F64F}\u{1F900}-\u{1F9FF}\u{20000}-\u{3FFFD}]/
+      # A string value longer than this (columns) is cut, and so is an
+      # array written on one line; --json has them whole.
+      LONG = 60
+      ARROW = "→"
+      ELLIPSIS = "…"
+
+      # The columns text takes on a terminal (colour codes take none).
+      def width(text)
+        s = text.to_s.gsub(ANSI, "")
+        s = s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless s.encoding == Encoding::UTF_8
+        s.scrub.each_char.sum { _1.match?(WIDE) ? 2 : 1 }
+      end
+
+      # The tokens joined with sep in lines at most cols columns wide: the
+      # first starts with first, the others with rest (spaces as wide as
+      # first by default). A plain token wider than a line is broken between
+      # characters (break_long: false keeps it whole, on a line of its own);
+      # a painted one (a method's signature) is kept whole. Returns the
+      # lines (at least one).
+      def wrap(tokens, cols, first: "", rest: nil, sep: " ", break_long: true)
+        rest ||= " " * width(first)
+        lines = []
+        line = first
+        lw = width(first)
+        empty = true
+        tokens.each do |tok|
+          tok = tok.to_s
+          tw = width(tok)
+          if !empty && lw + sep.size + tw > cols
+            lines << line
+            line = rest
+            lw = width(rest)
+            empty = true
+          end
+          while break_long && lw + tw > cols && !tok.match?(ANSI) && tok.size > 1
+            head, tail = split_width(tok, [cols - lw, 1].max)
+            break if tail.empty?
+            lines << (empty ? line : line + sep) + head
+            line = rest
+            lw = width(rest)
+            empty = true
+            tok = tail
+            tw = width(tok)
+          end
+          line += (empty ? "" : sep) + tok
+          lw += (empty ? 0 : sep.size) + tw
+          empty = false
+        end
+        lines << line
+        lines
+      end
+
+      # text's words wrapped (wrap), each paragraph (blank lines between)
+      # starting a new line with rest.
+      def wrap_text(text, cols, first: "", rest: nil)
+        rest ||= " " * width(first)
+        paras = text.to_s.strip.split(/\n\s*\n/).map(&:split).reject(&:empty?)
+        return [first.rstrip] if paras.empty?
+        paras.each_with_index.flat_map { |words, i| wrap(words, cols, first: i.zero? ? first : rest, rest: rest) }
+      end
+
+      # [the start of text no wider than cols (one character at least), the rest]
+      def split_width(text, cols)
+        w = 0
+        n = 0
+        text.each_char do |c|
+          cw = width(c)
+          break if n.positive? && w + cw > cols
+          w += cw
+          n += 1
+        end
+        [text[0, n], text[n..]]
+      end
+
+      # ------------------------------------------------------------ statuses
+
+      # A status (a Hash) as lines indented by indent spaces: the plain
+      # values of a level as key=value on one line (wrapped), a Hash of
+      # plain values as "key: k=v k=v", deeper ones as "key:" and their
+      # lines two spaces further in, an array with a Hash in it as "key:"
+      # and its elements as "- " lines. A key=value is never broken: one
+      # wider than the line has a line of its own (the terminal folds it).
+      def status_lines(h, cols, indent = 0)
+        pad = " " * indent
+        lines = []
+        flat = []
+        flush = lambda do
+          lines.concat(wrap(flat, cols, first: pad, break_long: false)) unless flat.empty?
+          flat = []
+        end
+        h.each do |k, v|
+          if plain?(v)
+            flat << pair(k, v)
+            next
+          end
+          flush.call
+          if v.is_a?(Hash) && v.empty?
+            lines << "#{pad}#{k}: {}"
+          elsif v.is_a?(Hash) && v.values.all? { plain?(_1) }
+            # The lines after the first under the first value (two spaces in
+            # when the key is long).
+            hang = width(k) + 2 > cols / 3 ? 2 : width(k) + 2
+            lines.concat(wrap(v.map { |kk, vv| pair(kk, vv) }, cols, first: "#{pad}#{k}: ", rest: pad + (" " * hang),
+                                                                    break_long: false))
+          elsif v.is_a?(Hash)
+            lines << "#{pad}#{k}:"
+            lines.concat(status_lines(v, cols, indent + 2))
+          else
+            lines << "#{pad}#{k}:"
+            v.each { |e| lines.concat(element_lines(e, cols, indent + 2)) }
+          end
+        end
+        flush.call
+        lines.empty? ? ["#{pad}{}"] : lines
+      end
+
+      # One element of an array that holds a Hash: "- " and the element.
+      def element_lines(e, cols, indent)
+        pad = " " * indent
+        if e.is_a?(Hash) && !e.empty? && e.values.all? { plain?(_1) }
+          wrap(e.map { |k, v| pair(k, v) }, cols, first: "#{pad}- ", rest: "#{pad}  ", break_long: false)
+        elsif e.is_a?(Hash) && !e.empty?
+          sub = status_lines(e, cols, indent + 2)
+          sub[0] = "#{pad}- #{sub[0].lstrip}"
+          sub
+        else
+          ["#{pad}- #{inline(e)}"]
+        end
+      end
+
+      # No Hash anywhere in v (it goes on one line).
+      def plain?(v)
+        case v
+        when Hash then false
+        when Array then v.all? { plain?(_1) }
+        else true
+        end
+      end
+
+      def pair(k, v)
+        "#{k}=#{inline(v)}"
+      end
+
+      # A value on one line: a word as it is, other text quoted (JSON), a
+      # long one cut; [a, b] (a long array cut, with the count left out);
+      # {k=v k=v}; nil as nil.
+      def inline(v)
+        case v
+        when Hash then "{#{v.map { |k, x| pair(k, x) }.join(' ')}}"
+        when Array then inline_array(v)
+        when String then inline_string(v)
+        when nil then "nil"
+        else v.to_s
+        end
+      end
+
+      def inline_string(s)
+        s = s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless s.encoding == Encoding::UTF_8
+        s = "#{split_width(s, LONG - 1)[0]}#{ELLIPSIS}" if width(s) > LONG
+        s.match?(/\A[^\s="'{}\[\],]+\z/) ? s : JSON.generate(s)
+      end
+
+      def inline_array(a)
+        parts = a.map { inline(_1) }
+        text = "[#{parts.join(', ')}]"
+        return text if width(text) <= LONG || parts.size < 2
+        kept = []
+        parts.each do |p|
+          break if width("[#{(kept + [p]).join(', ')}, #{ELLIPSIS}+#{parts.size}]") > LONG && kept.any?
+          kept << p
+        end
+        "[#{kept.join(', ')}, #{ELLIPSIS}+#{parts.size - kept.size}]"
+      end
+
+      # What changed from the status old to new, one String a change:
+      # "a.b 0→1" (a value changed), "+a.b=1" (a key came; a Hash on one
+      # line), "-a.b" (a key went). Hashes in both are compared key by key.
+      def status_diff(old, new, prefix = nil)
+        out = []
+        at = ->(k) { prefix ? "#{prefix}.#{k}" : k.to_s }
+        new.each do |k, v|
+          if !old.key?(k)
+            out << "+#{pair(at.(k), v)}"
+          elsif old[k].is_a?(Hash) && v.is_a?(Hash)
+            out.concat(status_diff(old[k], v, at.(k)))
+          elsif old[k] != v
+            out << "#{at.(k)} #{inline(old[k])}#{ARROW}#{inline(v)}"
+          end
+        end
+        old.each_key { |k| out << "-#{at.(k)}" unless new.key?(k) }
+        out
+      end
+    end
+  end
+end