Class: Magik::CLI::DocsCommand

Inherits:
Object
  • Object
show all
Defined in:
lib/magik/cli/docs_command.rb

Overview

magik docs — the documentation shipped inside this gem, served locally.

This is the command an agent runs instead of a web search. It answers from files that came out of the same .gem as the code, so the reference always matches the installed version, and it answers in milliseconds because there is no network in the path.

Four subcommands, and --json on every one of them:

Command Prints
magik docs / magik docs list the catalogue, grouped by audience
magik docs <slug> one page, as raw markdown
magik docs search <term> matching pages, with line numbers
magik docs path Docs.root, for your own grep and glob

magik docs path is the important one: it turns the shipped manual into a directory an agent can point its existing file tools at, which beats any output format this command could invent.

list, search and path are subcommand names, not slugs: if a shipped page is ever called one of them, the subcommand wins and the page is still reachable by its full slug.

Examples:

The whole reference, greppable

$ grep -rn "tenant_id" "$(magik docs path)"

See Also:

Constant Summary collapse

LINE_WIDTH =

Widest line magik docs prints before it clips a summary or a match.

Returns:

  • (Integer) 
108
HINTS =

Closing hints on magik docs list, in the order an agent needs them.

Returns:

  • (Array<String>) 
[
  "Read a page:   magik docs <slug>",
  "Search:        magik docs search <term>",
  "Grep it all:   grep -rn \"<term>\" \"$(magik docs path)\"",
  "As data:       magik docs list --json"
].freeze

Instance Method Summary collapse

Constructor Details

#initialize(out:, json: false) ⇒ DocsCommand

Returns a new instance of DocsCommand.

Examples:

Magik::CLI::DocsCommand.new(out: $stdout).call([])

Parameters:

  • out (IO) —

    stream for command output

  • json (Boolean) (defaults to: false) —

    emit JSON instead of prose



56
57
58
59
 
# File 'lib/magik/cli/docs_command.rb', line 56

def initialize(out:, json: false)
  @out = out
  @json = json
end

Instance Method Details

#call(args) ⇒ void

This method returns an undefined value.

Run a magik docs subcommand.

Examples:

Magik::CLI::DocsCommand.new(out: $stdout).call(["search", "ledger"])

Parameters:

  • args (Array<String>) —

    the arguments after docs

Raises:



71
72
73
74
75
76
77
78
79
 
# File 'lib/magik/cli/docs_command.rb', line 71

def call(args)
  rest = Array(args)
  case rest.first
  when nil, "list" then list
  when "path" then print_path
  when "search" then search(rest.drop(1).join(" "))
  else page(rest.first)
  end
end