ICouch v0.4.2 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

Returns the sum of all attachment data sizes in doc

Returns the size of the attachment data specified by filename in doc

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

Returns whether the document is marked as deleted

Tests two documents for equality

Tests the attachments of two documents for equality

Tests two documents for field equality

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

Deserializes a document including its attachment data from a list of multipart segments as returned by ICouch.Multipart.split/2

Returns the approximate size of this document if it was encoded entirely in JSON, including the attachments being represented as as Base64

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

Returns the approximate size of this document if it was encoded in JSON

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

Returns a list of full revision numbers given through the document’s _revisions or _revs_info field, or nil if the both fields are missing or invalid. The revisions are sorted from newest to oldest

Marks the document as deleted

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

Serializes the given document including its attachment data to a list of multipart segments as consumed by ICouch.Multipart.join/2

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 attachment_data_size(document) View Source
attachment_data_size(doc :: t) :: integer

Returns the sum of all attachment data sizes in doc.

The calculation is done for data that actually is present in this document, not neccessarily all attachments that are referenced in _attachments.

Link to this function attachment_data_size(document, filename) View Source
attachment_data_size(doc :: t, filename :: key) :: integer

Returns the size of the attachment data specified by filename in doc.

Note that this will return 0 if the attachment data is missing and/or the attachment does not exist.

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 deleted?(document) View Source
deleted?(doc :: t) :: boolean

Returns whether the document is marked as deleted.

Link to this function equal?(doc1, doc2) View Source
equal?(t | map, t | map) :: boolean

Tests two documents for equality.

Includes _id, _rev and _revisions/_revs_info. Attachments are compared using equal_attachments?/2.

Link to this function equal_attachments?(doc1, doc2) View Source
equal_attachments?(t | map, t | map) :: boolean

Tests the attachments of two documents for equality.

An attachment is considered equal if the name, content_type, length and digest are equal. If digests are absent, the data will be checked for equality; if both documents do not hold attachment data, this is considered equal as well.

Link to this function equal_content?(doc1, doc2) View Source
equal_content?(t | map, t | map) :: boolean

Tests two documents for field equality.

Ignores _id, _rev and _revisions. Attachments are compared using equal_attachments?/2.

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 from_multipart(list) View Source
from_multipart(parts :: [{map, binary}]) ::
  {:ok, t} |
  {:error, term}

Deserializes a document including its attachment data from a list of multipart segments as returned by ICouch.Multipart.split/2.

Link to this function full_json_byte_size(doc) View Source

Returns the approximate size of this document if it was encoded entirely in JSON, including the attachments being represented as as Base64.

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 json_byte_size(document) View Source

Returns the approximate size of this document if it was encoded in JSON.

Does not include the attachment data.

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.

The _attachments field is treated specially:

  • Any given data is decoded internally and the length attribute is set
  • The follows attribute is removed and the stub attribute is set
  • If the attachments are given as list of tuples, their order is preserved

If the document already had attachments:

  • If data is set for any given attachment, it will override existing data; if not, existing data is kept
  • If the attachments are given as map, the existing order is preserved; if not, the order is taken from the list
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 revisions(document) View Source
revisions(doc :: t) :: [String.t] | nil

Returns a list of full revision numbers given through the document’s _revisions or _revs_info field, or nil if the both fields are missing or invalid. The revisions are sorted from newest to oldest.

Link to this function set_deleted(doc, keep_fields \\ false) View Source
set_deleted(doc :: t, keep_fields :: boolean) :: t

Marks the document as deleted.

This removes all fields except _id and _rev and deletes all attachments unless keep_fields is set to true.

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.

Link to this function to_multipart(doc) View Source
to_multipart(doc :: t) :: {:ok, [{map, binary}]} | :error

Serializes the given document including its attachment data to a list of multipart segments as consumed by ICouch.Multipart.join/2.