togows 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3aa356b44bbb2bf65b5f57312ed7134c221480b1b0f21727310756f5f8f1aa05
+  data.tar.gz: 222d0166a0d845fae0dca15a94a178b9ff6f2f3ef0329331390f692f32e85c49
+SHA512:
+  metadata.gz: 986782292f69d0fe7db251001108570a20e4502ad4e0bc0e4865443f233ea536c4f72d23f1c64176d04eee3b12f78a322748d153867ff0c6dd96a616ee9a8b86
+  data.tar.gz: 38199b730174c357333a5ae268529add28e289888ade3d384286c69f60d9eaec718661addb336e4a2f6c5cabad9df4f87b8257e830a24e0b18932bde4d1252af

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kojix2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,19 @@
+# togows
+
+A small dependency-free Ruby command line client for the TogoWS REST API.
+
+```sh
+gem install togows
+```
+
+```sh
+togows databases
+togows entry pubmed 20472643 authors --format json
+togows search uniprot "FGF19" --limit 10
+```
+
+See the [user guide](docs/user-guide.md) for installation from source, command examples, exit status, and testing notes.
+
+## License
+
+MIT

data/docs/user-guide.md

@@ -0,0 +1,171 @@
+# User Guide
+
+## Installation
+
+Install the released gem:
+
+```sh
+gem install togows
+```
+
+Or build it from this repository:
+
+```sh
+gem build togows.gemspec
+gem install ./togows-*.gem
+```
+
+## Commands
+
+```text
+togows entry DATABASE ID[,ID...] [FIELD] [options]
+togows search DATABASE QUERY [options]
+togows convert SOURCE.FORMAT [FILE] [options]
+togows databases [entry|search] [options]
+togows ucsc [DATABASE] [TABLE] [QUERY] [options]
+```
+
+Run `togows help COMMAND` for command-specific examples:
+
+```sh
+togows help entry
+togows help search
+togows help convert
+```
+
+## Discover Databases
+
+TogoWS database names must be exact. Start here when you are unsure:
+
+```sh
+togows databases
+togows databases entry
+togows databases search
+```
+
+## Entry
+
+Fetch one entry:
+
+```sh
+togows entry nucleotide NC_001138
+```
+
+Fetch a field:
+
+```sh
+togows entry pubmed 20472643 authors --format json
+togows entry uniprot ACT_YEAST seq
+```
+
+Use comma-separated IDs for multiple entries:
+
+```sh
+togows entry pubmed 20472643,20472644 title
+```
+
+## Search
+
+Count search results:
+
+```sh
+togows search pubmed "lung cancer" --count
+```
+
+Fetch the first page of search results:
+
+```sh
+togows search uniprot "FGF19" --limit 10
+```
+
+Specify both offset and limit when you need a later page:
+
+```sh
+togows search uniprot "lung cancer" --offset 11 --limit 10
+```
+
+## Convert
+
+Convert a local file:
+
+```sh
+{
+  printf 'LOCUS       TEST                      12 bp    DNA     linear   UNA 01-JAN-2000\n'
+  printf 'FEATURES             Location/Qualifiers\n'
+  printf 'ORIGIN\n'
+  printf '        1 acgtacgtacgt\n'
+  printf '//\n'
+} > input.gb
+
+togows convert genbank.fasta input.gb
+```
+
+Convert from stdin:
+
+```sh
+{
+  printf 'LOCUS       TEST                      12 bp    DNA     linear   UNA 01-JAN-2000\n'
+  printf 'FEATURES             Location/Qualifiers\n'
+  printf 'ORIGIN\n'
+  printf '        1 acgtacgtacgt\n'
+  printf '//\n'
+} | togows convert genbank.fasta
+```
+
+## UCSC
+
+List UCSC genome databases or tables:
+
+```sh
+togows ucsc
+togows ucsc hg38
+```
+
+Query a table:
+
+```sh
+togows ucsc hg38 refGene name2=UVSSA
+```
+
+## Useful Options
+
+Print the constructed URL without making a request:
+
+```sh
+togows entry pubmed 20472643 authors --format json --raw-url
+```
+
+Page long output explicitly:
+
+```sh
+togows ucsc hg38 --pager
+```
+
+## Exit Status
+
+```text
+0  success
+2  usage or option error
+4  HTTP client error from TogoWS
+5  HTTP server error from TogoWS
+6  network, socket, or timeout error
+```
+
+## Testing
+
+```sh
+bundle exec rake test
+```
+
+Live tests are skipped by default. To make real requests to TogoWS:
+
+```sh
+TOGOWS_LIVE_TEST=1 bundle exec rake test
+```
+
+## Release
+
+```sh
+gem build togows.gemspec
+gem push togows-*.gem
+```

data/exe/togows

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/togows"
+
+exit TogoWS::CLI.new(ARGV, $stdin, $stdout, $stderr).run

data/lib/togows/cli.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "shellwords"
+require "timeout"
+
+module TogoWS
+  class CLI
+    DEFAULT_BASE_URL = "https://togows.org"
+    DEFAULT_TIMEOUT = 30
+
+    def initialize(argv, stdin, stdout, stderr)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @out_color = Color.new(Color.enabled_for?(stdout))
+      @err_color = Color.new(Color.enabled_for?(stderr))
+    end
+
+    def run
+      command = @argv.shift
+      return help_for(@argv.shift, 0) if ["help", "-h", "--help"].include?(command)
+      return help(nil, 0) if command.nil?
+      return version if ["version", "--version", "-v"].include?(command)
+
+      case command
+      when "entry" then run_entry
+      when "search" then run_search
+      when "convert" then run_convert
+      when "databases", "dbs" then run_databases
+      when "ucsc" then run_ucsc
+      else
+        error("unknown command: #{command}")
+        help(nil, 2)
+      end
+    rescue HTTPError => e
+      error("#{e.code} #{e.message_text}")
+      @stderr.puts e.body unless e.body.empty?
+      e.code >= 500 ? 5 : 4
+    rescue OptionParser::ParseError, Error => e
+      error(e.message)
+      2
+    rescue SystemCallError, SocketError, Timeout::Error => e
+      error("#{e.class}: #{e.message}")
+      6
+    end
+
+    private
+
+    def common_options
+      {
+        base_url: DEFAULT_BASE_URL,
+        timeout: DEFAULT_TIMEOUT,
+        format: nil,
+        raw_url: false,
+        pager: false,
+        pretty: false
+      }
+    end
+
+    def parser(options, banner)
+      OptionParser.new do |opts|
+        opts.banner = banner
+        opts.on("-f", "--format FORMAT", "Output format") { |v| options[:format] = v }
+        opts.on("--base-url URL", "Base URL") { |v| options[:base_url] = v }
+        opts.on("--timeout SEC", Integer, "Timeout seconds") { |v| options[:timeout] = v }
+        opts.on("--raw-url", "Print URL and exit") { options[:raw_url] = true }
+        opts.on("--pager", "Page output with PAGER when stdout is a terminal") { options[:pager] = true }
+        opts.on("--pretty", "Pretty-print JSON output") { options[:pretty] = true }
+        opts.on("-h", "--help", "Show help") do
+          @stdout.puts opts
+          throw :help
+        end
+      end
+    end
+
+    def run_entry
+      options = common_options
+      catch(:help) do
+        parser(options, "Usage: togows entry DATABASE ID[,ID...] [FIELD] [options]").parse!(@argv)
+        database, *rest = @argv
+        return command_help(:entry, "entry requires DATABASE and ID", 2) if database.nil? || rest.empty?
+
+        ids, field = parse_entry_arguments(rest)
+        path = URLBuilder.entry(database, ids, field, options[:format])
+        output_request(path, options, :get)
+      end || 0
+    end
+
+    def parse_entry_arguments(args)
+      raise Error, "entry accepts ID[,ID...] and optional FIELD; use commas for multiple IDs" if args.length > 2
+
+      ids = args.first.to_s.split(",")
+      field = args[1]
+      raise Error, "entry accepts comma-separated IDs, not space-separated IDs" if field && entry_id_like?(field)
+
+      [ids, field]
+    end
+
+    def entry_id_like?(value)
+      value.include?(",") || value.match?(/\A[A-Z0-9_]+(?:\.\d+)?\z/)
+    end
+
+    def run_search
+      options = common_options.merge(offset: nil, limit: nil, count: false)
+      catch(:help) do
+        p = parser(options, "Usage: togows search DATABASE QUERY [options]")
+        p.on("-o", "--offset N", Integer, "Result offset") { |v| options[:offset] = v }
+        p.on("-n", "--limit N", Integer, "Result limit") { |v| options[:limit] = v }
+        p.on("--count", "Count results") { options[:count] = true }
+        p.parse!(@argv)
+        database, query = @argv
+        return command_help(:search, "search requires DATABASE and QUERY", 2) if database.nil?
+        return command_help(:search, "search requires QUERY after DATABASE", 2) if query.nil?
+
+        validate_search_options(options)
+        options[:offset] = 1 if options[:limit] && !options[:offset]
+
+        path = URLBuilder.search(database, query, options[:offset], options[:limit], options[:count], options[:format])
+        output_request(path, options, :get)
+      end || 0
+    end
+
+    def validate_search_options(options)
+      if options[:count] && (options[:offset] || options[:limit])
+        raise Error, "--count cannot be used with --offset or --limit"
+      end
+
+      raise Error, "--offset and --limit must be used together" if options[:offset] && !options[:limit]
+    end
+
+    def run_convert
+      options = common_options.merge(to: nil)
+      catch(:help) do
+        p = parser(options, "Usage: togows convert SOURCE.FORMAT [FILE] [options]")
+        p.on("--to FORMAT", "Target format") { |v| options[:to] = v }
+        p.parse!(@argv)
+        source, file = @argv
+        return command_help(:convert, "convert requires SOURCE.FORMAT or SOURCE --to FORMAT", 2) if source.nil?
+
+        path = URLBuilder.convert(source, options[:to])
+        body = file ? File.read(file) : read_convert_stdin
+        output_request(path, options, :post, body)
+      end || 0
+    end
+
+    def read_convert_stdin
+      raise Error, "convert requires FILE or piped stdin; stdin is a terminal" if @stdin.tty?
+
+      @stdin.read
+    end
+
+    def run_ucsc
+      options = common_options.merge(offset: nil, limit: nil)
+      catch(:help) do
+        p = parser(options, "Usage: togows ucsc [DATABASE] [TABLE] [QUERY] [options]")
+        p.on("-o", "--offset N", Integer, "Result offset") { |v| options[:offset] = v }
+        p.on("-n", "--limit N", Integer, "Result limit") { |v| options[:limit] = v }
+        p.parse!(@argv)
+        raise Error, "--offset and --limit must be used together" if options[:offset] && !options[:limit]
+        raise Error, "--offset and --limit must be used together" if options[:limit] && !options[:offset]
+
+        database, table, *query_parts = @argv
+        query = query_parts.empty? ? nil : query_parts.join("/")
+        path = URLBuilder.ucsc(database, table, query, options[:offset], options[:limit], options[:format])
+        output_request(path, options, :get)
+      end || 0
+    end
+
+    def run_databases
+      options = common_options
+      catch(:help) do
+        parser(options, "Usage: togows databases [entry|search] [options]").parse!(@argv)
+        kind = @argv.shift
+        raise Error, "databases accepts only one argument: entry or search" unless @argv.empty?
+
+        kinds = if kind.nil?
+                  %w[entry search]
+                elsif %w[entry search].include?(kind)
+                  [kind]
+                else
+                  return command_help(:databases, "database list must be entry or search", 2)
+                end
+
+        output_database_lists(kinds, options)
+      end || 0
+    end
+
+    def output_request(path, options, method, body = nil)
+      if options[:raw_url]
+        @stdout.puts URLBuilder.full_url(options[:base_url], path)
+        return 0
+      end
+
+      client = Client.new(options[:base_url], options[:timeout])
+      response = with_status("Fetching...") do
+        (method == :post ? client.post(path, body) : client.get(path)).to_s
+      end
+      write_output(format_response(response, options), options)
+      0
+    end
+
+    def output_database_lists(kinds, options)
+      if options[:raw_url]
+        kinds.each { |kind| @stdout.puts URLBuilder.full_url(options[:base_url], URLBuilder.databases(kind)) }
+        return 0
+      end
+
+      client = Client.new(options[:base_url], options[:timeout])
+      responses = with_status("Fetching...") do
+        kinds.map { |kind| [kind, client.get(URLBuilder.databases(kind))] }
+      end
+      responses.each_with_index do |(kind, body), index|
+        @stdout.puts if index.positive?
+        @stdout.puts "#{kind}:"
+        @stdout.write(body)
+      end
+      @stdout.write("\n")
+      0
+    end
+
+    def format_response(response, options)
+      return response unless options[:pretty]
+
+      JSON.pretty_generate(JSON.parse(response))
+    rescue JSON::ParserError
+      response
+    end
+
+    def version
+      @stdout.puts "togows #{VERSION}"
+      0
+    end
+
+    def help(message, status)
+      @stderr.puts message if message
+      @stdout.puts color_help(<<~HELP)
+        Usage:
+          togows entry DATABASE ID[,ID...] [FIELD] [options]
+          togows search DATABASE QUERY [options]
+          togows convert SOURCE.FORMAT [FILE] [options]
+          togows databases [entry|search] [options]
+          togows ucsc [DATABASE] [TABLE] [QUERY] [options]
+
+        Commands:
+          entry     Retrieve database entries
+          search    Search database entries
+          convert   Convert data from stdin or FILE
+          databases List databases supported by TogoWS
+          ucsc      Access TogoWS UCSC API
+
+        Common options:
+          -f, --format FORMAT
+              --base-url URL
+              --timeout SEC
+              --raw-url
+              --pager
+              --pretty
+          -h, --help
+      HELP
+      status
+    end
+
+    def help_for(command, status)
+      return help(nil, status) if command.nil?
+
+      case command
+      when "entry" then command_help(:entry, nil, status)
+      when "search" then command_help(:search, nil, status)
+      when "convert" then command_help(:convert, nil, status)
+      when "databases", "dbs" then command_help(:databases, nil, status)
+      when "ucsc" then command_help(:ucsc, nil, status)
+      else
+        error("unknown command: #{command}")
+        help(nil, 2)
+      end
+    end
+
+    def command_help(command, message, status)
+      error(message) if message
+      @stdout.puts color_help(Help::COMMANDS.fetch(command))
+      status
+    end
+
+    def error(message)
+      @stderr.puts "#{@err_color.bold('togows:')} #{message}"
+    end
+
+    def write_output(response, options)
+      output = response.end_with?("\n") ? response : "#{response}\n"
+      return @stdout.write(output) unless options[:pager] && @stdout.respond_to?(:tty?) && @stdout.tty?
+
+      command = pager_command
+      return @stdout.write(output) if command.empty?
+
+      write_pager(command, output)
+    end
+
+    def pager_command
+      ENV.fetch("PAGER", "less -R").shellsplit
+    end
+
+    def write_pager(command, output)
+      IO.popen(command, "w") { |pager| pager.write(output) }
+    rescue Errno::EPIPE
+      nil
+    end
+
+    def with_status(message)
+      return yield unless @stderr.respond_to?(:tty?) && @stderr.tty?
+
+      @stderr.print "\r#{message}"
+      yield
+    ensure
+      clear_status(message) if @stderr.respond_to?(:tty?) && @stderr.tty?
+    end
+
+    def clear_status(message)
+      @stderr.print "\r#{' ' * message.length}\r"
+    end
+
+    def color_help(text)
+      highlighted = text.gsub(/^(Usage:)/) { @out_color.bold(Regexp.last_match(1)) }
+      color_help_headings(highlighted)
+    end
+
+    def color_help_headings(text)
+      headings = [
+        "Next arguments:",
+        "Common search databases:",
+        "Search options:",
+        "Convert options:",
+        "Examples:",
+        "Commands:",
+        "Common options:"
+      ]
+      pattern = /^(#{Regexp.union(headings)})/
+      text.gsub(pattern) { @out_color.bold(Regexp.last_match(1)) }
+    end
+  end
+end

data/lib/togows/client.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module TogoWS
+  class Client
+    MAX_REDIRECTS = 5
+    USER_AGENT = "togows/#{VERSION}".freeze
+
+    def initialize(base_url, timeout)
+      @base_url = base_url
+      @timeout = timeout
+    end
+
+    def get(path)
+      uri = URI.parse(URLBuilder.full_url(@base_url, path))
+      request(uri) do |http, request_uri|
+        req = Net::HTTP::Get.new(request_uri)
+        apply_headers(req)
+        http.request(req)
+      end
+    end
+
+    def post(path, body)
+      uri = URI.parse(URLBuilder.full_url(@base_url, path))
+      request(uri) do |http, request_uri|
+        req = Net::HTTP::Post.new(request_uri)
+        apply_headers(req)
+        req["Content-Type"] = "text/plain"
+        req.body = body
+        http.request(req)
+      end
+    end
+
+    private
+
+    def request(uri, redirects = 0, &)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      response = http.start { |h| yield h, uri.request_uri }
+      if response.is_a?(Net::HTTPRedirection) && redirects < MAX_REDIRECTS
+        return request(redirect_uri(uri, response), redirects + 1, &)
+      end
+
+      raise HTTPError.new(response.code, response.message, response.body) unless response.is_a?(Net::HTTPSuccess)
+
+      response.body
+    end
+
+    def redirect_uri(uri, response)
+      location = response["location"]
+      raise HTTPError.new(response.code, response.message, response.body) if location.nil? || location.empty?
+
+      uri + location
+    end
+
+    def apply_headers(request)
+      request["User-Agent"] = USER_AGENT
+    end
+  end
+end

data/lib/togows/color.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TogoWS
+  class Color
+    STYLES = {
+      bold: 1
+    }.freeze
+
+    def initialize(enabled)
+      @enabled = enabled
+    end
+
+    def self.enabled_for?(io)
+      io.respond_to?(:tty?) && io.tty? && !ENV.key?("NO_COLOR")
+    end
+
+    def apply(text, *styles)
+      return text unless @enabled
+
+      codes = styles.map { |style| STYLES.fetch(style) }
+      "\e[#{codes.join(';')}m#{text}\e[0m"
+    end
+
+    def bold(text)
+      apply(text, :bold)
+    end
+  end
+end

data/lib/togows/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TogoWS
+  class Error < StandardError; end
+
+  class HTTPError < Error
+    attr_reader :code, :message_text, :body
+
+    def initialize(code, message_text, body)
+      @code = code.to_i
+      @message_text = message_text
+      @body = body.to_s
+      super("#{code} #{message_text}")
+    end
+  end
+end

data/lib/togows/help.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module TogoWS
+  module Help
+    COMMANDS = {
+      entry: <<~HELP,
+        Usage: togows entry DATABASE ID[,ID...] [FIELD] [options]
+
+        Next arguments:
+          DATABASE       Database name such as pubmed, nucleotide, uniprot
+          ID[,ID...]     One ID or comma-separated IDs
+          FIELD          Optional field such as authors, title, seq, definition
+
+        Examples:
+          togows entry pubmed 20472643 authors --format json
+          togows entry uniprot ACT_YEAST seq
+          togows entry nucleotide NC_001138
+      HELP
+      search: <<~HELP,
+        Usage: togows search DATABASE QUERY [options]
+
+        Next arguments:
+          DATABASE       Search target. Run `togows databases search` to list choices.
+          QUERY          Search text or database query
+
+        Common search databases:
+          pubmed         Literature
+          uniprot        Protein entries
+          nucleotide     Nucleotide entries
+          protein        Protein sequences
+          gene           NCBI Gene
+          pathway        KEGG pathways
+
+        Search options:
+          -o, --offset N
+          -n, --limit N     Defaults to offset 1 when --offset is omitted
+              --count
+              --pager
+
+        Examples:
+          togows databases search
+          togows search pubmed "lung cancer" --count
+          togows search uniprot "FGF19" --limit 10
+          togows search uniprot "lung cancer" --offset 1 --limit 10
+      HELP
+      convert: <<~HELP,
+        Usage: togows convert SOURCE.FORMAT [FILE] [options]
+
+        Next arguments:
+          SOURCE.FORMAT  Conversion pair such as genbank.gff
+          FILE           Optional input file; stdin is used when omitted
+
+        Convert options:
+              --to FORMAT
+
+        Examples:
+          {
+            printf 'LOCUS       TEST                      12 bp    DNA     linear   UNA 01-JAN-2000\n'
+            printf 'FEATURES             Location/Qualifiers\n'
+            printf 'ORIGIN\n'
+            printf '        1 acgtacgtacgt\n'
+            printf '//\n'
+          } | togows convert genbank.fasta
+      HELP
+      databases: <<~HELP,
+        Usage: togows databases [entry|search] [options]
+
+        Next arguments:
+          entry          Databases usable with togows entry
+          search         Databases usable with togows search
+
+        Examples:
+          togows databases
+          togows databases entry
+          togows databases search
+      HELP
+      ucsc: <<~HELP
+        Usage: togows ucsc [DATABASE] [TABLE] [QUERY] [options]
+
+        Next arguments:
+          DATABASE       Genome database such as hg38 or hg19
+          TABLE          UCSC table such as refGene
+          QUERY          Optional query fragment such as name2=UVSSA
+
+        Examples:
+          togows ucsc
+          togows ucsc hg38
+          togows ucsc hg38 refGene name2=UVSSA
+      HELP
+    }.freeze
+  end
+end

data/lib/togows/url_builder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module TogoWS
+  module URLBuilder
+    module_function
+
+    def entry(database, ids, field = nil, format = nil)
+      id_list = Array(ids).join(",")
+      parts = ["entry", escape_segment(database), escape_segment(id_list)]
+      parts << escape_path(field) if field && !field.empty?
+      with_format("/#{parts.join('/')}", format)
+    end
+
+    def search(database, query, offset = nil, limit = nil, count = false, format = nil)
+      parts = ["search", escape_segment(database), escape_segment(query)]
+      if count
+        parts << "count"
+      elsif offset && limit
+        parts << "#{offset},#{limit}"
+      end
+      with_format("/#{parts.join('/')}", format)
+    end
+
+    def convert(source, format = nil)
+      data_source, target_format = split_source_format(source, format)
+      "/convert/#{escape_segment(data_source)}.#{escape_segment(target_format)}"
+    end
+
+    def databases(kind)
+      case kind
+      when "entry" then "/entry"
+      when "search" then "/search"
+      else
+        raise Error, "database list must be entry or search"
+      end
+    end
+
+    def ucsc(database = nil, table = nil, query = nil, offset = nil, limit = nil, format = nil)
+      parts = %w[api ucsc]
+      parts << escape_segment(database) if database && !database.empty?
+      parts << escape_segment(table) if table && !table.empty?
+      parts << escape_path(query) if query && !query.empty?
+      parts << "#{offset},#{limit}" if offset && limit
+      with_format("/#{parts.join('/')}", format)
+    end
+
+    def full_url(base_url, path)
+      base = base_url.to_s.sub(%r{/*\z}, "")
+      base + path
+    end
+
+    def escape_segment(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+
+    def escape_path(value)
+      value.to_s.split("/", -1).map { |part| escape_segment(part) }.join("/")
+    end
+
+    def with_format(path, format)
+      return path if format.nil? || format.empty?
+
+      "#{path}.#{escape_segment(format)}"
+    end
+
+    def split_source_format(source, format)
+      if format && !format.empty?
+        [source, format]
+      elsif source.to_s.include?(".")
+        source.to_s.split(".", 2)
+      else
+        raise Error, "missing target format; use SOURCE.FORMAT or --to FORMAT"
+      end
+    end
+  end
+end

data/lib/togows/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TogoWS
+  VERSION = "0.1.0"
+end

data/lib/togows.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "togows/version"
+require_relative "togows/color"
+require_relative "togows/error"
+require_relative "togows/help"
+require_relative "togows/url_builder"
+require_relative "togows/client"
+require_relative "togows/cli"

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: togows
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kojix2
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: togows provides a small Ruby command line interface for TogoWS entry,
+  search, convert, and UCSC API endpoints.
+email:
+- 2xijok@gmail.com
+executables:
+- togows
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- docs/user-guide.md
+- exe/togows
+- lib/togows.rb
+- lib/togows/cli.rb
+- lib/togows/client.rb
+- lib/togows/color.rb
+- lib/togows/error.rb
+- lib/togows/help.rb
+- lib/togows/url_builder.rb
+- lib/togows/version.rb
+homepage: https://github.com/kojix2/togows-cli
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kojix2/togows-cli
+  source_code_uri: https://github.com/kojix2/togows-cli/tree/main
+  bug_tracker_uri: https://github.com/kojix2/togows-cli/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Dependency-free command line client for the TogoWS REST API
+test_files: []