Nothing
Migrating old code to the new mRpostman's syntax
In mRpostman: An IMAP Client for R
Introduction
This vignette aims to provide an easy source of code migration examples so old mRpostman users can transition between the old version and the new format which implements an OO approach trough the use of R6 class and methods.
This is the summary of the main modifications in the package between versions 0.3.1 and 0.9.X:
-
All main functions, except list_attachments and the custom-search helper functions, now are methods of the R6 class ImapConf;
-
The way the connection token is passed through functions (now methods) has changed. The connection handle is created inside configure_imap() (or ImapCon$new()) and modified with custom requests from the methods that trigger IMAP commands. As a consequence, the password is now hidden inside the curl handle C pointer, resulting in a more secure token chain. This resulted in changes in every request function. These functions (that are methods now) do not use config_handle() anymore, and a call to curl::set_opt() is made in every request function so that a custom request is supplied or replaced by a new one in the original handle.
-
The "by" argument used in search and fetch functions was replaced by use_uid, which is a logical now with the default value set as FALSE. This is equivalent to the former by = MSN default configuration.
-
all functions that returned invisible(0L) now return invisible(TRUE)
-
Users that prefer a tidy approach, only need to apply the pipe %>% operator between search and fetch methods (or other complementary operations), in which messages' ids are carried from one level to another. The exposition pipe %$% is not necessary anymore.
In the following sections, we present some code migration examples between the old and the new version of mRpostman.
1) Configuring the IMAP connection
Previous code:
wzxhzdk:0
New format:
wzxhzdk:1
Although the object that is created is different (now we have an R6 ImapCon class), the code to create a connection object is pretty much the same, but with an alternative that uses the "initialize" method of the R6 class.
Other useful options are timeout_ms, verbose = TRUE, and buffersize. Further 'curl' options related to IMAP functionalities can be passed to configure_imap(), depending on the libcurl version installed on the user's machine. See curl::curl_options(). In this new version, there is an important curl parameter exposed, xoauth2_bearer, which enables OAuth2.0 authentication. For more details, check the "IMAP OAuth2.0 authentication in mRpostman" vignette.
2) Listing Server Capabilities
Previous code:
wzxhzdk:2
New format:
wzxhzdk:3
3) Mailbox Commands
3.1) Listing mail folders
Previous code:
wzxhzdk:4
New format:
wzxhzdk:5
3.2) Folder selection
Previous code:
wzxhzdk:6
New format:
wzxhzdk:7
3.3) Examining a mail folder
Previous code:
wzxhzdk:8
New format:
wzxhzdk:9
In the new format, the previously selected folder is kept during the session unless you execute a new selection.
3.4) Renaming a mail folder
Previous code:
wzxhzdk:10
New format:
wzxhzdk:11
4) Single Search
All search functions now return only the message ids.
Previous code:
wzxhzdk:12
New format:
wzxhzdk:13
You can also NEGATE the statement to search for messages NOT BEFORE a date:
Previous code:
wzxhzdk:14
New format:
wzxhzdk:15
This pattern is applied to all SEARCH functions.
Special attention should be paid to the search_string and search_flag methods due to changes in the names and order of the arguments.
Search by string - example 1
Previous code:
wzxhzdk:16
New format:
wzxhzdk:17
Search by string - example 2
Previous code:
wzxhzdk:18
New format:
wzxhzdk:19
#### Search by flag
Previous code:
wzxhzdk:20
New format:
wzxhzdk:21
Now you can check which flags are available in a mail folder with the `list_flags()` method. Also, you can pass multiple flags as the search criterion.
## 5) Custom Search
Previous code:
wzxhzdk:22
New format:
wzxhzdk:23
## 6) Fetch
### 6.1) Fetch body
Previous code:
wzxhzdk:24
New format:
wzxhzdk:25
### 6.2) Fetch header
Previous code:
wzxhzdk:26
New format:
wzxhzdk:27
### 6.3) Fetch text
Previous code:
wzxhzdk:28
New format:
wzxhzdk:29
### 6.4) Fetch metadata
Previous code:
wzxhzdk:30
New format:
wzxhzdk:31
You can check the available metadata attributes with `metadata_options()`.
## 7) Attachments
### 7.1) Attachments listing
Previous code:
wzxhzdk:32
New format:
wzxhzdk:33
Note that `list_attachment()` is an independent function. It is not a method of the `ImapCon` class that depends on the connection object.
The new version brings an alternative fetch method (`fetch_atachments_list()`) for listing attachments without the need of previously executing a `fetch_body` or `fetch_text` operation:
wzxhzdk:34
### 7.2) Attachments Extraction
Previous code:
wzxhzdk:35
New format:
wzxhzdk:36
The new version brings an alternative fetch method (`fetch_atachments()`) for downloading attachments without the need of previously executing a `fetch_body` or `fetch_text` operation:
wzxhzdk:37
## 8) Complementary Operations
### 8.1) Copy message(s)
Previous code:
wzxhzdk:38
New format:
wzxhzdk:39
### 8.2) Move message(s) (depends on MOVE capability)
Previous code:
wzxhzdk:40
New format:
wzxhzdk:41
### 8.3) Search the minimum message ID with specific flag(s) (depends on ESEARCH capability)
Previous code:
wzxhzdk:42
New format:
wzxhzdk:43
### 8.4) Search the maximum message ID with specific flag(s) (depends on ESEARCH capability)
Previous code:
wzxhzdk:44
New format:
wzxhzdk:45
### 8.5) Delete message(s)
Previous code:
wzxhzdk:46
New format:
wzxhzdk:47
### 8.6) Expunge
Previous code:
wzxhzdk:48
New format:
wzxhzdk:49
### 8.7) Add/Remove/Replace flags
#### 8.7.1) Add flags
Previous code:
wzxhzdk:50
New format:
wzxhzdk:51
#### 8.7.2) Remove flags
Previous code:
wzxhzdk:52
New format:
wzxhzdk:53
#### 8.7.3) Replace flags
Previous code:
wzxhzdk:54
New format:
wzxhzdk:55
Try the mRpostman package in your browser
Any scripts or data that you put into this service are public.
mRpostman documentation built on Oct. 29, 2022, 1:16 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.
Introduction
This vignette aims to provide an easy source of code migration examples so old mRpostman users can transition between the old version and the new format which implements an OO approach trough the use of R6 class and methods.
This is the summary of the main modifications in the package between versions 0.3.1 and 0.9.X:
-
All main functions, except
list_attachmentsand the custom-search helper functions, now are methods of the R6 classImapConf; -
The way the connection token is passed through functions (now methods) has changed. The connection handle is created inside
configure_imap()(orImapCon$new()) and modified with custom requests from the methods that trigger IMAP commands. As a consequence, the password is now hidden inside the curl handle C pointer, resulting in a more secure token chain. This resulted in changes in every request function. These functions (that are methods now) do not useconfig_handle()anymore, and a call tocurl::set_opt()is made in every request function so that a custom request is supplied or replaced by a new one in the original handle. -
The "by" argument used in search and fetch functions was replaced by
use_uid, which is a logical now with the default value set asFALSE. This is equivalent to the formerby = MSNdefault configuration. -
all functions that returned
invisible(0L)now returninvisible(TRUE) -
Users that prefer a tidy approach, only need to apply the pipe
%>%operator between search and fetch methods (or other complementary operations), in which messages' ids are carried from one level to another. The exposition pipe%$%is not necessary anymore.
In the following sections, we present some code migration examples between the old and the new version of mRpostman.
1) Configuring the IMAP connection
Previous code:
wzxhzdk:0
New format: wzxhzdk:1
New format: wzxhzdk:1
Although the object that is created is different (now we have an R6 ImapCon class), the code to create a connection object is pretty much the same, but with an alternative that uses the "initialize" method of the R6 class.
Other useful options are timeout_ms, verbose = TRUE, and buffersize. Further 'curl' options related to IMAP functionalities can be passed to configure_imap(), depending on the libcurl version installed on the user's machine. See curl::curl_options(). In this new version, there is an important curl parameter exposed, xoauth2_bearer, which enables OAuth2.0 authentication. For more details, check the "IMAP OAuth2.0 authentication in mRpostman" vignette.
2) Listing Server Capabilities
Previous code:
wzxhzdk:2
New format:
wzxhzdk:3
3) Mailbox Commands
3.1) Listing mail folders
Previous code:
wzxhzdk:4
New format:
wzxhzdk:5
3.2) Folder selection
Previous code:
wzxhzdk:6
New format:
wzxhzdk:7
3.3) Examining a mail folder
Previous code:
wzxhzdk:8
New format:
wzxhzdk:9
In the new format, the previously selected folder is kept during the session unless you execute a new selection.
3.4) Renaming a mail folder
Previous code:
wzxhzdk:10
New format: wzxhzdk:11
New format: wzxhzdk:11
4) Single Search
All search functions now return only the message ids.
Previous code:
wzxhzdk:12
New format: wzxhzdk:13
New format: wzxhzdk:13
You can also NEGATE the statement to search for messages NOT BEFORE a date:
Previous code:
wzxhzdk:14
New format:
wzxhzdk:15
This pattern is applied to all SEARCH functions.
Special attention should be paid to the search_string and search_flag methods due to changes in the names and order of the arguments.
Search by string - example 1
Previous code:
wzxhzdk:16
New format: wzxhzdk:17
New format: wzxhzdk:17
Search by string - example 2
Previous code:
wzxhzdk:18
New format: wzxhzdk:19 #### Search by flag
mRpostman documentation built on Oct. 29, 2022, 1:16 a.m.
New format: wzxhzdk:19 #### Search by flag
Previous code:
wzxhzdk:20
New format: wzxhzdk:21
Now you can check which flags are available in a mail folder with the `list_flags()` method. Also, you can pass multiple flags as the search criterion.
## 5) Custom Search
New format: wzxhzdk:21
Previous code:
wzxhzdk:22
New format:
wzxhzdk:23
## 6) Fetch
### 6.1) Fetch body
Previous code:
wzxhzdk:24
New format:
wzxhzdk:25
### 6.2) Fetch header
Previous code:
wzxhzdk:26
New format:
wzxhzdk:27
### 6.3) Fetch text
Previous code:
wzxhzdk:28
New format:
wzxhzdk:29
### 6.4) Fetch metadata
Previous code:
wzxhzdk:30
New format:
wzxhzdk:31
You can check the available metadata attributes with `metadata_options()`.
## 7) Attachments
### 7.1) Attachments listing
Previous code:
wzxhzdk:32
New format: wzxhzdk:33
Note that `list_attachment()` is an independent function. It is not a method of the `ImapCon` class that depends on the connection object.
The new version brings an alternative fetch method (`fetch_atachments_list()`) for listing attachments without the need of previously executing a `fetch_body` or `fetch_text` operation:
wzxhzdk:34
### 7.2) Attachments Extraction
New format: wzxhzdk:33
Previous code:
wzxhzdk:35
New format: wzxhzdk:36
The new version brings an alternative fetch method (`fetch_atachments()`) for downloading attachments without the need of previously executing a `fetch_body` or `fetch_text` operation:
wzxhzdk:37
## 8) Complementary Operations
### 8.1) Copy message(s)
New format: wzxhzdk:36
Previous code:
wzxhzdk:38
New format:
wzxhzdk:39
### 8.2) Move message(s) (depends on MOVE capability)
Previous code:
wzxhzdk:40
New format:
wzxhzdk:41
### 8.3) Search the minimum message ID with specific flag(s) (depends on ESEARCH capability)
Previous code:
wzxhzdk:42
New format:
wzxhzdk:43
### 8.4) Search the maximum message ID with specific flag(s) (depends on ESEARCH capability)
Previous code:
wzxhzdk:44
New format:
wzxhzdk:45
### 8.5) Delete message(s)
Previous code:
wzxhzdk:46
New format:
wzxhzdk:47
### 8.6) Expunge
Previous code:
wzxhzdk:48
New format: wzxhzdk:49
### 8.7) Add/Remove/Replace flags
#### 8.7.1) Add flags
New format: wzxhzdk:49
Previous code:
wzxhzdk:50
New format:
wzxhzdk:51
#### 8.7.2) Remove flags
Previous code:
wzxhzdk:52
New format:
wzxhzdk:53
#### 8.7.3) Replace flags
Previous code:
wzxhzdk:54
New format:
wzxhzdk:55
Try the mRpostman package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.