asterism 0.7.1 → 0.9.0

data/lib/asterism/cli/complete.rb

@@ -0,0 +1,282 @@
+# The shell's Tab completion: `asterism completion bash|zsh` prints a
+# script, and the script calls the hidden `asterism __complete` on each
+# Tab, which prints the candidates, one a line.
+#
+# The commands, the verbs and the options come from the command line's own
+# tables (no network). The names on the network (nodes, node/app,
+# node/app/object, an object's methods) come from the network named on the
+# line (--router, --credentials, --peer) or in the environment, asked
+# briefly (Complete::BUDGET: nothing comes back when it does not answer in
+# time, the shell is not kept waiting) and remembered for a few seconds
+# (Cache: a file per network under $XDG_CACHE_HOME/asterism, named by a
+# digest of where the network is; it holds names only, never a key or a
+# certificate). A name with "/" is completed a part at a time:
+# `ga<Tab>` gives `games/`, `games/games/<Tab>` the objects.
+require "json"
+require "digest"
+require "fileutils"
+require "shellwords"
+
+module Asterism
+  class CLI
+    class Complete
+      # Seconds the network may take to answer one Tab (connecting, the
+      # tokens, a meta get).
+      BUDGET = 1.5
+      # What a line of the output means "complete a file name here".
+      FILES = ":files"
+
+      # spec: the CLI (its command tables and option lists); source: what
+      # the network names (#names, #methods(path), #all_methods), each
+      # nil when it did not answer.
+      def initialize(spec, source)
+        @spec = spec
+        @source = source
+      end
+
+      # The candidates for the last word of words (the words after
+      # `asterism`, the last one the word being completed, "" for a new
+      # one), those that start with it, sorted.
+      def candidates(words)
+        words = words.dup
+        cur = words.pop || ""
+        pos = []
+        prev = nil
+        words.each do |w|
+          if prev
+            prev = nil
+            next
+          end
+          if w.start_with?("-") && w.size > 1
+            prev = w if @spec.option_takes_value?(w)
+            next
+          end
+          pos << w
+        end
+        key, args = @spec.command_key(pos)
+        list =
+          if prev then values(prev, key, args)
+          elsif cur.start_with?("-") then key ? @spec.options_for(key) : []
+          else positional(pos, key, args, cur)
+          end
+        return list if list == [FILES]
+        list.select { _1.start_with?(cur) }.uniq.sort
+      end
+
+      private
+
+      def values(opt, key, args)
+        case opt
+        when "-o", "--output" then %w[json yaml]
+        when "--credentials" then [FILES]
+        when "--call" then key == "ping" && args[0] ? methods_of(args[0]) : []
+        else []
+        end
+      end
+
+      def positional(pos, key, args, cur)
+        return @spec.command_words if pos.empty?
+        return @spec.verbs(pos[0]) if pos.size == 1 && @spec.noun?(pos[0])
+        return [] unless key
+        i = args.size
+        case [key, i]
+        when ["node info", 0] then nodes
+        when ["app info", 0], ["status get", 0], ["status echo", 0], ["status hz", 0] then staged(cur, apps, 2)
+        when ["object list", 0], ["object info", 0], ["objects", 0], ["call", 0] then staged(cur, objects, 3)
+        when ["ping", 0], ["echo", 0] then (cur.include?("/") ? [] : nodes) + staged(cur, objects, 3)
+        when ["object find", 0] then @source.all_methods || []
+        when ["call", 1] then methods_of(args[0])
+        when ["completion", 0] then %w[bash zsh]
+        when ["help", 0] then @spec.nouns
+        else []
+        end
+      end
+
+      def methods_of(path)
+        path.count("/") == 2 ? (@source.methods(path) || []) : []
+      end
+
+      def names
+        @names ||= @source.names || { "apps" => [], "objects" => [] }
+      end
+
+      def objects
+        names["objects"]
+      end
+
+      # The applications, with those that only objects tell of.
+      def apps
+        (names["apps"] + objects.map { _1.split("/")[0, 2].join("/") }).uniq
+      end
+
+      def nodes
+        (apps + objects).map { _1.split("/")[0] }.uniq
+      end
+
+      # The next part of the paths (depth parts each) that start with cur:
+      # the parts up to the one cur is in, with "/" after it when more come.
+      def staged(cur, paths, depth)
+        k = cur.count("/")
+        return [] if k >= depth
+        paths.filter_map do |p|
+          s = p.split("/")
+          next if s.size < depth
+          c = s[0..k].join("/")
+          c += "/" if k + 1 < depth
+          c if c.start_with?(cur)
+        end
+      end
+
+      public
+
+      # The words of a command line up to the cursor (bash's COMP_LINE cut
+      # at COMP_POINT): the words after the command, the last one the word
+      # being completed ("" after a space). An open quote is closed.
+      def self.split_line(line)
+        words = begin
+          Shellwords.split(line)
+        rescue ArgumentError
+          begin
+            Shellwords.split("#{line}\"")
+          rescue ArgumentError
+            Shellwords.split("#{line}'")
+          end
+        end
+        words << "" if line.match?(/\s\z/) || words.empty?
+        words.drop(1)
+      end
+
+      # Bash splits the word being completed at ":" and "=" (COMP_WORDBREAKS):
+      # the candidates without what comes before the last of them in cur.
+      def self.bash_trim(cands, cur)
+        cut = cur.rindex(/[:=]/)
+        return cands unless cut
+        cands.map { _1.start_with?(cur[0..cut]) ? _1[(cut + 1)..] : _1 }
+      end
+
+      # ------------------------------------------------------------ the cache
+
+      # What __complete remembers of a network for a few seconds: a JSON
+      # file per network ({entry => {"t" => seconds, "v" => value}}), the
+      # directory 0700 and the files 0600. The network's identity is a
+      # digest of where it is (router, the credentials file's path, peer);
+      # nothing else about it is written.
+      class Cache
+        TTL = 20
+
+        def initialize(dir:, network:, ttl: TTL, clock: -> { Time.now.to_f })
+          @dir = dir
+          @ttl = ttl
+          @clock = clock
+          id = network.map { _1.to_s }.join("\n")
+          @file = File.join(dir, "#{Digest::SHA256.hexdigest(id)[0, 24]}.json")
+        end
+
+        attr_reader :file
+
+        # The cache directory: $XDG_CACHE_HOME/asterism, else
+        # ~/.cache/asterism.
+        def self.dir(env)
+          base = env["XDG_CACHE_HOME"].to_s
+          base = File.join(Dir.home, ".cache") if base.empty?
+          File.join(base, "asterism")
+        rescue ArgumentError
+          nil
+        end
+
+        # The entry's value when it is fresh, else the block's (kept unless
+        # it is nil: what did not answer is asked again next time).
+        def fetch(entry)
+          data = read
+          e = data[entry]
+          now = @clock.call
+          return e["v"] if e.is_a?(Hash) && e["t"].is_a?(Numeric) && now - e["t"] < @ttl && now >= e["t"]
+          v = yield
+          return v if v.nil?
+          data = read.reject { |_, x| !x.is_a?(Hash) || !x["t"].is_a?(Numeric) || now - x["t"] >= @ttl }
+          data[entry] = { "t" => now, "v" => v }
+          write(data)
+          v
+        end
+
+        private
+
+        def read
+          h = JSON.parse(File.read(@file))
+          h.is_a?(Hash) ? h : {}
+        rescue StandardError
+          {}
+        end
+
+        def write(data)
+          FileUtils.mkdir_p(@dir, mode: 0o700)
+          tmp = "#{@file}.#{Process.pid}.tmp"
+          File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { _1.write(JSON.generate(data)) }
+          File.rename(tmp, @file)
+        rescue StandardError
+          begin
+            File.unlink(tmp) if tmp
+          rescue StandardError
+            nil
+          end
+          nil
+        end
+      end
+
+      # ------------------------------------------------------------ the scripts
+
+      BASH = <<~'BASH'
+        # asterism's Tab completion for bash: source <(asterism completion bash)
+        # (or put that line in ~/.bashrc). Each Tab runs `asterism __complete`;
+        # the names on the network come from the network named on the line
+        # (--router, --credentials, --peer) or in ASTERISM_CREDENTIALS /
+        # ASTERISM_ROUTER, asked briefly and remembered for a few seconds.
+        _asterism() {
+          local cur=${COMP_WORDS[COMP_CWORD]}
+          local IFS=$'\n'
+          local out
+          out=$(asterism __complete --bash "${COMP_LINE:0:COMP_POINT}" 2>/dev/null)
+          if [[ $out == ":files" ]]; then
+            compopt -o filenames 2>/dev/null
+            COMPREPLY=($(compgen -f -- "$cur"))
+            return 0
+          fi
+          COMPREPLY=($out)
+          local c
+          for c in "${COMPREPLY[@]}"; do
+            if [[ $c == */ ]]; then
+              compopt -o nospace 2>/dev/null
+              break
+            fi
+          done
+          return 0
+        }
+        complete -F _asterism asterism
+      BASH
+
+      ZSH = <<~'ZSH'
+        # asterism's Tab completion for zsh: source <(asterism completion zsh)
+        # after compinit (or put that line in ~/.zshrc). Each Tab runs
+        # `asterism __complete`; the names on the network come from the network
+        # named on the line (--router, --credentials, --peer) or in
+        # ASTERISM_CREDENTIALS / ASTERISM_ROUTER, asked briefly and remembered
+        # for a few seconds.
+        _asterism() {
+          local -a cands slash plain
+          cands=("${(@f)$(asterism __complete -- "${(@)words[2,CURRENT]}" 2>/dev/null)}")
+          cands=(${cands:#})
+          if [[ ${cands[1]} == ":files" ]]; then
+            _files
+            return
+          fi
+          slash=(${(M)cands:#*/})
+          plain=(${cands:#*/})
+          (( ${#plain} )) && compadd -- "${plain[@]}"
+          (( ${#slash} )) && compadd -S '' -- "${slash[@]}"
+          return 0
+        }
+        compdef _asterism asterism
+      ZSH
+    end
+  end
+end

data/lib/asterism/cli/hz.rb

@@ -0,0 +1,77 @@
+# `asterism status hz`: how often an application's status changes, as
+# `ros2 topic hz` tells how often a topic is published. Each change is a
+# time (a monotonic clock, given or Process.clock_gettime); the intervals
+# between the last ones (a window of them) give the average rate and the
+# intervals' min, max and standard deviation. A put that brings the same
+# status again (as after a reconnection) is not a change.
+module Asterism
+  class CLI
+    class Hz
+      attr_reader :count
+
+      # window: how many of the last intervals count. clock: a callable
+      # that returns the time in seconds (monotonic).
+      def initialize(window: 1000, clock: nil)
+        @window = window
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @times = []
+        @last = nil
+        @seeded = false
+        @count = 0
+        @reported = 0
+      end
+
+      # The status there at the start: what the first put is compared with
+      # (not a change itself).
+      def seed(status)
+        @last = status
+        @seeded = true
+      end
+
+      # A put of the status: a change (true) when it differs from the last
+      # one seen (the first put without a seed is one).
+      def put(status)
+        return false if @seeded && status == @last
+        @last = status
+        @seeded = true
+        add(@clock.call)
+        true
+      end
+
+      # A change at time t (seconds).
+      def add(t)
+        @count += 1
+        @times << t
+        @times.shift while @times.size > @window + 1
+      end
+
+      # {"rate_hz", "min_s", "max_s", "std_s", "window", "count"} over the
+      # intervals in the window, or nil before two changes.
+      def stats
+        return nil if @times.size < 2
+        ints = @times.each_cons(2).map { |a, b| b - a }
+        avg = ints.sum / ints.size
+        var = ints.sum { (_1 - avg)**2 } / ints.size
+        { "rate_hz" => avg.positive? ? 1.0 / avg : nil, "min_s" => ints.min, "max_s" => ints.max,
+          "std_s" => Math.sqrt(var), "window" => ints.size, "count" => @count }
+      end
+
+      # stats when a change came since the last report (else nil): what a
+      # period prints.
+      def report
+        return nil if @count == @reported
+        s = stats
+        @reported = @count if s
+        s
+      end
+
+      # The lines of a report, as ros2 topic hz prints them.
+      def self.text(s)
+        rate = s["rate_hz"] ? format("%.3f", s["rate_hz"]) : "inf"
+        ["average rate: #{rate} Hz",
+         format("  min: %.3f s  max: %.3f s  std dev: %.3f s  window: %d", s["min_s"], s["max_s"], s["std_s"],
+                s["window"])]
+      end
+    end
+  end
+end

data/lib/asterism/cli/literal.rb

@@ -0,0 +1,132 @@
+# The arguments of `asterism call` (and of the MCP bridge's tests): each is
+# read as JSON, else as a Ruby literal, else taken as the text it is.
+#
+#   Literal.parse('{"seat": 1}')   # => {"seat" => 1}          (JSON)
+#   Literal.parse("[1, :a, nil]")  # => [1, :a, nil]           (Ruby)
+#   Literal.parse("{seat: 1}")     # => {seat: 1}              (Ruby)
+#   Literal.parse("hello")         # => "hello"                (text)
+#
+# The Ruby form is read with Ripper and only literals are taken: nil,
+# true, false, integers, floats, strings without interpolation, symbols,
+# arrays (also %w / %i) and hashes. Nothing is evaluated: anything else (a
+# method call, a constant, a variable) makes it not a literal, and the
+# argument is then the text as written.
+require "json"
+require "ripper"
+
+module Asterism
+  class CLI
+    module Literal
+      class NotLiteral < StandardError; end
+
+      module_function
+
+      # The value of one argument (see above).
+      def parse(text)
+        json(text)
+      rescue JSON::ParserError
+        begin
+          ruby(text)
+        rescue NotLiteral
+          text
+        end
+      end
+
+      # JSON: a value of any kind at the top ("1", "\"x\"", "null" too).
+      def json(text)
+        JSON.parse(text)
+      end
+
+      # A Ruby literal, or NotLiteral.
+      def ruby(text)
+        tree = Ripper.sexp(text)
+        raise NotLiteral, "not Ruby" unless tree && tree[0] == :program
+        body = tree[1]
+        raise NotLiteral, "one value expected" unless body.is_a?(Array) && body.size == 1
+        node(body[0])
+      end
+
+      def node(n)
+        raise NotLiteral, "unexpected #{n.inspect}" unless n.is_a?(Array)
+        case n[0]
+        when :@int then Integer(n[1].delete("_"), 0)
+        when :@float then Float(n[1].delete("_"))
+        when :unary
+          raise NotLiteral, "only - before a number" unless n[1] == :-@ && %i[@int @float].include?(n[2][0])
+          -node(n[2])
+        when :var_ref, :@kw then keyword(n[0] == :var_ref ? n[1] : n)
+        when :string_literal then string(n[1])
+        when :symbol_literal then symbol(n[1])
+        when :dyna_symbol then string(n[1]).to_sym
+        when :array then array(n[1])
+        when :hash then hash(n[1])
+        when :bare_assoc_hash then pairs(n[1])
+        else raise NotLiteral, "not a literal: #{n[0]}"
+        end
+      end
+
+      def keyword(kw)
+        raise NotLiteral, "not a keyword" unless kw[0] == :@kw
+        case kw[1]
+        when "nil" then nil
+        when "true" then true
+        when "false" then false
+        else raise NotLiteral, "keyword #{kw[1]}"
+        end
+      end
+
+      # string_content: plain parts only (no #{...}).
+      def string(content)
+        return "" if content.nil?
+        parts = content[0] == :string_content ? content[1..] : content
+        parts.map do |p|
+          raise NotLiteral, "interpolation" unless p.is_a?(Array) && p[0] == :@tstring_content
+          unescape(p[1])
+        end.join
+      end
+
+      # The escapes of a double-quoted string (\n, \t, \", \\, \u...).
+      def unescape(s)
+        return s unless s.include?("\\")
+        "\"#{s}\"".undump
+      rescue RuntimeError
+        s
+      end
+
+      def symbol(sym)
+        raise NotLiteral, "symbol" unless sym[0] == :symbol
+        sym[1][1].to_sym
+      end
+
+      def array(items)
+        return [] if items.nil?
+        items.map do |e|
+          if e.is_a?(Array) && e[0] == :@tstring_content # %w[...]
+            e[1]
+          elsif e.is_a?(Array) && %i[qwords_add words_add qsymbols_add symbols_add].include?(e[0])
+            raise NotLiteral, "old Ripper form"
+          elsif e.is_a?(Array) && e[0] == :@ident # %i[...]
+            e[1].to_sym
+          else
+            node(e)
+          end
+        end
+      end
+
+      def hash(list)
+        return {} if list.nil?
+        raise NotLiteral, "hash" unless list[0] == :assoclist_from_args
+        pairs(list[1])
+      end
+
+      def pairs(assocs)
+        assocs.to_h do |a|
+          raise NotLiteral, "not a key => value" unless a[0] == :assoc_new
+          k = a[1]
+          key = k[0] == :@label ? k[1].chomp(":").to_sym : node(k)
+          [key, node(a[2])]
+        end
+      end
+    end
+  end
+end