ICouch v0.2.1 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
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
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
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
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
.
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.
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(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.
Like from_api/1
but raises an error on decoding failures.
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
.
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
.
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
.
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.
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 :: t, options :: [any]) :: binary
Like to_api/1
but raises an error on encoding failures.
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
.