add Host, Version and Secure options to replace URL

GitLab/API.pm

@@ -40,7 +40,15 @@ sub croak(@) { $log->fatal(@_); Carp::croak @_; }
 sub new {
     my ($class, %args) = @_;
 
-    croak "URL parameter is required" unless defined $args{URL};
+    croak "either URL or Host parameter is required, but not both"
+        unless (defined $args{URL} xor defined $args{Host});
+
+    if (defined $args{Host}) {
+        my $s = ($args{Secure} // 1) ? "https" : "http";
+        my $v = $args{Version} // 4;
+        $args{URL} = "$s://$args{Host}/api/v$v";
+    }
+
     $log->debug("initializing GitLab::API for \"$args{URL}\"");
 
     my $self = {
@@ -422,7 +430,7 @@ See L<GitLab API|http://doc.gitlab.com/ce/api/> for details.
 
     my $gitlab = GitLab::API->new(
         AuthToken   => $token,
-        URL         => $url,
+        Host        => $host,
     );
 
     # simple result
@@ -452,24 +460,81 @@ See L<GitLab API|http://doc.gitlab.com/ce/api/> for details.
 
 Creates a new instance of L<GitLab::API>. Takes a hash of arguments:
 
-    Login       user login
-    Email       user e-mail, required only if Login is not provided,
-    Password    user password
-    AuthToken   authentication token
-    URL         url to connect to, usually https://gitlab.domain/api/v3
-    DieOnError  see die_on_error() method
-    Cache       enable caching
+=over
+
+=item * Host specification
+
+Either C<URL> or C<Host> is required, but not both.
+
+=over
+
+=item C<URL>
+
+Fully specifies the API to connect to. Usually in format
+L<http(s)://gitlab.domain.com/api/v4>. Must not be combined with C<Host>.
+
+=item C<Host>
+
+Hostname of GitLab. Must not be combined with C<URL>.
+
+=item C<Version>
+
+Version of GitLab API to connect to. The default is C<4> and you should
+not change this unless you really need other versions.
+This options is ignored if C<URL> is used.
+
+=item C<Secure>
+
+Whether or not use HTTPS. The default is C<1>.
+This option is ignored if C<URL> is used.
+
+=back
+
+=item * Login information
+
+There are three ways to log in to GitLab, using a combination of parameters:
 
-C<URL> is always required.
-The method also requires I<either> C<AuthToken> I<or> ((C<Login> or C<Email>) and C<Password>).
-That is, the only meaningful combinations are
+=over
+
+=item C<AuthToken>
+
+Use GitLab Personal Token to access API. Does not need to use the Session
+API, hence avoids one step when setting up L<GitLab::API>.
+
+=item C<Login>, C<Password>
+
+This combination will use Session API to obtain token. Then it will
+continue as C<AuthToken> was specified.
+
+=item C<Email>, C<Password>
+
+An alternative to C<Login> and C<Password>.
+
+=back
+
+=item * Miscellaneous
 
-    GitLab::API->new(URL => $URL, AuthToken  => $TOKEN);
-    GitLab::API->new(URL => $URL, Login => $LOGIN, Password => $PASSWD);
-    GitLab::API->new(URL => $URL, Email => $EMAIL, Password => $PASSWD);
+=over
+
+=item C<DieOnError>
+
+API will call L<Carp/croak> if any request fails. This general option
+can be overriden when needed, by setting C<< -immortal => 1 >> to request.
+
+=item C<Cache>
+
+API will use L<GitLab::API::Cache> to store data along with their C<ETags>
+to speed up repetitive requests. This may, however, consume more memory.
+You may manually clear the cache by calling
 
-Caching is available since version L<9.0.0> and allows to cache responses
-based on C<ETag> headers. See L<GitLab::API::Cache> for more details.
+    $gitlab->cache->flush;
+
+The ETags are fully supported in GitLab since version 9.0.0. If L<GitLab::API>
+detects that GitLab is of earlier version, a warning will be logged.
+
+=back
+
+=back
 
 =item sudo()
 
@@ -480,9 +545,9 @@ Similar to L<sudo(8)|sudo>, changes identity to the user with the C<$username>.
 If the C<$username> argument is not defined, changes the identity back to the original user.
 
 I<This feature is available only to the admins.>
-You can test for that with the L</whoami> method this way:
+You can test for that with the L</is_admin> method like this:
 
-    if ($gitlab->whoami()->{is_admin}) {
+    if ($gitlab->is_admin) {
         # Booyah!
     }
 
@@ -507,7 +572,7 @@ The result is not affected by L</sudo()>.
     my $value = $gitlab->die_on_error();
     $gitlab->die_on_error($value);
 
-When called without an argument, returns the current value of the settings.
+When called without an argument, returns the current value of the setting.
 Otherwise sets the first argument as the value.
 
 If enabled, any call that returns an unsuccessful (!= 2**) HTTP code will call C<Carp/croak> with the status code.