README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, echo=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

[![Travis-CI Build Status](https://travis-ci.org/hrbrmstr/docxtractr.svg?branch=master)](https://travis-ci.org/hrbrmstr/docxtractr)
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/hrbrmstr/docxtractr?branch=master&svg=true)](https://ci.appveyor.com/project/hrbrmstr/docxtractr)
[![Coverage Status](https://img.shields.io/codecov/c/github/hrbrmstr/docxtractr/master.svg)](https://codecov.io/github/hrbrmstr/docxtractr?branch=master)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/docxtractr)](http://cran.r-project.org/package=docxtractr)

![](docxtractr-logo.png)

# docxtractr 

Extract Data Tables and Comments from 'Microsoft' 'Word' Documents

## Description 

An R package for extracting tables & comments out of Word documents (docx). Development versions are available here and production versions are [on CRAN](https://cran.rstudio.com/web/packages/docxtractr/index.html).

Microsoft Word docx files provide an XML structure that is fairly
straightforward to navigate, especially when it applies to Word tables. The docxtractr package provides tools to determine table count, table structure and extract tables from Microsoft Word docx documents.

Many tables in Word documents are in twisted formats where there may be labels or other oddities mixed in that make it difficult to work with the underlying data. `docxtractr` provides a function&mdash;`assign_colnames`&mdash;that makes it easy to identify a particular row in a scraped (or any, really) `data.frame` as the one containing column names and have it become the column names, removing it and (optionally) all of the rows before it (since that's usually what needs to be done).

## What's in the tin?

The following functions are implemented:

- `read_docx`:	Read in a Word document for table extraction
- `docx_describe_tbls`:	Returns a description of all the tables in the Word document
- `docx_describe_cmnts`:	Returns a description of all the comments in the Word document
- `docx_extract_tbl`:	Extract a table from a Word document
- `docx_extract_cmnts`:	Extract comments from a Word document
- `docx_extract_all_tbls`:	Extract all tables from a Word document (`docx_extract_all` is now deprecated)
- `docx_tbl_count`:	Get number of tables in a Word document
- `docx_cmnt_count`:	Get number of comments in a Word document
- `assign_colnames`:	Make a specific row the column names for the specified data.frame
- `mcga` : Make column names great again
- `set_libreoffice_path`:	Point to Local soffice.exe File

The following data file are included:

- `system.file("examples/data.docx", package="docxtractr")`: Word docx with 1 table
- `system.file("examples/data3.docx", package="docxtractr")`: Word docx with 3 tables
- `system.file("examples/none.docx", package="docxtractr")`: Word docx with 0 tables
- `system.file("examples/complex.docx", package="docxtractr")`: Word docx with non-uniform tables
- `system.file("examples/comments.docx", package="docxtractr")`: Word docx with comments
- `system.file("examples/realworld.docx", package="docxtractr")`: A "real world" Word docx file with tables of all shapes and sizes
- `system.file("examples/trackchanges.docx", package="docxtractr")`: Word docx with track changes in a table

## Installation

```{r inst, eval=FALSE}
# devtools::install_github("hrbrmstr/docxtractr")
# OR 
install.packages("docxtractr")
```

```{r opts, echo=FALSE}
options(width=120)
```

## Usage

```{r libs, message=FALSE, warning=FALSE}
library(docxtractr)
library(tibble)
library(dplyr)

# current version
packageVersion("docxtractr")

```

```{r sample}
# one table
doc <- read_docx(system.file("examples/data.docx", package="docxtractr"))

docx_tbl_count(doc)

docx_describe_tbls(doc)

docx_extract_tbl(doc, 1)

docx_extract_tbl(doc)

docx_extract_tbl(doc, header=FALSE)

# url 

budget <- read_docx("http://rud.is/dl/1.DOCX")

docx_tbl_count(budget)

docx_describe_tbls(budget)

docx_extract_tbl(budget, 1)

docx_extract_tbl(budget, 2) 

# three tables
doc3 <- read_docx(system.file("examples/data3.docx", package="docxtractr"))

docx_tbl_count(doc3)

docx_describe_tbls(doc3)

docx_extract_tbl(doc3, 3)

# no tables
none <- read_docx(system.file("examples/none.docx", package="docxtractr"))

docx_tbl_count(none)

# wrapping in try since it will return an error
# use docx_tbl_count before trying to extract in scripts/production
try(docx_describe_tbls(none))
try(docx_extract_tbl(none, 2))

# 5 tables, with two in sketchy formats
complx <- read_docx(system.file("examples/complex.docx", package="docxtractr"))

docx_tbl_count(complx)

docx_describe_tbls(complx)

docx_extract_tbl(complx, 3, header=TRUE)

docx_extract_tbl(complx, 4, header=TRUE)

docx_extract_tbl(complx, 5, header=TRUE)

# a "real" Word doc
real_world <- read_docx(system.file("examples/realworld.docx", package="docxtractr"))

docx_tbl_count(real_world)

# get all the tables
tbls <- docx_extract_all_tbls(real_world)

# see table 1
tbls[[1]]

# make table 1 better
assign_colnames(tbls[[1]], 2)

# make table 1's column names great again 
mcga(assign_colnames(tbls[[1]], 2))

# see table 5
tbls[[5]]

# make table 5 better
assign_colnames(tbls[[5]], 2)

# preserve lines
intracell_whitespace <- read_docx(system.file("examples/preserve.docx", package="docxtractr"))
docx_extract_all_tbls(intracell_whitespace, preserve=TRUE)

docx_extract_all_tbls(intracell_whitespace)

# comments
cmnts <- read_docx(system.file("examples/comments.docx", package="docxtractr"))

print(cmnts)

glimpse(docx_extract_all_cmnts(cmnts))
```

### Track Changes (depends on `pandoc` being available)

```{r track-changes}
# original
read_docx(
  system.file("examples/trackchanges.docx", package="docxtractr")
) %>% 
  docx_extract_all_tbls(guess_header = FALSE)

# accept
read_docx(
  system.file("examples/trackchanges.docx", package="docxtractr"),
  track_changes = "accept"
) %>% 
  docx_extract_all_tbls(guess_header = FALSE)

# reject
read_docx(
  system.file("examples/trackchanges.docx", package="docxtractr"),
  track_changes = "reject"
) %>% 
  docx_extract_all_tbls(guess_header = FALSE)
```

## Test Results

```{r test}
library(docxtractr)
library(testthat)

date()

test_dir("tests/")
```

### Code of Conduct

Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). 
By participating in this project you agree to abide by its terms.