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

Types

key()

t()

value()

Functions

attachment_data_size(document)

Returns the sum of all attachment data sizes in doc.

attachment_data_size(document, filename)

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

delete(doc, key)

Deletes the entry in doc for a specific key.

delete_attachment(doc, filename)

Deletes the attachment specified by filename from doc.

delete_attachment_data(doc)

Deletes the attachment data of all attachments in doc.

delete_attachment_data(doc, filename)

Deletes the attachment data specified by filename from doc.

delete_attachments(doc)

Deletes all attachments and attachment data from doc.

deleted?(document)

Returns whether the document is marked as deleted.

equal?(doc1, doc2)

Tests two documents for equality.

equal_attachments?(doc1, doc2)

Tests the attachments of two documents for equality.

equal_content?(doc1, doc2)

Tests two documents for field equality.

fetch(document, key)

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

from_api(doc)

Deserializes a document from a map or binary.

from_api!(doc)

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

from_multipart(list)

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

full_json_byte_size(doc)

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

get(doc, key, default \\ nil)

Gets the field value for a specific key in doc.

get_and_update(doc, key, fun)

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

get_attachment(document, filename)

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

get_attachment_data(document)

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

get_attachment_data(document, filename)

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

get_attachment_info(document, filename)

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

has_attachment?(document, filename)

Returns whether an attachment with the given filename exists.

has_attachment_data?(document, filename)

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

json_byte_size(document)

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

new(id_or_fields \\ nil, rev \\ nil)

Creates a new document struct.

pop(doc, key, default \\ nil)

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

put(doc, key, value)

Puts the given field value under key in doc.

put_attachment(doc, filename, data, content_type \\ "application/octet-stream", digest \\ nil)

put_attachment_data(doc, filename, data)

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.

put_attachment_info(doc, filename, info)

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

revisions(document)

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.

set_deleted(doc, keep_fields \\ false)

Marks the document as deleted.

set_id(doc, id)

Set the document ID for doc.

set_rev(doc, rev)

Set the revision number for doc.

to_api(doc, options \\ [])

Serializes the given document to a binary.

to_api!(doc, options \\ [])

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

to_multipart(doc)

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

key()

key() :: String.t()

t()

t() :: %ICouch.Document{
  attachment_data: %{optional(key()) => binary()},
  attachment_order: [String.t()],
  fields: %{optional(key()) => value()},
  id: String.t() | nil,
  rev: String.t() | nil
}

value()

value() :: any()

Link to this section Functions

attachment_data_size(document)

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.

attachment_data_size(document, filename)

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.

delete(doc, key)

delete(doc :: t(), key()) :: t()

Deletes the entry in doc for a specific key.

If the key does not exist, returns doc unchanged.

delete_attachment(doc, filename)

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.

delete_attachment_data(doc)

delete_attachment_data(doc :: t()) :: t()

Deletes the attachment data of all attachments in doc.

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

delete_attachment_data(doc, filename)

delete_attachment_data(doc :: t(), filename :: key()) :: t()

Deletes the attachment data specified by filename from doc.

delete_attachments(doc)

delete_attachments(doc :: t()) :: t()

Deletes all attachments and attachment data from doc.

deleted?(document)

deleted?(doc :: t()) :: boolean()

Returns whether the document is marked as deleted.

equal?(doc1, doc2)

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.

equal_attachments?(doc1, doc2)

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.

equal_content?(doc1, doc2)

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.

fetch(document, key)

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.

from_api(doc)

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.

from_api!(doc)

from_api!(fields :: map() | binary()) :: t()

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

from_multipart(list)

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.

full_json_byte_size(doc)

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

get(doc, key, default \\ nil)

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.

get_and_update(doc, key, fun)

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.

get_attachment(document, filename)

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.

get_attachment_data(document)

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.

get_attachment_data(document, filename)

get_attachment_data(doc :: t(), filename :: key()) :: binary() | nil

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

get_attachment_info(document, filename)

get_attachment_info(doc :: t(), filename :: key()) :: map() | nil

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

has_attachment?(document, filename)

has_attachment?(doc :: t(), filename :: key()) :: boolean()

Returns whether an attachment with the given filename exists.

has_attachment_data?(document, filename)

has_attachment_data?(doc :: t(), filename :: key()) :: boolean()

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

json_byte_size(document)

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

Does not include the attachment data.

new(id_or_fields \\ nil, rev \\ nil)

new(id_or_fields :: String.t() | nil | map(), 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.

pop(doc, key, default \\ nil)

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.

put(doc, key, value)

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

put_attachment(doc, filename, data, content_type \\ "application/octet-stream", digest \\ nil)

put_attachment(
  doc :: t(),
  filename :: key(),
  data :: binary() | {map(), binary()},
  content_type :: String.t(),
  digest :: String.t() | nil
) :: t()

put_attachment_data(doc, filename, data)

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.

put_attachment_info(doc, filename, info)

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.

revisions(document)

revisions(doc :: t()) :: [String.t()] | nil

set_deleted(doc, keep_fields \\ false)

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.

set_id(doc, id)

set_id(doc :: t(), id :: String.t() | nil) :: t()

Set the document ID for doc.

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

set_rev(doc, rev)

set_rev(doc :: t(), rev :: String.t() | nil) :: t()

Set the revision number for doc.

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

to_api(doc, options \\ [])

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.

to_api!(doc, options \\ [])

to_api!(doc :: t(), options :: [any()]) :: binary()

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

to_multipart(doc)

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.