7 | edit:
8 | link: https://github.com/rstudio-education/hopr/edit/master/%s
9 | text: "Edit"
10 | sharing: no
11 | css: hopr.css
12 |
--------------------------------------------------------------------------------
/a1-starting.rmd:
--------------------------------------------------------------------------------
1 | # (APPENDIX) Appendix {-}
2 |
3 | # Installing R and RStudio {#starting}
4 |
5 | To get started with R, you need to acquire your own copy. This appendix will show you how to download R as well as RStudio, a software application that makes R easier to use. You'll go from downloading R to opening your first R session.
6 |
7 | Both R and RStudio are free and easy to download.
8 |
9 | ## How to Download and Install R
10 |
11 | R is maintained by an international team of developers who make the language available through the web page of [The Comprehensive R Archive Network](http://cran.r-project.org). The top of the web page provides three links for downloading R. Follow the link that describes your operating system: Windows, Mac, or Linux.
12 |
13 | ### Windows
14 |
15 | To install R on Windows, click the "Download R for Windows" link. Then click the "base" link. Next, click the first link at the top of the new page. This link should say something like "Download R 3.0.3 for Windows," except the 3.0.3 will be replaced by the most current version of R. The link downloads an installer program, which installs the most up-to-date version of R for Windows. Run this program and step through the installation wizard that appears. The wizard will install R into your program files folders and place a shortcut in your Start menu. Note that you'll need to have all of the appropriate administration privileges to install new software on your machine.
16 |
17 | ### Mac
18 |
19 | To install R on a Mac, click the "Download R for Mac" link. Next, click on the `R-3.0.3` package link (or the package link for the most current release of R). An installer will download to guide you through the installation process, which is very easy. The installer lets you customize your installation, but the defaults will be suitable for most users. I've never found a reason to change them. If your computer requires a password before installing new progams, you'll need it here.
20 |
21 |
22 | ```{block2, type = "rmdnote"}
23 | **Binaries Versus Source **
24 |
25 | R can be installed from precompiled binaries or built from source on any operating system. For Windows and Mac machines, installing R from binaries is extremely easy. The binary comes preloaded in its own installer. Although you can build R from source on these platforms, the process is much more complicated and won't provide much benefit for most users. For Linux systems, the opposite is true. Precompiled binaries can be found for some systems, but it is much more common to build R from source files when installing on Linux. The download pages on [CRAN's website](http://cran.r-project.org) provide information about building R from source for the Windows, Mac, and Linux platforms.
26 | ```
27 |
28 | ### Linux
29 |
30 | R comes preinstalled on many Linux systems, but you'll want the newest version of R if yours is out of date. [The CRAN website](http://cran.r-project.org) provides files to build R from source on Debian, Redhat, SUSE, and Ubuntu systems under the link "Download R for Linux." Click the link and then follow the directory trail to the version of Linux you wish to install on. The exact installation procedure will vary depending on the Linux system you use. CRAN guides the process by grouping each set of source files with documentation or README files that explain how to install on your system.
31 |
32 | ```{block2, type = "rmdnote"}
33 | **32-bit Versus 64-bit**
34 |
35 | R comes in both 32-bit and 64-bit versions. Which should you use? In most cases, it won't matter. Both versions use 32-bit integers, which means they compute numbers to the same numerical precision. The difference occurs in the way each version manages memory. 64-bit R uses 64-bit memory pointers, and 32-bit R uses 32-bit memory pointers. This means 64-bit R has a larger memory space to use (and search through).
36 |
37 | As a rule of thumb, 32-bit builds of R are faster than 64-bit builds, though not always. On the other hand, 64-bit builds can handle larger files and data sets with fewer memory management problems. In either version, the maximum allowable vector size tops out at around 2 billion elements. If your operating system doesn't support 64-bit programs, or your RAM is less than 4 GB, 32-bit R is for you. The Windows and Mac installers will automatically install both versions if your system supports 64-bit R.
38 | ```
39 |
40 | ## Using R
41 |
42 | R isn't a program that you can open and start using, like Microsoft Word or Internet Explorer. Instead, R is a computer language, like C, C++, or UNIX. You use R by writing commands in the R language and asking your computer to interpret them. In the old days, people ran R code in a UNIX terminal window—as if they were hackers in a movie from the 1980s. Now almost everyone uses R with an application called RStudio, and I recommend that you do, too.
43 |
44 | ```{block2, type = "rmdtip"}
45 | **R and UNIX**
46 |
47 | You can still run R in a UNIX or BASH window by typing the command:
48 |
49 | R
50 |
51 | which opens an R interpreter. You can then do your work and close the interpreter by running *`q()`* when you are finished.
52 | ```
53 |
54 | ## RStudio
55 |
56 | RStudio _is_ an application like Microsoft Word—except that instead of helping you write in English, RStudio helps you write in R. I use RStudio throughout the book because it makes using R much easier. Also, the RStudio interface looks the same for Windows, Mac OS, and Linux. That will help me match the book to your personal experience.
57 |
58 | You can [download RStudio](http://www.rstudio.com/ide) for free. Just click the "Download RStudio" button and follow the simple instructions that follow. Once you've installed RStudio, you can open it like any other program on your computer—usually by clicking an icon on your desktop.
59 |
60 | ```{block2, type = "rmdtip"}
61 | **The R GUIs**
62 |
63 | Windows and Mac users usually do not program from a terminal window, so the Windows and Mac downloads for R come with a simple program that opens a terminal-like window for you to run R code in. This is what opens when you click the R icon on your Windows or Mac computer. These programs do a little more than the basic terminal window, but not much. You may hear people refer to them as the Windows or Mac R GUIs.
64 | ```
65 |
66 | When you open RStudio, a window appears with three panes in it, as in Figure \@ref(fig:layout). The largest pane is a console window. This is where you'll run your R code and see results. The console window is exactly what you'd see if you ran R from a UNIX console or the Windows or Mac GUIs. Everything else you see is unique to RStudio. Hidden in the other panes are a text editor, a graphics window, a debugger, a file manager, and much more. You'll learn about these panes as they become useful throughout the course of this book.
67 |
68 | ```{r layout, echo = FALSE, fig.cap = "The RStudio IDE for R."}
69 | knitr::include_graphics("images/hopr_aa01.png")
70 | ```
71 |
72 | ```{block2, type = "rmdtip"}
73 | **Do I still need to download R?**
74 |
75 | Even if you use RStudio, you'll still need to download R to your computer. RStudio helps you use the version of R that lives on your computer, but it doesn't come
76 | with a version of R on its own.
77 | ```
78 |
79 | ## Opening R
80 |
81 | Now that you have both R and RStudio on your computer, you can begin using R by opening the RStudio program. Open RStudio just as you would any program, by clicking on its icon or by typing "RStudio" at the Windows Run prompt.
82 |
--------------------------------------------------------------------------------
/a2-packages.rmd:
--------------------------------------------------------------------------------
1 | # R Packages {#packages2}
2 |
3 | Many of R's most useful functions do not come preloaded when you start R, but reside in _packages_ that can be installed on top of R. R packages are similar to libraries in C, C++, and Javascript, packages in Python, and gems in Ruby. An R package bundles together useful functions, help files, and data sets. You can use these functions within your own R code once you load the package they live in. Usually the contents of an R package are all related to a single type of task, which the package helps solve. R packages will let you take advantage of R's most useful features: its large community of package writers (many of whom are active data scientists) and its prewritten routines for handling many common (and exotic) data-science tasks.
4 |
5 | ```{block2, type = "rmdtip"}
6 | **Base R**
7 |
8 | You may hear R users (or me) refer to "base R." What is base R? It is just the collection of R functions that gets loaded every time you start R. These functions provide the basics of the language, and you don't have to load a package before you can use them.
9 | ```
10 |
11 | ## Installing Packages
12 |
13 | To use an R package, you must first install it on your computer and then load it in your current R session. The easiest way to install an R package is with the `install.packages` R function. Open R and type the following into the command line:
14 |
15 | ```r
16 | install.packages("")
17 | ```
18 |
19 | This will search for the specified package in the collection of packages hosted on the CRAN site. When R finds the package, it will download it into a libraries folder on your computer. R can access the package here in future R sessions without reinstalling it. Anyone can write an R package and disseminate it as they like; however, almost all R packages are published through the CRAN website. CRAN tests each R package before publishing it. This doesn't eliminate every bug inside a package, but it does mean that you can trust a package on CRAN to run in the current version of R on your OS.
20 |
21 | You can install multiple packages at once by linking their names with R's concatenate function, `c`. For example, to install the ggplot2, reshape2, and dplyr packages, run:
22 |
23 | ```r
24 | install.packages(c("ggplot2", "reshape2", "dplyr"))
25 | ```
26 |
27 | If this is your first time installing a package, R will prompt you to choose an online mirror of to install from. Mirrors are listed by location. Your downloads should be quickest if you select a mirror that is close to you. If you want to download a new package, try the Austria mirror first. This is the main CRAN repository, and new packages can sometimes take a couple of days to make it around to all of the other mirrors.
28 |
29 | ## Loading Packages
30 |
31 | Installing a package doesn't immediately place its functions at your fingertips. It just places them on your computer. To use an R package, you next have to load it in your R session with the command:
32 |
33 | ```r
34 | library()
35 | ```
36 |
37 | Notice that the quotation marks have disappeared. You can use them if you like, but quotation marks are optional for the `library` command. (This is not true for the `install.packages` command).
38 |
39 | `library` will make all of the package's functions, data sets, and help files available to you until you close your current R session. The next time you begin an R session, you'll have to reload the package with `library` if you want to use it, but you won't have to reinstall it. You only have to install each package once. After that, a copy of the package will live in your R library. To see which packages you currently have in your R library, run:
40 |
41 | ```r
42 | library()
43 | ```
44 |
45 | `library()` also shows the path to your actual R library, which is the folder that contains your R packages. You may notice many packages that you don't remember installing. This is because R automatically downloads a set of useful packages when you first install R.
46 |
47 | ```{block2, type = "rmdtip"}
48 | **Install packages from (almost) anywhere**
49 |
50 | The `devtools` R package makes it easy to install packages from locations other than the CRAN website. devtools provides functions like `install_github`, `install_gitorious`, `install_bitbucket`, and `install_url`. These work similar to `install.packages`, but they search new locations for R packages. `install_github` is especially useful because many R developers provide development versions of their packages on GitHub. The development version of a package will contain a sneak peek of new functions and patches but may not be as stable or as bug free as the CRAN version.
51 | ```
52 |
53 | Why does R make you bother with installing and loading packages? You can imagine an R where every package came preloaded, but this would be a very large and slow program. As of May 6, 2014, the CRAN website hosts 5,511 packages. It is simpler to only install and load the packages that you want to use when you want to use them. This keeps your copy of R fast because it has fewer functions and help pages to search through at any one time. The arrangement has other benefits as well. For example, it is possible to update your copy of an R package without updating your entire copy of R.
54 |
55 |
56 | ```{block2, type = "rmdtip"}
57 | **What's the best way to learn about R packages? **
58 |
59 | It is difficult to use an R package if you don't know that it exists. You could go to the CRAN website and click the Packages link to see a list of available packages, but you'll have to wade through thousands of them. Moreover, many R packages do the same things.
60 |
61 | How do you know which package does them best? The R-packages [mailing list](http://stat.ethz.ch/mailman/listinfo/r-packages) is a place to start. It sends out announcements of new packages and maintains an archive of old announcements. Blogs that aggregate posts about R can also provide valuable leads. I recommend [R-bloggers](www.r-bloggers.com). RStudio maintains a list of some of the most useful R packages in the Getting Started section of [http://support.rstudio.com](http://support.rstudio.com). Finally, CRAN groups together some of the most useful—and most respected—packages by [subject area](http://cran.r-project.org/web/views). This is an excellent place to learn about the packages designed for your area of work.
62 | ```
63 |
--------------------------------------------------------------------------------
/a3-updating.rmd:
--------------------------------------------------------------------------------
1 | # Updating R and Its Packages {#updating}
2 |
3 | The R Core Development Team continuously hones the R language by catching bugs, improving performance, and updating R to work with new technologies. As a result, new versions of R are released several times a year. The easiest way to stay current with R is to periodically check [the CRAN website](http://cran.r-project.org). The website is updated for each new release and makes the release available for download. You'll have to install the new release. The process is the same as when you first installed R.
4 |
5 | Don't worry if you're not interested in staying up-to-date on R Core's doings. R changes only slightly between releases, and you're not likely to notice the differences. However, updating to the current version of R is a good place to start if you ever encounter a bug that you can't explain.
6 |
7 | RStudio also constantly improves its product. You can acquire the newest updates just by downloading them from [RStudio](http://www.rstudio.com/ide).
8 |
9 | ## R Packages
10 |
11 | Package authors occasionally release new versions of their packages to add functions, fix bugs, or improve performance. The `update.packages` command checks whether you have the most current version of a package and installs the most current version if you do not. The syntax for `update.packages` follows that of `install.packages`. If you already have ggplot2, reshape2, and dplyr on your computer, it'd be a good idea to check for updates before you use them:
12 |
13 | ```r
14 | update.packages(c("ggplot2", "reshape2", "dplyr"))
15 | ```
16 |
17 | You should start a new R session after updating packages. If you have a package loaded when you update it, you'll have to close your R session and open a new one to begin using the updated version of the package.
18 |
--------------------------------------------------------------------------------
/a5-debug.rmd:
--------------------------------------------------------------------------------
1 | # Debugging R Code {#debug}
2 |
3 | ```{block2, type = "rmdnote"}
4 | This appendix refers to environments, the topic of [Environments], and uses examples from [Programs] and [S3]. You should read through these chapters first to get the most out of this appendix.
5 | ```
6 |
7 | R comes with a simple set of debugging tools that RStudio amplifies. You can use these tools to better understand code that produces an error or returns an unexpected result. Usually this will be your own code, but you can also examine the functions in R or one of its packages.
8 |
9 | Debugging code can take as much creativity and insight as writing code. There is no guarantee that you will find a bug or be able to fix it when you do. However, you can help yourself by using R's debugging tools. These include the `traceback`, `browser`, `debug`, `debugonce`, `trace`, and `recover` functions.
10 |
11 | Using these tools is usually a two-step process. First, you locate _where_ an error occurred. Then you try to determine _why_ it occurred. You can do the first step with R's `traceback` function.
12 |
13 | ## traceback
14 |
15 | The `traceback` tool pinpoints the location of an error. Many R functions call other R functions, which call other functions, and so on. When an error occurs, it may not be clear which of these functions went wrong. Let's consider an example. The following functions call one another, and the last function creates an error (you'll see why in a second):
16 |
17 | ```r
18 | first <- function() second()
19 | second <- function() third()
20 | third <- function() fourth()
21 | fourth <- function() fifth()
22 | fifth <- function() bug()
23 | ```
24 |
25 | When you run `first`, it will call `second`, which will call `third`, which will call `fourth`, which will call `fifth`, which will call `bug`, a function that does not exist. Here's what that will look like at the command line:
26 |
27 | ```r
28 | first()
29 | ## Error in fifth() : could not find function "bug"
30 | ```
31 |
32 | The error report tells us that the error occurred when R tried to run `fifth`. It also tells us the nature of the error (there is no function called `bug`). Here, it is obvious why R calls `fifth`, but it might not be so obvious why R calls a function when an error occurs in the wild.
33 |
34 | You can see the path of functions that R called before it hit an error by typing *`traceback()`* at the command line. `traceback` will return a call stack, a list of the functions that R called in the order that it called them. The bottom function will be the command that you entered in the command line. The top function will be the function that caused the error:
35 |
36 | ```r
37 | traceback()
38 | ## 5: fifth() at #1
39 | ## 4: fourth() at #1
40 | ## 3: third() at #1
41 | ## 2: second() at #1
42 | ## 1: first()
43 | ```
44 |
45 | `traceback` will always refer to the last error you encountered. If you would like to look at a less recent error, you will need to recreate it before running `traceback`.
46 |
47 | How can this help you? First, `traceback` returns a list of suspects. One of these functions caused the error, and each function is more suspicious than the ones below it. Chances are that our bug came from `fifth` (it did), but it is also possible that an earlier function did something odd—like call `fifth` when it shouldn't have.
48 |
49 | Second, `traceback` can show you if R stepped off the path that you expected it to take. If this happened, look at the last function before things went wrong.
50 |
51 | Third, `traceback` can reveal the frightening extent of infinite recursion errors. For example, if you change `fifth` so that it calls `second`, the functions will make a loop: `second` will call `third`, which will call `fourth`, which will call `fifth`, which will call `second` and start the loop over again. It is easier to do this sort of thing in practice than you might think:
52 |
53 | ```r
54 | fifth <- function() second()
55 | ```
56 |
57 | When you call `first()`, R will start to run the functions. After awhile, it will notice that it is repeating itself and will return an error. `traceback` will show just what R was doing:
58 |
59 | ```r
60 | first()
61 | ## Error: evaluation nested too deeply: infinite recursion/options(expressions=)?
62 |
63 | traceback()
64 | ## 5000: fourth() at #1
65 | ## 4999: third() at #1
66 | ## 4998: second() at #1
67 | ## 4997: fifth() at #1
68 | ## 4996: fourth() at #1
69 | ## 4995: third() at #1
70 | ## 4994: second() at #1
71 | ## 4993: fifth() at #1
72 | ## ...
73 | ```
74 |
75 | Notice that there are 5,000 lines of output in this `traceback`. If you are using RStudio, you will not get to see the traceback of an infinite recursion error (I used the Mac GUI to get this output). RStudio represses the traceback for infinite recursion errors to prevent the large call stacks from pushing your console history out of R's memory buffer. With RStudio, you will have to recognize the infinite recursion error by its error message. However, you can still see the imposing `traceback` by running things in a UNIX shell or the Windows or Mac GUIs.
76 |
77 | RStudio makes it very easy to use `traceback`. You do not even need to type in the function name. Whenever an error occurs, RStudio will display it in a gray box with two options. The first is Show Traceback, shown in Figure \@ref(fig:show-traceback).
78 |
79 | ```{r show-traceback, echo = FALSE, fig.cap = "RStudio's Show Traceback option."}
80 | knitr::include_graphics("images/hopr_ae01.png")
81 | ```
82 |
83 | If you click Show Traceback, RStudio will expand the gray box and display the `traceback` call stack, as in Figure \@ref(fig:hide-traceback). The Show Traceback option will persist beside an error message in your console, even as you write new commands. This means that you can go back and look at the call stacks for all errors—not just the most recent error.
84 |
85 | Imagine that you've used `traceback` to pinpoint a function that you think might cause a bug. Now what should you do? You should try to figure out what the function did to cause an error while it ran (if it did anything). You can examine how the function runs with `browser`.
86 |
87 | ```{r hide-traceback, echo = FALSE, fig.cap = "RStudio's Traceback display."}
88 | knitr::include_graphics("images/hopr_ae02.png")
89 | ```
90 |
91 | ## browser
92 |
93 | You can ask R to pause in the middle of running a function and give control back to you with `browser`. This will let you enter new commands at the command line. The active environment for these commands will not be the global environment (as usual); it will be the runtime environment of the function that you have paused. As a result, you can look at the objects that the function is using, look up their values with the same scoping rules that the function would use, and run code under the same conditions that the function would run it in. This arrangement provides the best chance for spotting the source of bugs in a function.
94 |
95 | To use `browser`, add the call `browser()` to the body of a function and then resave the function. For example, if I wanted to pause in the middle of the `score` function from [Programs], I could add `browser()` to the body of `score` and then rerun the following code, which defines `score`:
96 |
97 | ```r
98 | score <- function (symbols) {
99 | # identify case
100 | same <- symbols[1] == symbols[2] && symbols[2] == symbols[3]
101 | bars <- symbols %in% c("B", "BB", "BBB")
102 |
103 | # get prize
104 | if (same) {
105 | payouts <- c("DD" = 100, "7" = 80, "BBB" = 40, "BB" = 25,
106 | "B" = 10, "C" = 10, "0" = 0)
107 | prize <- unname(payouts[symbols[1]])
108 | } else if (all(bars)) {
109 | prize <- 5
110 | } else {
111 | cherries <- sum(symbols == "C")
112 | prize <- c(0, 2, 5)[cherries + 1]
113 | }
114 |
115 | browser()
116 |
117 | # adjust for diamonds
118 | diamonds <- sum(symbols == "DD")
119 | prize * 2 ^ diamonds
120 | }
121 | ```
122 |
123 | Now whenever R runs `score`, it will come to the call `browser()`. You can see this with the `play` function from [Programs]. If you don't have `play` handy, you can access it by running this code:
124 |
125 | ```r
126 | get_symbols <- function() {
127 | wheel <- c("DD", "7", "BBB", "BB", "B", "C", "0")
128 | sample(wheel, size = 3, replace = TRUE,
129 | prob = c(0.03, 0.03, 0.06, 0.1, 0.25, 0.01, 0.52))
130 | }
131 |
132 | play <- function() {
133 | symbols <- get_symbols()
134 | structure(score(symbols), symbols = symbols, class = "slots")
135 | }
136 | ```
137 |
138 | When you run `play`, `play` will call `get_symbols` and then `score`. As R works through `score`, it will come across the call to `browser` and run it. When R runs this call, several things will happen, as in Figure \@ref(fig:browser). First, R will stop running `score`. Second, the command prompt will change to `browser[1]>` and R will give me back control; I can now type new commands in at the new command prompt. Third, three buttons will appear above the console pane: Next, Continue, and Stop. Fourth, RStudio will display the source code for `score` in the scripts pane, and it will highlight the line that contains `browser()`. Fifth, the environments tab will change. Instead of revealing the objects that are saved in the global environment, it will reveal the objects that are saved in the runtime environment of `score` (see [Environments] for an explanation of R's environment system). Sixth, RStudio will open a new Traceback pane, which shows the call stack RStudio took to get to `browser`. The most recent function, `score`, will be highlighted.
139 |
140 | I'm now in a new R mode, called _browser mode_. Browser mode is designed to help you uncover bugs, and the new display in RStudio is designed to help you navigate this mode.
141 |
142 | Any command that you run in browser mode will be evaluated in the context of the runtime environment of the function that called `browser`. This will be the function that is highlighted in the new Traceback pane. Here, that function is `score`. So while we are in browser mode, the active environment will be `score`'s runtime environment. This lets you do two things.
143 |
144 | ```{r browser, echo = FALSE, fig.cap = "RStudio updates its display whenever you enter browser mode to help you navigate the mode."}
145 | knitr::include_graphics("images/hopr_ae03.png")
146 | ```
147 |
148 | First, you can inspect the objects that `score` uses. The updated Environments pane shows you which objects `score` has saved in its local environment. You can inspect any of them by typing their name at the browser prompt. This gives you a way to see the values of runtime variables that you normally would not be able to access. If a value looks clearly wrong, you may be close to finding a bug:
149 |
150 | ```r
151 | Browse[1]> symbols
152 | ## [1] "B" "B" "0"
153 |
154 | Browse[1]> same
155 | ## [1] FALSE
156 | ```
157 |
158 | Second, you can run code and see the same results that `score` would see. For example, you could run the remaining lines of the `score` function and see if they do anything unusual. You could run these lines by typing them into the command prompt, or you could use the three navigation buttons that now appear above the prompt, as in Figure \@ref(fig:browser-buttons).
159 |
160 | The first button, Next, will run the next line of code in `score`. The highlighted line in the scripts pane will advance by one line to show you your new location in the `score` function. If the next line begins a code chunk, like a `for` loop or an `if` tree, R will run the whole chunk and will highlight the whole chunk in the script window.
161 |
162 | The second button, Continue, will run all of the remaining lines of `score` and then exit the browser mode.
163 |
164 | The third button, Stop, will exit browser mode without running any more lines of `score`.
165 |
166 | ```{r browser-buttons, echo = FALSE, fig.cap = "You can navigate browser mode with the three buttons at the top of the console pane."}
167 | knitr::include_graphics("images/hopr_ae04.png")
168 | ```
169 |
170 | You can do the same things by typing the commands `n`, `c`, and `Q` into the browser prompt. This creates an annoyance: what if you want to look up an object named `n`, `c`, or `Q`? Typing in the object name will not work, R will either advance, continue, or quit the browser mode. Instead you will have to look these objects up with the commands `get("n")`, `get("c")`, and `get("Q")`. `cont` is a synonym for `c` in browser mode and `where` prints the call stack, so you'll have to look up these objects with `get` as well.
171 |
172 | Browser mode can help you see things from the perspective of your functions, but it cannot show you where the bug lies. However, browser mode can help you test hypotheses and investigate function behavior. This is usually all you need to spot and fix a bug. The browser mode is the basic debugging tool of R. Each of the following functions just provides an alternate way to enter the browser mode.
173 |
174 | Once you fix the bug, you should resave your function a third time—this time without the `browser()` call. As long as the browser call is in there, R will pause each time you, or another function, calls `score`.
175 |
176 | ## Break Points
177 |
178 | RStudio's break points provide a graphical way to add a `browser` statement to a function. To use them, open the script where you've defined a function. Then click to the left of the line number of the line of code in the function body where you'd like to add the browser statement. A hollow red dot will appear to show you where the break point will occur. Then run the script by clicking the Source button at the top of the Scripts pane. The hollow dot will turn into a solid red dot to show that the function has a break point (see Figure \@ref(fig:break-point)).
179 |
180 | R will treat the break point like a `browser` statement, going into browser mode when it encounters it. You can remove a break point by clicking on the red dot. The dot will disappear, and the break point will be removed.
181 |
182 | ```{r break-point, echo = FALSE, fig.cap = "Break points provide the graphical equivalent of a browser statement."}
183 | knitr::include_graphics("images/hopr_ae05.png")
184 | ```
185 |
186 | Break points and `browser` provide a great way to debug functions that you have defined. But what if you want to debug a function that already exists in R? You can do that with the `debug` function.
187 |
188 | ## debug
189 |
190 | You can "add" a browser call to the very start of a preexisting function with `debug`. To do this, run `debug` on the function. For example, you can run `debug` on `sample` with:
191 |
192 | ```r
193 | debug(sample)
194 | ```
195 |
196 | Afterward, R will act as if there is a `browser()` statement in the first line of the function. Whenever R runs the function, it will immediately enter browser mode, allowing you to step through the function one line at a time. R will continue to behave this way until you "remove" the browser statement with `undebug`:
197 |
198 | ```r
199 | undebug(sample)
200 | ```
201 |
202 | You can check whether a function is in "debugging" mode with `isdebugged`. This will return `TRUE` if you've ran `debug` on the function but have yet to run `undebug`:
203 |
204 | ```r
205 | isdebugged(sample)
206 | ## FALSE
207 | ```
208 |
209 | If this is all too much of a hassle, you can do what I do and use `debugonce` instead of `debug`. R will enter browser mode the very next time it runs the function but will automatically undebug the function afterward. If you need to browse through the function again, you can just run `debugonce` on it a second time.
210 |
211 | You can recreate `debugonce` in RStudio whenever an error occurs. "Rerun with debug" will appear in the grey error box beneath Show Traceback (Figure \@ref(fig:show-traceback)). If you click this option, RStudio will rerun the command as if you had first run `debugonce` on it. R will immediately go into browser mode, allowing you to step through the code. The browser behavior will only occur on this run of the code. You do not need to worry about calling `undebug` when you are done.
212 |
213 |
214 | ## trace
215 |
216 | You can add the browser statement further into the function, and not at the very start, with `trace`. `trace` takes the name of a function as a character string and then an R expression to insert into the function. You can also provide an `at` argument that tells `trace` at which line of the function to place the expression. So to insert a browser call at the fourth line of `sample`, you would run:
217 |
218 | ```r
219 | trace("sample", browser, at = 4)
220 | ```
221 |
222 | You can use `trace` to insert other R functions (not just `browser`) into a function, but you may need to think of a clever reason for doing so. You can also run `trace` on a function without inserting any new code. R will prints `trace:` at the command line every time R runs the function. This is a great way to test a claim I made in [S3], that R calls `print` every time it displays something at the command line:
223 |
224 | ```r
225 | trace(print)
226 |
227 | first
228 | ## trace: print(function () second())
229 | ## function() second()
230 |
231 | head(deck)
232 | ## trace: print
233 | ## face suit value
234 | ## 1 king spades 13
235 | ## 2 queen spades 12
236 | ## 3 jack spades 11
237 | ## 4 ten spades 10
238 | ## 5 nine spades 9
239 | ## 6 eight spades 8
240 | ```
241 |
242 | You can revert a function to normal after calling trace on it with `untrace`:
243 |
244 | ```r
245 | untrace(sample)
246 | untrace(print)
247 | ```
248 |
249 | ## recover
250 |
251 | The `recover` function provides one final option for debugging. It combines the call stack of `traceback` with the browser mode of `browser`. You can use `recover` just like `browser`, by inserting it directly into a function's body. Let's demonstrate `recover` with the `fifth` function:
252 |
253 | ```r
254 | fifth <- function() recover()
255 | ```
256 |
257 | When R runs `recover`, it will pause and display the call stack, but that's not all. R gives you the option of opening a browser mode in _any_ of the functions that appear in the call stack. Annoyingly, the call stack will be displayed upside down compared to `traceback`. The most recent function will be on the bottom, and the original function will be on the top:
258 |
259 | ```r
260 | first()
261 | ##
262 | ## Enter a frame number, or 0 to exit
263 | ##
264 | ## 1: first()
265 | ## 2: #1: second()
266 | ## 3: #1: third()
267 | ## 4: #1: fourth()
268 | ## 5: #1: fifth()
269 | ```
270 |
271 | To enter a browser mode, type in the number next to the function in whose runtime environment you would like to browse. If you do not wish to browse any of the functions, type `0`:
272 |
273 | ```r
274 | 3
275 | ## Selection: 3
276 | ## Called from: fourth()
277 | ## Browse[1]>
278 | ```
279 |
280 | You can then proceed as normal. `recover` gives you a chance to inspect variables up and down your call stack and is a powerful tool for uncovering bugs. However, adding `recover` to the body of an R function can be cumbersome. Most R users use it as a global option for handling errors.
281 |
282 | If you run the following code, R will automatically call `recover()` whenever an error occurs:
283 |
284 | ```r
285 | options(error = recover)
286 | ```
287 |
288 | This behavior will last until you close your R session, or reverse the behavior by calling:
289 |
290 | ```r
291 | options(error = NULL)
292 | ```
293 |
294 |
295 |
--------------------------------------------------------------------------------
/book.bib:
--------------------------------------------------------------------------------
1 | @Book{xie2015,
2 | title = {Dynamic Documents with {R} and knitr},
3 | author = {Yihui Xie},
4 | publisher = {Chapman and Hall/CRC},
5 | address = {Boca Raton, Florida},
6 | year = {2015},
7 | edition = {2nd},
8 | note = {ISBN 978-1498716963},
9 | url = {http://yihui.name/knitr/},
10 | }
11 |
--------------------------------------------------------------------------------
/cards.rmd:
--------------------------------------------------------------------------------
1 | # (PART) Part 2 {-}
2 |
3 | # Project 2: Playing Cards
4 |
5 | This project--which spans the next four chapters--will teach you how to store, retrieve, and change data values in your computer's memory. These skills will help you save and manage data without accumulating errors. In the project, you'll design a deck of playing cards that you can shuffle and deal from. Best of all, the deck will remember which cards have been dealt--just like a real deck. You can use the deck to play card games, tell fortunes, and test card-counting strategies.
6 |
7 | Along the way, you will learn how to:
8 |
9 | * Save new types of data, like character strings and logical values
10 | * Save a data set as a vector, matrix, array, list, or data frame
11 | * Load and save your own data sets with R
12 | * Extract individual values from a data set
13 | * Change individual values within a data set
14 | * Write logical tests
15 | * Use R's missing-value symbol, NA
16 |
17 | To keep the project simple, I've divided it into four tasks. Each task will teach you a new skill for managing data with R:
18 |
19 | **Task 1: build the deck**
20 | In [R Objects], you will design and build a virtual deck of playing cards. This will be a complete data set, just like the ones you will use as a data scientist. You'll need to know how to use R's data types and data structures to make this work.
21 |
22 | **Task 2: write functions that deal and shuffle**
23 | Next, in [R Notation], you will write two functions to use with the deck. One function will deal cards from the deck, and the other will reshuffle the deck. To write these functions, you'll need to know how to extract values from a data set with R.
24 |
25 | **Task 3: change the point system to suit your game**
26 | In [Modifying Values], you will use R's notation system to change the point values of your cards to match the card games you may wish to play, like war, hearts, or blackjack. This will help you change values in place in existing data sets.
27 |
28 | **Task 4: manage the state of the deck**
29 | Finally, in [Environments], you will make sure that your deck remembers which cards it has dealt. This is an advanced task, and it will introduce R's environment system and scoping rules. To do it successfully, you will need to learn the minute details of how R looks up and uses the data that you have stored in your computer.
30 |
--------------------------------------------------------------------------------
/cover.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/cover.png
--------------------------------------------------------------------------------
/dice.rmd:
--------------------------------------------------------------------------------
1 | # (PART) Part 1 {-}
2 |
3 | # Project 1: Weighted Dice
4 |
5 | Computers let you assemble, manipulate, and visualize data sets, all at speeds that would have wowed yesterday's scientists. In short, computers give you scientific superpowers! But if you wish to use them, you'll need to pick up some programming skills.
6 |
7 | As a data scientist who knows how to program, you will improve your ability to:
8 |
9 | * Memorize (store) entire data sets
10 | * Recall data values on demand
11 | * Perform complex calculations with large amounts of data
12 | * Do repetitive tasks without becoming careless or bored
13 |
14 | Computers can do all of these things quickly and error free, which lets your mind do the things _it_ does well: make decisions and assign meaning.
15 |
16 | Sound exciting? Great! Let's begin.
17 |
18 | When I was a college student, I sometimes daydreamed of going to Las Vegas. I thought that knowing statistics might help me win big. If that's what led _you_ to data science, you better sit down; I have some bad news. Even a statistician will lose money in a casino over the long run. This is because the odds for each game are always stacked in the casino's favor. However, there is a loophole to this rule. You can make money--and reliably too. All you have to do is _be the casino_.
19 |
20 | Believe it or not, R can help you do that. Over the course of the book, you will use R to build three virtual objects: a pair of dice that you can roll to generate random numbers, a deck of cards that you can shuffle and deal from, and a slot machine modeled after some real-life video lottery terminals. After that, you'll just need to add some video graphics and a bank account (and maybe get a few government licenses), and you'll be in business. I'll leave those details to you.
21 |
22 | These projects are lighthearted, but they are also deep. As you complete them, you will become an expert at the skills you need to work with data as a data scientist. You will learn how to store data in your computer's memory, how to access data that is already there, and how to transform data values in memory when necessary. You will also learn how to write your own programs in R that you can use to analyze data and run simulations.
23 |
24 | If simulating a slot machine (or dice, or cards) seems frivilous, think of it this way: playing a slot machine is a process. Once you can simulate it, you'll be able to simulate other processes, such as bootstrap sampling, Markov chain Monte Carlo, and other data-analysis procedures. Plus, these projects provide concrete examples for learning all of the components of R programming: objects, data types, classes, notation, functions, environments, `if` trees, loops, and vectorization. This first project will make it easier to study these things by teaching you the basics of R.
25 |
26 | Your first mission is simple: assemble R code that will simulate rolling a pair of dice, like at a craps table. Once you have done that, we'll weight the dice a bit in your favor, just to keep things interesting.
27 |
28 | In this project, you will learn how to:
29 |
30 | * Use the R and RStudio interfaces
31 | * Run R commands
32 | * Create R objects
33 | * Write your own R functions and scripts
34 | * Load and use R packages
35 | * Generate random samples
36 | * Create quick plots
37 | * Get help when you need it
38 |
39 | Don't worry if it seems like we cover a lot of ground fast. This project is designed to give you a concise overview of the R language. You will return to many of the concepts we meet here in projects 2 and 3, where you will examine the concepts in depth.
40 |
41 | You'll need to have both R and RStudio installed on your computer before you can use them. Both are free and easy to download. See [Appendix A](#starting) for complete instructions. If you are ready to begin, open RStudio on your computer and read on.
--------------------------------------------------------------------------------
/docs/.nojekyll:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/.nojekyll
--------------------------------------------------------------------------------
/docs/cover.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/cover.png
--------------------------------------------------------------------------------
/docs/hopr.css:
--------------------------------------------------------------------------------
1 | .book .book-header h1 {
2 | opacity: 1;
3 | text-align: left;
4 | }
5 |
6 | #header .title {
7 | margin-bottom: 0em;
8 | }
9 | #header h4.author {
10 | margin: 0;
11 | color: #666;
12 | }
13 | #header h4.author em {
14 | font-style: normal;
15 | }
16 |
17 |
18 | .rmdcaution, .rmdimportant, .rmdnote, .rmdtip, .rmdwarning {
19 | padding: 1em 1em 1em 4em;
20 | margin-bottom: 10px;
21 | background: #f5f5f5 5px center/3em no-repeat;
22 | }
23 | .rmdcaution {
24 | background-image: url("images/caution.png");
25 | }
26 | .rmdimportant {
27 | background-image: url("images/important.png");
28 | }
29 | .rmdnote {
30 | background-image: url("images/note.png");
31 | }
32 | .rmdtip {
33 | background-image: url("images/tip.png");
34 | }
35 | .rmdwarning {
36 | background-image: url("images/warning.png");
37 | }
--------------------------------------------------------------------------------
/docs/images/caution.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/caution.png
--------------------------------------------------------------------------------
/docs/images/hopr_0101.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0101.png
--------------------------------------------------------------------------------
/docs/images/hopr_0102.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0102.png
--------------------------------------------------------------------------------
/docs/images/hopr_0103.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0103.png
--------------------------------------------------------------------------------
/docs/images/hopr_0104.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0104.png
--------------------------------------------------------------------------------
/docs/images/hopr_0105.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0105.png
--------------------------------------------------------------------------------
/docs/images/hopr_0106.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0106.png
--------------------------------------------------------------------------------
/docs/images/hopr_0107.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0107.png
--------------------------------------------------------------------------------
/docs/images/hopr_0108.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0108.png
--------------------------------------------------------------------------------
/docs/images/hopr_0201.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0201.png
--------------------------------------------------------------------------------
/docs/images/hopr_0202.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0202.png
--------------------------------------------------------------------------------
/docs/images/hopr_0203.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0203.png
--------------------------------------------------------------------------------
/docs/images/hopr_0204.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0204.png
--------------------------------------------------------------------------------
/docs/images/hopr_0205.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0205.png
--------------------------------------------------------------------------------
/docs/images/hopr_0301.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0301.png
--------------------------------------------------------------------------------
/docs/images/hopr_0302.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0302.png
--------------------------------------------------------------------------------
/docs/images/hopr_0303.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0303.png
--------------------------------------------------------------------------------
/docs/images/hopr_0304.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0304.png
--------------------------------------------------------------------------------
/docs/images/hopr_0305.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0305.png
--------------------------------------------------------------------------------
/docs/images/hopr_0306.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0306.png
--------------------------------------------------------------------------------
/docs/images/hopr_0401.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0401.png
--------------------------------------------------------------------------------
/docs/images/hopr_0402.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0402.png
--------------------------------------------------------------------------------
/docs/images/hopr_0403.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0403.png
--------------------------------------------------------------------------------
/docs/images/hopr_0501.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0501.png
--------------------------------------------------------------------------------
/docs/images/hopr_0601.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0601.png
--------------------------------------------------------------------------------
/docs/images/hopr_0602.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0602.png
--------------------------------------------------------------------------------
/docs/images/hopr_0603.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0603.png
--------------------------------------------------------------------------------
/docs/images/hopr_0604.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0604.png
--------------------------------------------------------------------------------
/docs/images/hopr_0605.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0605.png
--------------------------------------------------------------------------------
/docs/images/hopr_0606.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0606.png
--------------------------------------------------------------------------------
/docs/images/hopr_0607.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0607.png
--------------------------------------------------------------------------------
/docs/images/hopr_0608.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0608.png
--------------------------------------------------------------------------------
/docs/images/hopr_0609.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0609.png
--------------------------------------------------------------------------------
/docs/images/hopr_0701.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0701.png
--------------------------------------------------------------------------------
/docs/images/hopr_0702.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0702.png
--------------------------------------------------------------------------------
/docs/images/hopr_0703.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0703.png
--------------------------------------------------------------------------------
/docs/images/hopr_0704.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_0704.png
--------------------------------------------------------------------------------
/docs/images/hopr_1001.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_1001.png
--------------------------------------------------------------------------------
/docs/images/hopr_1002.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_1002.png
--------------------------------------------------------------------------------
/docs/images/hopr_1003.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_1003.png
--------------------------------------------------------------------------------
/docs/images/hopr_1004.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_1004.png
--------------------------------------------------------------------------------
/docs/images/hopr_aa01.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_aa01.png
--------------------------------------------------------------------------------
/docs/images/hopr_ae01.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_ae01.png
--------------------------------------------------------------------------------
/docs/images/hopr_ae02.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_ae02.png
--------------------------------------------------------------------------------
/docs/images/hopr_ae03.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_ae03.png
--------------------------------------------------------------------------------
/docs/images/hopr_ae04.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_ae04.png
--------------------------------------------------------------------------------
/docs/images/hopr_ae05.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/hopr_ae05.png
--------------------------------------------------------------------------------
/docs/images/important.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/important.png
--------------------------------------------------------------------------------
/docs/images/note.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/note.png
--------------------------------------------------------------------------------
/docs/images/tip.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/tip.png
--------------------------------------------------------------------------------
/docs/images/warning.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/images/warning.png
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/css/fontawesome/fontawesome-webfont.ttf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/rstudio-education/hopr/fbd5536401eb0b822ee3ab457f996c3c4846ec54/docs/libs/gitbook-2.6.7/css/fontawesome/fontawesome-webfont.ttf
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/css/plugin-bookdown.css:
--------------------------------------------------------------------------------
1 | .book .book-header h1 {
2 | padding-left: 20px;
3 | padding-right: 20px;
4 | }
5 | .book .book-header.fixed {
6 | position: fixed;
7 | right: 0;
8 | top: 0;
9 | left: 0;
10 | border-bottom: 1px solid rgba(0,0,0,.07);
11 | }
12 | span.search-highlight {
13 | background-color: #ffff88;
14 | }
15 | @media (min-width: 600px) {
16 | .book.with-summary .book-header.fixed {
17 | left: 300px;
18 | }
19 | }
20 | @media (max-width: 1240px) {
21 | .book .book-body.fixed {
22 | top: 50px;
23 | }
24 | .book .book-body.fixed .body-inner {
25 | top: auto;
26 | }
27 | }
28 | @media (max-width: 600px) {
29 | .book.with-summary .book-header.fixed {
30 | left: calc(100% - 60px);
31 | min-width: 300px;
32 | }
33 | .book.with-summary .book-body {
34 | transform: none;
35 | left: calc(100% - 60px);
36 | min-width: 300px;
37 | }
38 | .book .book-body.fixed {
39 | top: 0;
40 | }
41 | }
42 |
43 | .book .book-body.fixed .body-inner {
44 | top: 50px;
45 | }
46 | .book .book-body .page-wrapper .page-inner section.normal sub, .book .book-body .page-wrapper .page-inner section.normal sup {
47 | font-size: 85%;
48 | }
49 |
50 | @media print {
51 | .book .book-summary, .book .book-body .book-header, .fa {
52 | display: none !important;
53 | }
54 | .book .book-body.fixed {
55 | left: 0px;
56 | }
57 | .book .book-body,.book .book-body .body-inner, .book.with-summary {
58 | overflow: visible !important;
59 | }
60 | }
61 | .kable_wrapper {
62 | border-spacing: 20px 0;
63 | border-collapse: separate;
64 | border: none;
65 | margin: auto;
66 | }
67 | .kable_wrapper > tbody > tr > td {
68 | vertical-align: top;
69 | }
70 | .book .book-body .page-wrapper .page-inner section.normal table tr.header {
71 | border-top-width: 2px;
72 | }
73 | .book .book-body .page-wrapper .page-inner section.normal table tr:last-child td {
74 | border-bottom-width: 2px;
75 | }
76 | .book .book-body .page-wrapper .page-inner section.normal table td, .book .book-body .page-wrapper .page-inner section.normal table th {
77 | border-left: none;
78 | border-right: none;
79 | }
80 | .book .book-body .page-wrapper .page-inner section.normal table.kable_wrapper > tbody > tr, .book .book-body .page-wrapper .page-inner section.normal table.kable_wrapper > tbody > tr > td {
81 | border-top: none;
82 | }
83 | .book .book-body .page-wrapper .page-inner section.normal table.kable_wrapper > tbody > tr:last-child > td {
84 | border-bottom: none;
85 | }
86 |
87 | div.theorem, div.lemma, div.corollary, div.proposition, div.conjecture {
88 | font-style: italic;
89 | }
90 | span.theorem, span.lemma, span.corollary, span.proposition, span.conjecture {
91 | font-style: normal;
92 | }
93 | div.proof:after {
94 | content: "\25a2";
95 | float: right;
96 | }
97 | .header-section-number {
98 | padding-right: .5em;
99 | }
100 |
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/css/plugin-fontsettings.css:
--------------------------------------------------------------------------------
1 | /*
2 | * Theme 1
3 | */
4 | .color-theme-1 .dropdown-menu {
5 | background-color: #111111;
6 | border-color: #7e888b;
7 | }
8 | .color-theme-1 .dropdown-menu .dropdown-caret .caret-inner {
9 | border-bottom: 9px solid #111111;
10 | }
11 | .color-theme-1 .dropdown-menu .buttons {
12 | border-color: #7e888b;
13 | }
14 | .color-theme-1 .dropdown-menu .button {
15 | color: #afa790;
16 | }
17 | .color-theme-1 .dropdown-menu .button:hover {
18 | color: #73553c;
19 | }
20 | /*
21 | * Theme 2
22 | */
23 | .color-theme-2 .dropdown-menu {
24 | background-color: #2d3143;
25 | border-color: #272a3a;
26 | }
27 | .color-theme-2 .dropdown-menu .dropdown-caret .caret-inner {
28 | border-bottom: 9px solid #2d3143;
29 | }
30 | .color-theme-2 .dropdown-menu .buttons {
31 | border-color: #272a3a;
32 | }
33 | .color-theme-2 .dropdown-menu .button {
34 | color: #62677f;
35 | }
36 | .color-theme-2 .dropdown-menu .button:hover {
37 | color: #f4f4f5;
38 | }
39 | .book .book-header .font-settings .font-enlarge {
40 | line-height: 30px;
41 | font-size: 1.4em;
42 | }
43 | .book .book-header .font-settings .font-reduce {
44 | line-height: 30px;
45 | font-size: 1em;
46 | }
47 | .book.color-theme-1 .book-body {
48 | color: #704214;
49 | background: #f3eacb;
50 | }
51 | .book.color-theme-1 .book-body .page-wrapper .page-inner section {
52 | background: #f3eacb;
53 | }
54 | .book.color-theme-2 .book-body {
55 | color: #bdcadb;
56 | background: #1c1f2b;
57 | }
58 | .book.color-theme-2 .book-body .page-wrapper .page-inner section {
59 | background: #1c1f2b;
60 | }
61 | .book.font-size-0 .book-body .page-inner section {
62 | font-size: 1.2rem;
63 | }
64 | .book.font-size-1 .book-body .page-inner section {
65 | font-size: 1.4rem;
66 | }
67 | .book.font-size-2 .book-body .page-inner section {
68 | font-size: 1.6rem;
69 | }
70 | .book.font-size-3 .book-body .page-inner section {
71 | font-size: 2.2rem;
72 | }
73 | .book.font-size-4 .book-body .page-inner section {
74 | font-size: 4rem;
75 | }
76 | .book.font-family-0 {
77 | font-family: Georgia, serif;
78 | }
79 | .book.font-family-1 {
80 | font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
81 | }
82 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal {
83 | color: #704214;
84 | }
85 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal a {
86 | color: inherit;
87 | }
88 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h1,
89 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h2,
90 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h3,
91 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h4,
92 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h5,
93 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h6 {
94 | color: inherit;
95 | }
96 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h1,
97 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h2 {
98 | border-color: inherit;
99 | }
100 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal h6 {
101 | color: inherit;
102 | }
103 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal hr {
104 | background-color: inherit;
105 | }
106 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal blockquote {
107 | border-color: #c4b29f;
108 | opacity: 0.9;
109 | }
110 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal pre,
111 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal code {
112 | background: #fdf6e3;
113 | color: #657b83;
114 | border-color: #f8df9c;
115 | }
116 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal .highlight {
117 | background-color: inherit;
118 | }
119 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal table th,
120 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal table td {
121 | border-color: #f5d06c;
122 | }
123 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal table tr {
124 | color: inherit;
125 | background-color: #fdf6e3;
126 | border-color: #444444;
127 | }
128 | .book.color-theme-1 .book-body .page-wrapper .page-inner section.normal table tr:nth-child(2n) {
129 | background-color: #fbeecb;
130 | }
131 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal {
132 | color: #bdcadb;
133 | }
134 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal a {
135 | color: #3eb1d0;
136 | }
137 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h1,
138 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h2,
139 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h3,
140 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h4,
141 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h5,
142 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h6 {
143 | color: #fffffa;
144 | }
145 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h1,
146 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h2 {
147 | border-color: #373b4e;
148 | }
149 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal h6 {
150 | color: #373b4e;
151 | }
152 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal hr {
153 | background-color: #373b4e;
154 | }
155 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal blockquote {
156 | border-color: #373b4e;
157 | }
158 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal pre,
159 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal code {
160 | color: #9dbed8;
161 | background: #2d3143;
162 | border-color: #2d3143;
163 | }
164 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal .highlight {
165 | background-color: #282a39;
166 | }
167 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal table th,
168 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal table td {
169 | border-color: #3b3f54;
170 | }
171 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal table tr {
172 | color: #b6c2d2;
173 | background-color: #2d3143;
174 | border-color: #3b3f54;
175 | }
176 | .book.color-theme-2 .book-body .page-wrapper .page-inner section.normal table tr:nth-child(2n) {
177 | background-color: #35394b;
178 | }
179 | .book.color-theme-1 .book-header {
180 | color: #afa790;
181 | background: transparent;
182 | }
183 | .book.color-theme-1 .book-header .btn {
184 | color: #afa790;
185 | }
186 | .book.color-theme-1 .book-header .btn:hover {
187 | color: #73553c;
188 | background: none;
189 | }
190 | .book.color-theme-1 .book-header h1 {
191 | color: #704214;
192 | }
193 | .book.color-theme-2 .book-header {
194 | color: #7e888b;
195 | background: transparent;
196 | }
197 | .book.color-theme-2 .book-header .btn {
198 | color: #3b3f54;
199 | }
200 | .book.color-theme-2 .book-header .btn:hover {
201 | color: #fffff5;
202 | background: none;
203 | }
204 | .book.color-theme-2 .book-header h1 {
205 | color: #bdcadb;
206 | }
207 | .book.color-theme-1 .book-body .navigation {
208 | color: #afa790;
209 | }
210 | .book.color-theme-1 .book-body .navigation:hover {
211 | color: #73553c;
212 | }
213 | .book.color-theme-2 .book-body .navigation {
214 | color: #383f52;
215 | }
216 | .book.color-theme-2 .book-body .navigation:hover {
217 | color: #fffff5;
218 | }
219 | /*
220 | * Theme 1
221 | */
222 | .book.color-theme-1 .book-summary {
223 | color: #afa790;
224 | background: #111111;
225 | border-right: 1px solid rgba(0, 0, 0, 0.07);
226 | }
227 | .book.color-theme-1 .book-summary .book-search {
228 | background: transparent;
229 | }
230 | .book.color-theme-1 .book-summary .book-search input,
231 | .book.color-theme-1 .book-summary .book-search input:focus {
232 | border: 1px solid transparent;
233 | }
234 | .book.color-theme-1 .book-summary ul.summary li.divider {
235 | background: #7e888b;
236 | box-shadow: none;
237 | }
238 | .book.color-theme-1 .book-summary ul.summary li i.fa-check {
239 | color: #33cc33;
240 | }
241 | .book.color-theme-1 .book-summary ul.summary li.done > a {
242 | color: #877f6a;
243 | }
244 | .book.color-theme-1 .book-summary ul.summary li a,
245 | .book.color-theme-1 .book-summary ul.summary li span {
246 | color: #877f6a;
247 | background: transparent;
248 | font-weight: normal;
249 | }
250 | .book.color-theme-1 .book-summary ul.summary li.active > a,
251 | .book.color-theme-1 .book-summary ul.summary li a:hover {
252 | color: #704214;
253 | background: transparent;
254 | font-weight: normal;
255 | }
256 | /*
257 | * Theme 2
258 | */
259 | .book.color-theme-2 .book-summary {
260 | color: #bcc1d2;
261 | background: #2d3143;
262 | border-right: none;
263 | }
264 | .book.color-theme-2 .book-summary .book-search {
265 | background: transparent;
266 | }
267 | .book.color-theme-2 .book-summary .book-search input,
268 | .book.color-theme-2 .book-summary .book-search input:focus {
269 | border: 1px solid transparent;
270 | }
271 | .book.color-theme-2 .book-summary ul.summary li.divider {
272 | background: #272a3a;
273 | box-shadow: none;
274 | }
275 | .book.color-theme-2 .book-summary ul.summary li i.fa-check {
276 | color: #33cc33;
277 | }
278 | .book.color-theme-2 .book-summary ul.summary li.done > a {
279 | color: #62687f;
280 | }
281 | .book.color-theme-2 .book-summary ul.summary li a,
282 | .book.color-theme-2 .book-summary ul.summary li span {
283 | color: #c1c6d7;
284 | background: transparent;
285 | font-weight: 600;
286 | }
287 | .book.color-theme-2 .book-summary ul.summary li.active > a,
288 | .book.color-theme-2 .book-summary ul.summary li a:hover {
289 | color: #f4f4f5;
290 | background: #252737;
291 | font-weight: 600;
292 | }
293 |
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/css/plugin-search.css:
--------------------------------------------------------------------------------
1 | .book .book-summary .book-search {
2 | padding: 6px;
3 | background: transparent;
4 | position: absolute;
5 | top: -50px;
6 | left: 0px;
7 | right: 0px;
8 | transition: top 0.5s ease;
9 | }
10 | .book .book-summary .book-search input,
11 | .book .book-summary .book-search input:focus,
12 | .book .book-summary .book-search input:hover {
13 | width: 100%;
14 | background: transparent;
15 | border: 1px solid #ccc;
16 | box-shadow: none;
17 | outline: none;
18 | line-height: 22px;
19 | padding: 7px 4px;
20 | color: inherit;
21 | box-sizing: border-box;
22 | }
23 | .book.with-search .book-summary .book-search {
24 | top: 0px;
25 | }
26 | .book.with-search .book-summary ul.summary {
27 | top: 50px;
28 | }
29 |
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/css/plugin-table.css:
--------------------------------------------------------------------------------
1 | .book .book-body .page-wrapper .page-inner section.normal table{display:table;width:100%;border-collapse:collapse;border-spacing:0;overflow:auto}.book .book-body .page-wrapper .page-inner section.normal table td,.book .book-body .page-wrapper .page-inner section.normal table th{padding:6px 13px;border:1px solid #ddd}.book .book-body .page-wrapper .page-inner section.normal table tr{background-color:#fff;border-top:1px solid #ccc}.book .book-body .page-wrapper .page-inner section.normal table tr:nth-child(2n){background-color:#f8f8f8}.book .book-body .page-wrapper .page-inner section.normal table th{font-weight:700}
2 |
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/js/jquery.highlight.js:
--------------------------------------------------------------------------------
1 | gitbook.require(["jQuery"], function(jQuery) {
2 |
3 | /*
4 | * jQuery Highlight plugin
5 | *
6 | * Based on highlight v3 by Johann Burkard
7 | * http://johannburkard.de/blog/programming/javascript/highlight-javascript-text-higlighting-jquery-plugin.html
8 | *
9 | * Code a little bit refactored and cleaned (in my humble opinion).
10 | * Most important changes:
11 | * - has an option to highlight only entire words (wordsOnly - false by default),
12 | * - has an option to be case sensitive (caseSensitive - false by default)
13 | * - highlight element tag and class names can be specified in options
14 | *
15 | * Copyright (c) 2009 Bartek Szopka
16 | *
17 | * Licensed under MIT license.
18 | *
19 | */
20 |
21 | jQuery.extend({
22 | highlight: function (node, re, nodeName, className) {
23 | if (node.nodeType === 3) {
24 | var match = node.data.match(re);
25 | if (match) {
26 | var highlight = document.createElement(nodeName || 'span');
27 | highlight.className = className || 'highlight';
28 | var wordNode = node.splitText(match.index);
29 | wordNode.splitText(match[0].length);
30 | var wordClone = wordNode.cloneNode(true);
31 | highlight.appendChild(wordClone);
32 | wordNode.parentNode.replaceChild(highlight, wordNode);
33 | return 1; //skip added node in parent
34 | }
35 | } else if ((node.nodeType === 1 && node.childNodes) && // only element nodes that have children
36 | !/(script|style)/i.test(node.tagName) && // ignore script and style nodes
37 | !(node.tagName === nodeName.toUpperCase() && node.className === className)) { // skip if already highlighted
38 | for (var i = 0; i < node.childNodes.length; i++) {
39 | i += jQuery.highlight(node.childNodes[i], re, nodeName, className);
40 | }
41 | }
42 | return 0;
43 | }
44 | });
45 |
46 | jQuery.fn.unhighlight = function (options) {
47 | var settings = { className: 'highlight', element: 'span' };
48 | jQuery.extend(settings, options);
49 |
50 | return this.find(settings.element + "." + settings.className).each(function () {
51 | var parent = this.parentNode;
52 | parent.replaceChild(this.firstChild, this);
53 | parent.normalize();
54 | }).end();
55 | };
56 |
57 | jQuery.fn.highlight = function (words, options) {
58 | var settings = { className: 'highlight', element: 'span', caseSensitive: false, wordsOnly: false };
59 | jQuery.extend(settings, options);
60 |
61 | if (words.constructor === String) {
62 | words = [words];
63 | }
64 | words = jQuery.grep(words, function(word, i){
65 | return word !== '';
66 | });
67 | words = jQuery.map(words, function(word, i) {
68 | return word.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
69 | });
70 | if (words.length === 0) { return this; }
71 |
72 | var flag = settings.caseSensitive ? "" : "i";
73 | var pattern = "(" + words.join("|") + ")";
74 | if (settings.wordsOnly) {
75 | pattern = "\\b" + pattern + "\\b";
76 | }
77 | var re = new RegExp(pattern, flag);
78 |
79 | return this.each(function () {
80 | jQuery.highlight(this, re, settings.element, settings.className);
81 | });
82 | };
83 |
84 | });
85 |
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/js/lunr.js:
--------------------------------------------------------------------------------
1 | /**
2 | * lunr - http://lunrjs.com - A bit like Solr, but much smaller and not as bright - 0.5.12
3 | * Copyright (C) 2015 Oliver Nightingale
4 | * MIT Licensed
5 | * @license
6 | */
7 | !function(){var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.5.12",t.utils={},t.utils.warn=function(t){return function(e){t.console&&console.warn&&console.warn(e)}}(this),t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var t=Array.prototype.slice.call(arguments),e=t.pop(),n=t;if("function"!=typeof e)throw new TypeError("last argument must be a function");n.forEach(function(t){this.hasHandler(t)||(this.events[t]=[]),this.events[t].push(e)},this)},t.EventEmitter.prototype.removeListener=function(t,e){if(this.hasHandler(t)){var n=this.events[t].indexOf(e);this.events[t].splice(n,1),this.events[t].length||delete this.events[t]}},t.EventEmitter.prototype.emit=function(t){if(this.hasHandler(t)){var e=Array.prototype.slice.call(arguments,1);this.events[t].forEach(function(t){t.apply(void 0,e)})}},t.EventEmitter.prototype.hasHandler=function(t){return t in this.events},t.tokenizer=function(t){return arguments.length&&null!=t&&void 0!=t?Array.isArray(t)?t.map(function(t){return t.toLowerCase()}):t.toString().trim().toLowerCase().split(/[\s\-\/]+/):[]},t.Pipeline=function(){this._stack=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in this.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[e.label]=e},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.registeredFunctions[e];if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._stack.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._stack.indexOf(e);if(-1==i)throw new Error("Cannot find existingFn");i+=1,this._stack.splice(i,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._stack.indexOf(e);if(-1==i)throw new Error("Cannot find existingFn");this._stack.splice(i,0,n)},t.Pipeline.prototype.remove=function(t){var e=this._stack.indexOf(t);-1!=e&&this._stack.splice(e,1)},t.Pipeline.prototype.run=function(t){for(var e=[],n=t.length,i=this._stack.length,o=0;n>o;o++){for(var r=t[o],s=0;i>s&&(r=this._stack[s](r,o,t),void 0!==r);s++);void 0!==r&&e.push(r)}return e},t.Pipeline.prototype.reset=function(){this._stack=[]},t.Pipeline.prototype.toJSON=function(){return this._stack.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Vector=function(){this._magnitude=null,this.list=void 0,this.length=0},t.Vector.Node=function(t,e,n){this.idx=t,this.val=e,this.next=n},t.Vector.prototype.insert=function(e,n){this._magnitude=void 0;var i=this.list;if(!i)return this.list=new t.Vector.Node(e,n,i),this.length++;if(en.idx?n=n.next:(i+=e.val*n.val,e=e.next,n=n.next);return i},t.Vector.prototype.similarity=function(t){return this.dot(t)/(this.magnitude()*t.magnitude())},t.SortedSet=function(){this.length=0,this.elements=[]},t.SortedSet.load=function(t){var e=new this;return e.elements=t,e.length=t.length,e},t.SortedSet.prototype.add=function(){var t,e;for(t=0;t1;){if(r===t)return o;t>r&&(e=o),r>t&&(n=o),i=n-e,o=e+Math.floor(i/2),r=this.elements[o]}return r===t?o:-1},t.SortedSet.prototype.locationFor=function(t){for(var e=0,n=this.elements.length,i=n-e,o=e+Math.floor(i/2),r=this.elements[o];i>1;)t>r&&(e=o),r>t&&(n=o),i=n-e,o=e+Math.floor(i/2),r=this.elements[o];return r>t?o:t>r?o+1:void 0},t.SortedSet.prototype.intersect=function(e){for(var n=new t.SortedSet,i=0,o=0,r=this.length,s=e.length,a=this.elements,h=e.elements;;){if(i>r-1||o>s-1)break;a[i]!==h[o]?a[i]h[o]&&o++:(n.add(a[i]),i++,o++)}return n},t.SortedSet.prototype.clone=function(){var e=new t.SortedSet;return e.elements=this.toArray(),e.length=e.elements.length,e},t.SortedSet.prototype.union=function(t){var e,n,i;return this.length>=t.length?(e=this,n=t):(e=t,n=this),i=e.clone(),i.add.apply(i,n.toArray()),i},t.SortedSet.prototype.toJSON=function(){return this.toArray()},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.Store,this.tokenStore=new t.TokenStore,this.corpusTokens=new t.SortedSet,this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var t=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,t)},t.Index.prototype.off=function(t,e){return this.eventEmitter.removeListener(t,e)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;return n._fields=e.fields,n._ref=e.ref,n.documentStore=t.Store.load(e.documentStore),n.tokenStore=t.TokenStore.load(e.tokenStore),n.corpusTokens=t.SortedSet.load(e.corpusTokens),n.pipeline=t.Pipeline.load(e.pipeline),n},t.Index.prototype.field=function(t,e){var e=e||{},n={name:t,boost:e.boost||1};return this._fields.push(n),this},t.Index.prototype.ref=function(t){return this._ref=t,this},t.Index.prototype.add=function(e,n){var i={},o=new t.SortedSet,r=e[this._ref],n=void 0===n?!0:n;this._fields.forEach(function(n){var r=this.pipeline.run(t.tokenizer(e[n.name]));i[n.name]=r,t.SortedSet.prototype.add.apply(o,r)},this),this.documentStore.set(r,o),t.SortedSet.prototype.add.apply(this.corpusTokens,o.toArray());for(var s=0;s0&&(i=1+Math.log(this.documentStore.length/n)),this._idfCache[e]=i},t.Index.prototype.search=function(e){var n=this.pipeline.run(t.tokenizer(e)),i=new t.Vector,o=[],r=this._fields.reduce(function(t,e){return t+e.boost},0),s=n.some(function(t){return this.tokenStore.has(t)},this);if(!s)return[];n.forEach(function(e,n,s){var a=1/s.length*this._fields.length*r,h=this,l=this.tokenStore.expand(e).reduce(function(n,o){var r=h.corpusTokens.indexOf(o),s=h.idf(o),l=1,u=new t.SortedSet;if(o!==e){var c=Math.max(3,o.length-e.length);l=1/Math.log(c)}return r>-1&&i.insert(r,a*s*l),Object.keys(h.tokenStore.get(o)).forEach(function(t){u.add(t)}),n.union(u)},new t.SortedSet);o.push(l)},this);var a=o.reduce(function(t,e){return t.intersect(e)});return a.map(function(t){return{ref:t,score:i.similarity(this.documentVector(t))}},this).sort(function(t,e){return e.score-t.score})},t.Index.prototype.documentVector=function(e){for(var n=this.documentStore.get(e),i=n.length,o=new t.Vector,r=0;i>r;r++){var s=n.elements[r],a=this.tokenStore.get(s)[e].tf,h=this.idf(s);o.insert(this.corpusTokens.indexOf(s),a*h)}return o},t.Index.prototype.toJSON=function(){return{version:t.version,fields:this._fields,ref:this._ref,documentStore:this.documentStore.toJSON(),tokenStore:this.tokenStore.toJSON(),corpusTokens:this.corpusTokens.toJSON(),pipeline:this.pipeline.toJSON()}},t.Index.prototype.use=function(t){var e=Array.prototype.slice.call(arguments,1);e.unshift(this),t.apply(this,e)},t.Store=function(){this.store={},this.length=0},t.Store.load=function(e){var n=new this;return n.length=e.length,n.store=Object.keys(e.store).reduce(function(n,i){return n[i]=t.SortedSet.load(e.store[i]),n},{}),n},t.Store.prototype.set=function(t,e){this.has(t)||this.length++,this.store[t]=e},t.Store.prototype.get=function(t){return this.store[t]},t.Store.prototype.has=function(t){return t in this.store},t.Store.prototype.remove=function(t){this.has(t)&&(delete this.store[t],this.length--)},t.Store.prototype.toJSON=function(){return{store:this.store,length:this.length}},t.stemmer=function(){var t={ational:"ate",tional:"tion",enci:"ence",anci:"ance",izer:"ize",bli:"ble",alli:"al",entli:"ent",eli:"e",ousli:"ous",ization:"ize",ation:"ate",ator:"ate",alism:"al",iveness:"ive",fulness:"ful",ousness:"ous",aliti:"al",iviti:"ive",biliti:"ble",logi:"log"},e={icate:"ic",ative:"",alize:"al",iciti:"ic",ical:"ic",ful:"",ness:""},n="[^aeiou]",i="[aeiouy]",o=n+"[^aeiouy]*",r=i+"[aeiou]*",s="^("+o+")?"+r+o,a="^("+o+")?"+r+o+"("+r+")?$",h="^("+o+")?"+r+o+r+o,l="^("+o+")?"+i,u=new RegExp(s),c=new RegExp(h),f=new RegExp(a),d=new RegExp(l),p=/^(.+?)(ss|i)es$/,m=/^(.+?)([^s])s$/,v=/^(.+?)eed$/,y=/^(.+?)(ed|ing)$/,g=/.$/,S=/(at|bl|iz)$/,w=new RegExp("([^aeiouylsz])\\1$"),x=new RegExp("^"+o+i+"[^aeiouwxy]$"),k=/^(.+?[^aeiou])y$/,b=/^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/,E=/^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/,_=/^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/,F=/^(.+?)(s|t)(ion)$/,O=/^(.+?)e$/,P=/ll$/,N=new RegExp("^"+o+i+"[^aeiouwxy]$"),T=function(n){var i,o,r,s,a,h,l;if(n.length<3)return n;if(r=n.substr(0,1),"y"==r&&(n=r.toUpperCase()+n.substr(1)),s=p,a=m,s.test(n)?n=n.replace(s,"$1$2"):a.test(n)&&(n=n.replace(a,"$1$2")),s=v,a=y,s.test(n)){var T=s.exec(n);s=u,s.test(T[1])&&(s=g,n=n.replace(s,""))}else if(a.test(n)){var T=a.exec(n);i=T[1],a=d,a.test(i)&&(n=i,a=S,h=w,l=x,a.test(n)?n+="e":h.test(n)?(s=g,n=n.replace(s,"")):l.test(n)&&(n+="e"))}if(s=k,s.test(n)){var T=s.exec(n);i=T[1],n=i+"i"}if(s=b,s.test(n)){var T=s.exec(n);i=T[1],o=T[2],s=u,s.test(i)&&(n=i+t[o])}if(s=E,s.test(n)){var T=s.exec(n);i=T[1],o=T[2],s=u,s.test(i)&&(n=i+e[o])}if(s=_,a=F,s.test(n)){var T=s.exec(n);i=T[1],s=c,s.test(i)&&(n=i)}else if(a.test(n)){var T=a.exec(n);i=T[1]+T[2],a=c,a.test(i)&&(n=i)}if(s=O,s.test(n)){var T=s.exec(n);i=T[1],s=c,a=f,h=N,(s.test(i)||a.test(i)&&!h.test(i))&&(n=i)}return s=P,a=c,s.test(n)&&a.test(n)&&(s=g,n=n.replace(s,"")),"y"==r&&(n=r.toLowerCase()+n.substr(1)),n};return T}(),t.Pipeline.registerFunction(t.stemmer,"stemmer"),t.stopWordFilter=function(e){return e&&t.stopWordFilter.stopWords[e]!==e?e:void 0},t.stopWordFilter.stopWords={a:"a",able:"able",about:"about",across:"across",after:"after",all:"all",almost:"almost",also:"also",am:"am",among:"among",an:"an",and:"and",any:"any",are:"are",as:"as",at:"at",be:"be",because:"because",been:"been",but:"but",by:"by",can:"can",cannot:"cannot",could:"could",dear:"dear",did:"did","do":"do",does:"does",either:"either","else":"else",ever:"ever",every:"every","for":"for",from:"from",get:"get",got:"got",had:"had",has:"has",have:"have",he:"he",her:"her",hers:"hers",him:"him",his:"his",how:"how",however:"however",i:"i","if":"if","in":"in",into:"into",is:"is",it:"it",its:"its",just:"just",least:"least",let:"let",like:"like",likely:"likely",may:"may",me:"me",might:"might",most:"most",must:"must",my:"my",neither:"neither",no:"no",nor:"nor",not:"not",of:"of",off:"off",often:"often",on:"on",only:"only",or:"or",other:"other",our:"our",own:"own",rather:"rather",said:"said",say:"say",says:"says",she:"she",should:"should",since:"since",so:"so",some:"some",than:"than",that:"that",the:"the",their:"their",them:"them",then:"then",there:"there",these:"these",they:"they","this":"this",tis:"tis",to:"to",too:"too",twas:"twas",us:"us",wants:"wants",was:"was",we:"we",were:"were",what:"what",when:"when",where:"where",which:"which","while":"while",who:"who",whom:"whom",why:"why",will:"will","with":"with",would:"would",yet:"yet",you:"you",your:"your"},t.Pipeline.registerFunction(t.stopWordFilter,"stopWordFilter"),t.trimmer=function(t){var e=t.replace(/^\W+/,"").replace(/\W+$/,"");return""===e?void 0:e},t.Pipeline.registerFunction(t.trimmer,"trimmer"),t.TokenStore=function(){this.root={docs:{}},this.length=0},t.TokenStore.load=function(t){var e=new this;return e.root=t.root,e.length=t.length,e},t.TokenStore.prototype.add=function(t,e,n){var n=n||this.root,i=t[0],o=t.slice(1);return i in n||(n[i]={docs:{}}),0===o.length?(n[i].docs[e.ref]=e,void(this.length+=1)):this.add(o,e,n[i])},t.TokenStore.prototype.has=function(t){if(!t)return!1;for(var e=this.root,n=0;n's that are truncated
107 | $('a').each(function(i, el) {
108 | if (el.offsetWidth >= el.scrollWidth) return;
109 | if (typeof el.title === 'undefined') return;
110 | el.title = el.text;
111 | });
112 |
113 | // restore TOC scroll position
114 | var pos = gs.get('tocScrollTop');
115 | if (typeof pos !== 'undefined') summary.scrollTop(pos);
116 |
117 | // highlight the TOC item that has same text as the heading in view as scrolling
118 | if (toc && toc.scroll_highlight !== false) (function() {
119 | // scroll the current TOC item into viewport
120 | var ht = $(window).height(), rect = li[0].getBoundingClientRect();
121 | if (rect.top >= ht || rect.top <= 0 || rect.bottom <= 0) {
122 | summary.scrollTop(li[0].offsetTop);
123 | }
124 | // current chapter TOC items
125 | var items = $('a[href^="' + href + '"]').parent('li.chapter'),
126 | m = items.length;
127 | if (m === 0) {
128 | items = summary.find('li.chapter');
129 | m = items.length;
130 | }
131 | if (m === 0) return;
132 | // all section titles on current page
133 | var hs = bookInner.find('.page-inner').find('h1,h2,h3'), n = hs.length,
134 | ts = hs.map(function(i, el) { return $(el).text(); });
135 | if (n === 0) return;
136 | var scrollHandler = function(e) {
137 | var ht = $(window).height();
138 | clearTimeout($.data(this, 'scrollTimer'));
139 | $.data(this, 'scrollTimer', setTimeout(function() {
140 | // find the first visible title in the viewport
141 | for (var i = 0; i < n; i++) {
142 | var rect = hs[i].getBoundingClientRect();
143 | if (rect.top >= 0 && rect.bottom <= ht) break;
144 | }
145 | if (i === n) return;
146 | items.removeClass('active');
147 | for (var j = 0; j < m; j++) {
148 | if (items.eq(j).children('a').first().text() === ts[i]) break;
149 | }
150 | if (j === m) j = 0; // highlight the chapter title
151 | // search bottom-up for a visible TOC item to highlight; if an item is
152 | // hidden, we check if its parent is visible, and so on
153 | while (j > 0 && items.eq(j).is(':hidden')) j--;
154 | items.eq(j).addClass('active');
155 | }, 250));
156 | };
157 | bookInner.on('scroll.bookdown', scrollHandler);
158 | bookBody.on('scroll.bookdown', scrollHandler);
159 | })();
160 |
161 | // do not refresh the page if the TOC item points to the current page
162 | $('a[href="' + href + '"]').parent('li.chapter').children('a')
163 | .on('click', function(e) {
164 | bookInner.scrollTop(0);
165 | bookBody.scrollTop(0);
166 | return false;
167 | });
168 |
169 | var toolbar = config.toolbar;
170 | if (!toolbar || toolbar.position !== 'static') {
171 | var bookHeader = $('.book-header');
172 | bookBody.addClass('fixed');
173 | bookHeader.addClass('fixed')
174 | .css('background-color', bookBody.css('background-color'))
175 | .on('click.bookdown', function(e) {
176 | // the theme may have changed after user clicks the theme button
177 | bookHeader.css('background-color', bookBody.css('background-color'));
178 | });
179 | }
180 |
181 | });
182 |
183 | gitbook.events.bind("page.change", function(e) {
184 | // store TOC scroll position
185 | var summary = $('ul.summary');
186 | gs.set('tocScrollTop', summary.scrollTop());
187 | });
188 |
189 | var bookBody = $('.book-body'), bookInner = bookBody.find('.body-inner');
190 | var chapterTitle = function() {
191 | return bookInner.find('.page-inner').find('h1,h2').first().text();
192 | };
193 | var bookTitle = function() {
194 | return bookInner.find('.book-header > h1').first().text();
195 | };
196 | var saveScrollPos = function(e) {
197 | // save scroll position before page is reloaded
198 | gs.set('bodyScrollTop', {
199 | body: bookBody.scrollTop(),
200 | inner: bookInner.scrollTop(),
201 | focused: document.hasFocus(),
202 | title: chapterTitle()
203 | });
204 | };
205 | $(document).on('servr:reload', saveScrollPos);
206 |
207 | // check if the page is loaded in an iframe (e.g. the RStudio preview window)
208 | var inIFrame = function() {
209 | var inIframe = true;
210 | try { inIframe = window.self !== window.top; } catch (e) {}
211 | return inIframe;
212 | };
213 | $(window).on('blur unload', function(e) {
214 | if (inIFrame()) saveScrollPos(e);
215 | gs.set('bookTitle', bookTitle());
216 | });
217 |
218 | $(function(e) {
219 | if (gs.get('bookTitle', '') !== bookTitle()) localStorage.clear();
220 | var pos = gs.get('bodyScrollTop');
221 | if (pos) {
222 | if (pos.title === chapterTitle()) {
223 | if (pos.body !== 0) bookBody.scrollTop(pos.body);
224 | if (pos.inner !== 0) bookInner.scrollTop(pos.inner);
225 | }
226 | if (pos.focused) bookInner.find('.page-wrapper').focus();
227 | }
228 | // clear book body scroll position
229 | gs.remove('bodyScrollTop');
230 | });
231 |
232 | });
233 |
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/js/plugin-fontsettings.js:
--------------------------------------------------------------------------------
1 | gitbook.require(["gitbook", "lodash", "jQuery"], function(gitbook, _, $) {
2 | var fontState;
3 |
4 | var THEMES = {
5 | "white": 0,
6 | "sepia": 1,
7 | "night": 2
8 | };
9 |
10 | var FAMILY = {
11 | "serif": 0,
12 | "sans": 1
13 | };
14 |
15 | // Save current font settings
16 | function saveFontSettings() {
17 | gitbook.storage.set("fontState", fontState);
18 | update();
19 | }
20 |
21 | // Increase font size
22 | function enlargeFontSize(e) {
23 | e.preventDefault();
24 | if (fontState.size >= 4) return;
25 |
26 | fontState.size++;
27 | saveFontSettings();
28 | };
29 |
30 | // Decrease font size
31 | function reduceFontSize(e) {
32 | e.preventDefault();
33 | if (fontState.size <= 0) return;
34 |
35 | fontState.size--;
36 | saveFontSettings();
37 | };
38 |
39 | // Change font family
40 | function changeFontFamily(index, e) {
41 | e.preventDefault();
42 |
43 | fontState.family = index;
44 | saveFontSettings();
45 | };
46 |
47 | // Change type of color
48 | function changeColorTheme(index, e) {
49 | e.preventDefault();
50 |
51 | var $book = $(".book");
52 |
53 | if (fontState.theme !== 0)
54 | $book.removeClass("color-theme-"+fontState.theme);
55 |
56 | fontState.theme = index;
57 | if (fontState.theme !== 0)
58 | $book.addClass("color-theme-"+fontState.theme);
59 |
60 | saveFontSettings();
61 | };
62 |
63 | function update() {
64 | var $book = gitbook.state.$book;
65 |
66 | $(".font-settings .font-family-list li").removeClass("active");
67 | $(".font-settings .font-family-list li:nth-child("+(fontState.family+1)+")").addClass("active");
68 |
69 | $book[0].className = $book[0].className.replace(/\bfont-\S+/g, '');
70 | $book.addClass("font-size-"+fontState.size);
71 | $book.addClass("font-family-"+fontState.family);
72 |
73 | if(fontState.theme !== 0) {
74 | $book[0].className = $book[0].className.replace(/\bcolor-theme-\S+/g, '');
75 | $book.addClass("color-theme-"+fontState.theme);
76 | }
77 | };
78 |
79 | function init(config) {
80 | var $bookBody, $book;
81 |
82 | //Find DOM elements.
83 | $book = gitbook.state.$book;
84 | $bookBody = $book.find(".book-body");
85 |
86 | // Instantiate font state object
87 | fontState = gitbook.storage.get("fontState", {
88 | size: config.size || 2,
89 | family: FAMILY[config.family || "sans"],
90 | theme: THEMES[config.theme || "white"]
91 | });
92 |
93 | update();
94 | };
95 |
96 |
97 | gitbook.events.bind("start", function(e, config) {
98 | var opts = config.fontsettings;
99 |
100 | // Create buttons in toolbar
101 | gitbook.toolbar.createButton({
102 | icon: 'fa fa-font',
103 | label: 'Font Settings',
104 | className: 'font-settings',
105 | dropdown: [
106 | [
107 | {
108 | text: 'A',
109 | className: 'font-reduce',
110 | onClick: reduceFontSize
111 | },
112 | {
113 | text: 'A',
114 | className: 'font-enlarge',
115 | onClick: enlargeFontSize
116 | }
117 | ],
118 | [
119 | {
120 | text: 'Serif',
121 | onClick: _.partial(changeFontFamily, 0)
122 | },
123 | {
124 | text: 'Sans',
125 | onClick: _.partial(changeFontFamily, 1)
126 | }
127 | ],
128 | [
129 | {
130 | text: 'White',
131 | onClick: _.partial(changeColorTheme, 0)
132 | },
133 | {
134 | text: 'Sepia',
135 | onClick: _.partial(changeColorTheme, 1)
136 | },
137 | {
138 | text: 'Night',
139 | onClick: _.partial(changeColorTheme, 2)
140 | }
141 | ]
142 | ]
143 | });
144 |
145 |
146 | // Init current settings
147 | init(opts);
148 | });
149 | });
150 |
151 |
152 |
--------------------------------------------------------------------------------
/docs/libs/gitbook-2.6.7/js/plugin-search.js:
--------------------------------------------------------------------------------
1 | gitbook.require(["gitbook", "lodash", "jQuery"], function(gitbook, _, $) {
2 | var index = null;
3 | var $searchInput, $searchLabel, $searchForm;
4 | var $highlighted, hi = 0, hiOpts = { className: 'search-highlight' };
5 | var collapse = false;
6 |
7 | // Use a specific index
8 | function loadIndex(data) {
9 | // [Yihui] In bookdown, I use a character matrix to store the chapter
10 | // content, and the index is dynamically built on the client side.
11 | // Gitbook prebuilds the index data instead: https://github.com/GitbookIO/plugin-search
12 | // We can certainly do that via R packages V8 and jsonlite, but let's
13 | // see how slow it really is before improving it. On the other hand,
14 | // lunr cannot handle non-English text very well, e.g. the default
15 | // tokenizer cannot deal with Chinese text, so we may want to replace
16 | // lunr with a dumb simple text matching approach.
17 | index = lunr(function () {
18 | this.ref('url');
19 | this.field('title', { boost: 10 });
20 | this.field('body');
21 | });
22 | data.map(function(item) {
23 | index.add({
24 | url: item[0],
25 | title: item[1],
26 | body: item[2]
27 | });
28 | });
29 | }
30 |
31 | // Fetch the search index
32 | function fetchIndex() {
33 | return $.getJSON(gitbook.state.basePath+"/search_index.json")
34 | .then(loadIndex); // [Yihui] we need to use this object later
35 | }
36 |
37 | // Search for a term and return results
38 | function search(q) {
39 | if (!index) return;
40 |
41 | var results = _.chain(index.search(q))
42 | .map(function(result) {
43 | var parts = result.ref.split("#");
44 | return {
45 | path: parts[0],
46 | hash: parts[1]
47 | };
48 | })
49 | .value();
50 |
51 | // [Yihui] Highlight the search keyword on current page
52 | hi = 0;
53 | $highlighted = results.length === 0 ? undefined : $('.page-inner')
54 | .unhighlight(hiOpts).highlight(q, hiOpts).find('span.search-highlight');
55 | scrollToHighlighted();
56 | toggleTOC(results.length > 0);
57 |
58 | return results;
59 | }
60 |
61 | // [Yihui] Scroll the chapter body to the i-th highlighted string
62 | function scrollToHighlighted() {
63 | if (!$highlighted) return;
64 | var n = $highlighted.length;
65 | if (n === 0) return;
66 | var $p = $highlighted.eq(hi), p = $p[0], rect = p.getBoundingClientRect();
67 | if (rect.top < 0 || rect.bottom > $(window).height()) {
68 | ($(window).width() >= 1240 ? $('.body-inner') : $('.book-body'))
69 | .scrollTop(p.offsetTop - 100);
70 | }
71 | $highlighted.css('background-color', '');
72 | // an orange background color on the current item and removed later
73 | $p.css('background-color', 'orange');
74 | setTimeout(function() {
75 | $p.css('background-color', '');
76 | }, 2000);
77 | }
78 |
79 | // [Yihui] Expand/collapse TOC
80 | function toggleTOC(show) {
81 | if (!collapse) return;
82 | var toc_sub = $('ul.summary').children('li[data-level]').children('ul');
83 | if (show) return toc_sub.show();
84 | var href = window.location.pathname;
85 | href = href.substr(href.lastIndexOf('/') + 1);
86 | if (href === '') href = 'index.html';
87 | var li = $('a[href^="' + href + location.hash + '"]').parent('li.chapter').first();
88 | toc_sub.hide().parent().has(li).children('ul').show();
89 | li.children('ul').show();
90 | }
91 |
92 | // Create search form
93 | function createForm(value) {
94 | if ($searchForm) $searchForm.remove();
95 | if ($searchLabel) $searchLabel.remove();
96 | if ($searchInput) $searchInput.remove();
97 |
98 | $searchForm = $('
