## #' 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))

## }

#' @name pagination_algo

#' @rdname pagination_algo

#' @title 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`) already  adjusted for rendered  elements which

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

#' pagination is  performed via  the following  algorithm, and  with a

#' `start = 1`:

#'

#' Core Pagination Algorithm:

#' 1. Initial guess for pagination point 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 ever 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`

#'

NULL

#' Create row of pagination data frame

#' @param nm character(1). Name

#' @param lab character(1). Label

#' @param rnum numeric(1). Absolute row number

#' @param pth character or NULL. Path within larger table

#' @param sibpos integer(1). Position among sibling rows

#' @param nsibs integer(1). Number of siblings (including self).

#' @param extent numeric(1). Number of lines required to print the row

#' @param colwidths numeric. Column widths

#' @param repext integer(1). Number of lines required to reprint all context for this row if it appears directly

#'   after pagination.

#' @param repind integer. Vector of row numbers to be reprinted if this row appears directly after pagination.

#' @param indent integer. Indent

#' @param rclass character(1). Class of row object.

#' @param nrowrefs integer(1). Number of row referential footnotes for this row

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

#' @param nreflines integer(1). Total number of lines required by all referential footnotes

#' @param force_page logical(1). Currently Ignored.

#' @param page_title logical(1). Currently Ignored.

#' @param trailing_sep character(1). The string to used as a separator below this row during printing (or

#' `NA_character_` for no separator).

#' @param row ANY. Object representing the row, which is used for default values of \code{nm}, \code{lab},

#' \code{extent} and \code{rclass} if provided. Must have methods for \code{obj_name}, \code{obj_label},

#' and \code{nlines}, respectively, for default values of \code{nm}, \code{lab} and \code{extent} to

#' be retrieved, respectively.

#'

#' @return a single row data.frame with the columns appropriate 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,

                           start, guess, rep_ext, n_reprint,

                           reflines, n_refs, sectlines) {

    } else  { ## !row

   }

}

valid_pag <- function(pagdf,

                      guess,

                      start,

                      rlpp,

                      min_sibs,

                      nosplit = NULL,

                      div_height = 1L,

                      verbose = FALSE,

                      row = TRUE,

                      have_col_fnotes = FALSE) {

    )

  }

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

  ## 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

      }

  }

    }

  }

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

        )

      }

        )

      }

    }

    }

  }

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

      },

        }

      }

    }

  }

  }

}

find_pag <- function(pagdf,

                     start,

                     guess,

                     rlpp,

                     min_siblings,

                     nosplitin = character(),

                     verbose = FALSE,

                     row = TRUE,

                     have_col_fnotes = FALSE,

                     div_height = 1L) {

  )) {

  }

  }

}

#' Find Pagination Indices From Pagination Info Dataframe

#'

#' 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.

#'

#' @details `pab_indices_inner` implements the Core Pagination Algorithm

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

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

#' lines (or characters) per page.

#'

#' @inheritSection pagination_algo Pagination Algorithm

#' @param pagdf data.frame. A pagination info data.frame as created by

#' either `make_rows_df` or `make_cols_df`.

#' @param rlpp numeric. Maximum number of \emph{row} lines per page (not including header materials), including

#'   (re)printed header and context rows

#' @param min_siblings  numeric. Minimum sibling rows which must appear on either side of pagination row for a

#'   mid-subtable split to be valid. Defaults to 2.

#' @param nosplitin character. List of names of sub-tables where page-breaks are not allowed, regardless of other

#'   considerations. Defaults to none.

#' @param verbose logical(1). Should additional informative messages about the search for

#' pagination breaks be shown. Defaults to \code{FALSE}.

#' @param row logical(1). Is pagination happening in row

#' space (`TRUE`, the default) or column space (`FALSE`)

#' @param have_col_fnotes logical(1). Does the table-like object being rendered have

#' column-associated referential footnotes.

#' @param div_height numeric(1). The height of the divider line when the

#' associated object is rendered. Defaults to `1`.

#' @return A list containing the 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,

                              min_siblings,

                              nosplitin = character(),

                              verbose = FALSE,

                              row = TRUE,

                              have_col_fnotes = FALSE,

                              div_height = 1L) {

      } else {

      }

    }

    )

    )))

  }

}

#' Find Column Indices for Vertical Pagination

#' @param  obj   ANY.  object   to   be  paginated.   Must  have   a

#'     \code{\link{matrix_form}} method.

#' @param cpp numeric(1). Number of characters per page (width)

#' @param colwidths numeric vector.  Column widths (in characters) for

#'     use with vertical pagination.

#' @param rep_cols numeric(1). Number of \emph{columns} (not including

#'     row labels) to be repeated on every page. Defaults to 0

#' @inheritParams pag_indices_inner

#'

#' @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)]

      "]"

    )

  }

  )

}

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

    }

        )

    }

    )

}

#' Basic/spoof pagination info dataframe

#'

#' Returns a minimal pagination info data.frame (with no sibling/footnote/etc info).

#' @inheritParams basic_matrix_form

#' @param rnames character. Vector of row names

#' @param labs character. Vector of row labels (defaults to names)

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

#' @param extents integer. Number of lines each row will take to print, defaults to 1 for all rows

#' @param rclass character. Class(es) for the rows. Defaults to "NA"

#'

#' @return A data.frame suitable for use in both the `matrix_print_form` 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 = "NA",

                        parent_path = "root") {

  )

}

## 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

    }

    ## 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) {

}

#' @title Paginate a table-like object for rendering

#'

#' @description

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

#' an object.

#'

#' `paginate_to_mpfs` renders `obj` into the `MatrixPrintForm` (`MPF`)

#' intermediate representation, and then paginates that `MPF` into

#' component `MPF`s each corresponding to an individual page and

#' returns those in a list.

#'

#' `paginate_indices` renders `obj` into an `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

#' \code{obj} itself (see details for an important caveat).

#'

#' `diagnose_pagination` attempts pagination via `paginate_to_mpfs`

#' and then returns diagnostic information which explains why page

#' breaks were positioned where they were, or alternatively why

#' no valid paginations 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 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_pagination` 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_pagination` method.

#'

#' `paginate_indices`, on the other hand, \emph{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 more 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. 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. 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. A pre-calculated page

#'     size specification. Typically this is not set in end user code.

#' @param col_gap numeric(1). Currently unused.

#' @return for `paginate_indices` a list with two elements of the same

#'     length:   `pag_row_indices`,    and   `pag_col_indices`.    For

#'     `paginate_to_mpfs`,   a  list   of  `MatrixPrintForm` objects

#'     representing each individual page after pagination (including

#'     forced pagination if necessary).

#' @export

#' @aliases paginate pagination

#' @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)

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 occured.

    ## this wraps the cell contents AND shoves referential footnote

    ## info into mf_rinfo(mpf)

    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,

                     rep_cols = num_rep_cols(obj),

                     col_gap = 2,

                     verbose = FALSE) {

    else

    }

    ## 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.

    }

    ## 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...

        })

    })

}

#' @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 total.

#'

#' To get information about intermediate attempts, perform pagination

#' with `verbose = TRUE` and inspect the messages in order.

#'

#' @return For `diagnose_pagination` 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.

#'

#' @note `diagnose_pagination` is intended for interactive debugging

#' use and \emph{should not be programmed against}, as the exact

#' content and form of the  verbose messages it captures and

#' returns is subject to change.

#'

#' @note 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.

#'

#' @export

#'

#' @rdname paginate_indices

#' @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

#'

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,

                                ...) {

    }

    }

    }, "")

    }, "")

}

## until we do it for real

#' @title Matrix Print Form - Intermediate Representation for ASCII Table Printing

#'

#' @name MatrixPrintForm-class

#'

#' @rdname MatrixPrintForm_class

#' @aliases MatrixPrintForm-class

#' @exportClass MatrixPrintForm

setOldClass(c("MatrixPrintForm", "list"))

mform_handle_newlines <- function(matform) {

  # Retrieving relevant information

  # nlines detects if there is a newline character

  # There is something to change

    # Header indices

    ## groundwork for sad haxx to get tl to not be messed up

        ## recalc them without topleft cause thats handled separately

    } else {

    }

    ## used below even though we don't store it on the resulting object

      ),

    )

      ),

    )

    ## sad haxx :(

        stop("Expanding top-left material resulted in more lines (", length(newtl), # nocov

             "than fit in the header.") # nocov

      }

    }

##    mf_display(matform) <- expand_mat_rows(mf_display(matform), row_nlines, rep_vec_to_len)

  }

}

disp_from_spans <- function(spans) {

            ##         display <- t(apply(spans, 1, function(row) {

            ## print_cells <- row == 1

                ## need to calculate which cell need to be printed

            }

        }

        )

    }

}

## constructor

#' @title Matrix Print Form - Intermediate Representation for ASCII Table Printing

#'

#' @note The bare constructor for the `MatrixPrintForm` should generally

#' only be called by `matrix_form` custom methods, and almost never from other code.

#'

#' @param  strings character  matrix.  Matrix  of formatted,  ready to

#'     display  strings  organized as  they  will  be positioned  when

#'     rendered.   Elements that  span more  than one  column must  be

#'     followed  by  the  correct number  of  placeholders  (typically

#'     either empty strings or repeats of the value).

#' @param  spans  numeric  matrix.    Matrix  of  same  dimension  as

#'     \code{strings}  giving   the  spanning  information   for  each

#'     element.    Must  be   repeated   to   match  placeholders   in

#'     \code{strings}.

#' @param  aligns character  matrix.   Matrix  of same  dimension  as

#'     \code{strings} giving  the text alignment information  for each

#'     element. Must  be   repeated   to   match  placeholders   in

#'     \code{strings}. Must be a supported text alignment. See

#'     [decimal_align] allowed values.

#' @param formats  matrix. Matrix  of same dimension

#'     as  \code{strings} giving  the text  format information  for

#'     each  element.   Must  be  repeated to  match  placeholders  in

#'     \code{strings}.

#' @param  row_info   data.frame.   Data.frame  with  row-information

#'     necessary for pagination (XXX document exactly what that is).

#' @param  line_grouping integer. Sequence of  integers indicating how

#'     print  lines  correspond  to   semantic  rows  in  the  object.

#'     Typically   this   should   not    be   set   manually   unless

#'     `expact_newlines` is set to \code{FALSE}.

#' @param  ref_fnotes  list.   Referential  footnote  information  if

#'     applicable.

#' @param  nlines_header numeric(1). Number  of lines taken up  by the

#'     values of the header (i.e. not including the divider).

#' @param nrow_header numeric(1).  Number of \emph{rows} corresponding

#'     to the header.

#' @param  has_topleft logical(1).  Does the  corresponding table have

#'     'top left information' which should be treated differently when

#'     expanding  newlines.   Ignored   if  \code{expand_newlines}  is

#'     \code{FALSE}.

#' @param has_rowlabs  logical(1). Do  the matrices  (\code{strings},

#'     \code{spans},  \code{aligns})   each  contain  a   column  that

#'     corresponds  with  row  labels  (Rather than  with  table  cell

#'     values).  Defaults to \code{TRUE}.

#' @param main_title character(1). Main title as a string.

#' @param subtitles character. Subtitles, as a character vector.

#' @param page_titles character.  Page-specific titles, as a character

#'     vector.

#' @param main_footer character(1). Main footer as a string.

#' @param  prov_footer character.  Provenance footer  information as a

#'     character vector.

#' @param expand_newlines logical(1). Should the matrix form generated

#'     expand  rows  whose  values   contain  newlines  into  multiple

#'     'physical'  rows  (as  they  will  appear  when  rendered  into

#'     ASCII). Defaults to \code{TRUE}

#' @param col_gap numeric(1). Space (in characters) between columns

#' @param table_inset numeric(1). Table inset. See

#' \code{\link{table_inset}}

#' @param colwidths numeric. NULL, or a vector of column rendering widths.

#'     if non-NULL, must have length equal to `ncol(strings)`

#' @param indent_size numeric(1). Number of spaces to be used per level of indent (if supported by

#' the relevant method). Defaults to 2.

#' @export

#' @return An object of class `MatrixPrintForm`. Currently this is

#' implemented as an S3 class inheriting from list with the following

#' elements:

#' \describe{

#' \item{\code{strings}}{see argument}

#' \item{\code{spans}}{see argument}

#' \item{\code{aligns}}{see argument}

#' \item{\code{display}}{logical matrix of same dimension as `strings`

#' that specifies whether an element in `strings` will be displayed

#' when the table is rendered}

#' \item{\code{formats}}{see argument}

#' \item{\code{row_info}}{see argument}

#' \item{\code{line_grouping}}{see argument}

#' \item{\code{ref_footnotes}}{see argument}

#' \item{\code{main_title}}{see argument}

#' \item{\code{subtitles}}{see argument}

#' \item{\code{page_titles}}{see argument}

#' \item{\code{main_footer}}{see argument}

#' \item{\code{prov_footer}}{see argument}

#' \item{\code{col_gap}}{see argument}

#' \item{\code{table_inset}}{see argument}

#' }

#'

#' as well as the following attributes:

#' \describe{

#' \item{\code{nlines_header}}{see argument}

#' \item{\code{nrow_header}}{see argument}

#' \item{\code{ncols}}{number of columns \emph{of the table}, not including

#' any row names/row labels}

#' }

MatrixPrintForm <- function(strings = NULL,

                            spans,

                            aligns,

                            formats,

                            row_info,

                            line_grouping = seq_len(NROW(strings)),

                            ref_fnotes = list(),

                            nlines_header,

                            nrow_header,

                            has_topleft = TRUE,

                            has_rowlabs = has_topleft,

                            expand_newlines = TRUE,

                            main_title = "",

                            subtitles = character(),

                            page_titles = character(),

                            main_footer = "",

                            prov_footer = character(),

                            col_gap = 3,

                            table_inset = 0L,

                            colwidths = NULL,

                            indent_size = 2) {

        ),

    )

    ## .do_mat_expand(ret)

    }

    ##  ret <- shove_refdf_into_rowinfo(ret)

}

#'Create a row for a referential footnote information dataframe

#'

#' @inheritParams nlines

#' @param row_path character. row path (`NA_character_` for none)

#' @param col_path character. column path (`NA_character_` for none)

#' @param row integer(1). Integer position of the row.

#' @param col integer(1). Integer position of the column.

#' @param symbol character(1). Symbol for the reference. `NA_character_` to use the `ref_index` automatically.

#' @param ref_index integer(1). The index of the footnote, used for ordering even when symbol is not NA

#' @param msg character(1). The string message, not including the symbol portion (`{symbol} - `)

#'

#' @return a single row data.frame with the appropriate columns.

#'

#' @export

#'

ref_df_row <- function(row_path = NA_character_, col_path = NA_character_, row = NA_integer_, col = NA_integer_, symbol = NA_character_, ref_index = NA_integer_, msg = NA_character_, max_width = NULL) {

}

## this entire thing is a hatchetjob of a hack which should not be necessary.

## mf_rinfo(mform) should have the relevant info in it and

## mf_cinfo(mform) should be non-null (!!!) and have the info in it

## in which case this becomes silly and dumb, but here we are, so here we go.

infer_ref_info <- function(mform, colspace_only) {

    else

    ## they're nested so \\2 is the inner one, without the brackets

    ## handle spanned values

    ## we want to count across rows first, not down columns, cause

    ## thats how footnote numbering works