Class: Helipad

Inherits:
Object
  • Object
show all
Defined in:
lib/helipad.rb

Overview

Class Helipad provides a wrapper for the Helipad XML API.

See the documentation in the file README for an overview.

Defined Under Namespace

Classes: Document, Response

Instance Method Summary collapse

Constructor Details

#initialize(email, password) ⇒ Helipad

Create a new Helipad object.

Parameters

email and password are the same credentials you use to log on to your Helipad account.

Raises:

  • (ArgumentError) 


20
21
22
23
24
25
 
# File 'lib/helipad.rb', line 20

def initialize(email, password)
  @email = email
  @password = password
  raise(ArgumentError, "Email address not specified", caller) if @email.nil?
  raise(ArgumentError, "Password not specified", caller) if @password.nil?
end

Instance Method Details

#create(*args) ⇒ Object

Create a new Helipad document.

Parameters

args is a Hash containing properties for the created document.

  • :title - Title for the new document. This parameter is required.

  • :tags - Space-separated list of tags for the new document

  • :source - Body of the new document. Helipad understands Textile markup, which you can use to format the document’s text.

Returns

This method returns a Helipad::Response object, which has the following methods:

  • saved? - true if the document was created successfully

  • doc_id - ID of the newly created document

Example

hp = Helipad.new("[email protected]", "password")
response = hp.create(:title => "Marsupial Inventory",
                     :tags  => "marsupial australia animals",
                     :source => "|koala|2|\n|kangaroo|8|\n|platypus|1|")
puts "Inventory saved as document #{response.doc_id}" if response.saved?

Raises:

  • (ArgumentError) 


50
51
52
53
54
55
56
57
 
# File 'lib/helipad.rb', line 50

def create(*args)
  options = args.extract_options!
  validate_options(options, :create)
  raise(ArgumentError, "No document options specified", caller) if options.empty?
  raise(ArgumentError, "Document must have a title", caller) if options[:title].nil?
  url = URI.parse("http://pad.helicoid.net/document/create")
  Response.new(send_request(url, build_request(options)))
end

#destroy(id) ⇒ Object

Delete a Helipad document.

Parameter

  • id - ID of the document to delete

Returns

This method returns a Helipad::Response object, which has the following method:

  • deleted? - true if the document was deleted successfully

Example

hp = Helipad.new("[email protected]", "password")
response = hp.destroy(81)
puts "Document deleted" if response.deleted?



72
73
74
75
 
# File 'lib/helipad.rb', line 72

def destroy(id)
  url = URI.parse("http://pad.helicoid.net/document/#{id}/destroy")
  Response.new(send_request(url, build_request))
end

#find(*args) ⇒ Object

Search for Helipad documents by text content or by tags.

Parameters

The find method searches differently depending on its arguments:

  • find(String) - Search for the string in the titles and bodies of documents.

  • find(:tag, String) - Search for documents tagged with the string.

Returns

This method returns an Array of Helipad::Document objects, or nil if nothing could be found matching the given search string. See Helipad::Document for more details about the Document object.

Examples

hp = Helipad.new("[email protected]", "password")
docs = hp.find("wibble")
puts "#{docs.size} documents contain 'wibble'"

docs = hp.find(:tag, "diary")
puts "First diary entry is titled '#{docs.first.title}'"

Raises:

  • (ArgumentError) 


96
97
98
99
100
101
102
103
104
 
# File 'lib/helipad.rb', line 96

def find(*args)
  raise(ArgumentError, "No find arguments supplied", caller) if args.size == 0
  term = args.extract_search_term!
  case args.first
    when :tag then find_by_tag(term)
    when nil  then search(term)
    else           raise(ArgumentError, "Unknown find option '#{args.first}' supplied", caller)
  end
end

#get(id) ⇒ Object

Retrieve a Helipad document.

Parameter

  • id - ID of the document to retrieve

Returns

This method returns a Helipad::Document object, which holds the contents and properties of the document. See Helipad::Document for more details about the Document object.

Example

hp = Helipad.new("[email protected]", "password")
document = hp.get(29)
puts "#{document.title} contains #{document.source.length} characters."



120
121
122
123
 
# File 'lib/helipad.rb', line 120

def get(id)
  url = URI.parse("http://pad.helicoid.net/document/#{id}/get")
  Document.new(send_request(url, build_request))
end

#get_all ⇒ Object

Retrieve all documents on a Helipad account.

Returns

This method returns an Array of Helipad::Document objects. See Helipad::Document for more details about the document object.

Example

hp = Helipad.new("[email protected]", "password")
docs = hp.get_all
case docs.size
  when > 1000 then puts "Slow down there, Shakespeare!"
  when >  100 then puts "That's a respectable amount of writing."
  when >   10 then puts "Keep at it!"
  else             puts "Do you even use your Helipad account?"
end



141
142
143
144
145
146
147
148
149
 
# File 'lib/helipad.rb', line 141

def get_all
  url = URI.parse("http://pad.helicoid.net/")
  response = REXML::Document.new(send_request(url, build_request))
  documents = Array.new
  REXML::XPath.match(response, "//document").each do |doc|
    documents.push Document.new(doc)
  end
  documents
end

#get_html(id) ⇒ Object

Retrieve an HTML-formatted version of a Helipad document.

Parameter

  • id - ID of the document to retrieve

Returns

This method returns a String containing the HTML-formatted document.

Example

hp = Helipad.new("[email protected]", "password")
puts hp.get_html(94)



162
163
164
165
166
 
# File 'lib/helipad.rb', line 162

def get_html(id)
  url = URI.parse("http://pad.helicoid.net/document/#{id}/format/html")
  doc = REXML::Document.new(send_request(url, build_request))
  REXML::XPath.match(doc, "html/child::text()").join.strip
end

#get_titles ⇒ Object

Retrieve a list of all the document titles in a Helipad account.

Returns

This method returns an Array of Helipad::Document objects that contain titles, but no document source. See Helipad::Document for more details about the Document object.

Example

hp = Helipad.new("[email protected]", "password")
puts "Table of Contents"
hp.get_titles.each do |doc|
  puts doc.title
end



180
181
182
183
184
185
186
187
188
 
# File 'lib/helipad.rb', line 180

def get_titles
  url = URI.parse("http://pad.helicoid.net/documents/titles")
  response = REXML::Document.new(send_request(url, build_request))
  documents = Array.new
  REXML::XPath.match(response, "//document").each do |doc|
    documents.push Document.new(doc)
  end
  documents
end

#update(id, *args) ⇒ Object

Update an existing Helipad document.

Parameters

id is the ID of the document to be updated.

args is a Hash containing properties to update in the document. All of the properties are optional.

  • :title - Updated title for the document

  • :tags - Space-separated list of tags for the document

  • :source - Updated body of the document. Helipad understands Textile markup, which you can use to format the document’s text.

Returns

This method returns a Helipad::Response object, which has the following method:

  • saved? - true if the document was created successfully

Example

hp = Helipad.new("[email protected]", "password")
response = hp.update(:title => "Marsupial Inventory (amended)",
                     :source => "|koala|2|\n|kangaroo|2|\n|platypus|19|")
puts "Inventory updated" if response.saved?

Raises:

  • (ArgumentError) 


213
214
215
216
217
218
219
 
# File 'lib/helipad.rb', line 213

def update(id, *args)
  url = URI.parse("http://pad.helicoid.net/document/#{id}/update")
  options = args.extract_options!
  validate_options(options, :update)
  raise(ArgumentError, "No options specified", caller) if options.empty?
  Response.new(send_request(url, build_request(options)))
end