Update pod-GitLab-Users.md

5090dd03 · Roman Lacko · 21c47855 · 5090dd03
Commit 5090dd03 authored Sep 29, 2016 by Roman Lacko
--- a/pod-GitLab-Users.md
+++ b/pod-GitLab-Users.md
 # NAME

-GitLab::Users - implements user API calls
+`GitLab::Users` - implements user API calls

 See [GitLab API -- Users](http://doc.gitlab.com/ce/api/users.html) for details and
 response formats.
@@ -12,35 +12,41 @@ Checked 2016-09-29 for GitLab CE `v8.12.1`.

 # SYNOPSIS

-    use GitLab::API;
-    use GitLab::Users;
-    # all calls from GitLab::Users are "injected" into the GitLab::API as methods
+```{.pl}
+use GitLab::API;
+use GitLab::Users;
+# all calls from GitLab::Users are "injected" into the GitLab::API as methods

-    my $api = GitLab::API->new();
+my $api = GitLab::API->new(...);

-    my $john = $api->users(username => "john_doe");
+my $john = $api->users(username => "john_doe");

-    $api->user_create(
-        email       => "jane34@somewhere.com",
-        password    => "s3cre1",
-        username    => "jane.doe",
-        name        => "Jane Doe"
-    );
+$api->user_create(
+    email       => "jane34@somewhere.com",
+    password    => "s3cre1",
+    username    => "jane.doe",
+    name        => "Jane Doe"
+);
+```

 # DESCRIPTION

 ## Notation

 All methods take a hash of arguments as specified in the documentation for
-["exec\_request" in GitLab::API](https://metacpan.org/pod/GitLab::API#exec_request), but to simplify the documentation,
+[`exec_request` in GitLab::API](pod-GitLab-API.md#exec_request), but to simplify the documentation,
 we will use the following notation:

-    users( :username, :search )
+```{.rb}
+users( :username, :search )
+```

 which means that the `users` method takes a hash with two keys, `username`
 and `search`, so it can be called as

-    $gitlab->users(search => "john_doe");
+```{.pl}
+$gitlab->users(search => "john_doe");
+```

 Optional arguments are denoted as ` [:username] `.
 Note that not all optional arguments are listed.
@@ -48,47 +54,61 @@ Please refer to the official documentation for the full list.

 ## User CRUD operations

- users()
+- `users()`

-        $users = $gitlab->users( [:username], [:search] );
+    ```{.pl}
+    $users = $gitlab->users( [:username], [:search] );
+    ```

    This method returns all users. The optional arguments can be used
    to filter out the results:

-        username        search for a user by his username (exact match)
-        search          search for users with username or email (substring match)
+    | argument      | description |
+    | ------------- | ----------- |
+    | `username`    | search for a user by his username (**exact match**) |
+    | `search`      | search for users with username or email (**substring match**) |

    Note that the returned value is still an array even when `users(username => $username)`
    always returns at most one result.

- user\_by\_id()
+- `user_by_id()`

-        $user = $gitlab->user_by_id( :uid );
+    ```{.pl}
+    $user = $gitlab->user_by_id( :uid );
+    ```

    Returns a user with the given `uid`.

- user\_create()
+- `user_create()`

-        $user = $gitlab->user_create( :email, :password, :username, :name );
+    ```{.pl}
+    $user = $gitlab->user_create( :email, :password, :username, :name [, ...]);
+    ```

    Creates a new user and if succeeds, returns the generated account information.

-        email               primary email, must not exist in GitLab,
-        password            user password,
-        username            login, must not exist in GitLab,
-        name                display name
+    | argument            | description |
+    | ------------------- | ----------- |
+    | `email`             | primary email, must not exist in GitLab |
+    | `password`          | user password |
+    | `username`          | login, must not exist in GitLab |
+    | `name`              | display name |

    The function can take many optional arguments. Please see the API documentation for
    the full list. Most interesting arguments are:

-        admin               create an admin account (bool)
-        can_create_group    the user will be able to create group (bool)
-        external            create an external account (bool)
-        projects_limit      maximum number of projects the user can own
+    | argument | description |
+    | -------- | ----------- |
+    | `admin`  |  create an admin account (bool) |
+    | `can_create_group` | the user will be able to create group (bool) |
+    | `external` | create an external account (bool) |
+    | `projects_limit` |  maximum number of projects the user can own |

- user\_update()
+- `user_update()`

-        $user = $gitlab->user_update( :uid );
+    ```{.pl}
+    $user = $gitlab->user_update( :uid );
+    ```

    Updates the user with the given `uid`. It takes the same arguments as `user_create`
    except they are all optional. Note that though it is possible to change user's primary e-mail
@@ -96,150 +116,189 @@ Please refer to the official documentation for the full list.

    Also, from documentation:

-        Note, at the moment this method does only return a 404 error, even in cases where
-        a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one.
+    > Note, at the moment this method does only return a 404 error, even in cases where
+    > a 409 (Conflict) would be more appropriate, e.g. when renaming the email address to some existing one.

- user\_delete()
+- `user_delete()`

-        $gitlab->user_delete( :uid );
+    ```{.pl}
+    $gitlab->user_delete( :uid );
+    ```

    Deletes the user with the given `uid`.

    Note that

-        calling this function for a non-existent user id still returns a status code 200 OK.
-        The JSON response differs if the user was actually deleted or not.
+    > calling this function for a non-existent user id still returns a status code 200 OK.
+    > The JSON response differs if the user was actually deleted or not.

    (from the GitLab API documentation).

- user()
+- `user()`

-        $user = $gitlab->user();
+    ```{.pl}
+    $user = $gitlab->user();
+    ```

    Returns the user whose authentication key is used for the request
    (or impersonated user if `sudo` is in effect).

-    Behaves the same as the ["whoami" in GitLab::API](https://metacpan.org/pod/GitLab::API#whoami) method.
+    Behaves the same as the [`whoami` in GitLab::API](https://metacpan.org/pod/GitLab::API#whoami) method.

 ## SSH keys

- self\_ssh\_keys()
+- `self_ssh_keys()`

-        $keys = $gitlab->self_ssh_keys();
+    ```{.pl}
+    $keys = $gitlab->self_ssh_keys();
+    ```

    Returns a list of SSH keys for the user that makes the request.

- self\_get\_ssh\_key()
+- `self_get_ssh_key()`

-        $key = $gitlab->self_get_ssh_key( :keyid );
+    ```{.pl}
+    $key = $gitlab->self_get_ssh_key( :keyid );
+    ```

    For the user that makes the request, the function returns the SSH key with the given `keyid`.

- user\_get\_ssh\_keys()
+- `user_get_ssh_keys()`

-        $keys = $gitlab->user_get_ssh_keys( :uid );
+    ```{.pl}
+    $keys = $gitlab->user_get_ssh_keys( :uid );
+    ```

    Returns a list of SSH keys for the user with the given `uid`.

- self\_add\_ssh\_key()
+- `self_add_ssh_key()`

-        $key = $gitlab->self_add_ssh_key( :title, :key );
+    ```{.pl}
+    $key = $gitlab->self_add_ssh_key( :title, :key );
+    ```

    Adds a new key for the user that makes the request. Required arguments are

-        title               the title of the key
-        key                 public SSH key
+    | argument | description |
+    | -------- | ----------- |
+    | `title`  | the title of the key |
+    | `key`    | public SSH key |

- user\_add\_ssh\_key()
+- `user_add_ssh_key()`

-        $key = $gitlab->user_add_ssh_key( :uid, :title, :key );
+    ```{.pl}
+    $key = $gitlab->user_add_ssh_key( :uid, :title, :key );
+    ```

    Similar to `self_add_ssh_key`, but targets the user with the given `uid`.

- self\_delete\_ssh\_key()
+- `self_delete_ssh_key()`

-        $gitlab->self_delete_ssh_key( :keyid )
+    ```{.pl}
+    $gitlab->self_delete_ssh_key( :keyid )
+    ```

    Removes the SSH key with the given `keyid` for the user that makes the request.

- user\_delete\_ssh\_key()
+- `user_delete_ssh_key()`

-        $gitlab->user_delete_ssh_key( :uid, :keyid );
+    ```{.pl}
+    $gitlab->user_delete_ssh_key( :uid, :keyid );
+    ```

    Removes the SSH key with the `keyid` for the user with the given `uid`.

 ## E-mails

- self\_get\_emails()
+- `self_get_emails()`

-        $emails = $gitlab->self_get_emails();
+    ```{.pl}
+    $emails = $gitlab->self_get_emails();
+    ```

    Returns a list of **secondary** e-mails for the user that makes the request.

    Note that primary e-mail can be obtained from the result of `whoami`.

- user\_get\_emails()
+- `user_get_emails()`

-        $emails = $gitlab->user_get_emails( :uid );
+    ```{.pl}
+    $emails = $gitlab->user_get_emails( :uid );
+    ```

    Returns a list of **secondary** e-mails for the user with the `uid`.

    Note that primary e-mail can be obtained from the result of `user_by_id`.

- self\_get\_email()
+- `self_get_email()`

-        $email = $gitlab->self_get_email( :eid );
+    ```{.pl}
+    $email = $gitlab->self_get_email( :eid );
+    ```

    Returns the e-mail with the given `eid` of the user that makes the request.

- self\_add\_email()
+- `self_add_email()`

-        $email = $gitlab->self_add_email( :email );
+    ```{.pl}
+    $email = $gitlab->self_add_email( :email );
+    ```

    Adds a new `email` for the user that makes the request. The e-mail must
    not exist in GitLab.

- user\_add\_email()
+- `user_add_email()`

-        $email = $gitlab->user_add_email( :uid, :email );
+    ```{.pl}
+    $email = $gitlab->user_add_email( :uid, :email );
+    ```

    Adds a new `email` for the user with the given `uid`. The e-mail must
    not exist in GitLab.

- self\_delete\_email()
+- `self_delete_email()`

-        $gitlab->self_delete_email( :eid );
+    ```{.pl}
+    $gitlab->self_delete_email( :eid );
+    ```

    Deletes the e-mail with `eid` of the user that makes the request.

- user\_delete\_email()
+- `user_delete_email()`

-        $gitlab->user_delete_email( :uid, :eid );
+    ```{.pl}
+    $gitlab->user_delete_email( :uid, :eid );
+    ```

    Removes the e-mail with `eid` of the user with the given `uid`.

 ## Account blocking

- user\_block()
+- `user_block()`

-        $gitlab->user_block( :uid );
+    ```{.pl}
+    $gitlab->user_block( :uid );
+    ```

    Blocks the user with `uid` in the GitLab.

- user\_unblock()
+- `user_unblock()`

-        $gitlab->user_unblock( :uid );
+    ```{.pl}
+    $gitlab->user_unblock( :uid );
+    ```

    Unblocks the user with `uid` in the GitLab.
+    
    Note that LDAP blocked users cannot be unblocked by this function.
    In that case the API would return `403 Forbidden`.

 # AUTHOR

-Roman Lacko <[xlacko1@fi.muni.cz](https://metacpan.org/pod/xlacko1@fi.muni.cz)>
+Roman Lacko <[`xlacko1@fi.muni.cz`](mailto:xlacko1@fi.muni.cz)>

 # SEE ALSO

- [GitLab](https://metacpan.org/pod/GitLab)
+- [GitLab](pod-GitLab.md)

-    Wrapper around [GitLab::API](https://metacpan.org/pod/GitLab::API) and other `GitLab::*` modules.
+    Wrapper around [GitLab::API](pod-GitLab-API.md) and other `GitLab::*` modules.