# FUNCTION: update_user -------------------------------------------------------
#
#' Update your user properties in GitHub
#'
#' This function updates your user properties in GitHub. You cannot update
#' someone else's profile.
#'
#' For more details see the GitHub API documentation:
#'
#' - <https://docs.github.com/en/rest/reference/users#update-the-authenticated-user>
#'
#' @param name (string, optional) The new name of the user.
#' @param email (string, optional) The publicly visible email address of the
#' user.
#' @param blog (string, optional) The new blog URL of the user.
#' @param company (string, optional) The new company of the user.
#' @param location (string, optional) The new location of the user.
#' @param hireable (boolean, optional) The new hiring availability of the user.
#' @param bio (string, optional) The new short biography of the user.
#' @param ... Parameters passed to [gh_request()].
#'
#' @return `update_user()` returns a list of the new user properties.
#'
#' **User Properties:**
#'
#' - **id**: The ID of the user.
#' - **login**: The login name of the user.
#' - **name**: The name of the user.
#' - **email**: The public email address of the user.
#' - **blog**: The blog address of the user.
#' - **company**: The company the user works for.
#' - **location**: The location of the user.
#' - **hireable**: Whether the user currently hireable.
#' - **bio**: The biography of the user.
#' - **type**: The type of account.
#' - **site_admin**: Whether the user is an administrator.
#' - **html_url**: The GitHub page for the user.
#'
#' @examples
#' \dontrun{
#'
#' # Update your name
#' update_user(name = "Bob Smith")
#'
#' # Update your company
#' update_user(company = "Acme")
#'
#' # Update your hireable status
#' update_user(hireable = TRUE)
#'
#' }
#'
#' @export
#'
update_user <- function(
name,
email,
blog,
company,
location,
hireable,
bio,
...
) {
payload <- list()
if (!is_missing_or_null(name)) {
assert_character(name, n = 1)
payload$name <- name
}
if (!is_missing_or_null(email)) {
assert_character(email, n = 1)
payload$email <- email
}
if (!is_missing_or_null(blog)) {
assert_character(blog, n = 1)
payload$blog <- blog
}
if (!is_missing_or_null(company)) {
assert_character(company, n = 1)
payload$company <- company
}
if (!is_missing_or_null(location)) {
assert_character(location, n = 1)
payload$location <- location
}
if (!is_missing_or_null(hireable)) {
assert_logical(hireable, n = 1)
payload$hireable <- hireable
}
if (!is_missing_or_null(bio)) {
assert_character(bio, n = 1)
payload$bio <- bio
}
info("Updating user")
user_lst <- gh_url("user") %>%
gh_request("PATCH", payload = payload, ...)
info("Transforming results", level = 4)
user_gh <- select_properties(user_lst, properties$user)
info("Done", level = 7)
user_gh
}
# FUNCTION: view_users --------------------------------------------------------
#
#' View users in GitHub
#'
#' `view_users()` summarises users in a table with the properties as columns and
#' a row for each user. `view_user()` returns a list of all properties for a
#' single user. `browse_user()` opens the web page for the user in the default
#' browser.
#'
#' You can summarise all the users associated with either an organization or a
#' team within an organization. If none of those are supplied the first `n_max`
#' users of GitHub are returned.
#'
#' For more details see the GitHub API documentation:
#'
#' - <https://docs.github.com/en/rest/reference/orgs#list-organization-members>
#' - <https://docs.github.com/en/rest/reference/teams#list-team-members>
#' - <https://docs.github.com/en/rest/reference/users#list-users>
#' - <https://docs.github.com/en/rest/reference/users#get-a-user>
#'
#' @param user (string) The login of the user.
#' @param org (string, optional) The name of the organization.
#' @param team (string, optional) The name of the team.
#' @param role (string, optional) Filter the result by role. Can specify either
#' `"admin"`, `"member"` or `"all"`. Default: `"all"`.
#' @param n_max (integer, optional) Maximum number to return. Default: `1000`.
#' @param ... Parameters passed to [gh_page()] or [gh_request()].
#'
#' @return `view_users()` returns a tibble of user properties. `view_user()`
#' returns a list of properties for a single user. `browse_user()` opens the
#' default browser on the user's page and returns the URL.
#'
#' **user Properties:**
#'
#' - **id**: The ID of the user.
#' - **login**: The login name of the user.
#' - **name**: The name of the user (only available in `view_user()`).
#' - **email**: The public email address of the user (only available in
#' `view_user()`).
#' - **blog**: The blog address of the user (only available in `view_user()`).
#' - **company**: The company the user works for (only available in
#' `view_user()`).
#' - **location**: The location of the user (only available in `view_user()`).
#' - **hireable**: Whether the user currently hireable (only available in
#' `view_user()`).
#' - **bio**: The biography of the user (only available in `view_user()`).
#' - **site_admin**: Whether the user is an administrator.
#' - **html_url**: The GitHub page for the user.
#'
#' @examples
#' \dontrun{
#'
#' # View users collaborating on a repository
#' view_users(repo = "ChadGoymer/githapi")
#'
#' # View users in an organization
#' view_users(org = "HairyCoos")
#'
#' # View users in a team within an organization
#' view_users(org = "HairyCoos", team = "HeadCoos")
#'
#' # View the admins of an organization
#' view_users(org = "HairyCoos", role = "admin")
#'
#' # View a single user
#' view_user("ChadGoymer")
#'
#' # Browse a user's GitHub page
#' browse_user("ChadGoymer")
#'
#' }
#'
#' @export
#'
view_users <- function(
org,
team,
role = "all",
n_max = 1000,
...
) {
assert_natural(n_max, n = 1)
if (!is_missing_or_null(org)) {
assert_character(org, n = 1)
assert_character(role, n = 1)
assert_in(role, values$user$role)
if (!is_missing_or_null(team)) {
assert_character(team, n = 1)
team <- gh_url("orgs", org, "teams") %>%
gh_find(property = "name", value = team, ...)
info("Viewing users in team '", team$name, "'")
url <- gh_url("teams", team$id, "members", role = role)
}
else {
info("Viewing users in organization '", org, "'")
url <- gh_url("orgs", org, "members", role = role)
}
}
else {
info("Viewing all users")
url <- gh_url("users")
}
users_lst <- gh_page(url = url, n_max = n_max, ...)
info("Transforming results", level = 4)
users_gh <- bind_properties(users_lst, properties$users)
info("Done", level = 7)
users_gh
}
# FUNCTION: view_user ---------------------------------------------------------
#
#' @rdname view_users
#' @export
#'
view_user <- function(
user,
...
) {
if (is_missing_or_null(user)) {
info("Viewing authenticated user")
url <- gh_url("user")
}
else {
assert_character(user, n = 1)
info("Viewing user '", user, "'")
url <- gh_url("users", user)
}
user_lst <- gh_request("GET", url = url, ...)
info("Transforming results", level = 4)
user_gh <- select_properties(user_lst, properties$user)
info("Done", level = 7)
user_gh
}
# FUNCTION: browse_user -------------------------------------------------------
#
#' @rdname view_users
#' @export
#'
browse_user <- function(
user,
...
) {
user <- view_user(user, ...)
info("Browsing user '", user$name, "'")
httr::BROWSE(user$html_url)
info("Done", level = 7)
structure(
user$html_url,
class = c("github", "character"),
url = attr(user, "url"),
request = attr(user, "request"),
status = attr(user, "status"),
header = attr(user, "header")
)
}
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.