ICouch v0.1.0 ICouch.Document View Source

Module which handles CouchDB documents.

The struct’s main use is to to conveniently handle attachments. You can access the fields transparently with doc["fieldname"] since this struct implements the Elixir Access behaviour. You can also retrieve or pattern match the internal document with the fields attribute.

Note that you should not manipulate the fields directly, especially the attachments. This is because of the efficient multipart transmission which requires the attachments to be in the same order within the JSON as in the multipart body. The accessor functions provided in this module handle this.

Link to this section Summary

Functions

Deletes the entry in doc for a specific key

Deletes the attachment specified by filename from doc

Deletes the attachment data of all attachments in doc

Deletes the attachment data specified by filename from doc

Deletes all attachments and attachment data from doc

Fetches the field value for a specific key in the given doc

Deserializes a document from a map or binary

Like from_api/1 but raises an error on decoding failures

Gets the field value for a specific key in doc

Gets the field value from key and updates it, all in one pass

Returns both the info and data of the attachment specified by filename if present or nil. The data itself can be missing

Returns a list of tuples with attachment names and data, in the order in which they will appear in the serialized JSON

Returns the data of the attachment specified by filename if present or nil

Returns the attachment info (stub) for a specific filename or nil if not found

Returns whether an attachment with the given filename exists

Returns whether the attachment specified by filename is present and has data associated with it

Creates a new document struct

Returns and removes the field value associated with key in doc

Puts the given field value under key in doc

Inserts or updates the attachment data in doc for the attachment specified by filename. The attachment info (stub) has to exist or an error is raised

Inserts or updates the attachment info (stub) in doc for the attachment specified by filename

Set the document ID for doc

Set the revision number for doc

Serializes the given document to a binary

Like to_api/1 but raises an error on encoding failures

Link to this section Types

Link to this type t() View Source
t() :: %ICouch.Document{attachment_data: %{optional(key) => binary}, attachment_order: [String.t], fields: %{optional(key) => value}, id: String.t | nil, rev: String.t | nil}
Link to this type value() View Source
value() :: any

Link to this section Functions

Link to this function delete(doc, key) View Source
delete(doc :: t, key) :: t

Deletes the entry in doc for a specific key.

If the key does not exist, returns doc unchanged.

Link to this function delete_attachment(doc, filename) View Source
delete_attachment(doc :: t, filename :: key) :: t

Deletes the attachment specified by filename from doc.

Returns the document unchanged, if the attachment didn’t exist.

Link to this function delete_attachment_data(doc) View Source
delete_attachment_data(doc :: t) :: t

Deletes the attachment data of all attachments in doc.

This does not delete the respective attachment info (stub).

Link to this function delete_attachment_data(doc, filename) View Source
delete_attachment_data(doc :: t, filename :: key) :: t

Deletes the attachment data specified by filename from doc.

Link to this function delete_attachments(doc) View Source
delete_attachments(doc :: t) :: t

Deletes all attachments and attachment data from doc.

Link to this function fetch(document, key) View Source
fetch(doc :: t, key) :: {:ok, value} | :error

Fetches the field value for a specific key in the given doc.

If doc contains the given key with value value, then {:ok, value} is returned. If doc doesn’t contain key, :error is returned.

Part of the Access behavior.

Link to this function from_api(doc) View Source
from_api(fields :: map | binary) :: {:ok, t} | :error

Deserializes a document from a map or binary.

If attachments with data exist, they will be decoded and stored in the struct separately.

Link to this function from_api!(doc) View Source
from_api!(fields :: map | binary) :: t

Like from_api/1 but raises an error on decoding failures.

Link to this function get(doc, key, default \\ nil) View Source
get(doc :: t, key, default :: value) :: value

Gets the field value for a specific key in doc.

If key is present in doc with value value, then value is returned. Otherwise, default is returned (which is nil unless specified otherwise).

Part of the Access behavior.

Link to this function get_and_update(doc, key, fun) View Source
get_and_update(doc :: t, key, (value -> {get, value} | :pop)) :: {get, t} when get: term

Gets the field value from key and updates it, all in one pass.

fun is called with the current value under key in doc (or nil if key is not present in doc) and must return a two-element tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under key in the resulting new document. fun may also return :pop, which means the current value shall be removed from doc and returned (making this function behave like Document.pop(doc, key).

The returned value is a tuple with the “get” value returned by fun and a new document with the updated value under key.

Part of the Access behavior.

Link to this function get_attachment(document, filename) View Source
get_attachment(doc :: t, filename :: key) ::
  {map, binary | nil} |
  nil

Returns both the info and data of the attachment specified by filename if present or nil. The data itself can be missing.

Link to this function get_attachment_data(document) View Source
get_attachment_data(doc :: t) :: [{String.t, binary | nil}]

Returns a list of tuples with attachment names and data, in the order in which they will appear in the serialized JSON.

Note that the list will also contain attachments that have no associated data.

Link to this function get_attachment_data(document, filename) View Source
get_attachment_data(doc :: t, filename :: key) :: binary | nil

Returns the data of the attachment specified by filename if present or nil.

Link to this function get_attachment_info(document, filename) View Source
get_attachment_info(doc :: t, filename :: key) :: map | nil

Returns the attachment info (stub) for a specific filename or nil if not found.

Link to this function has_attachment?(document, filename) View Source
has_attachment?(doc :: t, filename :: key) :: map | nil

Returns whether an attachment with the given filename exists.

Link to this function has_attachment_data?(document, filename) View Source
has_attachment_data?(doc :: t, filename :: key) :: boolean

Returns whether the attachment specified by filename is present and has data associated with it.

Link to this function new(id \\ nil, rev \\ nil) View Source
new(id :: String.t | nil, rev :: String.t | nil) :: t

Creates a new document struct.

You can create an empty document or give it an ID and revision number or create a document struct from a map.

Link to this function pop(doc, key, default \\ nil) View Source
pop(doc :: t, key, default :: value) :: {value, t}

Returns and removes the field value associated with key in doc.

If key is present in doc with value value, {value, new_doc} is returned where new_doc is the result of removing key from doc. If key is not present in doc, {default, doc} is returned.

Link to this function put(doc, key, value) View Source
put(doc :: t, key, value) :: t

Puts the given field value under key in doc.

Link to this function put_attachment(doc, filename, data, content_type \\ "application/octet-stream", digest \\ nil) View Source
put_attachment(doc :: t, filename :: key, data :: binary | {map | binary}, content_type :: String.t, digest :: String.t | nil) :: t
Link to this function put_attachment_data(doc, filename, data) View Source
put_attachment_data(doc :: t, filename :: key, data :: binary) :: t

Inserts or updates the attachment data in doc for the attachment specified by filename. The attachment info (stub) has to exist or an error is raised.

Link to this function put_attachment_info(doc, filename, info) View Source
put_attachment_info(doc :: t, filename :: key, info :: map) :: t

Inserts or updates the attachment info (stub) in doc for the attachment specified by filename.

Link to this function set_id(doc, id) View Source
set_id(doc :: t, id :: String.t) :: t

Set the document ID for doc.

Attempts to set it to nil will actually remove the ID from the document.

Link to this function set_rev(doc, rev) View Source
set_rev(doc :: t, rev :: String.t) :: t

Set the revision number for doc.

Attempts to set it to nil will actually remove the revision number from the document.

Link to this function to_api(doc, options \\ []) View Source
to_api(doc :: t, options :: [any]) ::
  {:ok, binary} |
  {:error, term}

Serializes the given document to a binary.

This will encode the attachments unless multipart: true is given as option at which point the attachments that have data are marked with "follows": true. The attachment order is maintained.

Link to this function to_api!(doc, options \\ []) View Source
to_api!(doc :: t, options :: [any]) :: binary

Like to_api/1 but raises an error on encoding failures.