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/RtmpKkKyQb/data
#> - name for the datasets: mwlef
#> - 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: /home/runner/work/_temp/Library/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: /home/runner/work/_temp/Library/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 (usually empty)
getOption("IssueTrackeR.selector")
#> No selectors

# Set a default selector
options(IssueTrackeR.selector = sel1)

# Now, get_issues() will use sel1 by default
# Note: This requires a working environment/token to actually run get_issues()

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