NAME

Etherpad - interact with Etherpad API

VERSION

version 1.2.14.0

SYNOPSIS


            
              
              use Etherpad;
my $ec = Etherpad->new(
  url      => 'http://pad.example.org',
  apikey   => 'secret_etherpad_API_key',
  user     => 'http_user',
  password => 'http_password',
  proxy    => {
      http  => 'http://proxy.example.org',
      https => 'http://proxy.example.org'
  }
);
$ec->create_pad('new_pad_name');

DESCRIPTION

Client module for the Etherpad HTTP API.

The Etherpad API currently supported is the 1.2.13 (Etherpad version: 1.6.0)

This module aims to replace Etherpad::API

ATTRIBUTES

Etherpad implements the following attributes.

url


            
              
              my $url = $ec->url;
$ec     = $ec->url('http://pad.example.org');

MANDATORY. The Etherpad URL, no default.

apikey


            
              
              my $apikey = $ec->apikey;
$ec        = $ec->apikey('secret_etherpad_API_key');

MANDATORY. Secret API key, located in the APIKEY.txt file of your Etherpad installation directory, no default.

ua


            
              
              my $ua = $ec->ua;
$ec    = $ec->ua(Mojo::UserAgent->new);

OPTIONAL. User agent, default to a Mojo::UserAgent. Please, don't use anything other than a Mojo::Useragent.

user


            
              
              my $user = $ec->user;
$ec      = $ec->user('bender');

OPTIONAL. HTTP user, use it if your Etherpad is protected by a HTTP authentication, no default.

password


            
              
              my $password = $ec->password;
$ec          = $ec->password('beer');

OPTIONAL. HTTP password, use it if your Etherpad is protected by a HTTP authentication, no default.

proxy


            
              
              my $proxy = $ec->proxy;
$ec       = $ec->proxy({
  http  => 'http://proxy.example.org',
  https => 'http://proxy.example.org'
});

OPTIONAL. Proxy settings. If set to { detect => 1 }, Etherpad will check environment variables HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, NO_PROXY and no_proxy for proxy information. No default.

METHODS

Etherpad inherits all methods from Mojo::Base and implements the following new ones.

Groups

Pads can belong to a group. The padID of grouppads is starting with a groupID like g.asdfasdfasdfasdf$test

See https://etherpad.org/doc/v1.6.0/#index_groups

create_group


            
              
              Usage     : $ec->create_group();
Purpose   : Creates a new group
Returns   : The new group ID
Argument  : None
See       : https://etherpad.org/doc/v1.6.0/#index_creategroup

create_group_if_not_exists_for


            
              
              Usage     : $ec->create_group_if_not_exists_for('groupMapper');
Purpose   : This functions helps you to map your application group ids to epl group ids
Returns   : The epl group id
Argument  : Your application group id
See       : https://etherpad.org/doc/v1.6.0/#index_creategroupifnotexistsfor_groupmapper

delete_group


            
              
              Usage     : $ec->delete_group('groupId');
Purpose   : Deletes a group
Returns   : 1 if it succeeds
Argument  : The id of the group you want to delete
See       : https://etherpad.org/doc/v1.6.0/#index_deletegroup_groupid

list_pads


            
              
              Usage     : $ec->list_pads('groupId');
Purpose   : Returns all pads of this group
Returns   : An array or an array reference (depending on the context) which contains the pad ids
Argument  : The id of the group from which you want the pads
See       : https://etherpad.org/doc/v1.6.0/#index_listpads_groupid

create_group_pad


            
              
              Usage     : $ec->create_group_pad('groupID', 'padName' [, 'text'])
Purpose   : Creates a new pad in this group
Returns   : 1 if it succeeds
Argument  : The group id, the pad name, optionally takes the pad's initial text
See       : https://etherpad.org/doc/v1.6.0/#index_creategrouppad_groupid_padname_text

list_all_groups


            
              
              Usage     : $ec->list_all_groups()
Purpose   : Lists all existing groups
Returns   : An array or an array reference (depending on the context) which contains the groups ids
Argument  : None
See       : https://etherpad.org/doc/v1.6.0/#index_listallgroups

Author

These authors are bound to the attributes the users choose (color and name).

See https://etherpad.org/doc/v1.6.0/#index_author

create_author


            
              
              Usage     : $ec->create_author(['name'])
Purpose   : Creates a new author
Returns   : The new author ID
Argument  : Optionally takes a string as argument : the new author's name
See       : https://etherpad.org/doc/v1.6.0/#index_createauthor_name

create_author_if_not_exists_for


            
              
              Usage     : $ec->create_author_if_not_exists_for(authorMapper [, name])
Purpose   : This functions helps you to map your application author ids to epl author ids
Returns   : The epl author ID
Argument  : Your application author ID (mandatory) and optionally the epl author name
See       : https://etherpad.org/doc/v1.6.0/#index_createauthorifnotexistsfor_authormapper_name

list_pads_of_author


            
              
              Usage     : $ec->list_pads_of_author('authorID')
Purpose   : Returns an array of all pads this author contributed to
Returns   : An array or an array reference depending on the context, containing the pads names
Argument  : An epl author ID
See       : https://etherpad.org/doc/v1.6.0/#index_listpadsofauthor_authorid

get_author_name


            
              
              Usage     : $ec->get_author_name('authorID')
Purpose   : Returns the Author Name of the author
Returns   : The author name
Argument  : The epl author ID
See       : https://etherpad.org/doc/v1.6.0/#index_getauthorname_authorid

Session

Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-seperated sessionIDs, allowing a user to edit pads in different groups at the same time. Only users with a valid session for this group, can access group pads. You can create a session after you authenticated the user at your web application, to give them access to the pads. You should save the sessionID of this session and delete it after the user logged out.

See https://etherpad.org/doc/v1.6.0/#index_session

create_session


            
              
              Usage     : $ec->create_session('groupID', 'authorID', 'validUntil')
Purpose   : Creates a new session. validUntil is an unix timestamp in seconds
Returns   : The epl session ID
Argument  : An epl group ID, an epl author ID and an valid unix timestamp (the session validity end date)
See       : https://etherpad.org/doc/v1.6.0/#index_createsession_groupid_authorid_validuntil

delete_session


            
              
              Usage     : $ec->delete_session('sessionID')
Purpose   : Deletes a session
Returns   : 1 if it succeeds
Argument  : An epl session ID
See       : https://etherpad.org/doc/v1.6.0/#index_deletesession_sessionid

get_session_info


            
              
              Usage     : $ec->get_session_info('sessionID')
Purpose   : Returns informations about a session
Returns   : A hash reference, containing 3 keys : authorID, groupID and validUntil
Argument  : An epl session ID
See       : https://etherpad.org/doc/v1.6.0/#index_getsessioninfo_sessionid

list_sessions_of_group


            
              
              Usage     : $ec->list_sessions_of_group('groupID')
Purpose   : Returns all sessions of a group
Returns   : Returns a hash reference, which keys are sessions ID and values are sessions infos (see get_session_info)
Argument  : An epl group ID
See       : https://etherpad.org/doc/v1.6.0/#index_listsessionsofgroup_groupid

list_sessions_of_author


            
              
              Usage     : $ec->list_sessions_of_author('authorID')
Purpose   : Returns all sessions of an author
Returns   : Returns a hash reference, which keys are sessions ID and values are sessions infos (see get_session_info)
Argument  : An epl group ID
See       : https://etherpad.org/doc/v1.6.0/#index_listsessionsofauthor_authorid

Pad Content

Pad content can be updated and retrieved through the API.

See https://etherpad.org/doc/v1.6.0/#index_pad_content

get_text


            
              
              Usage     : $ec->get_text('padID', ['rev'])
Purpose   : Returns the text of a pad
Returns   : A string, containing the text of the pad
Argument  : Takes a pad ID (mandatory) and optionally a revision number
See       : https://etherpad.org/doc/v1.6.0/#index_gettext_padid_rev

set_text


            
              
              Usage     : $ec->set_text('padID', 'text')
Purpose   : Sets the text of a pad
Returns   : 1 if it succeeds
Argument  : Takes a pad ID and the text you want to set (both mandatory)
See       : https://etherpad.org/doc/v1.6.0/#index_settext_padid_text

append_text


            
              
              Usage     : $ec->append_text('padID', 'text')
Purpose   : Appends text to a pad
Returns   : 1 if it succeeds
Argument  : Takes a pad ID and the text you want to append (both mandatory)
See       : https://etherpad.org/doc/v1.6.0/#index_appendtext_padid_text

get_html


            
              
              Usage     : $ec->get_html('padID', ['rev'])
Purpose   : Returns the text of a pad formatted as html
Returns   : A string, containing the text of the pad formatted as html
Argument  : Takes a pad ID (mandatory) and optionally a revision number
See       : https://etherpad.org/doc/v1.6.0/#index_gethtml_padid_rev

set_html


            
              
              Usage     : $ec->set_html('padID', 'html')
Purpose   : Sets the text of a pad based on HTML, HTML must be well formed.
Returns   : 1 if it succeeds
Argument  : Takes a pad ID and the HTML code you want to set (both mandatory)
See       : https://etherpad.org/doc/v1.6.0/#index_sethtml_padid_html

get_attribute_pool


            
              
              Usage     : $ec->get_attribute_pool('padID')
Purpose   : Returns the attribute pool of a pad
Returns   : A hash reference, containing 3 keys
            * numToAttrib, containing a hash reference, which keys are integers and contents are array references
            * attribToNum, containing a hash reference, which keys are string and contents are integers
            * nextNum, which content is an integer
Argument  : Takes a pad ID (mandatory)
See       : https://etherpad.org/doc/v1.6.0/#index_getattributepool_padid

get_revision_changeset


            
              
              Usage     : $ec->get_revision_changeset('padID' [, rev])
Purpose   : Get the changeset at a given revision, or last revision if 'rev' is not defined
Returns   : A string, representing an etherpad changeset
Argument  : Takes a pad ID (mandatory) and optionally a revision number
See       : https://etherpad.org/doc/v1.6.0/#index_getrevisionchangeset_padid_rev

create_diff_html


            
              
              Usage     : $ec->create_diff_html('padId', rev1, rev2)
Purpose   : Returns an object of diffs from 2 points in a pad
Returns   : A hash reference which keys are
            * html, which content is a string representing the diff between the two revisions
            * authors, which content is an array reference of authors
Argument  : Takes a pad ID, a revision number to start and a revision number to end. All arguments are mandatory
See       : https://etherpad.org/doc/v1.6.0/#index_creatediffhtml_padid_startrev_endrev

restore_revision


            
              
              Usage     : $ec->restore_revision('padId', rev)
Purpose   : Restores revision from past as new changeset
Returns   : 1 if it succeeds
Argument  : Takes a pad ID, a revision number to restore. All arguments are mandatory
See       : https://etherpad.org/doc/v1.7.0/#index_restorerevision_padid_rev

Chat

See https://etherpad.org/doc/v1.6.0/#index_chat

get_chat_history


            
              
              Usage     : $ec->get_chat_history('padID' [, start, end])
Purpose   : Returns
             - a part of the chat history, when start and end are given
             - the whole chat history, when no extra parameters are given
Returns   : An array or an array reference, depending of the context, containing hash references with 4 keys :
             - text     => text of the message
             - userId   => epl user id
             - time     => unix timestamp of the message
             - userName => epl user name
Argument  : Takes a pad ID (mandatory) and optionally the start and the end numbers of the messages you want.
            The start number can't be higher than or equal to the current chatHead. The first chat message is number 0.
            If you specify a start but not an end, all messages will be returned.
See       : https://etherpad.org/doc/v1.6.0/#index_getchathistory_padid_start_end

get_chat_head


            
              
              Usage     : $ec->get_chat_head('padID')
Purpose   : Returns the chatHead (last number of the last chat-message) of the pad
Returns   : The last chat-message number. -1 if there is no chat message
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_getchathead_padid

append_chat_message


            
              
              Usage     : $ec->append_chat_message('padID', 'text', 'authorID', 'timestamp')
Purpose   : Add a message to chat
Returns   : 1 if it succeeds
Argument  : Takes a pad ID (mandatory), a text (mandatory), an author ID (mandatory) and a timestamp (mantdatory)
See       : Undocumented yet

Pad

Group pads are normal pads, but with the name schema GROUPID$PADNAME. A security manager controls access of them and its forbidden for normal pads to include a $ in the name.

See https://etherpad.org/doc/v1.6.0/#index_pad

create_pad


            
              
              Usage     : $ec->create_pad('padID' [, 'text'])
Purpose   : Creates a new (non-group) pad. Note that if you need to create a group Pad, you should call create_group_pad.
Returns   : 1 if it succeeds
Argument  : Takes a pad ID (mandatory) and optionally a text to fill the pad
See       : https://etherpad.org/doc/v1.6.0/#index_createpad_padid_text

get_revisions_count


            
              
              Usage     : $ec->get_revisions_count('padID')
Purpose   : Returns the number of revisions of this pad
Returns   : The number of revisions
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_getrevisionscount_padid

get_saved_revisions_count


            
              
              Usage     : $ec->get_saved_revisions_count('padID')
Purpose   : Returns the number of saved revisions of this pad
Returns   : The number of saved revisions
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_getsavedrevisionscount_padid

list_saved_revisions


            
              
              Usage     : $ec->list_saved_revisions('padID')
Purpose   : Returns the list of saved revisions of this pad
Returns   : An array or an array reference, depending of the context, containing the saved revisions numbers
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_listsavedrevisions_padid

save_revision


            
              
              Usage     : $ec->save_revision('padID', ['rev'])
Purpose   : Saves a revision
Returns   : 1 if it succeeds
Argument  : Takes a pad ID (mandatory) and optionally a revision number
See       : https://etherpad.org/doc/v1.6.0/#index_saverevision_padid_rev

get_users_count


            
              
              Alias for pad_users_count (see below)

pad_users_count


            
              
              Usage     : $ec->pad_users_count('padID')
Purpose   : Returns the number of user that are currently editing this pad
Returns   : The number of users
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_paduserscount_padid

pad_users


            
              
              Usage     : $ec->pad_users('padID')
Purpose   : Returns the list of users that are currently editing this pad
Returns   : An array or an array reference, depending of the context, containing hash references with 3 keys : colorId, name and timestamp
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_padusers_padid

delete_pad


            
              
              Usage     : $ec->delete_pad('padID')
Purpose   : Deletes a pad
Returns   : 1 if it succeeds
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_deletepad_padid

copy_pad


            
              
              Usage     : $ec->copy_pad('sourceID', 'destinationID' [, 1])
Purpose   : Copies a pad with full history and chat. If force is true and the destination pad exists, it will be overwritten
Returns   : 1 if it succeeds
Argument  : A source pad ID
            A destination pad ID
            A force flag : a value which is true or false, in perl interpretation (for example; 0 and '' are false, 1, 2 and 'foo' are true)
See       : https://etherpad.org/doc/v1.6.0/#index_copypad_sourceid_destinationid_force_false

move_pad


            
              
              Usage     : $ec->move_pad('sourceID', 'destinationID' [, 1])
Purpose   : Moves a pad. If force is true and the destination pad exists, it will be overwritten
Returns   : 1 if it succeeds
Argument  : A source pad ID
            A destination pad ID
            A force flag : a value which is true or false, in perl interpretation (for example; 0 and '' are false, 1, 2 and 'foo' are true)
See       : https://etherpad.org/doc/v1.6.0/#index_movepad_sourceid_destinationid_force_false

get_read_only_id


            
              
              Usage     : $ec->get_read_only_id('padID')
Purpose   : Returns the read only link of a pad
Returns   : A string
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_getreadonlyid_padid

get_pad_id


            
              
              Usage     : $ec->get_pad_id('readOnlyID')
Purpose   : Returns the id of a pad which is assigned to the readOnlyID
Returns   : A string
Argument  : A read only ID
See       : https://etherpad.org/doc/v1.6.0/#index_getpadid_readonlyid

set_public_status


            
              
              Usage     : $ec->set_public_status('padID', 'publicStatus')
Purpose   : Sets a boolean for the public status of a pad
Returns   : 1 if it succeeds
Argument  : A pad ID and the public status you want to set : 1 or 0
See       : https://etherpad.org/doc/v1.6.0/#index_setpublicstatus_padid_publicstatus

get_public_status


            
              
              Usage     : $ec->get_public_status('padID')
Purpose   : Return true of false
Returns   : 1 or 0
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_getpublicstatus_padid

set_password


            
              
              Usage     : $ec->set_password('padID', 'password')
Purpose   : Returns ok or a error message
Returns   : 1 if it succeeds
Argument  : A pad ID and a password
See       : https://etherpad.org/doc/v1.6.0/#index_setpassword_padid_password

is_password_protected


            
              
              Usage     : $ec->is_password_protected('padID')
Purpose   : Returns true or false
Returns   : 1 or 0
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_ispasswordprotected_padid

list_authors_of_pad


            
              
              Usage     : $ec->list_authors_of_pad('padID')
Purpose   : Returns an array of authors who contributed to this pad
Returns   : An array or an array reference depending on the context, containing the epl authors IDs
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_listauthorsofpad_padid

list_names_of_authors_of_pad


            
              
              Usage     : $ec->list_names_authors_of_pad('padID')
Returns   : Returns an array of the names of the authors who contributed to this pad in list context
            Returns an array reference in scalar context
Argument  : The pad ID
See       : This is not part of the Etherpad API but a facility offered by this module

get_last_edited


            
              
              Usage     : $ec->get_last_edited('padID')
Purpose   : Returns the timestamp of the last revision of the pad
Returns   : A unix timestamp
Argument  : A pad ID
See       : https://etherpad.org/doc/v1.6.0/#index_getlastedited_padid

send_clients_message


            
              
              Usage     : $ec->send_clients_message('padID', 'msg')
Purpose   : Sends a custom message of type msg to the pad
Returns   : 1 if it succeeds
Argument  : A pad ID and the message you want to send
See       : https://etherpad.org/doc/v1.6.0/#index_sendclientsmessage_padid_msg

check_token


            
              
              Usage     : $ec->check_token()
Purpose   : Returns ok when the current api token is valid
Returns   : 1 if the token is valid, 0 otherwise
Argument  : None
See       : https://etherpad.org/doc/v1.6.0/#index_checktoken

Pads

See https://etherpad.org/doc/v1.6.0/#index_pads

list_all_pads


            
              
              Usage     : $ec->list_all_pads()
Purpose   : Lists all pads on this epl instance
Returns   : An array or an array reference depending on the context, containing the pads names
See       : https://etherpad.org/doc/v1.6.0/#index_listallpads

Global

See https://etherpad.org/doc/v1.8.3/#global

(URL not usable yet)

get_stats


            
              
              Usage     : $ec->get_stats()
Purpose   : Get stats of the etherpad instance
Returns   : A hash reference, containing 3 keys : totalPads, totalSessions and totalActivePads
See       : https://etherpad.org/doc/v1.8.3/#getstats (URL not usable yet)

INSTALL

After getting the tarball on https://metacpan.org/release/Etherpad, untar it, go to the directory and:


            
              
              perl Makefile.PL
make
make test
make install

If you are on a windows box you should use 'nmake' rather than 'make'.

BUGS and SUPPORT

You can find documentation for this module with the perldoc command.


            
              
              perldoc Etherpad

Bugs and feature requests will be tracked on:


            
              
              https://framagit.org/fiat-tux/etherpad/issues

The latest source code can be browsed and fetched at:


            
              
              https://framagit.org/fiat-tux/etherpad
git clone https://framagit.org/fiat-tux/etherpad.git

Source code mirror:


            
              
              https://github.com/ldidry/etherpad

You can also look for information at:


            
              
              AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Etherpad
CPAN Ratings
http://cpanratings.perl.org/d/Etherpad
Search CPAN
http://search.cpan.org/dist/Etherpad

AUTHOR


            
              
              Luc DIDRY
CPAN ID: LDIDRY
ldidry@cpan.org
https://fiat-tux.fr/

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

AUTHOR

Luc Didry <ldidry@cpan.org>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install Etherpad, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Etherpad

CPAN shell

perl -MCPAN -e shell
install Etherpad

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

ATTRIBUTES

url

apikey

ua

user

password

proxy

METHODS

Groups

create_group

create_group_if_not_exists_for

delete_group

list_pads

create_group_pad

list_all_groups

Author

create_author

create_author_if_not_exists_for

list_pads_of_author

get_author_name

Session

create_session

delete_session

get_session_info

list_sessions_of_group

list_sessions_of_author

Pad Content

get_text

set_text

append_text

get_html

set_html

get_attribute_pool

get_revision_changeset

create_diff_html

restore_revision

Chat

get_chat_history

get_chat_head

append_chat_message

Pad

create_pad

get_revisions_count

get_saved_revisions_count

list_saved_revisions

save_revision

get_users_count

pad_users_count

pad_users

delete_pad

copy_pad

move_pad

get_read_only_id

get_pad_id

set_public_status

get_public_status

set_password

is_password_protected

list_authors_of_pad

list_names_of_authors_of_pad

get_last_edited

send_clients_message

check_token

Pads

list_all_pads

Global

get_stats

INSTALL

BUGS and SUPPORT

AUTHOR

COPYRIGHT

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions