---
title: "{Rmoji} R package"
Type: "Package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{{Rmoji} R package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Introduction

The `{Rmoji}` package provides functions and tools for inserting emojis into your R scripts, R Markdown, and Quarto documents, including using easy keyboard shortcut. The Shortcut and addin options makes it easy for users and use emojies like a direct keyboard entity. This vignette demonstrates how to use the package. The Rmoji package also provided a function to insert to git commit messages.

## Installing the Package

You can install the package from CRAN or from GitHub:

```{r install-from-github, eval = FALSE }

# Install from CRAN

## Using the base R
# install.packages("Rmoji")

## using the {pacman} package
# pacman::p_load(Rmoji)

# Install from GitHub

# install.packages("devtools")

 devtools::install_github("3p1d3m/Rmoji")

# load the package

library(Rmoji)

```


## features

🔹`insert_emoji()` – Inserts emojis with name-based auto completion.

🔹`insert_emoji_subset` - To subset the the first/last n, number of emojies. 

🔹`insert_emoji_addin()` – A GUI addin to select and insert emojis.

🔹`emoji_shortcut()` – Add to RStudio keyboard shortcuts.

🔹`git_emoji()` – Easily add emojis to your Git commit messages.

🔹`emoji_list()` – View the full emoji dictionary.

🔹`shiny_emoji ()` - shiny addin with drop down option


## Example Usage

### Listing emojies

🔸 The `{Rmoji}` package use a list of selected Emojies for the moment and they can be accessed through the `emoji_list()` function. this will print the available emojies and the images in the console.

```{r r emoji-preview, echo = TRUE}

data("emoji_dict", package = "Rmoji")

# Print first 10 emoji names
emoji_names <- head(names(emoji_dict), 10)

```



### Insert emojies on cursor

🔸 to insert the emojies on cursor `insert_emojies()` function is used and and it takes string name of the emoji form the emoji list dictionary. This can also be used with inline codes in Rmd.

```{r emoji-insert-examples, eval=FALSE}

# Insert the smile emoji 
smile <- insert_emoji("smile")

# returns smile = 😄

# Insert the start emoji
start <- insert_emoji("star")

# returns star = ⭐

```

### Insert emojis using addin popup

🔸 The insert_emoji_addin() function is an RStudio addin that opens a prompt asking the user to input an emoji name. If the emoji name is valid, the corresponding emoji is inserted at the current cursor position in the active editor. below Emojis are inserted using this addin.

🧠To use this addin:

  ✅ Navigate to the Addins menu in RStudio.

  ✅ Select `Insert Emoji Addin`

  ✅ Type an emoji name (e.g., "smile") in the prompt that appears.

  ✅ The emoji will be inserted into your active script or document.

### Inserting emoji through keyboard shortcut

🔸 The main advantage of this package is to visually insert the emoji using the keyboard shortcut. To custom create a short cut, go to your `Rstudio-->Tools-->Modify keyboard shortcuts`, then search for `Emoji shortcut addin` and hit the short cut you want to assign in your keyboard. Mine is `Cmd + E`. Assign yours as you feel comfortable.

``` r

Cmd + E

```

## Insert emoji using shiny dropdown

🔸 Since we have thousands of of emojis and sometime hard to remember them by name, there is a shiny option with drop-down to select the proper emoji. It is available in the addins as `shiny emoji` and it can also be assigned to any keyboard shortcut. in R studio go to `Tools`—\>`modify keyboard shortcuts` —\>`shiny emoji` then hit the short cut you wanted in your keyboard. mine is `Shift + E`. This will pop up a shiny up with options to search and select form the drop down.

### Using Emojis in Git Commit Messages

🔸 Using emojis in your Git commit messages is a fun way to make your Git history more expressive and easy to understand. It can help indicate the purpose of each commit more clearly—whether it’s fixing a bug, adding a new feature, or just updating documentation. You can access a wide range of emojis from the `git_emoji()` function to customize your messages.

#### Step 1: Selecting an Emoji for the Commit

First, you’ll need to call the `git_emoji()` function and pass the emoji name you'd like to use in your commit message.

For example, let's say you want to use a "bug" emoji to indicate a bug fixed for your code:

```{r get-bug-emoji, eval = FALSE}

# Get the bug 

bug_emoji <- git_emoji("bug")

# Returns:🐛

bug_emoji

```

This will return the Unicode for the bug emoji (🐛), which you can include in your Git commit message.

#### Step 2: Adding the Emoji to Your Commit Message

🔸 Now, you can include the emoji in your Git commit message. Here’s an example of how to make a commit in Git, using the system() function to execute Git commands directly from R console:

``` r

# check the status of documenst in directory and git
system("git status") # to check the git status 

# add the files to be added to commit
system("git add {file}")  # Replace with your file name

# optional to add all files pedning commit 
system("git add -a") # To push all changes at once, less recommende

# create the bug for commiting 
bug_emoji <- git_emoji("bug") # create the emojy you wanted to push

# create the commit message 
commit_message <- paste("Fixed the issue with user authentication", bug_emoji)

# commit the change 
system(paste("git commit -m", shQuote(commit_message)))

```

#### Step 3: Pushing the Commit to GitHub (Optional)

If you want to push the commit to your GitHub repository, you can do so by executing the following command from R:

``` r

# Push the commit to the remote repository
system("git push origin main")  # Replace "main" with your branch if different

```

If you wanted to push them all together as well:

``` r

system("git add {R/..} && git commit -m 'update' && git push") # replace the path with yours 

```

#### Citation:

To cite the {Rmoji} package in publications, use: Tesfay, BE. (2025). {Rmoji}: A package for inserting emojis in RStudio. R package version 0.1.0. Available at: <https://github.com/3p1d3m/Rmoji>

🥲 can I be cited though❓ I 'm an emoji 😄😸