## #' Page Dimensions

## #'

## #' Dimensions for mapping page dimensions to text dimensions

## #' @references https://www.ietf.org/rfc/rfc0678.txt

## #' @export

## #' @rdname pagedims

## lpi_vert <- 6

## #' @export

## #' @rdname pagedims

## cpi_horiz <- 10

## #' @export

## #' @rdname pagedims

## horiz_margin_chars <- 13

## #' @export

## #' @rdname pagedims

## horiz_margin_inches <- horiz_margin_chars / cpi_horiz

## #' @export

## #' @rdname pagedims

## vert_margin_lines <- 6

## #' @export

## #' @rdname pagedims

## vert_margin_inches <- vert_margin_lines / lpi_vert

## #' Physical Page dimensions to chars x lines

## #'

## #' Calculate number of lines long and characters wide a page size is,

## #' after excluding margins

## #' @export

## #' @examples

## #' phys_page_to_lc()

## phys_page_to_lc <- function(width = 8.5, len = 11,

##                             h_margin = horiz_margin_inches,

##                             v_margin = vert_margin_inches) {

##     lgl_width <- width - h_margin

##     lgl_len <- len - v_margin

##     c(chars_wide = floor(lgl_width * cpi_horiz),

##       lines_long = floor(lgl_len * lpi_vert))

## }

#' Pagination

#'

#' @section Pagination Algorithm:

#'

#' Pagination is performed independently in the vertical and horizontal

#' directions based solely on a *pagination data frame*, which includes the

#' following information for each row/column:

#'

#'   - Number of lines/characters rendering the row will take **after

#'     word-wrapping** (`self_extent`)

#'   - The indices (`reprint_inds`) and number of lines (`par_extent`)

#'     of the rows which act as **context** for the row

#'   - The row's number of siblings and position within its siblings

#'

#' Given `lpp` (`cpp`) is already adjusted for rendered elements which

#' are not rows/columns and a data frame of pagination information,

#' pagination is performed via the following algorithm with `start = 1`.

#'

#' Core Pagination Algorithm:

#'

#' 1. Initial guess for pagination position is `start + lpp` (`start + cpp`)

#' 2. While the guess is not a valid pagination position, and `guess > start`,

#'    decrement guess and repeat.

#'      - An error is thrown if all possible pagination positions between

#'        `start` and `start + lpp` (`start + cpp`) would be `< start`

#'        after decrementing

#' 3. Retain pagination index

#' 4. If pagination point was less than `NROW(tt)` (`ncol(tt)`), set

#'    `start` to `pos + 1`, and repeat steps (1) - (4).

#'

#' Validating Pagination Position:

#'

#' Given an (already adjusted) `lpp` or `cpp` value, a pagination is invalid if:

#'

#'   - The rows/columns on the page would take more than (adjusted) `lpp` lines/`cpp`

#'     characters to render **including**:

#'       - word-wrapping

#'       - (vertical only) context repetition

#'   - (vertical only) footnote messages and/or section divider lines

#'     take up too many lines after rendering rows

#'   - (vertical only) row is a label or content (row-group summary) row

#'   - (vertical only) row at the pagination point has siblings, and

#'     it has less than `min_siblings` preceding or following siblings

#'   - pagination would occur within a sub-table listed in `nosplitin`

#'

#' @name pagination_algo

NULL

#' Create a row of a pagination data frame

#'

#' @param nm (`string`)\cr name.

#' @param lab (`string`)\cr label.

#' @param rnum (`numeric(1)`)\cr absolute row number.

#' @param pth (`character` or `NULL`)\cr path within larger table.

#' @param sibpos (`integer(1)`)\cr position among sibling rows.

#' @param nsibs (`integer(1)`)\cr number of siblings (including self).

#' @param extent (`numeric(1)`)\cr number of lines required to print the row.

#' @param colwidths (`numeric`)\cr column widths.

#' @param repext (`integer(1)`)\cr number of lines required to reprint all context for this row if it appears directly

#'   after pagination.

#' @param repind (`integer`)\cr vector of row numbers to be reprinted if this row appears directly after pagination.

#' @param indent (`integer`)\cr indent.

#' @param rclass (`string`)\cr class of row object.

#' @param nrowrefs (`integer(1)`)\cr number of row referential footnotes for this row.

#' @param ncellrefs (`integer(1)`)\cr number of cell referential footnotes for the cells in this row.

#' @param nreflines (`integer(1)`)\cr total number of lines required by all referential footnotes.

#' @param force_page (`flag`)\cr currently ignored.

#' @param page_title (`flag`)\cr currently ignored.

#' @param trailing_sep (`string`)\cr the string to use as a separator below this row during printing.

#'   If `NA_character_`, no separator is used.

#' @param row (`ANY`)\cr object representing the row, which is used for default values of `nm`, `lab`,

#'   `extent`, and `rclass` if provided. Must have methods for `obj_name`, `obj_label`, and `nlines`, to retrieve

#'   default values of `nm`, `lab`, and `extent`, respectively.

#'

#' @return A single row `data.frame` with the appropriate columns for a pagination info data frame.

#'

#' @export

pagdfrow <- function(row,

                     nm = obj_name(row),

                     lab = obj_label(row),

                     rnum,

                     pth,

                     sibpos = NA_integer_,

                     nsibs = NA_integer_,

                     extent = nlines(row, colwidths),

                     colwidths = NULL,

                     repext = 0L,

                     repind = integer(),

                     indent = 0L,

                     rclass = class(row),

                     nrowrefs = 0L,

                     ncellrefs = 0L,

                     nreflines = 0L,

                     # ref_df = .make_ref_df(NULL, NULL),

                     force_page = FALSE,

                     page_title = NA_character_,

                     trailing_sep = NA_character_) {

    # ref_info_df = I(list(ref_df)),

  )

}

calc_ref_nlines_df <- function(pagdf) {

  ## XXX XXX XXX this is dangerous and wrong!!!

  }

  }

}

build_fail_msg <- function(row, lines, raw_rowlines,

                           allowed_lines, lpp, decoration_lines,

                           start, guess, rep_ext, n_reprint,

                           reflines, n_refs, sectlines) {

      ),

    )

  } else { ## !row

    )

  }

}

valid_pag <- function(pagdf,

                      guess,

                      start,

                      rlpp,

                      lpp, # for informational purposes only

                      context_lpp, # for informational purposes only (headers/footers)

                      min_sibs,

                      nosplit = NULL,

                      div_height = 1L,

                      verbose = FALSE,

                      row = TRUE,

                      have_col_fnotes = FALSE) {

  # FALSE output from this function means that another guess is taken till success or failure

    )

  }

  # Fix for counting the right number of lines when there is wrapping on a keycols

  }

  }

  ##  reflines <- sum(pagdf[start:guess, "nreflines"])

  ## self extent includes reflines

  ## self extent does ***not*** currently include trailing sep

  ## we don't include the trailing_sep for guess because if we paginate here it won't be printed

      )

    }

  }

  # Special cases: is it a label or content row?

    # check if it has children; if no children then valid

      }

        )

      }

    } else {

      }

    }

  }

  # Siblings handling

  # okpos <- min(min_sibs + 1, rw[["n_siblings"]])

        )

      }

        )

      }

    }

    }

  }

    ## paths end at the leaf name which is *always* different

          )

        }

      }

    }

  }

  # Usual output when found

  }

}

find_pag <- function(pagdf,

                     current_page,

                     start,

                     guess,

                     rlpp,

                     lpp_or_cpp,

                     context_lpp_or_cpp,

                     min_siblings,

                     nosplitin = character(),

                     verbose = FALSE,

                     row = TRUE,

                     have_col_fnotes = FALSE,

                     div_height = 1L,

                     do_error = FALSE) {

    } else {

    }

  }

  )) {

  }

    # Repeat pagination process to see what went wrong with verbose on

      )

    }

      ),

    )

  }

}

#' Find pagination indices from pagination info data frame

#'

#' Pagination methods should typically call the `make_row_df` method

#' for their object and then call this function on the resulting

#' pagination info `data.frame`.

#'

#' @param pagdf (`data.frame`)\cr a pagination info `data.frame` as created by

#'   either `make_rows_df` or `make_cols_df`.

#' @param rlpp (`numeric`)\cr maximum number of *row* lines per page (not including header materials), including

#'   (re)printed header and context rows.

#' @param lpp_or_cpp (`numeric`)\cr total maximum number of *row* lines or content (column-wise characters) per page

#'   (including header materials and context rows). This is only for informative results with `verbose = TRUE`.

#'   It will print `NA` if not specified by the pagination machinery.

#' @param context_lpp_or_cpp (`numeric`)\cr total number of context *row* lines or content (column-wise characters)

#'   per page (including header materials). Uses `NA` if not specified by the pagination machinery and is only

#'   for informative results with `verbose = TRUE`.

#' @param min_siblings (`numeric`)\cr minimum sibling rows which must appear on either side of pagination row for a

#'   mid-subtable split to be valid. Defaults to 2 for tables. It is automatically turned off (set to 0) for listings.

#' @param nosplitin (`character`)\cr list of names of subtables where page breaks are not allowed, regardless of other

#'   considerations. Defaults to none.

#' @param verbose (`flag`)\cr whether additional informative messages about the search for

#'   pagination breaks should be shown. Defaults to `FALSE`.

#' @param row (`flag`)\cr whether pagination is happening in row space (`TRUE`, the default) or column

#'   space (`FALSE`).

#' @param have_col_fnotes (`flag`)\cr whether the table-like object being rendered has column-associated

#'   referential footnotes.

#' @param div_height (`numeric(1)`)\cr the height of the divider line when the associated object is rendered.

#'   Defaults to `1`.

#'

#' @details `pab_indices_inner` implements the core pagination algorithm (see below)

#' for a single direction (vertical if `row = TRUE` (the default), horizontal otherwise)

#' based on the pagination data frame and (already adjusted for non-body rows/columns)

#' lines (or characters) per page.

#'

#' @inheritSection pagination_algo Pagination Algorithm

#'

#' @return A `list` containing a vector of row numbers, broken up by page.

#'

#' @examples

#' mypgdf <- basic_pagdf(row.names(mtcars))

#'

#' paginds <- pag_indices_inner(mypgdf, rlpp = 15, min_siblings = 0)

#' lapply(paginds, function(x) mtcars[x, ])

#'

#' @export

pag_indices_inner <- function(pagdf,

                              rlpp,

                              lpp_or_cpp = NA_integer_, context_lpp_or_cpp = NA_integer_, # Context number of lines

                              min_siblings,

                              nosplitin = character(),

                              verbose = FALSE,

                              row = TRUE,

                              have_col_fnotes = FALSE,

                              div_height = 1L) {

      } else {

      }

    }

    )

    )))

  }

}

#' Find column indices for vertical pagination

#'

#' @inheritParams pag_indices_inner

#' @param obj (`ANY`)\cr object to be paginated. Must have a [matrix_form()] method.

#' @param cpp (`numeric(1)`)\cr number of characters per page (width).

#' @param colwidths (`numeric`)\cr vector of column widths (in characters) for use in vertical pagination.

#' @param rep_cols (`numeric(1)`)\cr number of *columns* (not including row labels) to be repeated on every page.

#'   Defaults to 0.

#'

#' @return A `list` partitioning the vector of column indices into subsets for 1 or more horizontally paginated pages.

#'

#' @examples

#' mf <- basic_matrix_form(df = mtcars)

#' colpaginds <- vert_pag_indices(mf)

#' lapply(colpaginds, function(j) mtcars[, j, drop = FALSE])

#'

#' @export

vert_pag_indices <- function(obj, cpp = 40, colwidths = NULL, verbose = FALSE, rep_cols = 0L) {

  }

  # rep_extent <- pdf$par_extent[nrow(pdf)]

      "]"

    )

  }

    # cpp - sum(clwds[seq_len(rep_cols)]),

  )

}

mpf_infer_cinfo <- function(mf, colwidths = NULL, rep_cols = num_rep_cols(mf)) {

  }

      )

    }

  )

}

#' Basic/spoof pagination info data frame

#'

#' Returns a minimal pagination info `data.frame` (with no info on siblings, footnotes, etc.).

#'

#' @inheritParams test_matrix_form

#' @param rnames (`character`)\cr vector of row names.

#' @param labs (`character`)\cr vector of row labels. Defaults to `rnames`.

#' @param rnums (`integer`)\cr vector of row numbers. Defaults to `seq_along(rnames)`.

#' @param extents (`integer`)\cr number of lines each row requires to print. Defaults to 1 for all rows.

#' @param rclass (`character`)\cr class(es) for the rows. Defaults to `"DataRow"`.

#' @param paths (`list`)\cr list of paths to the rows. Defaults to `lapply(rnames, function(x) c(parent_path, x))`.

#'

#' @return A `data.frame` suitable for use in both the `MatrixPrintForm` constructor and the pagination machinery.

#'

#' @examples

#' basic_pagdf(c("hi", "there"))

#'

#' @export

basic_pagdf <- function(rnames,

                        labs = rnames,

                        rnums = seq_along(rnames),

                        extents = 1L,

                        rclass = "DataRow",

                        parent_path = NULL,

                        paths = lapply(rnames, function(x) c(parent_path, x))) {

  )

    # These things are used in the simple case of a split, hence having labels.

    # To improve and extend to other cases

  }

}

## write paginate() which operates **solely** on a MatrixPrintForm obj

page_size_spec <- function(lpp, cpp, max_width) {

}

calc_lcpp <- function(page_type = NULL,

                      landscape = FALSE,

                      pg_width = page_dim(page_type)[if (landscape) 2 else 1],

                      pg_height = page_dim(page_type)[if (landscape) 1 else 2],

                      font_family = "Courier",

                      font_size = 8, # grid parameters

                      cpp = NA_integer_,

                      lpp = NA_integer_,

                      tf_wrap = TRUE,

                      max_width = NULL,

                      lineheight = 1,

                      margins = c(bottom = .5, left = .75, top = .5, right = .75),

                      colwidths,

                      col_gap,

                      inset) {

  )

  }

  }

}

calc_rlpp <- function(pg_size_spec, mf, colwidths, tf_wrap, verbose) {

    ## +1 is for blank line between subtitles and divider

    ## dh is for divider line **between subtitles and column labels**

    ## other divider line is accounted for in cinfo_lines

    } else {

    }

  } else {

  }

  ## dh for divider line between column labels and table body

    )

  }

    )

  }

    } ## space between main and prov footer.

  }

  ## this time its for the divider between the footers and whatever is above them

  ## (either table body or referential footnotes)

  }

  ## this time its for the divider between the referential footnotes and

  ## the table body IFF we have any, otherwise that divider+blanks pace doesn't get drawn

  }

    )

  }

  }

}

calc_rcpp <- function(pg_size_spec, mf, colwidths) {

}

splice_idx_lists <- function(lsts) {

  )

}

#' Paginate a table-like object for rendering

#'

#' These functions perform or diagnose bi-directional pagination on an object.

#'

#' `paginate_indices` renders `obj` into a `MatrixPrintForm` (MPF), then uses that representation to

#' calculate the rows and columns of `obj` corresponding to each page of the pagination of `obj`, but

#' simply returns these indices rather than paginating `obj` itself (see Details for an important caveat).

#'

#' `paginate_to_mpfs` renders `obj` into its MPF intermediate representation, then paginates that MPF into

#' component MPFs each corresponding to an individual page and returns those in a `list`.

#'

#' `diagnose_pagination` attempts pagination via `paginate_to_mpfs`, then returns diagnostic information

#' which explains why page breaks were positioned where they were, or alternatively why no valid pagination

#' could be found.

#'

#' @details

#' All three of these functions generally support all classes which have a corresponding [matrix_form()]

#' method which returns a valid `MatrixPrintForm` object (including `MatrixPrintForm` objects themselves).

#'

#' `paginate_indices` is directly called by `paginate_to_mpfs` (and thus `diagnose_pagination`). For most

#' classes, and most tables represented by supported classes, calling `paginate_to_mpfs` is equivalent to a

#' manual `paginate_indices -> subset obj into pages -> matrix_form` workflow.

#'

#' The exception to this equivalence is objects which support "forced pagination", or pagination logic which

#' is built into the object itself rather than being a function of space on a page. Forced pagination

#' generally involves the creation of, e.g., page-specific titles which apply to these forced paginations.

#' `paginate_to_mpfs` and `diagnose_pagination` support forced pagination by automatically calling the

#' [do_forced_paginate()] generic on the object and then paginating each object returned by that generic

#' separately. The assumption here, then, is that page-specific titles and such are handled by the class'

#' [do_forced_paginate()] method.

#'

#' `paginate_indices`, on the other hand, *does not support forced pagination*, because it returns only a

#' set of indices for row and column subsetting for each page, and thus cannot retain any changes, e.g.,

#' to titles, done within [do_forced_paginate()]. `paginate_indices` does call [do_forced_paginate()], but

#' instead of continuing it throws an error in the case that the result is larger than a single "page".

#'

#' @inheritParams vert_pag_indices

#' @inheritParams pag_indices_inner

#' @inheritParams page_lcpp

#' @inheritParams toString

#' @inheritParams propose_column_widths

#' @param lpp (`numeric(1)` or `NULL`)\cr lines per page. If `NA` (the default), this is calculated automatically

#'   based on the specified page size). `NULL` indicates no vertical pagination should occur.

#' @param cpp (`numeric(1)` or `NULL`)\cr width (in characters) per page. If `NA` (the default), this is calculated

#'   automatically based on the specified page size). `NULL` indicates no horizontal pagination should occur.

#' @param pg_size_spec (`page_size_spec`)\cr. a pre-calculated page size specification. Typically this is not set by

#'   end users.

#' @param col_gap (`numeric(1)`)\cr currently ignored.

#' @param page_num (`string`)\cr placeholder string for page numbers. See [default_page_number] for more

#'   information. Defaults to `NULL`.

#'

#' @return

#' * `paginate_indices` returns a `list` with two elements of the same length: `pag_row_indices` and `pag_col_indices`.

#' * `paginate_to_mpfs` returns a `list` of  `MatrixPrintForm` objects representing each individual page after

#'   pagination (including forced pagination if necessary).

#'

#' @examples

#' mpf <- basic_matrix_form(mtcars)

#'

#' paginate_indices(mpf, pg_width = 5, pg_height = 3)

#'

#' paginate_to_mpfs(mpf, pg_width = 5, pg_height = 3)

#'

#' @aliases paginate pagination

#' @export

paginate_indices <- function(obj,

                             page_type = "letter",

                             font_family = "Courier",

                             font_size = 8,

                             lineheight = 1,

                             landscape = FALSE,

                             pg_width = NULL,

                             pg_height = NULL,

                             margins = c(top = .5, bottom = .5, left = .75, right = .75),

                             lpp = NA_integer_,

                             cpp = NA_integer_,

                             min_siblings = 2,

                             nosplitin = character(),

                             colwidths = NULL,

                             tf_wrap = FALSE,

                             max_width = NULL,

                             indent_size = 2,

                             pg_size_spec = NULL,

                             rep_cols = num_rep_cols(obj),

                             col_gap = 3,

                             verbose = FALSE) {

  ## this MUST alsways return a list, inluding list(obj) when

  ## no forced pagination is needed! otherwise stuff breaks for things

  ## based on s3 classes that are lists underneath!!!

  ## if we have more than one forced "page",

  ## paginate each of them individually and return the result.

  ## forced pagination is ***currently*** only vertical, so

  ## we don't have to worry about divying up colwidths here,

  ## but we will if we ever allow force_paginate to do horiz

  ## pagination.

    )

  }

  ## I'm not sure this is worth doing.

  ## ## We can't support forced pagination here, but we can support calls to,

  ## ## e.g., paginate_indices(do_forced_pag(tt))

  ## if(is.list(obj) && !is.object(obj)) {

  ##     res <- lapply(obj, paginate_indices,

  ##                   page_type = page_type,

  ##                   font_family = font_family,

  ##                   font_size = font_size,

  ##                   lineheight = lineheight,

  ##                   landscape = landscape,

  ##                   pg_width = pg_width,

  ##                   pg_height = pg_height,

  ##                   margins = margins,

  ##                   lpp = lpp,

  ##                   cpp = cpp,

  ##                   tf_wrap = tf_wrap,

  ##                   max_width = max_width,

  ##                   colwidths = colwidths,

  ##                   min_siblings = min_siblings,

  ##                   nosplitin = nosplitin,

  ##                   col_gap = col_gap,

  ##                   ## not setting num_rep_cols here cause it wont' get it right

  ##                   verbose = verbose)

  ##     return(splice_idx_lists(res))

  ## }

  ## order is annoying here, since we won't actually need the mpf if

  ## we run into forced pagination, but life is short and this should work fine.

  } else {

  }

  }

    )

  }

  ## we can't support forced pagination in paginate_indices because

  ## forced pagination is generally going to set page titles, which

  ## we can't preserve when just returning lists of indices.

  ## Instead we make a hard assumption here that any forced pagination

  ## has already occurred.

  ## this wraps the cell contents AND shoves referential footnote

  ## info mf_rinfo(mpf)

  # rlistings note: if there is a wrapping in a keycol, it is not calculated correctly

  #                 in the above call, so we need to keep this information in mf_rinfo

  #                 and use it here.

    # Lets determine the groupings created by keycols

        # This makes the function work also in the case we have only matrix form (mainly for testing purposes)

        }

      } else {

      }

    }

    # Creating the real self_extend for mf_rinfo (if the line is chosen for pagination start)

  }

  } else {

    )

    )

  }

  } else {

    )

  }

}

#' @rdname paginate_indices

#' @export

paginate_to_mpfs <- function(obj,

                             page_type = "letter",

                             font_family = "Courier",

                             font_size = 8,

                             lineheight = 1,

                             landscape = FALSE,

                             pg_width = NULL,

                             pg_height = NULL,

                             margins = c(top = .5, bottom = .5, left = .75, right = .75),

                             lpp = NA_integer_,

                             cpp = NA_integer_,

                             min_siblings = 2,

                             nosplitin = character(),

                             colwidths = NULL,

                             tf_wrap = FALSE,

                             max_width = NULL,

                             indent_size = 2,

                             pg_size_spec = NULL,

                             page_num = default_page_number(),

                             rep_cols = NULL,

                             col_gap = 2,

                             verbose = FALSE) {

  }

  # We can return a list of paginated tables and listings

      }),

    )

        })

      )

    }

  }

    # Only adding a line for pagination -> lpp - 1 would have worked too

  }

  # Turning off min_siblings for listings

  }

  # Checking colwidths

  } else {

    }

      )

    }

  }

  # For listings, keycols are mandatory rep_num_cols

  }

  }

    )

  }

  ## this MUST always return a list, including list(obj) when

  ## no forced pagination is needed! otherwise stuff breaks for things

  ## based on s3 classes that are lists underneath!!!

  ## if we have more than one forced "page",

  ## paginate each of them individually and return the result.

  ## forced pagination is ***currently*** only vertical, so

  ## we don't have to worry about divying up colwidths here,

  ## but we will if we ever allow force_paginate to do horiz

  ## pagination.

    # Correction for case we are entering here (page_by?)

    }

    )

  }

  ## we run into forced pagination, but life is short and this should work fine.

  }

    ## page_type = page_type,

    ## font_family = font_family,

    ## font_size = font_size,

    ## lineheight = lineheight,

    ## landscape = landscape,

    ## pg_width = pg_width,

    ## pg_height = pg_height,

    ## margins = margins,

    ## lpp = lpp,

    ## cpp = cpp,

    ## max_width = max_width,

  )

  })

  ## these chunks now carry around their (correctly subset) col widths...

    })

  })

  # Adding page numbers if needed

    )

  }

}

.modify_footer_for_page_nums <- function(mf_list, page_num_format, current_cpp) {

    },

  )

  }

  })

}

# This works only with matrix_form objects

.is_listing_mf <- function(mf) {

}

# Extended copy of get_keycols

.get_keycols_from_listing <- function(obj) {

  } else {

  }

}

#' @importFrom utils capture.output

#' @details

#' `diagnose_pagination` attempts pagination and then, regardless of success or failure, returns diagnostic

#' information about pagination attempts (if any) after each row and column.

#'

#' The diagnostics data reflects the final time the pagination algorithm evaluated a page break at the

#' specified location, regardless of how many times the position was assessed in total.

#'

#' To get information about intermediate attempts, perform pagination with `verbose = TRUE` and inspect

#' the messages in order.

#'

#' @importFrom utils capture.output

#'

#' @return

#' * `diagnose_pagination` returns a `list` containing:

#'

#'   \describe{

#'     \item{`lpp_diagnostics`}{Diagnostic information regarding lines per page.}

#'     \item{`row_diagnostics`}{Basic information about rows, whether pagination was attempted

#'       after each row, and the final result of such an attempt, if made.}

#'     \item{`cpp_diagnostics`}{Diagnostic information regarding columns per page.}

#'     \item{`col_diagnostics`}{Very basic information about leaf columns, whether pagination

#'       was attempted after each leaf column, ad the final result of such attempts, if made.}

#'   }

#'

#' @note

#' For `diagnose_pagination`, the column labels are not displayed in the `col_diagnostics` element

#' due to certain internal implementation details; rather the diagnostics are reported in terms of

#' absolute (leaf) column position. This is a known limitation, and may eventually be changed, but the

#' information remains useful as it is currently reported.

#'

#' `diagnose_pagination` is intended for interactive debugging use and *should not be programmed against*,

#' as the exact content and form of the verbose messages it captures and returns is subject to change.

#'

#' Because `diagnose_pagination` relies on `capture.output(type = "message")`, it cannot be used within the

#' `testthat` (and likely other) testing frameworks, and likely cannot be used within `knitr`/`rmarkdown`

#' contexts either, as this clashes with those systems' capture of messages.

#'

#' @examples

#' diagnose_pagination(mpf, pg_width = 5, pg_height = 3)

#' clws <- propose_column_widths(mpf)

#' clws[1] <- floor(clws[1] / 3)

#' dgnost <- diagnose_pagination(mpf, pg_width = 5, pg_height = 3, colwidths = clws)

#' try(diagnose_pagination(mpf, pg_width = 1)) # fails

#'

#' @rdname paginate_indices

#' @export

diagnose_pagination <- function(obj,

                                page_type = "letter",

                                font_family = "Courier",

                                font_size = 8,

                                lineheight = 1,

                                landscape = FALSE,

                                pg_width = NULL,

                                pg_height = NULL,

                                margins = c(top = .5, bottom = .5, left = .75, right = .75),

                                lpp = NA_integer_,

                                cpp = NA_integer_,

                                min_siblings = 2,

                                nosplitin = character(),

                                colwidths = propose_column_widths(matrix_form(obj, TRUE)),

                                tf_wrap = FALSE,

                                max_width = NULL,

                                indent_size = 2,

                                pg_size_spec = NULL,

                                rep_cols = num_rep_cols(obj),

                                col_gap = 2,

                                verbose = FALSE,

                                ...) {

    ))

  }

    {

        )

      )

    },

  )

  }

  }, "")

  )

  }, "")

  )

  )

}

.need_pag <- function(page_type, pg_width, pg_height, cpp, lpp) {

}

#' Export a table-like object to plain (ASCII) text with page breaks

#'

#' This function converts `x` to a `MatrixPrintForm` object via [matrix_form()], paginates it

#' via [paginate_to_mpfs()], converts each page to ASCII text via [toString()], and outputs

#' the strings, separated by `page_break`, to `file`.

#'

#' @inheritParams paginate_indices

#' @inheritParams toString

#' @inheritParams propose_column_widths

#' @param x (`ANY`)\cr a table-like object to export. Must have an applicable `matrix_form` method.

#' @param file (`string` or `NULL`)\cr if non-`NULL`, the path to write a text file to

#'   containing `x` rendered as ASCII text.

#' @param page_break (`string`)\cr page break symbol (defaults to `"\\n\\s"`).

#' @param paginate (`flag`)\cr whether pagination should be performed. Defaults to `TRUE`

#'   if page size is specified (including the default).

#' @param ... additional parameters passed to [paginate_to_mpfs()].

#'

#' @details

#' If `x` has a `num_rep_cols` method, the value returned by it will be used for `rep_cols` by

#' default. Otherwise, 0 will be used.

#'

#' If `x` has an applicable `do_forced_paginate` method, it will be invoked during the

#' pagination process.

#'

#' @return If `file` is `NULL`, the full paginated and concatenated string value is returned,

#'   otherwise the output is written to `file` and no value (invisible `NULL`) is returned.

#'

#' @examples

#' export_as_txt(basic_matrix_form(mtcars), pg_height = 5, pg_width = 4)

#'

#' @export

export_as_txt <- function(x,

                          file = NULL,

                          page_type = NULL,