Module: JSONRPC2::TextileEmitter

Included in:
Interface
Defined in:
lib/jsonrpc2/textile.rb

Overview

Textile documentation output functions

Instance Method Summary collapse

Instance Method Details

#about_method(name) ⇒ Object

Gets method docs for method #name



121
122
123
 
# File 'lib/jsonrpc2/textile.rb', line 121

def about_method(name)
  @about[name.to_s]
end

#method_to_textile(info) ⇒ Object

Returns method description in textile



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/jsonrpc2/textile.rb', line 57

def method_to_textile(info)
  str = ''
  str << "\n\nh3. #{info[:name]}\n"
  str << "\n#{info[:desc]}\n" if info[:desc]
  str << "\n\nh5. Params\n"
  if info[:params].nil?
    str << "\n* _None_\n"
  elsif info[:params].is_a?(Array)
    str << "\n|_. Name |_. Type |_. Required |_. Description |\n"
    info[:params].each do |param|
      str << "| @#{param[:name]}@ | @#{param[:type]}@ | #{param[:required] ? 'Yes' : 'No'} | #{param[:desc]} |\n"
    end
  end

  if res = info[:returns]
    str << "\n\nh5. Result\n"
    str << "\n* @#{res[:type]}@"		
    str << " - #{res[:desc]}" if res[:desc]
    str << "\n"
  else
    str << "\n\nh5. Result\n"
    str << "\n* @null@"
  end

  if examples = info[:examples]
    str << "\n\nh5. Sample usage\n"

    nice_json = lambda do |data|
      JSON.pretty_unparse(data).gsub(/\n\n+/,"\n").gsub(/[{]\s+[}]/m, '{ }').gsub(/\[\s+\]/m, '[ ]')
    end
    examples.each do |ex|
      str << "\n#{ex[:desc]}\n"
      code = ex[:code]
      if code.is_a?(String)
        str << "\nbc. #{ex[:code]}\n"
      elsif code.is_a?(Hash) && code.has_key?(:params) && (code.has_key?(:result) || code.has_key?(:error))

        str << "\nbc. "
        if code[:result] # ie. we expect success
          unless JSONRPC2::Types.valid_params?(self, info[:name], code[:params])
            raise "Invalid example params for #{info[:name]} / #{ex[:desc]}"
          end
        end
        input = { 'jsonrpc' => 2.0, 'method' => info[:name], 'params' => code[:params], 'id' => 0 }
        str << "--> #{nice_json.call(input)}\n"

        if code[:error]
          error = { 'jsonrpc' => 2.0, 'error' => code[:error], 'id' => 0 }
          str << "<-- #{nice_json.call(error)}\n"
        elsif code[:result]
          unless JSONRPC2::Types.valid_result?(self, info[:name], code[:result])
            raise "Invalid result example for #{info[:name]} / #{ex[:desc]}"
          end

          result = { 'jsonrpc' => 2.0, 'result' => code[:result], 'id' => 0 }
          str << "<-- #{nice_json.call(result)}\n"
        end
      end
    end
  end

  str
end

#to_textile ⇒ Object

Returns interface description in textile



7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/jsonrpc2/textile.rb', line 7

def to_textile
	return nil if @about.nil? or @about.empty?
	str = ""

	if @title
		str << "h1. #{@title}\n"
    else
      str << "h1. #{name}\n"
	end

	if @introduction
		str << "\nh2. Introduction\n\n#{@introduction}\n"
	end

    # Output type descriptions
    #
	unless @types.nil? or @types.empty?
		str << "\n\nh2. Types\n"
		@types.sort_by { |k,v| k }.each do |k,type|
			str << "\n\nh5. #{k} type\n"

			str << "\n|_. Field |_. Type |_. Required? |_. Description |"
			type.fields.each do |field|
				str << "\n| @#{field[:name]}@ | @#{field[:type]}@ | #{field[:required] ? 'Yes' : 'No'} | #{field[:desc]} |"
			end
			str << "\n"
		end
	end


    # Output method definitions
    #
	(@sections||[]).each do |section|
		str << "\n\nh2. #{section[:name]}\n"
		if section[:summary]
			str << "\n#{section[:summary]}\n"
		end
		
		str += to_textile_group(section).to_s
	end

	miscfn = to_textile_group({:name => nil})
	if miscfn
		str << "\n\nh2. Misc functions\n" if @sections && ! @sections.empty?
		str << miscfn
	end

	str
end

#to_textile_group(section) ⇒ Object

Returns documentation #section contents in textile



125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/jsonrpc2/textile.rb', line 125

def to_textile_group(section)
	list = @about.values.select { |info| info[:section] == section[:name] }

	return nil if list.empty?

	str = ''
	
	list.sort_by { |info| info[:index] }.each do |info|
      str << method_to_textile(info)
	end

	str
end