Add Clipboard::readWithMetadata

This includes the associated metadata and Clipboard::read now returns
a String.

spec/clipboard-spec.coffee

@@ -1,11 +1,12 @@
 describe "Clipboard", ->
   describe "write(text, metadata) and read()", ->
     it "writes and reads text to/from the native clipboard", ->
-      expect(atom.clipboard.read().text).toBe 'initial clipboard content'
+      expect(atom.clipboard.read()).toBe 'initial clipboard content'
       atom.clipboard.write('next')
-      expect(atom.clipboard.read().text).toBe 'next'
+      expect(atom.clipboard.read()).toBe 'next'
 
     it "returns metadata if the item on the native clipboard matches the last written item", ->
       atom.clipboard.write('next', {meta: 'data'})
-      expect(atom.clipboard.read().text).toBe 'next'
-      expect(atom.clipboard.read().metadata).toEqual {meta: 'data'}
+      expect(atom.clipboard.read()).toBe 'next'
+      expect(atom.clipboard.readWithMetadata().text).toBe 'next'
+      expect(atom.clipboard.readWithMetadata().metadata).toEqual {meta: 'data'}

spec/editor-spec.coffee

@@ -1885,7 +1885,7 @@ describe "Editor", ->
                 editor.cutToEndOfLine()
                 expect(buffer.lineForRow(2)).toBe '    if (items.length'
                 expect(buffer.lineForRow(3)).toBe '    var pivot = item'
-                expect(atom.clipboard.read().text).toBe ' <= 1) return items;\ns.shift(), current, left = [], right = [];'
+                expect(atom.clipboard.read()).toBe ' <= 1) return items;\ns.shift(), current, left = [], right = [];'
 
             describe "when text is selected", ->
               it "only cuts the selected text, not to the end of the line", ->
@@ -1895,7 +1895,7 @@ describe "Editor", ->
 
                 expect(buffer.lineForRow(2)).toBe '    if (items.lengthurn items;'
                 expect(buffer.lineForRow(3)).toBe '    var pivot = item'
-                expect(atom.clipboard.read().text).toBe ' <= 1) ret\ns.shift(), current, left = [], right = [];'
+                expect(atom.clipboard.read()).toBe ' <= 1) ret\ns.shift(), current, left = [], right = [];'
 
         describe ".copySelectedText()", ->
           it "copies selected text onto the clipboard", ->

spec/editor-view-spec.coffee

@@ -2517,7 +2517,7 @@ describe "EditorView", ->
   describe "when editor:copy-path is triggered", ->
     it "copies the absolute path to the editor view's file to the clipboard", ->
       editorView.trigger 'editor:copy-path'
-      expect(atom.clipboard.read().text).toBe editor.getPath()
+      expect(atom.clipboard.read()).toBe editor.getPath()
 
   describe "when editor:move-line-up is triggered", ->
     describe "when there is no selection", ->

src/clipboard.coffee

@@ -11,16 +11,19 @@ class Clipboard
 
   # Creates an `md5` hash of some text.
   #
-  # text - A {String} to encrypt.
+  # * text: A {String} to hash.
   #
-  # Returns an encrypted {String}.
+  # Returns a hashed {String}.
   md5: (text) ->
     crypto.createHash('md5').update(text, 'utf8').digest('hex')
 
   # Public: Write the given text to the clipboard.
   #
-  # text - A {String} to store.
-  # metadata - An {Object} of additional info to associate with the text.
+  # The metadata associated with the text is available by calling
+  # {.readWithMetadata}.
+  #
+  # * text: A {String} to store.
+  # * metadata: An {Object} of additional info to associate with the text.
   write: (text, metadata) ->
     @signatureForMetadata = @md5(text)
     @metadata = metadata
@@ -28,14 +31,18 @@ class Clipboard
 
   # Public: Read the text from the clipboard.
   #
+  # Returns a {String}.
+  read: ->
+    clipboard.readText()
+
+  # Public: Read the text from the clipboard and return both the text and the
+  # associated metadata.
+  #
   # Returns an {Object} with a `text` key and a `metadata` key if it has
   # associated metadata.
-  read: ->
-    text = clipboard.readText()
-    #TODO Return object once packages have been updated.
-    contents = [text]
-    contents.text = text
+  readWithMetadata: ->
+    text = @read()
     if @signatureForMetadata is @md5(text)
-      contents.push(@metadata)
-      contents.metadata = @metadata
-    contents
+      {text, @metadata}
+    else
+      {text}

src/editor.coffee

@@ -559,7 +559,7 @@ class Editor extends Model
   # * options:
   #    + A set of options equivalent to {Selection.insertText}.
   pasteText: (options={}) ->
-    {text, metadata} = atom.clipboard.read()
+    {text, metadata} = atom.clipboard.readWithMetadata()
 
     containsNewlines = text.indexOf('\n') isnt -1