Class luchia.document

High-level document class.

Contains all of the high-level methods to manage documents and attachments. This module should be used instead of the core modules when possible.

See the document.lua example for more detail.

Info:

  • Copyright: 2011-2015 Chad Phillips
  • Author: Chad Phillips

Local Functions

luchia.document.document_call(self, method, path, query_parameters, data) Make a document-related request to the server.
luchia.document.make_document(self, data, id, rev) Make a document object.
luchia.document.make_attachment(self, file_path, content_type, file_name, custom_loader_function) Make an attachment object.

Methods

luchia.document:new(database, server_params) Create a new document handler object.
luchia.document:list(query_parameters) List all documents.
luchia.document:retrieve(id, query_parameters) Retrieve a document.
luchia.document:create(document, id) Create a document.
luchia.document:update(document, id, rev) Update a document.
luchia.document:copy(id, destination) Copy a document.
luchia.document:delete(id, rev) Delete a document.
luchia.document:info(id) Get basic information on a document.
luchia.document:current_revision(id) Get the current revision for a document.
luchia.document:add_standalone_attachment(file_path, content_type, file_name, id, rev, custom_loader_function) Add a standalone attachment to a document.
luchia.document:add_inline_attachment(file_path, content_type, file_name, document, id, rev, custom_loader_function) Add an inline attachment to a document.
luchia.document:retrieve_attachment(attachment, id) Retrieve an attachment.
luchia.document:delete_attachment(attachment, id, rev) Delete an attachment.
luchia.document:response_ok(response) Check the response for success.


Local Functions

Methods
luchia.document.document_call(self, method, path, query_parameters, data)
Make a document-related request to the server.

Parameters:

  • self
  • method Required. The HTTP method.
  • path Required. The server path.
  • query_parameters Optional. A table of query parameters to pass to the server, key is parameter name, value is parameter value, eg. '{ include_docs = "true", limit = "3" }'.
  • data Optional. A data object.

Returns:

    The following four values, in this order: responsedata, responsecode, headers, status_code.
luchia.document.make_document(self, data, id, rev)
Make a document object.

Parameters:

  • self
  • data Optional. A table of data representing the document.
  • id Optional. The document ID.
  • rev Optional. The document revision.

Returns:

    The new document object.
luchia.document.make_attachment(self, file_path, content_type, file_name, custom_loader_function)
Make an attachment object.

Parameters:

  • self
  • file_path Required. The path to the file to add as an attachment. Relative paths can be used, but must have a path component, eg. "./myfile" or "/tmp/attachment.txt".
  • content_type Required. The mime content type of the attachment, eg. "text/plain"
  • file_name Optional. The name of the attachment as stored in CouchDB. If not provided, then the base name of file_path will be used.
  • custom_loader_function Optional. Custom function to load the attachment.

Returns:

    The new attachment object.

Methods

luchia.document:new(database, server_params)
Create a new document handler object.

Parameters:

  • database Required. The database to connect to.
  • server_params Optional. A table of server connection parameters (identical to default.server in luchia.conf. If not provided, a server object will be generated from the default server configuration.

Returns:

    A document handler object.

Usage:

    doc = luchia.document:new("example_database", server_params)
luchia.document:list(query_parameters)
List all documents.

Parameters:

Returns:

    Same values as document_call, response_data is a list of documents.

See also:

Usage:

    response = doc:list()
luchia.document:retrieve(id, query_parameters)
Retrieve a document.

Parameters:

  • id Required. The document ID.
  • query_parameters Optional. Same as the document_call method.

Returns:

    Same values as document_call, response_data is a table representing the document.

See also:

Usage:

    response = doc:retrieve("document-id")
luchia.document:create(document, id)
Create a document.

Parameters:

  • document Optional. A table representing the document. If none is provided, an empty document will be created by default.
  • id Optional. The document ID. If not provided, a server-generated uuid will be used instead.

Returns:

    Same values as document_call, response_data is a table of the request result.

See also:

Usage:

    response = doc:create({hello = "world"}, "document-id")
luchia.document:update(document, id, rev)
Update a document.

Parameters:

  • document Required. A table representing the updated document.
  • id Required. The document ID.
  • rev Required. The document revision.

Returns:

    Same values as document_call, response_data is a table of the request result.

See also:

Usage:

    response = doc:update({hello = "another world"}, "document-id",
       "1-15f65339921e497348be384867bb940f")
luchia.document:copy(id, destination)
Copy a document.

Parameters:

  • id Required. The document ID.
  • destination Required. The ID of the destination document.

Returns:

    Same values as document_call, response_data is a table of the request result.

See also:

Usage:

    response = doc:copy("document-id", "document-copy")
luchia.document:delete(id, rev)
Delete a document.

Parameters:

  • id Required. The document ID.
  • rev Required. The document revision.

Returns:

    Same values as document_call, response_data is a table of the request result.

See also:

Usage:

    response = doc:delete("document-id",
       "1-15f65339921e497348be384867bb940f")
luchia.document:info(id)
Get basic information on a document.

This method makes a HEAD request.

Parameters:

  • id Required. The document ID.

Returns:

    A table of the returned headers.

Usage:

    response = doc:info("document-id")
luchia.document:current_revision(id)
Get the current revision for a document.

Parameters:

  • id Required. The document ID.

Returns:

    The current revision.

Usage:

    response = doc:current_revision("document-id")
luchia.document:add_standalone_attachment(file_path, content_type, file_name, id, rev, custom_loader_function)
Add a standalone attachment to a document.

Parameters:

  • file_path Required. Same as make_attachment.
  • content_type Required. Same as make_attachment.
  • file_name Optional. Same as make_attachment.
  • id Optional. The document ID to attach the file to. If no document exists, one will be created for the attachment.
  • rev The document revision. This is only required if attaching to an existing document.
  • custom_loader_function Optional. Custom function to load the attachment.

Returns:

    Same values as document_call, response_data is a table of the request result.

See also:

Usage:

     response = doc:add_standalone_attachment("/tmp/file.txt",
       "text/plain", "afile", "document-id",
       "1-15f65339921e497348be384867bb940f")
luchia.document:add_inline_attachment(file_path, content_type, file_name, document, id, rev, custom_loader_function)
Add an inline attachment to a document.

Parameters:

  • file_path Required. Same as make_attachment.
  • content_type Required. Same as make_attachment.
  • file_name Optional. Same as make_attachment.
  • document Optional. A table representing the document to add the attachment to. If none is provided, an empty document will be used.
  • id Optional. The document ID to attach the file to. If no document exists, one will be created for the attachment.
  • rev The document revision. This is only required if attaching to an existing document.
  • custom_loader_function Optional. Custom function to load the attachment.

Returns:

    Same values as document_call, response_data is a table of the request result.

See also:

Usage:

     response = doc:add_inline_attachment("/tmp/file.txt",
       "text/plain", "afile", {hello = "world"}, "document-id",
       "1-15f65339921e497348be384867bb940f")
luchia.document:retrieve_attachment(attachment, id)
Retrieve an attachment.

Parameters:

  • attachment Required. The attachment name.
  • id Required. The document ID.

Returns:

    Same values as document_call, response_data is the attachment data.

See also:

Usage:

    response = doc:retrieve_attachment("afile", "document-id")
luchia.document:delete_attachment(attachment, id, rev)
Delete an attachment.

Parameters:

  • attachment Required. The attachment name.
  • id Required. The document ID.
  • rev Required. The document revision.

Returns:

    Same values as document_call, response_data is a table of the request result.

See also:

Usage:

    response = doc:delete_attachment("afile", "document-id",
       "1-15f65339921e497348be384867bb940f")
luchia.document:response_ok(response)
Check the response for success.

A convenience method to ensure a successful request.

Parameters:

  • response Required. The response object returned from the server request.

Returns:

    true if the server responsed with an ok:true, false otherwise.

Usage:

    operation_succeeded = doc:response_ok(response)
generated by LDoc 1.4.3 Last updated 2016-01-14 11:22:48