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
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 section Functions
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
.
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.
Deletes the entry in doc
for a specific key
.
If the key
does not exist, returns doc
unchanged.
Deletes the attachment specified by filename
from doc
.
Returns the document unchanged, if the attachment didn't exist.
Deletes the attachment data of all attachments in doc
.
This does not delete the respective attachment info (stub).
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.
Includes _id
, _rev
and _revisions
/_revs_info
.
Attachments are compared using equal_attachments?/2
.
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.
Tests two documents for field equality.
Ignores _id
, _rev
and _revisions
.
Attachments are compared using equal_attachments?/2
.
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.
Deserializes a document from a map or binary.
If attachments with data exist, they will be decoded and stored in the struct separately.
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
.
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.
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.
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.
Note that the list will also contain attachments that have no associated data.
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.
Does not include the attachment data.
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.
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.
Puts the given field value
under key
in doc
.
The _attachments
field is treated specially:
- Any given
data
is decoded internally and thelength
attribute is set - The
follows
attribute is removed and thestub
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)
View SourceInserts 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.
This removes all fields except _id
and _rev
and deletes all attachments
unless keep_fields
is set to true
.
Set the document ID for doc
.
Attempts to set it to nil
will actually remove the ID from the document.
Set the revision number for doc
.
Attempts to set it to nil
will actually remove the revision number from the
document.
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.
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
.