diff --git a/.gitignore b/.gitignore index 886732b..9e8ec76 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,4 @@ vignettes/*.pdf *.utf8.md *.knit.md .Rproj.user +inst/doc diff --git a/DESCRIPTION b/DESCRIPTION index ea0f3d3..ec24108 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,12 +1,22 @@ Package: felp Type: Package -Title: Print function and its help simultaneously -Version: 0.1.3 +Title: Functional help for functions, objects, and packages +Version: 0.2.0 Author: YASUMOTO Atsushi Maintainer: YASUMOTO Atsushi -Description: Try `?help` and `help?.`. +Description: This package extends utils::`?` by pseudo-postfix operators `?.` for objects and `?p` for packages. For objects, a result of `str` or `print.function` is also displayed. License: MIT + file LICENSE Encoding: UTF-8 LazyData: true +Roxygen: list(markdown = TRUE) RoxygenNote: 6.1.1 -Imports: prettycode +Imports: + prettycode +Suggests: + knitr, + pkgdown, + printr, + rmarkdown, + roxygen2 +VignetteBuilder: + knitr diff --git a/NAMESPACE b/NAMESPACE index d417142..ba301b3 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,7 +1,5 @@ # Generated by roxygen2: do not edit by hand -S3method("?","function") -S3method("?",default) export("?") export(felp) importFrom(utils,"?") diff --git a/NEWS.md b/NEWS.md index 5cd1c03..1798add 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,14 +1,31 @@ -# felp 0.1.3.9000 +# felp 0.2.0 # Major changes -- `felp()` has more consistent arguments to `utils::help` by changing - a name of first argument to "topic" from "x". -- Pseudo-postfix operator `?.` supports arguments other than fucntions. +- `felp()` and `?` returns structure of a value specified to the first argument + if possible. If function is specified, the source of function is returned + instead of the structure. +- `felp()` + - improves consistency with `utils::help` in terms of arguments + - supports to display package documentation just like `help(package = )` +- Pseudo-postfix operators + - `?.` supports arguments other than fucntions. + - `?p` is added to display document of a package. +- Updates on documents with `pkgdown` site + +# felp 0.1.3.9000 + +Tagged, but not released. + +## Major changes + +- felp() has more consistent arguments to utils::help by changing a name of first argument to "topic" from "x". +- Pseudo-postfix operator ?. supports arguments other than fucntions. + +## Minor changes -# Minor changes +- felp() is simplified. -- `felp()` is simplified. # felp 0.1.3 diff --git a/R/data.R b/R/data.R new file mode 100644 index 0000000..4e47ec5 --- /dev/null +++ b/R/data.R @@ -0,0 +1,4 @@ +#' A dummy data for felp +#' +#' @docType data +dummy <- list(a = "a", b = 1) diff --git a/R/felp.R b/R/felp.R index 5bb00aa..a92c5fe 100644 --- a/R/felp.R +++ b/R/felp.R @@ -1,24 +1,25 @@ -#' Returns source and help of a function simultaneously +#' Functional help which displays structure of an object in addition to help #' -#' @param topic A name or character string specifying the function for which help and source are sought. Package to be sought can also be defined simultaneously if x is specified in the style of package::name or package:::name -#' @param package A name or character string specifying the package for which help and source are sought. If the package is specified by x, this parameter is neglected, or NULL (default). -#' @param ... Other arguments passed to help +#' Structure of object is returned by `str()`. +#' For a function, its source is returned instead of `str()`. +#' +#' @inheritParams utils::help +#' @inheritDotParams utils::help -topic -package #' @importFrom utils help #' @export #' felp <- function(topic, package = NULL, ...) { - # convert package::name to c("name", "package", "`::`") - # or name to "name" + # Display package document + if (missing(topic)) return(do.call(help, list(package = substitute(package), ...))) + + # Convert `package::name` to c("name", "package", "`::`") or `name` to "name" t <- rev(as.character(substitute(topic))) p <- c(as.character(substitute(package)), t[2L])[1L] if (is.na(p)) p <- NULL - # Print source of the function - prettycode:::print.function(get( - t[1L], envir = `if`(is.null(p), parent.frame(), asNamespace(p)) - )) + # Display structure and document of an object + str(get(t[1L], envir = `if`(is.null(p), parent.frame(), asNamespace(p)))) try(help(t[1L], p[1L], ...)) - } diff --git a/R/question.R b/R/question.R index e48d0b3..98b0d8b 100644 --- a/R/question.R +++ b/R/question.R @@ -1,29 +1,28 @@ -#' S3 version of [utils::`?`] +#' Functional help with `?` operator +#' +#' Displays help and structure of an object, or help of a package. +#' Two syntaxes are added to those of `utils::?`. +#' One is `object?.` which works as if `?object`. +#' Another is `package?p` which works as if `help(package = package)` #' #' @param e1 -#' A topic ought to be documented. Refer to `topic` argument described in `` utils::`?` ``. +#' A topic of document. +#' Refer to `topic` argument described in `` utils::`?` ``. #' @param e2 -#' `.` equals to `missing(e2)`. If else, see `type` argument described in `` utils::`?` ``. -#' @rdname question -#' @aliases ? -#' @export -`?` <- function(e1, e2) UseMethod("?") - -#' @rdname question -#' @aliases ? -#' @export -`?.function` <- function(e1, e2) { - if (!missing(e2) && as.character(substitute(e2)) != ".") NextMethod() - do.call(felp, list(topic = substitute(e1))) -} - +#' `.` and `p` have special meanings as documented above. +#' Otherwise, `e2` is same as `type` argument of `` utils::`?` ``. +#' #' @rdname question #' @aliases ? +#' #' @importFrom utils ? #' @export -`?.default` <- function(e1, e2) { - .arg <- list(e1 = substitute(e1)) +`?` <- function(e1, e2) { + .e1 <- substitute(e1) .e2 <- substitute(e2) - if (!missing(.e2) && as.character(.e2) != ".") .arg$e2 <- .e2 - do.call(utils::"?", .arg) + if (missing(e2)) return(do.call(felp, list(topic = .e1))) + .e2_chr <- as.character(.e2) + if (.e2_chr == ".") return(do.call(felp, list(topic = .e1))) + if (.e2_chr == "p") return(do.call(help, list(package = .e1))) + do.call(utils::`?`, list(e1 = .e1, e2 = .e2)) } diff --git a/R/str.R b/R/str.R new file mode 100644 index 0000000..28da9b8 --- /dev/null +++ b/R/str.R @@ -0,0 +1,5 @@ +#' str for function +#' @noRd +str.function <- function(object, ...) { + prettycode:::print.function(object, ...) +} diff --git a/README.md b/README.md index 7be8060..b8e13f9 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ # felp -felp is a short of **f**unction h**elp**. -This package provides functions to print -source and help of a function simultaneously. +`felp` is a short of **f**unctional h**elp** + +- the `?.` pseudo-post fix operator to simultaneously display a help document + and a structure of an object +- the `?p` pseudo-post fix operator to display document of a package + +and more in [Syntax](#Syntax) and [Get started](https://felp.atusy.net/articles/felp.html) ## Installation @@ -12,17 +16,24 @@ Copy & paste: source("https://install-github.me/atusy/felp") ``` -## Example - -These provide same results to print help and source of `help`. +## Syntax ``` r -help?. -utils::help?. +# ? operator ?help ?utils::help + +# ?. pseudo postfix operator for functions and objects +help?. +utils::help?. + +# ?p pseudo postfix operator for packages +utils?. + +# felp as an extention of utils::help felp(help) felp("help") felp(utils::help) felp(help, utils) +felp(package = utils) ``` diff --git a/docs/LICENSE-text.html b/docs/LICENSE-text.html new file mode 100644 index 0000000..add69a7 --- /dev/null +++ b/docs/LICENSE-text.html @@ -0,0 +1,146 @@ + + + + + + + + +License • felp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+

License

+
+ +
MIT License
+
+Copyright (c) 2018 atusy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+ +
+ +
+ + +
+
+

Developed by YASUMOTO Atsushi.

+
+ +
+

Site built with pkgdown 1.3.0.

+
+
+
+ + + + + + diff --git a/docs/articles/felp.html b/docs/articles/felp.html new file mode 100644 index 0000000..6d042e9 --- /dev/null +++ b/docs/articles/felp.html @@ -0,0 +1,337 @@ + + + + + + + +felp • felp + + + + + + + + + +
+
+ + + +
+
+
+

felp

+ + + + + +
+ + + + +
library(felp)
+library(printr) # To include documents output by `?` in this article
+

The felp package provides

+
    +
  • the ?. pseudo-post fix operator to simultaneously display a help document and a structure of an object
    • +
  • the ?p pseudo-post fix operator to display document of a package
    • +
  • the felp function and ? operator to extend help and ? in the utils package by displaying structure of an object
    • +
+ +
+

+felp(function)

+ + +
+ + + +
+felp + +R Documentation +
+

+Functional help which displays structure an object in addition to help +

+

+Description +

+

+Structure of object is returned by str(). For a function, its source is returned instead of str(). +

+

+Usage +

+
+felp(topic, package = NULL, ...)
+
+

+Arguments +

+ + + + + + + + + + + + + +
+topic + +

+usually, a name or character string specifying the topic for which help is sought. A character string (enclosed in explicit single or double quotes) is always taken as naming a topic. +

+

+If the value of topic is a length-one character vector the topic is taken to be the value of the only element. Otherwise topic must be a name or a reserved word (if syntactically valid) or character string. +

+

+See ‘Details’ for what happens if this is omitted. +

+
+package + +

+a name or character vector giving the packages to look into for documentation, or NULL. By default, all packages whose namespaces are loaded are used. To avoid a name being deparsed use e.g. (pkg_ref) (see the examples). +

+
+… + +

+Arguments passed on to utils::help +

+
+
+lib.loc +
+
+

+a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries. This is not used for HTML help (see ‘Details’). +

+
+
+verbose +
+
+

+logical; if TRUE, the file name is reported. +

+
+
+try.all.packages +
+
+

+logical; see Note. +

+
+
+help_type +
+
+

+character string: the type of help required. Possible values are “text”, “html” and “pdf”. Case is ignored, and partial matching is allowed. +

+
+
+
+
+
+
+

+felp(dataset)

+ +
List of 2
+ $ a: chr "a"
+ $ b: num 1
+
+ + + +
+dummy + +R Documentation +
+

+A dummy data for felp +

+

+Description +

+

+A dummy data for felp +

+

+Usage +

+
+dummy
+
+

+Format +

+

+An object of class list of length 2. +

+
+
+
+

+felp(package)

+ +
        Information on package 'felp'
+
+Description:
+
+Package:           felp
+Type:              Package
+Title:             Functional help for functions, objects, and
+                   packages
+Version:           0.2.0
+Author:            YASUMOTO Atsushi
+Maintainer:        YASUMOTO Atsushi <atusy7+felp@gmail.com>
+Description:       `help?.` works as if `?help` and `felp?p` works
+                   as if `help(package = felp)`.
+License:           MIT + file LICENSE
+Encoding:          UTF-8
+LazyData:          true
+Roxygen:           list(markdown = TRUE)
+RoxygenNote:       6.1.1
+Imports:           prettycode
+Suggests:          knitr, pkgdown, printr, rmarkdown, roxygen2
+VignetteBuilder:   knitr
+Built:             R 3.6.0; ; 2019-05-26 00:49:37 UTC; unix
+
+Index:
+
+?                       Functional help with '?' operator
+dummy                   A dummy data for felp
+felp                    Functional help which displays structure an
+                        object in addition to help
+
+
+ + + +
+ + +
+

Developed by YASUMOTO Atsushi.

+
+ +
+

Site built with pkgdown 1.3.0.

+
+
+
+ + + + + diff --git a/docs/articles/index.html b/docs/articles/index.html new file mode 100644 index 0000000..fd602e9 --- /dev/null +++ b/docs/articles/index.html @@ -0,0 +1,129 @@ + + + + + + + + +Articles • felp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+

Articles

+
+ +
+

All vignettes

+

+ + +
+
+
+ +
+
+

Developed by YASUMOTO Atsushi.

+
+ +
+

Site built with pkgdown 1.3.0.

+
+
+
+ + + + + + diff --git a/docs/authors.html b/docs/authors.html new file mode 100644 index 0000000..1ea0bcd --- /dev/null +++ b/docs/authors.html @@ -0,0 +1,130 @@ + + + + + + + + +Authors • felp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+

Authors

+
+ +
    +
  • +

    YASUMOTO Atsushi. Maintainer. +

    +
    • +
+ +
+ +
+ + +
+
+

Developed by YASUMOTO Atsushi.

+
+ +
+

Site built with pkgdown 1.3.0.

+
+
+
+ + + + + + diff --git a/docs/docsearch.css b/docs/docsearch.css new file mode 100644 index 0000000..e5f1fe1 --- /dev/null +++ b/docs/docsearch.css @@ -0,0 +1,148 @@ +/* Docsearch -------------------------------------------------------------- */ +/* + Source: https://github.com/algolia/docsearch/ + License: MIT +*/ + +.algolia-autocomplete { + display: block; + -webkit-box-flex: 1; + -ms-flex: 1; + flex: 1 +} + +.algolia-autocomplete .ds-dropdown-menu { + width: 100%; + min-width: none; + max-width: none; + padding: .75rem 0; + background-color: #fff; + background-clip: padding-box; + border: 1px solid rgba(0, 0, 0, .1); + box-shadow: 0 .5rem 1rem rgba(0, 0, 0, .175); +} + +@media (min-width:768px) { + .algolia-autocomplete .ds-dropdown-menu { + width: 175% + } +} + +.algolia-autocomplete .ds-dropdown-menu::before { + display: none +} + +.algolia-autocomplete .ds-dropdown-menu [class^=ds-dataset-] { + padding: 0; + background-color: rgb(255,255,255); + border: 0; + max-height: 80vh; +} + +.algolia-autocomplete .ds-dropdown-menu .ds-suggestions { + margin-top: 0 +} + +.algolia-autocomplete .algolia-docsearch-suggestion { + padding: 0; + overflow: visible +} + +.algolia-autocomplete .algolia-docsearch-suggestion--category-header { + padding: .125rem 1rem; + margin-top: 0; + font-size: 1.3em; + font-weight: 500; + color: #00008B; + border-bottom: 0 +} + +.algolia-autocomplete .algolia-docsearch-suggestion--wrapper { + float: none; + padding-top: 0 +} + +.algolia-autocomplete .algolia-docsearch-suggestion--subcategory-column { + float: none; + width: auto; + padding: 0; + text-align: left +} + +.algolia-autocomplete .algolia-docsearch-suggestion--content { + float: none; + width: auto; + padding: 0 +} + +.algolia-autocomplete .algolia-docsearch-suggestion--content::before { + display: none +} + +.algolia-autocomplete .ds-suggestion:not(:first-child) .algolia-docsearch-suggestion--category-header { + padding-top: .75rem; + margin-top: .75rem; + border-top: 1px solid rgba(0, 0, 0, .1) +} + +.algolia-autocomplete .ds-suggestion .algolia-docsearch-suggestion--subcategory-column { + display: block; + padding: .1rem 1rem; + margin-bottom: 0.1; + font-size: 1.0em; + font-weight: 400 + /* display: none */ +} + +.algolia-autocomplete .algolia-docsearch-suggestion--title { + display: block; + padding: .25rem 1rem; + margin-bottom: 0; + font-size: 0.9em; + font-weight: 400 +} + +.algolia-autocomplete .algolia-docsearch-suggestion--text { + padding: 0 1rem .5rem; + margin-top: -.25rem; + font-size: 0.8em; + font-weight: 400; + line-height: 1.25 +} + +.algolia-autocomplete .algolia-docsearch-footer { + width: 110px; + height: 20px; + z-index: 3; + margin-top: 10.66667px; + float: right; + font-size: 0; + line-height: 0; +} + +.algolia-autocomplete .algolia-docsearch-footer--logo { + background-image: url("data:image/svg+xml;utf8,"); + background-repeat: no-repeat; + background-position: 50%; + background-size: 100%; + overflow: hidden; + text-indent: -9000px; + width: 100%; + height: 100%; + display: block; + transform: translate(-8px); +} + +.algolia-autocomplete .algolia-docsearch-suggestion--highlight { + color: #FF8C00; + background: rgba(232, 189, 54, 0.1) +} + + +.algolia-autocomplete .algolia-docsearch-suggestion--text .algolia-docsearch-suggestion--highlight { + box-shadow: inset 0 -2px 0 0 rgba(105, 105, 105, .5) +} + +.algolia-autocomplete .ds-suggestion.ds-cursor .algolia-docsearch-suggestion--content { + background-color: rgba(192, 192, 192, .15) +} diff --git a/docs/docsearch.js b/docs/docsearch.js new file mode 100644 index 0000000..b35504c --- /dev/null +++ b/docs/docsearch.js @@ -0,0 +1,85 @@ +$(function() { + + // register a handler to move the focus to the search bar + // upon pressing shift + "/" (i.e. "?") + $(document).on('keydown', function(e) { + if (e.shiftKey && e.keyCode == 191) { + e.preventDefault(); + $("#search-input").focus(); + } + }); + + $(document).ready(function() { + // do keyword highlighting + /* modified from https://jsfiddle.net/julmot/bL6bb5oo/ */ + var mark = function() { + + var referrer = document.URL ; + var paramKey = "q" ; + + if (referrer.indexOf("?") !== -1) { + var qs = referrer.substr(referrer.indexOf('?') + 1); + var qs_noanchor = qs.split('#')[0]; + var qsa = qs_noanchor.split('&'); + var keyword = ""; + + for (var i = 0; i < qsa.length; i++) { + var currentParam = qsa[i].split('='); + + if (currentParam.length !== 2) { + continue; + } + + if (currentParam[0] == paramKey) { + keyword = decodeURIComponent(currentParam[1].replace(/\+/g, "%20")); + } + } + + if (keyword !== "") { + $(".contents").unmark({ + done: function() { + $(".contents").mark(keyword); + } + }); + } + } + }; + + mark(); + }); +}); + +/* Search term highlighting ------------------------------*/ + +function matchedWords(hit) { + var words = []; + + var hierarchy = hit._highlightResult.hierarchy; + // loop to fetch from lvl0, lvl1, etc. + for (var idx in hierarchy) { + words = words.concat(hierarchy[idx].matchedWords); + } + + var content = hit._highlightResult.content; + if (content) { + words = words.concat(content.matchedWords); + } + + // return unique words + var words_uniq = [...new Set(words)]; + return words_uniq; +} + +function updateHitURL(hit) { + + var words = matchedWords(hit); + var url = ""; + + if (hit.anchor) { + url = hit.url_without_anchor + '?q=' + escape(words.join(" ")) + '#' + hit.anchor; + } else { + url = hit.url + '?q=' + escape(words.join(" ")); + } + + return url; +} diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..cf35396 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,138 @@ + + + + + + + +Functional help for functions, objects, and packages • felp + + + + + + + + + +
+
+ + + +
+
+
+

+felp

+

felp is a short of functional help, and provides

+
    +
  • +?. pseudo-post fix operator to simultaneously display a help document and a structure of an object.
    • +
  • +?p pseudo-post fix operator to display document of a package.
    • +
+

and more in Syntax and Get started

+
+

+Installation

+

Copy & paste:

+
source("https://install-github.me/atusy/felp")
+
+ +
+
+ + +
+ +
+

Developed by YASUMOTO Atsushi.

+
+ +
+

Site built with pkgdown 1.3.0.

+
+
+
+ + + + + diff --git a/docs/link.svg b/docs/link.svg new file mode 100644 index 0000000..88ad827 --- /dev/null +++ b/docs/link.svg @@ -0,0 +1,12 @@ + + + + + + diff --git a/docs/news/index.html b/docs/news/index.html new file mode 100644 index 0000000..b4e633f --- /dev/null +++ b/docs/news/index.html @@ -0,0 +1,201 @@ + + + + + + + + +Changelog • felp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ +
+
+
+

Changelog

+ +
+ +
+

+felp 0.2.0

+
+
+

+felp 0.1.3

+
    +
  • Officially support function?. form to print function and its help simultaneously. +
      +
    • This feature was already present in felp 0.1.1 without knowing it.
      • +
    • Before 0.1.3, . of function?. can be any like function?hoge. This behavior is changed because of conflicts with type?topic form of utils::`?`.
      • +
    +
    • +
+
+
+

+felp 0.1.2

+
    +
  • Use prettycode:::print.function() +
    • +
+
+
+

+felp 0.1.1

+
    +
  • Added S3 version of ? +
      +
    • A method ?.function provides print.function() and help() simultaneously.
      • +
    • A default method ?.default is equivalent to utils::? +
      • +
    +
    • +
  • Unexported print.function as it may conflict with autocompletions of RStudio.
    • +
+
+

+Help wanted

+

R CMD check results gives a warning, but I have no idea to solve it.

+
❯ checking Rd \usage sections ... WARNING
+  Undocumented arguments in documentation object '?'
+    ‘e1’ ‘e2’
+  
+  Bad \usage lines found in documentation object '?':
+    <unescaped bksl>method{?}{function}(e1, e2)
+    <unescaped bksl>method{?}{default}(e1, e2)
+  
+  Functions with \usage entries need to have the appropriate \alias
+  entries, and all their arguments documented.
+  The \usage entries must correspond to syntactically valid R code.
+  See chapter ‘Writing R documentation files’ in the ‘Writing R
+  Extensions’ manual.
+
+
+
+

+felp 0.1.0

+

A first version

+ +
+
+ + + +
+ +
+
+

Developed by YASUMOTO Atsushi.

+
+ +
+

Site built with pkgdown 1.3.0.

+
+
+
+ + + + + + diff --git a/docs/pkgdown.css b/docs/pkgdown.css new file mode 100644 index 0000000..c03fb08 --- /dev/null +++ b/docs/pkgdown.css @@ -0,0 +1,236 @@ +/* Sticky footer */ + +/** + * Basic idea: https://philipwalton.github.io/solved-by-flexbox/demos/sticky-footer/ + * Details: https://github.com/philipwalton/solved-by-flexbox/blob/master/assets/css/components/site.css + * + * .Site -> body > .container + * .Site-content -> body > .container .row + * .footer -> footer + * + * Key idea seems to be to ensure that .container and __all its parents__ + * have height set to 100% + * + */ + +html, body { + height: 100%; +} + +body > .container { + display: flex; + height: 100%; + flex-direction: column; + + padding-top: 60px; +} + +body > .container .row { + flex: 1 0 auto; +} + +footer { + margin-top: 45px; + padding: 35px 0 36px; + border-top: 1px solid #e5e5e5; + color: #666; + display: flex; + flex-shrink: 0; +} +footer p { + margin-bottom: 0; +} +footer div { + flex: 1; +} +footer .pkgdown { + text-align: right; +} +footer p { + margin-bottom: 0; +} + +img.icon { + float: right; +} + +img { + max-width: 100%; +} + +/* Fix bug in bootstrap (only seen in firefox) */ +summary { + display: list-item; +} + +/* Typographic tweaking ---------------------------------*/ + +.contents .page-header { + margin-top: calc(-60px + 1em); +} + +/* Section anchors ---------------------------------*/ + +a.anchor { + margin-left: -30px; + display:inline-block; + width: 30px; + height: 30px; + visibility: hidden; + + background-image: url(./link.svg); + background-repeat: no-repeat; + background-size: 20px 20px; + background-position: center center; +} + +.hasAnchor:hover a.anchor { + visibility: visible; +} + +@media (max-width: 767px) { + .hasAnchor:hover a.anchor { + visibility: hidden; + } +} + + +/* Fixes for fixed navbar --------------------------*/ + +.contents h1, .contents h2, .contents h3, .contents h4 { + padding-top: 60px; + margin-top: -40px; +} + +/* Static header placement on mobile devices */ +@media (max-width: 767px) { + .navbar-fixed-top { + position: absolute; + } + .navbar { + padding: 0; + } +} + + +/* Sidebar --------------------------*/ + +#sidebar { + margin-top: 30px; +} +#sidebar h2 { + font-size: 1.5em; + margin-top: 1em; +} + +#sidebar h2:first-child { + margin-top: 0; +} + +#sidebar .list-unstyled li { + margin-bottom: 0.5em; +} + +.orcid { + height: 16px; + vertical-align: middle; +} + +/* Reference index & topics ----------------------------------------------- */ + +.ref-index th {font-weight: normal;} + +.ref-index td {vertical-align: top;} +.ref-index .icon {width: 40px;} +.ref-index .alias {width: 40%;} +.ref-index-icons .alias {width: calc(40% - 40px);} +.ref-index .title {width: 60%;} + +.ref-arguments th {text-align: right; padding-right: 10px;} +.ref-arguments th, .ref-arguments td {vertical-align: top;} +.ref-arguments .name {width: 20%;} +.ref-arguments .desc {width: 80%;} + +/* Nice scrolling for wide elements --------------------------------------- */ + +table { + display: block; + overflow: auto; +} + +/* Syntax highlighting ---------------------------------------------------- */ + +pre { + word-wrap: normal; + word-break: normal; + border: 1px solid #eee; +} + +pre, code { + background-color: #f8f8f8; + color: #333; +} + +pre code { + overflow: auto; + word-wrap: normal; + white-space: pre; +} + +pre .img { + margin: 5px 0; +} + +pre .img img { + background-color: #fff; + display: block; + height: auto; +} + +code a, pre a { + color: #375f84; +} + +a.sourceLine:hover { + text-decoration: none; +} + +.fl {color: #1514b5;} +.fu {color: #000000;} /* function */ +.ch,.st {color: #036a07;} /* string */ +.kw {color: #264D66;} /* keyword */ +.co {color: #888888;} /* comment */ + +.message { color: black; font-weight: bolder;} +.error { color: orange; font-weight: bolder;} +.warning { color: #6A0366; font-weight: bolder;} + +/* Clipboard --------------------------*/ + +.hasCopyButton { + position: relative; +} + +.btn-copy-ex { + position: absolute; + right: 0; + top: 0; + visibility: hidden; +} + +.hasCopyButton:hover button.btn-copy-ex { + visibility: visible; +} + +/* mark.js ----------------------------*/ + +mark { + background-color: rgba(255, 255, 51, 0.5); + border-bottom: 2px solid rgba(255, 153, 51, 0.3); + padding: 1px; +} + +/* vertical spacing after htmlwidgets */ +.html-widget { + margin-bottom: 10px; +} diff --git a/docs/pkgdown.js b/docs/pkgdown.js new file mode 100644 index 0000000..eb7e83d --- /dev/null +++ b/docs/pkgdown.js @@ -0,0 +1,115 @@ +/* http://gregfranko.com/blog/jquery-best-practices/ */ +(function($) { + $(function() { + + $("#sidebar") + .stick_in_parent({offset_top: 40}) + .on('sticky_kit:bottom', function(e) { + $(this).parent().css('position', 'static'); + }) + .on('sticky_kit:unbottom', function(e) { + $(this).parent().css('position', 'relative'); + }); + + $('body').scrollspy({ + target: '#sidebar', + offset: 60 + }); + + $('[data-toggle="tooltip"]').tooltip(); + + var cur_path = paths(location.pathname); + var links = $("#navbar ul li a"); + var max_length = -1; + var pos = -1; + for (var i = 0; i < links.length; i++) { + if (links[i].getAttribute("href") === "#") + continue; + // Ignore external links + if (links[i].host !== location.host) + continue; + + var nav_path = paths(links[i].pathname); + + var length = prefix_length(nav_path, cur_path); + if (length > max_length) { + max_length = length; + pos = i; + } + } + + // Add class to parent
  • , and enclosing
  • if in dropdown + if (pos >= 0) { + var menu_anchor = $(links[pos]); + menu_anchor.parent().addClass("active"); + menu_anchor.closest("li.dropdown").addClass("active"); + } + }); + + function paths(pathname) { + var pieces = pathname.split("/"); + pieces.shift(); // always starts with / + + var end = pieces[pieces.length - 1]; + if (end === "index.html" || end === "") + pieces.pop(); + return(pieces); + } + + // Returns -1 if not found + function prefix_length(needle, haystack) { + if (needle.length > haystack.length) + return(-1); + + // Special case for length-0 haystack, since for loop won't run + if (haystack.length === 0) { + return(needle.length === 0 ? 0 : -1); + } + + for (var i = 0; i < haystack.length; i++) { + if (needle[i] != haystack[i]) + return(i); + } + + return(haystack.length); + } + + /* Clipboard --------------------------*/ + + function changeTooltipMessage(element, msg) { + var tooltipOriginalTitle=element.getAttribute('data-original-title'); + element.setAttribute('data-original-title', msg); + $(element).tooltip('show'); + element.setAttribute('data-original-title', tooltipOriginalTitle); + } + + if(ClipboardJS.isSupported()) { + $(document).ready(function() { + var copyButton = ""; + + $(".examples, div.sourceCode").addClass("hasCopyButton"); + + // Insert copy buttons: + $(copyButton).prependTo(".hasCopyButton"); + + // Initialize tooltips: + $('.btn-copy-ex').tooltip({container: 'body'}); + + // Initialize clipboard: + var clipboardBtnCopies = new ClipboardJS('[data-clipboard-copy]', { + text: function(trigger) { + return trigger.parentNode.textContent; + } + }); + + clipboardBtnCopies.on('success', function(e) { + changeTooltipMessage(e.trigger, 'Copied!'); + e.clearSelection(); + }); + + clipboardBtnCopies.on('error', function() { + changeTooltipMessage(e.trigger,'Press Ctrl+C or Command+C to copy'); + }); + }); + } +})(window.jQuery || window.$) diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml new file mode 100644 index 0000000..efb386c --- /dev/null +++ b/docs/pkgdown.yml @@ -0,0 +1,6 @@ +pandoc: 2.7.2 +pkgdown: 1.3.0 +pkgdown_sha: ~ +articles: + felp: felp.html + diff --git a/docs/reference/dummy.html b/docs/reference/dummy.html new file mode 100644 index 0000000..8b480a4 --- /dev/null +++ b/docs/reference/dummy.html @@ -0,0 +1,147 @@ + + + + + + + + +A dummy data for felp — dummy • felp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    A dummy data for felp

    + + +
    + +
    + +

    A dummy data for felp

    + +
    + + 
    dummy
    + +

    Format

    + +

    An object of class list of length 2.

    + + +
    + +
    + +
    +
    +

    Developed by YASUMOTO Atsushi.

    +
    + +
    +

    Site built with pkgdown 1.3.0.

    +
    +
    +
    + + + + + + diff --git a/docs/reference/felp.html b/docs/reference/felp.html new file mode 100644 index 0000000..ea600a4 --- /dev/null +++ b/docs/reference/felp.html @@ -0,0 +1,182 @@ + + + + + + + + +Functional help which displays structure an object in addition to help — felp • felp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Functional help which displays structure an object in addition to help

    + + +
    + +
    + +

    Structure of object is returned by str(). +For a function, its source is returned instead of str().

    + +
    + + 
    felp(topic, package = NULL, ...)
    + +

    Arguments

    + + + + + + + + + + + + + + +
    topic

    usually, a name or character string specifying the + topic for which help is sought. A character string (enclosed in + explicit single or double quotes) is always taken as naming a topic.

    +

    If the value of topic is a length-one + character vector the topic is taken to be the value of the only + element. Otherwise topic must be a name or a reserved + word (if syntactically valid) or character string.

    +

    See ‘Details’ for what happens if this is omitted.

    package

    a name or character vector giving the packages to look + into for documentation, or NULL. By default, all packages + whose namespaces are loaded are used. To avoid a name being deparsed use e.g. + (pkg_ref) (see the examples).

    ...

    Arguments passed on to utils::help

    +
    lib.loc

    a character vector of directory names of R libraries, + or NULL. The default value of NULL corresponds to all + libraries currently known. If the default is used, the loaded + packages are searched before the libraries. This is not used for + HTML help (see ‘Details’).

    +
    verbose

    logical; if TRUE, the file name is reported.

    +
    try.all.packages

    logical; see Note.

    +
    help_type

    character string: the type of help required. + Possible values are "text", "html" and "pdf". + Case is ignored, and partial matching is allowed.

    +
    + + +
    + +
    + +
    +
    +

    Developed by YASUMOTO Atsushi.

    +
    + +
    +

    Site built with pkgdown 1.3.0.

    +
    +
    +
    + + + + + + diff --git a/docs/reference/index.html b/docs/reference/index.html new file mode 100644 index 0000000..151fb91 --- /dev/null +++ b/docs/reference/index.html @@ -0,0 +1,164 @@ + + + + + + + + +Function reference • felp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Reference

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +

    All functions

    +

    +
    +

    dummy

    +

    A dummy data for felp

    +

    felp()

    +

    Functional help which displays structure an object in addition to help

    +

    `?`()

    +

    Functional help with ? operator

    +
    + + +
    + +
    +
    +

    Developed by YASUMOTO Atsushi.

    +
    + +
    +

    Site built with pkgdown 1.3.0.

    +
    +
    +
    + + + + + + diff --git a/docs/reference/question.html b/docs/reference/question.html new file mode 100644 index 0000000..7f67a0f --- /dev/null +++ b/docs/reference/question.html @@ -0,0 +1,163 @@ + + + + + + + + +Functional help with <code>?</code> operator — ? • felp + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + +
    + +
    +
    +
    +

    Functional help with ? operator

    + + +
    + +
    + +

    Displays help and structure of an object, or help of a package. +Two syntaxes are added to those of utils::?. +One is object?. which works as if ?object. +Another is package?p which works as if help(package = package)

    + +
    + + 
    "?"(e1, e2)
    + +

    Arguments

    + + + + + + + + + + +
    e1

    A topic of document. +Refer to topic argument described in utils::`?`.

    e2

    . and p have special meanings as documented above. +Otherwise, e2 is same as type argument of utils::`?`.

    + + +
    + +
    + + +
    + + + + + + diff --git a/man/dummy.Rd b/man/dummy.Rd new file mode 100644 index 0000000..5e95716 --- /dev/null +++ b/man/dummy.Rd @@ -0,0 +1,14 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/data.R +\docType{data} +\name{dummy} +\alias{dummy} +\title{A dummy data for felp} +\format{An object of class \code{list} of length 2.} +\usage{ +dummy +} +\description{ +A dummy data for felp +} +\keyword{datasets} diff --git a/man/felp.Rd b/man/felp.Rd index 886d509..3f9e279 100644 --- a/man/felp.Rd +++ b/man/felp.Rd @@ -2,17 +2,43 @@ % Please edit documentation in R/felp.R \name{felp} \alias{felp} -\title{Returns source and help of a function simultaneously} +\title{Functional help which displays structure an object in addition to help} \usage{ felp(topic, package = NULL, ...) } \arguments{ -\item{topic}{A name or character string specifying the function for which help and source are sought. Package to be sought can also be defined simultaneously if x is specified in the style of package::name or package:::name} +\item{topic}{usually, a \link{name} or character string specifying the + topic for which help is sought. A character string (enclosed in + explicit single or double quotes) is always taken as naming a topic. -\item{package}{A name or character string specifying the package for which help and source are sought. If the package is specified by x, this parameter is neglected, or NULL (default).} + If the value of \code{topic} is a length-one + character vector the topic is taken to be the value of the only + element. Otherwise \code{topic} must be a name or a \link{reserved} + word (if syntactically valid) or character string. -\item{...}{Other arguments passed to help} + See \sQuote{Details} for what happens if this is omitted. + } + +\item{package}{a name or character vector giving the packages to look + into for documentation, or \code{NULL}. By default, all packages + whose namespaces are loaded are used. To avoid a name being deparsed use e.g. + \code{(pkg_ref)} (see the examples).} + +\item{...}{Arguments passed on to \code{utils::help} +\describe{ + \item{lib.loc}{a character vector of directory names of \R libraries, + or \code{NULL}. The default value of \code{NULL} corresponds to all + libraries currently known. If the default is used, the loaded + packages are searched before the libraries. This is not used for + HTML help (see \sQuote{Details}).} + \item{verbose}{logical; if \code{TRUE}, the file name is reported.} + \item{try.all.packages}{logical; see \code{Note}.} + \item{help_type}{character string: the type of help required. + Possible values are \code{"text"}, \code{"html"} and \code{"pdf"}. + Case is ignored, and partial matching is allowed.} +}} } \description{ -Returns source and help of a function simultaneously +Structure of object is returned by \code{str()}. +For a function, its source is returned instead of \code{str()}. } diff --git a/man/question.Rd b/man/question.Rd index be35845..1205b80 100644 --- a/man/question.Rd +++ b/man/question.Rd @@ -2,21 +2,20 @@ % Please edit documentation in R/question.R \name{?} \alias{?} -\alias{?.function} -\alias{?.default} -\title{S3 version of [utils::`?`]} +\title{Functional help with \code{?} operator} \usage{ "?"(e1, e2) - -\method{?}{function}(e1, e2) - -\method{?}{default}(e1, e2) } \arguments{ -\item{e1}{A topic ought to be documented. Refer to `topic` argument described in `` utils::`?` ``.} +\item{e1}{A topic of document. +Refer to \code{topic} argument described in \code{utils::`?`}.} -\item{e2}{`.` equals to `missing(e2)`. If else, see `type` argument described in `` utils::`?` ``.} +\item{e2}{\code{.} and \code{p} have special meanings as documented above. +Otherwise, \code{e2} is same as \code{type} argument of \code{utils::`?`}.} } \description{ -S3 version of [utils::`?`] +Displays help and structure of an object, or help of a package. +Two syntaxes are added to those of \code{utils::?}. +One is \code{object?.} which works as if \code{?object}. +Another is \code{package?p} which works as if \code{help(package = package)} } diff --git a/vignettes/.gitignore b/vignettes/.gitignore new file mode 100644 index 0000000..097b241 --- /dev/null +++ b/vignettes/.gitignore @@ -0,0 +1,2 @@ +*.html +*.R diff --git a/vignettes/felp.Rmd b/vignettes/felp.Rmd new file mode 100644 index 0000000..6d35f00 --- /dev/null +++ b/vignettes/felp.Rmd @@ -0,0 +1,83 @@ +--- +title: "felp" +output: + rmarkdown::html_vignette: default +vignette: > + %\VignetteIndexEntry{felp} + %\VignetteEncoding{UTF-8} + %\VignetteEngine{knitr::rmarkdown} +--- + +```{css, echo = FALSE} +h1 { + color: darkblue; +} +``` + + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = FALSE, + comment = "", + class.output = "text" +) +``` + +```{r setup, include = FALSE} +library(felp) +library(printr) # To include documents output by `?` in this article +``` + +```{r setup-echo, ref.label='setup', eval = FALSE} + +``` + +The `felp` package provides + +- the `?.` pseudo-post fix operator to simultaneously display a help document + and a structure of an object +- the `?p` pseudo-post fix operator to display document of a package +- the `felp` function and `?` operator to extend `help` and `?` in the `utils` package + by displaying structure of an object + +# Syntax + +``` r +# ? as a prefix operator +?help +?utils::help + +# ?. as a pseudo postfix operator for functions and objects +help?. +utils::help?. + +# ?p as a pseudo postfix operator fur packages +utils?. + +# felp as an extention of utils::help +felp(help) +felp("help") +felp(utils::help) +felp(help, utils) +felp(package = utils) +``` + +# felp(function) + +```{r fun, attr.output=".r"} +felp?. # and `felp(felp)` return source and document of `felp` function +``` + + +# felp(dataset) + +```{r data} +dummy?. # and `felp(dummy)` return sructure and document of `dummy` dataset. +``` + +# felp(package) + +```{r pkg} +felp?p # and `felp(package = felp)` return document of `felp` package +``` +