The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

The role of selector in {IssueTrackeR}

Introduction

In {IssueTrackeR}, a selector is a fundamental object used to specify the data sources from which you want to retrieve information (issues, labels, milestones, etc.).

library("IssueTrackeR")
#> Currently, the default options are:
#> - location for datasets: /tmp/RtmpRy8zET/data
#> - name for the datasets: ngiib
#> - selector:
#> 
#> Attaching package: 'IssueTrackeR'
#> The following objects are masked from 'package:base':
#> 
#>     append, sample, write

What is a selector?

A selector is an object of class SelectorTB. Technically, it is a list of configurations, where each configuration describes a specific source and the parameters needed to access it.

Supported sources

A selector can contain different types of sources:

  1. GitHub: Uses owner and repo (or just owner to fetch all repositories).
  2. GitLab: Uses project_id.
  3. Local: Uses a path to a YAML file containing issue data.

Note: When using source = "local", functions get_issues(), get_labels() and get_milestones() and update_database() will use the dataset_dir argument to look for files following the pattern list_issues_<dataset_name>.yaml, list_labels_<dataset_name>.yaml, or list_milestones_<dataset_name>.yaml.

How to create a selector?

The main way to create a selector is using the init_selector() function.

# GitHub selector
gh_sel <- init_selector(
    source = "GitHub",
    owner = "TanguyBarthelemy",
    repo = "IssueTrackeR"
)

# GitLab selector
gl_sel <- init_selector(source = "GitLab", project_id = 4578L)

# Local selector
local_sel <- init_selector(
    source = "local",
    dataset_dir = system.file("data_issues", package = "IssueTrackeR"),
    dataset_name = NULL
)

How is it displayed?

When you print() a SelectorTB object, it provides a formatted summary showing the number of selectors and the details for each one.

# Displaying them
print(gh_sel)
#> There is 1 selector. 
#> 
#> Selector n°1 
#> source: GitHub 
#> repo: IssueTrackeR 
#> owner: TanguyBarthelemy
print(gl_sel)
#> There is 1 selector. 
#> 
#> Selector n°1 
#> source: GitLab 
#> project_id: 4578
print(local_sel)
#> There is 1 selector. 
#> 
#> Selector n°1 
#> source: local 
#> dataset_name: NULL 
#> dataset_dir: /tmp/RtmpPUL2tK/Rinst18a12b5bf809/IssueTrackeR/data_issues

Manipulating a list of selectors

Since a SelectorTB is a list, you can combine, extract, or remove selectors.

Adding a new selector to a list of selectors

Use merge_selector() to combine multiple selectors into one.

sel1 <- init_selector(
    source = "GitHub",
    owner = "TanguyBarthelemy",
    repo = "IssueTrackeR"
)
sel2 <- init_selector(
    source = "local",
    dataset_dir = system.file("data_issues", package = "IssueTrackeR"),
    dataset_name = NULL
)

combined_sel <- merge_selector(sel1, sel2)
print(combined_sel)
#> There are 2 selectors. 
#> 
#> Selector n°1 
#> source: GitHub 
#> repo: IssueTrackeR 
#> owner: TanguyBarthelemy 
#> 
#> Selector n°2 
#> source: local 
#> dataset_name: NULL 
#> dataset_dir: /tmp/RtmpPUL2tK/Rinst18a12b5bf809/IssueTrackeR/data_issues

Extracting a selector from a list of selectors

Use extract_nth() to retrieve a specific selector by its index.

extracted <- extract_nth(combined_sel, 1L)
#> The 1th selector will be extracted.
print(extracted)
#> There is 1 selector. 
#> 
#> Selector n°1 
#> source: GitHub 
#> repo: IssueTrackeR 
#> owner: TanguyBarthelemy

Removing a selector from a list of selectors

Use remove_nth() to remove a selector at a specific position.

# Let's create a list of 3 selectors to demonstrate
sel3 <- init_selector(
    source = "GitHub",
    owner = "rstudio",
    repo = "rstudio"
)
list_sel <- merge_selector(sel1, sel2, sel3)

# Remove the second one
reduced_sel <- remove_nth(list_sel, 2L)
#> The 2th selector will be removed
print(reduced_sel)
#> There are 2 selectors. 
#> 
#> Selector n°1 
#> source: GitHub 
#> repo: IssueTrackeR 
#> owner: TanguyBarthelemy 
#> 
#> Selector n°2 
#> source: GitHub 
#> repo: rstudio 
#> owner: rstudio

The IssueTrackeR.selector option

The package provides a global option IssueTrackeR.selector. This option defines the default selector used by retrieval functions (like get_issues(), get_labels(), etc.) when no selector argument is explicitly provided.

# Check the current default
get_default_selector()
#> No selectors

# Set a default selector
set_default_selector(sel1)
get_default_selector()
#> There is 1 selector. 
#> 
#> Selector n°1 
#> source: GitHub 
#> repo: IssueTrackeR 
#> owner: TanguyBarthelemy

Now, get_issues() will use sel1 by default

You can reset the options to their default value (when loading for the first time the package).

reset_options()
#> Reset the default options to: 
#> - location for datasets:  /tmp/RtmpRy8zET/data 
#> - name for the datasets:  qxrhu 
#> - selector: NULL

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.