32 changed files with 2676 additions and 149 deletions
@ -0,0 +1,146 @@ |
|||||||
|
[comment {--- punk::docgen generated from inline doctools comments ---}] |
||||||
|
[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}] |
||||||
|
[comment {--- punk::docgen overwrites this file ---}] |
||||||
|
[manpage_begin punkshell_module_punk::fileline 0 0.1.0] |
||||||
|
[copyright "2024"] |
||||||
|
[titledesc {file line-handling utilities}] [comment {-- Name section and table of contents description --}] |
||||||
|
[moddesc {punk fileline}] [comment {-- Description at end of page heading --}] |
||||||
|
[require punk::fileline] |
||||||
|
[keywords module text parse file] |
||||||
|
[description] |
||||||
|
[para] - |
||||||
|
[section Overview] |
||||||
|
[para]Utilities for in-memory analysis of text file data as both line data and byte/char-counted data whilst preserving the line-endings (even if mixed) |
||||||
|
[para]This is important for certain text files where examining the number of chars/bytes is important |
||||||
|
[para]For example - windows .cmd/.bat files need some byte counting to determine if labels lie on chunk boundaries and need to be moved. |
||||||
|
[para]Despite including the word 'file', the library doesn't deal with reading/writing to the filesystem. It is for operating on text-file like data. |
||||||
|
[subsection Concepts] |
||||||
|
[para]A chunk of textfile data (possibly representing a whole file - but usually at least a complete set of lines) is loaded into a punk::fileline::class::textinfo instance at object creation. |
||||||
|
[example_begin] |
||||||
|
package require punk::fileline |
||||||
|
package require fileutil |
||||||
|
set rawdata [lb]fileutil::cat data.txt -translation binary[rb] |
||||||
|
punk::fileline::class::textinfo create obj_data $rawdata |
||||||
|
puts stdout [lb]obj_data linecount[rb] |
||||||
|
[example_end] |
||||||
|
[subsection Notes] |
||||||
|
[para]Line records are referred to by a zero-based index instead of a one-based index as is commonly used when displaying files. |
||||||
|
[para]This is for programming consistency and convenience, and the module user should do their own conversion to one-based indexing for line display or messaging if desired. |
||||||
|
[para]No support for lone carriage-returns being interpreted as line-endings. |
||||||
|
[para]CR line-endings that are intended to be interpreted as such should be mapped to something else before the data is supplied to this module. |
||||||
|
[subsection dependencies] |
||||||
|
[para] packages used by punk::fileline |
||||||
|
[list_begin itemized] |
||||||
|
[item] [package {Tcl 8.6}] |
||||||
|
[list_end] |
||||||
|
[section API] |
||||||
|
[subsection {Namespace punk::fileline::class}] |
||||||
|
[para] class definitions |
||||||
|
[list_begin enumerated] |
||||||
|
[enum] CLASS [class textinfo] |
||||||
|
[list_begin definitions] |
||||||
|
[para] [emph METHODS] |
||||||
|
[call class::textinfo [method constructor] [arg datachunk] [opt {option value...}]] |
||||||
|
[para] Constructor for textinfo object which represents a chunk or all of a file |
||||||
|
[para] datachunk should be passed with the file data including line-endings as-is for full functionality. ie use something like: |
||||||
|
[example_begin] |
||||||
|
fconfigure $fd -translation binary |
||||||
|
set chunkdata [lb]read $fd[rb]] |
||||||
|
or |
||||||
|
set chunkdata [lb]fileutil::cat <filename> -translation binary[rb] |
||||||
|
[example_end] |
||||||
|
[para] when loading the data |
||||||
|
[call class::textinfo [method chunk] [arg chunkstart] [arg chunkend]] |
||||||
|
[para]Return a range of bytes from the underlying raw chunk data. |
||||||
|
[para] e.g The following retrieves the entire chunk |
||||||
|
[para] objName chunk 0 end |
||||||
|
[call class::textinfo [method chunklen]] |
||||||
|
[para] Number of bytes/characters in the raw data of the file |
||||||
|
[call class::textinfo [method linecount]] |
||||||
|
[para] Number of lines in the raw data of the file, counted as per the policy in effect |
||||||
|
[call class::textinfo [method regenerate_lines]] |
||||||
|
[para]generate a list of lines from the stored raw data chunk and keep a map of line-endings indexed by lineindex |
||||||
|
[call class::textinfo [method line] [arg lineindex]] |
||||||
|
[para]Reconstructs and returns the raw line using the payload and per-line stored line-ending metadata |
||||||
|
[para]A 'line' may be returned without a line-ending if the unerlying chunk had trailing data without a line-ending (or the chunk was loaded under a non-standard -policy setting) |
||||||
|
[para]Whilst such data may not conform to definitions (e.g POSIX) of the terms 'textfile' and 'line' - it is useful here to represent it as a line with metadata le set to "none" |
||||||
|
[para]To return just the data which might more commonly be needed for dealing with lines, use the [method linepayload] method - which returns the line data minus line-ending |
||||||
|
[call class::textinfo [method linepayload] [arg lineindex]] |
||||||
|
[para]Return the text of the line indicated by the zero-based lineindex |
||||||
|
[para]The line-ending is not returned in the data - but is still stored against this lineindex |
||||||
|
[para]Line Metadata such as the line-ending for a particular line and the byte/character range it occupies within the chunk can be retrieved with the [method linemeta] method |
||||||
|
[para]To retrieve both the line text and metadata in a single call the [method lineinfo] method can be used |
||||||
|
[para]To retrieve an entire line including line-ending use the [method line] method. |
||||||
|
[call class::textinfo [method linemeta] [arg lineindex]] |
||||||
|
[para]Return a dict of the metadata for the line indicated by the zero-based lineindex |
||||||
|
[para]Keys returned include |
||||||
|
[list_begin itemized] |
||||||
|
[item] le |
||||||
|
[para] A string representing the type of line-ending: crlf|lf|none |
||||||
|
[item] linelen |
||||||
|
[para] The number of characters/bytes in the whole line including line-ending if any |
||||||
|
[item] payloadlen |
||||||
|
[para] The number of character/bytes in the line excluding line-ending |
||||||
|
[item] start |
||||||
|
[para] The zero-based index into the associated raw file data indicating at which byte/character index this line begins |
||||||
|
[item] end |
||||||
|
[para] The zero-based index into the associated raw file data indicating at which byte/character index this line ends |
||||||
|
[para] This end-point corresponds to the last character of the line-ending if any - not necessarily the last character of the line's payload |
||||||
|
[list_end] |
||||||
|
[call class::textinfo [method lineinfo] [arg lineindex]] |
||||||
|
[para]Return a dict of the metadata and text for the line indicated by the zero-based lineindex |
||||||
|
[para]This returns the same info as the [method linemeta] with an added key of 'payload' which is the text of the line without line-ending. |
||||||
|
[para]The 'payload' value is the same as is returned from the [method linepayload] method. |
||||||
|
[call class::textinfo [method linerange_to_chunkrange] [arg startidx] [arg endidx]] |
||||||
|
[call class::textinfo [method linerange_to_chunk] [arg startidx] [arg endidx]] |
||||||
|
[call class::textinfo [method lines] [arg startidx] [arg endidx]] |
||||||
|
[call class::textinfo [method linepayloads] [arg startidx] [arg endidx]] |
||||||
|
[call class::textinfo [method chunkrange_to_linerange] [arg chunkstart] [arg chunkend]] |
||||||
|
[call class::textinfo [method chunkrange_to_lineinfolist] [arg chunkstart] [arg chunkend] [opt {option value...}]] |
||||||
|
[para]Return a list of dicts each with structure like the result of the [method lineinfo] method - but possibly with extra keys for truncation information if -show_truncated 1 is supplied |
||||||
|
[para]The truncation key in a lineinfo dict may be returned for first and/or last line in the resulting list. |
||||||
|
[para]truncation shows the shortened (missing bytes on left and/or right side) part of the entire line (potentially including line-ending or even partial line-ending) |
||||||
|
[para]Note that this truncation info is only in the return value of this method - and will not be reflected in [method lineinfo] queries to the main chunk. |
||||||
|
[call class::textinfo [method numeric_linerange] [arg startidx] [arg endidx]] |
||||||
|
[para]A helper to return any Tcl-style end end-x values given to startidx or endidx; converted to their specific values based on the current state of the underlying line data |
||||||
|
[para]This is used internally by API functions such as [method line] to enable it to accept more expressive indices |
||||||
|
[call class::textinfo [method numeric_chunkrange] [arg startidx] [arg endidx]] |
||||||
|
[para]A helper to return any Tcl-style end end-x entries supplied to startidx or endidx; converted to their specific values based on the current state of the underlying chunk data |
||||||
|
[call class::textinfo [method normalize_indices] [arg startidx] [arg endidx] [arg max]] |
||||||
|
[para]A utility to convert some of the of Tcl-style list-index expressions such as end, end-1 etc to valid indices in the range 0 to the supplied max |
||||||
|
[para]Basic addition and subtraction expressions such as 4-1 5+2 are accepted |
||||||
|
[para]startidx higher than endidx is allowed |
||||||
|
[para]Unlike Tcl's index expressions - we raise an error if the calculated index is out of bounds 0 to max |
||||||
|
[list_end] |
||||||
|
[list_end] [comment {--- end class enumeration ---}] |
||||||
|
[subsection {Namespace punk::fileline}] |
||||||
|
[para] Core API functions for punk::fileline |
||||||
|
[list_begin definitions] |
||||||
|
[list_end] [comment {--- end definitions namespace punk::fileline ---}] |
||||||
|
[subsection {Namespace punk::fileline::lib}] |
||||||
|
[para] Secondary functions that are part of the API |
||||||
|
[list_begin definitions] |
||||||
|
[call [fun lib::range_spans_chunk_boundaries] [arg start] [arg end] [arg chunksize]] |
||||||
|
[para]Takes start and end offset, generally representing bytes or character indices, and computes a list of boundaries at multiples of the chunksize that are spanned by the start and end range. |
||||||
|
[list_begin arguments] |
||||||
|
[arg_def integer start] |
||||||
|
[para] zero-based start index of range |
||||||
|
[arg_def integer end] |
||||||
|
[para] zero-based end index of range |
||||||
|
[arg_def integer chunksize] |
||||||
|
[para] Number of bytes/characters in chunk |
||||||
|
[list_end] |
||||||
|
[para]returns a dict with the keys is_span and boundaries |
||||||
|
[para]is_span 0|1 indicates if the range specified spans a boundary of chunksize |
||||||
|
[para]boundaries contains a list of the spanned boundaries - which are always multiples of the chunksize |
||||||
|
[para]e.g |
||||||
|
[example_begin] |
||||||
|
range_spans_chunk_boundaries 10 1750 512 |
||||||
|
is_span 1 boundaries {512 1024 1536} |
||||||
|
[example_end] |
||||||
|
[para] This function automatically uses lseq (if Tcl >= 8.7) when number of boundaries spanned is approximately greater than 75 |
||||||
|
[list_end] [comment {--- end definitions namespace punk::fileline::lib ---}] |
||||||
|
[section Internal] |
||||||
|
[subsection {Namespace punk::fileline::system}] |
||||||
|
[para] Internal functions that are not part of the API |
||||||
|
[manpage_end] |
||||||
@ -0,0 +1,559 @@ |
|||||||
|
'\" |
||||||
|
'\" Generated from file '_module_fileline-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' |
||||||
|
'\" Copyright (c) 2024 |
||||||
|
'\" |
||||||
|
.TH "punkshell_module_punk::fileline" 0 0\&.1\&.0 doc "punk fileline" |
||||||
|
.\" The -*- nroff -*- definitions below are for supplemental macros used |
||||||
|
.\" in Tcl/Tk manual entries. |
||||||
|
.\" |
||||||
|
.\" .AP type name in/out ?indent? |
||||||
|
.\" Start paragraph describing an argument to a library procedure. |
||||||
|
.\" type is type of argument (int, etc.), in/out is either "in", "out", |
||||||
|
.\" or "in/out" to describe whether procedure reads or modifies arg, |
||||||
|
.\" and indent is equivalent to second arg of .IP (shouldn't ever be |
||||||
|
.\" needed; use .AS below instead) |
||||||
|
.\" |
||||||
|
.\" .AS ?type? ?name? |
||||||
|
.\" Give maximum sizes of arguments for setting tab stops. Type and |
||||||
|
.\" name are examples of largest possible arguments that will be passed |
||||||
|
.\" to .AP later. If args are omitted, default tab stops are used. |
||||||
|
.\" |
||||||
|
.\" .BS |
||||||
|
.\" Start box enclosure. From here until next .BE, everything will be |
||||||
|
.\" enclosed in one large box. |
||||||
|
.\" |
||||||
|
.\" .BE |
||||||
|
.\" End of box enclosure. |
||||||
|
.\" |
||||||
|
.\" .CS |
||||||
|
.\" Begin code excerpt. |
||||||
|
.\" |
||||||
|
.\" .CE |
||||||
|
.\" End code excerpt. |
||||||
|
.\" |
||||||
|
.\" .VS ?version? ?br? |
||||||
|
.\" Begin vertical sidebar, for use in marking newly-changed parts |
||||||
|
.\" of man pages. The first argument is ignored and used for recording |
||||||
|
.\" the version when the .VS was added, so that the sidebars can be |
||||||
|
.\" found and removed when they reach a certain age. If another argument |
||||||
|
.\" is present, then a line break is forced before starting the sidebar. |
||||||
|
.\" |
||||||
|
.\" .VE |
||||||
|
.\" End of vertical sidebar. |
||||||
|
.\" |
||||||
|
.\" .DS |
||||||
|
.\" Begin an indented unfilled display. |
||||||
|
.\" |
||||||
|
.\" .DE |
||||||
|
.\" End of indented unfilled display. |
||||||
|
.\" |
||||||
|
.\" .SO ?manpage? |
||||||
|
.\" Start of list of standard options for a Tk widget. The manpage |
||||||
|
.\" argument defines where to look up the standard options; if |
||||||
|
.\" omitted, defaults to "options". The options follow on successive |
||||||
|
.\" lines, in three columns separated by tabs. |
||||||
|
.\" |
||||||
|
.\" .SE |
||||||
|
.\" End of list of standard options for a Tk widget. |
||||||
|
.\" |
||||||
|
.\" .OP cmdName dbName dbClass |
||||||
|
.\" Start of description of a specific option. cmdName gives the |
||||||
|
.\" option's name as specified in the class command, dbName gives |
||||||
|
.\" the option's name in the option database, and dbClass gives |
||||||
|
.\" the option's class in the option database. |
||||||
|
.\" |
||||||
|
.\" .UL arg1 arg2 |
||||||
|
.\" Print arg1 underlined, then print arg2 normally. |
||||||
|
.\" |
||||||
|
.\" .QW arg1 ?arg2? |
||||||
|
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). |
||||||
|
.\" |
||||||
|
.\" .PQ arg1 ?arg2? |
||||||
|
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally |
||||||
|
.\" (for trailing punctuation) and then a closing parenthesis. |
||||||
|
.\" |
||||||
|
.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
||||||
|
.if t .wh -1.3i ^B |
||||||
|
.nr ^l \n(.l |
||||||
|
.ad b |
||||||
|
.\" # Start an argument description |
||||||
|
.de AP |
||||||
|
.ie !"\\$4"" .TP \\$4 |
||||||
|
.el \{\ |
||||||
|
. ie !"\\$2"" .TP \\n()Cu |
||||||
|
. el .TP 15 |
||||||
|
.\} |
||||||
|
.ta \\n()Au \\n()Bu |
||||||
|
.ie !"\\$3"" \{\ |
||||||
|
\&\\$1 \\fI\\$2\\fP (\\$3) |
||||||
|
.\".b |
||||||
|
.\} |
||||||
|
.el \{\ |
||||||
|
.br |
||||||
|
.ie !"\\$2"" \{\ |
||||||
|
\&\\$1 \\fI\\$2\\fP |
||||||
|
.\} |
||||||
|
.el \{\ |
||||||
|
\&\\fI\\$1\\fP |
||||||
|
.\} |
||||||
|
.\} |
||||||
|
.. |
||||||
|
.\" # define tabbing values for .AP |
||||||
|
.de AS |
||||||
|
.nr )A 10n |
||||||
|
.if !"\\$1"" .nr )A \\w'\\$1'u+3n |
||||||
|
.nr )B \\n()Au+15n |
||||||
|
.\" |
||||||
|
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
||||||
|
.nr )C \\n()Bu+\\w'(in/out)'u+2n |
||||||
|
.. |
||||||
|
.AS Tcl_Interp Tcl_CreateInterp in/out |
||||||
|
.\" # BS - start boxed text |
||||||
|
.\" # ^y = starting y location |
||||||
|
.\" # ^b = 1 |
||||||
|
.de BS |
||||||
|
.br |
||||||
|
.mk ^y |
||||||
|
.nr ^b 1u |
||||||
|
.if n .nf |
||||||
|
.if n .ti 0 |
||||||
|
.if n \l'\\n(.lu\(ul' |
||||||
|
.if n .fi |
||||||
|
.. |
||||||
|
.\" # BE - end boxed text (draw box now) |
||||||
|
.de BE |
||||||
|
.nf |
||||||
|
.ti 0 |
||||||
|
.mk ^t |
||||||
|
.ie n \l'\\n(^lu\(ul' |
||||||
|
.el \{\ |
||||||
|
.\" Draw four-sided box normally, but don't draw top of |
||||||
|
.\" box if the box started on an earlier page. |
||||||
|
.ie !\\n(^b-1 \{\ |
||||||
|
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
||||||
|
.\} |
||||||
|
.el \}\ |
||||||
|
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
||||||
|
.\} |
||||||
|
.\} |
||||||
|
.fi |
||||||
|
.br |
||||||
|
.nr ^b 0 |
||||||
|
.. |
||||||
|
.\" # VS - start vertical sidebar |
||||||
|
.\" # ^Y = starting y location |
||||||
|
.\" # ^v = 1 (for troff; for nroff this doesn't matter) |
||||||
|
.de VS |
||||||
|
.if !"\\$2"" .br |
||||||
|
.mk ^Y |
||||||
|
.ie n 'mc \s12\(br\s0 |
||||||
|
.el .nr ^v 1u |
||||||
|
.. |
||||||
|
.\" # VE - end of vertical sidebar |
||||||
|
.de VE |
||||||
|
.ie n 'mc |
||||||
|
.el \{\ |
||||||
|
.ev 2 |
||||||
|
.nf |
||||||
|
.ti 0 |
||||||
|
.mk ^t |
||||||
|
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
||||||
|
.sp -1 |
||||||
|
.fi |
||||||
|
.ev |
||||||
|
.\} |
||||||
|
.nr ^v 0 |
||||||
|
.. |
||||||
|
.\" # Special macro to handle page bottom: finish off current |
||||||
|
.\" # box/sidebar if in box/sidebar mode, then invoked standard |
||||||
|
.\" # page bottom macro. |
||||||
|
.de ^B |
||||||
|
.ev 2 |
||||||
|
'ti 0 |
||||||
|
'nf |
||||||
|
.mk ^t |
||||||
|
.if \\n(^b \{\ |
||||||
|
.\" Draw three-sided box if this is the box's first page, |
||||||
|
.\" draw two sides but no top otherwise. |
||||||
|
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
||||||
|
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
||||||
|
.\} |
||||||
|
.if \\n(^v \{\ |
||||||
|
.nr ^x \\n(^tu+1v-\\n(^Yu |
||||||
|
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
||||||
|
.\} |
||||||
|
.bp |
||||||
|
'fi |
||||||
|
.ev |
||||||
|
.if \\n(^b \{\ |
||||||
|
.mk ^y |
||||||
|
.nr ^b 2 |
||||||
|
.\} |
||||||
|
.if \\n(^v \{\ |
||||||
|
.mk ^Y |
||||||
|
.\} |
||||||
|
.. |
||||||
|
.\" # DS - begin display |
||||||
|
.de DS |
||||||
|
.RS |
||||||
|
.nf |
||||||
|
.sp |
||||||
|
.. |
||||||
|
.\" # DE - end display |
||||||
|
.de DE |
||||||
|
.fi |
||||||
|
.RE |
||||||
|
.sp |
||||||
|
.. |
||||||
|
.\" # SO - start of list of standard options |
||||||
|
.de SO |
||||||
|
'ie '\\$1'' .ds So \\fBoptions\\fR |
||||||
|
'el .ds So \\fB\\$1\\fR |
||||||
|
.SH "STANDARD OPTIONS" |
||||||
|
.LP |
||||||
|
.nf |
||||||
|
.ta 5.5c 11c |
||||||
|
.ft B |
||||||
|
.. |
||||||
|
.\" # SE - end of list of standard options |
||||||
|
.de SE |
||||||
|
.fi |
||||||
|
.ft R |
||||||
|
.LP |
||||||
|
See the \\*(So manual entry for details on the standard options. |
||||||
|
.. |
||||||
|
.\" # OP - start of full description for a single option |
||||||
|
.de OP |
||||||
|
.LP |
||||||
|
.nf |
||||||
|
.ta 4c |
||||||
|
Command-Line Name: \\fB\\$1\\fR |
||||||
|
Database Name: \\fB\\$2\\fR |
||||||
|
Database Class: \\fB\\$3\\fR |
||||||
|
.fi |
||||||
|
.IP |
||||||
|
.. |
||||||
|
.\" # CS - begin code excerpt |
||||||
|
.de CS |
||||||
|
.RS |
||||||
|
.nf |
||||||
|
.ta .25i .5i .75i 1i |
||||||
|
.. |
||||||
|
.\" # CE - end code excerpt |
||||||
|
.de CE |
||||||
|
.fi |
||||||
|
.RE |
||||||
|
.. |
||||||
|
.\" # UL - underline word |
||||||
|
.de UL |
||||||
|
\\$1\l'|0\(ul'\\$2 |
||||||
|
.. |
||||||
|
.\" # QW - apply quotation marks to word |
||||||
|
.de QW |
||||||
|
.ie '\\*(lq'"' ``\\$1''\\$2 |
||||||
|
.\"" fix emacs highlighting |
||||||
|
.el \\*(lq\\$1\\*(rq\\$2 |
||||||
|
.. |
||||||
|
.\" # PQ - apply parens and quotation marks to word |
||||||
|
.de PQ |
||||||
|
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 |
||||||
|
.\"" fix emacs highlighting |
||||||
|
.el (\\*(lq\\$1\\*(rq\\$2)\\$3 |
||||||
|
.. |
||||||
|
.\" # QR - quoted range |
||||||
|
.de QR |
||||||
|
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 |
||||||
|
.\"" fix emacs highlighting |
||||||
|
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 |
||||||
|
.. |
||||||
|
.\" # MT - "empty" string |
||||||
|
.de MT |
||||||
|
.QW "" |
||||||
|
.. |
||||||
|
.BS |
||||||
|
.SH NAME |
||||||
|
punkshell_module_punk::fileline \- file line-handling utilities |
||||||
|
.SH SYNOPSIS |
||||||
|
package require \fBpunk::fileline \fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBconstructor\fR \fIdatachunk\fR ?option value\&.\&.\&.? |
||||||
|
.sp |
||||||
|
class::textinfo \fBchunk\fR \fIchunkstart\fR \fIchunkend\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBchunklen\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBlinecount\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBregenerate_lines\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBline\fR \fIlineindex\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBlinepayload\fR \fIlineindex\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBlinemeta\fR \fIlineindex\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBlineinfo\fR \fIlineindex\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBlinerange_to_chunkrange\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBlinerange_to_chunk\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBlines\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBlinepayloads\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBchunkrange_to_linerange\fR \fIchunkstart\fR \fIchunkend\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBchunkrange_to_lineinfolist\fR \fIchunkstart\fR \fIchunkend\fR ?option value\&.\&.\&.? |
||||||
|
.sp |
||||||
|
class::textinfo \fBnumeric_linerange\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBnumeric_chunkrange\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.sp |
||||||
|
class::textinfo \fBnormalize_indices\fR \fIstartidx\fR \fIendidx\fR \fImax\fR |
||||||
|
.sp |
||||||
|
\fBlib::range_spans_chunk_boundaries\fR \fIstart\fR \fIend\fR \fIchunksize\fR |
||||||
|
.sp |
||||||
|
.BE |
||||||
|
.SH DESCRIPTION |
||||||
|
.PP |
||||||
|
- |
||||||
|
.SH OVERVIEW |
||||||
|
.PP |
||||||
|
Utilities for in-memory analysis of text file data as both line data and byte/char-counted data whilst preserving the line-endings (even if mixed) |
||||||
|
.PP |
||||||
|
This is important for certain text files where examining the number of chars/bytes is important |
||||||
|
.PP |
||||||
|
For example - windows \&.cmd/\&.bat files need some byte counting to determine if labels lie on chunk boundaries and need to be moved\&. |
||||||
|
.PP |
||||||
|
Despite including the word 'file', the library doesn't deal with reading/writing to the filesystem\&. It is for operating on text-file like data\&. |
||||||
|
.SS CONCEPTS |
||||||
|
.PP |
||||||
|
A chunk of textfile data (possibly representing a whole file - but usually at least a complete set of lines) is loaded into a punk::fileline::class::textinfo instance at object creation\&. |
||||||
|
.CS |
||||||
|
|
||||||
|
|
||||||
|
package require punk::fileline |
||||||
|
package require fileutil |
||||||
|
set rawdata [fileutil::cat data\&.txt -translation binary] |
||||||
|
punk::fileline::class::textinfo create obj_data $rawdata |
||||||
|
puts stdout [obj_data linecount] |
||||||
|
|
||||||
|
.CE |
||||||
|
.SS NOTES |
||||||
|
.PP |
||||||
|
Line records are referred to by a zero-based index instead of a one-based index as is commonly used when displaying files\&. |
||||||
|
.PP |
||||||
|
This is for programming consistency and convenience, and the module user should do their own conversion to one-based indexing for line display or messaging if desired\&. |
||||||
|
.PP |
||||||
|
No support for lone carriage-returns being interpreted as line-endings\&. |
||||||
|
.PP |
||||||
|
CR line-endings that are intended to be interpreted as such should be mapped to something else before the data is supplied to this module\&. |
||||||
|
.SS DEPENDENCIES |
||||||
|
.PP |
||||||
|
packages used by punk::fileline |
||||||
|
.IP \(bu |
||||||
|
\fBTcl 8\&.6\fR |
||||||
|
.PP |
||||||
|
.SH API |
||||||
|
.SS "NAMESPACE PUNK::FILELINE::CLASS" |
||||||
|
.PP |
||||||
|
class definitions |
||||||
|
.IP [1] |
||||||
|
CLASS \fBtextinfo\fR |
||||||
|
.RS |
||||||
|
.sp |
||||||
|
\fIMETHODS\fR |
||||||
|
.TP |
||||||
|
class::textinfo \fBconstructor\fR \fIdatachunk\fR ?option value\&.\&.\&.? |
||||||
|
.sp |
||||||
|
Constructor for textinfo object which represents a chunk or all of a file |
||||||
|
.sp |
||||||
|
datachunk should be passed with the file data including line-endings as-is for full functionality\&. ie use something like: |
||||||
|
.CS |
||||||
|
|
||||||
|
|
||||||
|
fconfigure $fd -translation binary |
||||||
|
set chunkdata [read $fd]] |
||||||
|
or |
||||||
|
set chunkdata [fileutil::cat <filename> -translation binary] |
||||||
|
|
||||||
|
.CE |
||||||
|
.sp |
||||||
|
when loading the data |
||||||
|
.TP |
||||||
|
class::textinfo \fBchunk\fR \fIchunkstart\fR \fIchunkend\fR |
||||||
|
.sp |
||||||
|
Return a range of bytes from the underlying raw chunk data\&. |
||||||
|
.sp |
||||||
|
e\&.g The following retrieves the entire chunk |
||||||
|
.sp |
||||||
|
objName chunk 0 end |
||||||
|
.TP |
||||||
|
class::textinfo \fBchunklen\fR |
||||||
|
.sp |
||||||
|
Number of bytes/characters in the raw data of the file |
||||||
|
.TP |
||||||
|
class::textinfo \fBlinecount\fR |
||||||
|
.sp |
||||||
|
Number of lines in the raw data of the file, counted as per the policy in effect |
||||||
|
.TP |
||||||
|
class::textinfo \fBregenerate_lines\fR |
||||||
|
.sp |
||||||
|
generate a list of lines from the stored raw data chunk and keep a map of line-endings indexed by lineindex |
||||||
|
.TP |
||||||
|
class::textinfo \fBline\fR \fIlineindex\fR |
||||||
|
.sp |
||||||
|
Reconstructs and returns the raw line using the payload and per-line stored line-ending metadata |
||||||
|
.sp |
||||||
|
A 'line' may be returned without a line-ending if the unerlying chunk had trailing data without a line-ending (or the chunk was loaded under a non-standard -policy setting) |
||||||
|
.sp |
||||||
|
Whilst such data may not conform to definitions (e\&.g POSIX) of the terms 'textfile' and 'line' - it is useful here to represent it as a line with metadata le set to "none" |
||||||
|
.sp |
||||||
|
To return just the data which might more commonly be needed for dealing with lines, use the \fBlinepayload\fR method - which returns the line data minus line-ending |
||||||
|
.TP |
||||||
|
class::textinfo \fBlinepayload\fR \fIlineindex\fR |
||||||
|
.sp |
||||||
|
Return the text of the line indicated by the zero-based lineindex |
||||||
|
.sp |
||||||
|
The line-ending is not returned in the data - but is still stored against this lineindex |
||||||
|
.sp |
||||||
|
Line Metadata such as the line-ending for a particular line and the byte/character range it occupies within the chunk can be retrieved with the \fBlinemeta\fR method |
||||||
|
.sp |
||||||
|
To retrieve both the line text and metadata in a single call the \fBlineinfo\fR method can be used |
||||||
|
.sp |
||||||
|
To retrieve an entire line including line-ending use the \fBline\fR method\&. |
||||||
|
.TP |
||||||
|
class::textinfo \fBlinemeta\fR \fIlineindex\fR |
||||||
|
.sp |
||||||
|
Return a dict of the metadata for the line indicated by the zero-based lineindex |
||||||
|
.sp |
||||||
|
Keys returned include |
||||||
|
.RS |
||||||
|
.IP \(bu |
||||||
|
le |
||||||
|
.sp |
||||||
|
A string representing the type of line-ending: crlf|lf|none |
||||||
|
.IP \(bu |
||||||
|
linelen |
||||||
|
.sp |
||||||
|
The number of characters/bytes in the whole line including line-ending if any |
||||||
|
.IP \(bu |
||||||
|
payloadlen |
||||||
|
.sp |
||||||
|
The number of character/bytes in the line excluding line-ending |
||||||
|
.IP \(bu |
||||||
|
start |
||||||
|
.sp |
||||||
|
The zero-based index into the associated raw file data indicating at which byte/character index this line begins |
||||||
|
.IP \(bu |
||||||
|
end |
||||||
|
.sp |
||||||
|
The zero-based index into the associated raw file data indicating at which byte/character index this line ends |
||||||
|
.sp |
||||||
|
This end-point corresponds to the last character of the line-ending if any - not necessarily the last character of the line's payload |
||||||
|
.RE |
||||||
|
.TP |
||||||
|
class::textinfo \fBlineinfo\fR \fIlineindex\fR |
||||||
|
.sp |
||||||
|
Return a dict of the metadata and text for the line indicated by the zero-based lineindex |
||||||
|
.sp |
||||||
|
This returns the same info as the \fBlinemeta\fR with an added key of 'payload' which is the text of the line without line-ending\&. |
||||||
|
.sp |
||||||
|
The 'payload' value is the same as is returned from the \fBlinepayload\fR method\&. |
||||||
|
.TP |
||||||
|
class::textinfo \fBlinerange_to_chunkrange\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.TP |
||||||
|
class::textinfo \fBlinerange_to_chunk\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.TP |
||||||
|
class::textinfo \fBlines\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.TP |
||||||
|
class::textinfo \fBlinepayloads\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.TP |
||||||
|
class::textinfo \fBchunkrange_to_linerange\fR \fIchunkstart\fR \fIchunkend\fR |
||||||
|
.TP |
||||||
|
class::textinfo \fBchunkrange_to_lineinfolist\fR \fIchunkstart\fR \fIchunkend\fR ?option value\&.\&.\&.? |
||||||
|
.sp |
||||||
|
Return a list of dicts each with structure like the result of the \fBlineinfo\fR method - but possibly with extra keys for truncation information if -show_truncated 1 is supplied |
||||||
|
.sp |
||||||
|
The truncation key in a lineinfo dict may be returned for first and/or last line in the resulting list\&. |
||||||
|
.sp |
||||||
|
truncation shows the shortened (missing bytes on left and/or right side) part of the entire line (potentially including line-ending or even partial line-ending) |
||||||
|
.sp |
||||||
|
Note that this truncation info is only in the return value of this method - and will not be reflected in \fBlineinfo\fR queries to the main chunk\&. |
||||||
|
.TP |
||||||
|
class::textinfo \fBnumeric_linerange\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.sp |
||||||
|
A helper to return any Tcl-style end end-x values given to startidx or endidx; converted to their specific values based on the current state of the underlying line data |
||||||
|
.sp |
||||||
|
This is used internally by API functions such as \fBline\fR to enable it to accept more expressive indices |
||||||
|
.TP |
||||||
|
class::textinfo \fBnumeric_chunkrange\fR \fIstartidx\fR \fIendidx\fR |
||||||
|
.sp |
||||||
|
A helper to return any Tcl-style end end-x entries supplied to startidx or endidx; converted to their specific values based on the current state of the underlying chunk data |
||||||
|
.TP |
||||||
|
class::textinfo \fBnormalize_indices\fR \fIstartidx\fR \fIendidx\fR \fImax\fR |
||||||
|
.sp |
||||||
|
A utility to convert some of the of Tcl-style list-index expressions such as end, end-1 etc to valid indices in the range 0 to the supplied max |
||||||
|
.sp |
||||||
|
Basic addition and subtraction expressions such as 4-1 5+2 are accepted |
||||||
|
.sp |
||||||
|
startidx higher than endidx is allowed |
||||||
|
.sp |
||||||
|
Unlike Tcl's index expressions - we raise an error if the calculated index is out of bounds 0 to max |
||||||
|
.RE |
||||||
|
.PP |
||||||
|
.SS "NAMESPACE PUNK::FILELINE" |
||||||
|
.PP |
||||||
|
Core API functions for punk::fileline |
||||||
|
.PP |
||||||
|
.SS "NAMESPACE PUNK::FILELINE::LIB" |
||||||
|
.PP |
||||||
|
Secondary functions that are part of the API |
||||||
|
.TP |
||||||
|
\fBlib::range_spans_chunk_boundaries\fR \fIstart\fR \fIend\fR \fIchunksize\fR |
||||||
|
.sp |
||||||
|
Takes start and end offset, generally representing bytes or character indices, and computes a list of boundaries at multiples of the chunksize that are spanned by the start and end range\&. |
||||||
|
.RS |
||||||
|
.TP |
||||||
|
integer \fIstart\fR |
||||||
|
.sp |
||||||
|
zero-based start index of range |
||||||
|
.TP |
||||||
|
integer \fIend\fR |
||||||
|
.sp |
||||||
|
zero-based end index of range |
||||||
|
.TP |
||||||
|
integer \fIchunksize\fR |
||||||
|
.sp |
||||||
|
Number of bytes/characters in chunk |
||||||
|
.RE |
||||||
|
.sp |
||||||
|
returns a dict with the keys is_span and boundaries |
||||||
|
.sp |
||||||
|
is_span 0|1 indicates if the range specified spans a boundary of chunksize |
||||||
|
.sp |
||||||
|
boundaries contains a list of the spanned boundaries - which are always multiples of the chunksize |
||||||
|
.sp |
||||||
|
e\&.g |
||||||
|
.CS |
||||||
|
|
||||||
|
|
||||||
|
range_spans_chunk_boundaries 10 1750 512 |
||||||
|
is_span 1 boundaries {512 1024 1536} |
||||||
|
|
||||||
|
.CE |
||||||
|
.sp |
||||||
|
This function automatically uses lseq (if Tcl >= 8\&.7) when number of boundaries spanned is approximately greater than 75 |
||||||
|
.PP |
||||||
|
.SH INTERNAL |
||||||
|
.SS "NAMESPACE PUNK::FILELINE::SYSTEM" |
||||||
|
.PP |
||||||
|
Internal functions that are not part of the API |
||||||
|
.SH KEYWORDS |
||||||
|
file, module, parse, text |
||||||
|
.SH COPYRIGHT |
||||||
|
.nf |
||||||
|
Copyright (c) 2024 |
||||||
|
|
||||||
|
.fi |
||||||
@ -1 +1 @@ |
|||||||
{shell {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} changelog {{doc/files/project_changes.md punkshell__project_changes}} filesystem {{doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} path {{doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} capability {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap}} module {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} {doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} punk {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} plugin {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap}} repl {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}}} {{changelog doc/files/project_changes.md punkshell__project_changes} . {shell doc/files/project_changes.md punkshell__project_changes} . {shell doc/files/main.md punkshell} . {repl doc/files/project_intro.md punkshell__project_intro} . {module doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {plugin doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {filesystem doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {path doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {module doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {shell doc/files/project_intro.md punkshell__project_intro} . {punk doc/files/project_changes.md punkshell__project_changes} . {punk doc/files/main.md punkshell} . {repl doc/files/project_changes.md punkshell__project_changes} . {punk doc/files/project_intro.md punkshell__project_intro} . {repl doc/files/main.md punkshell} . {capability doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} .} 9 {shell shell changelog changelog filesystem filesystem path path capability capability module module punk punk plugin plugin repl repl} |
{file {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline}} repl {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} text {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline}} shell {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} changelog {{doc/files/project_changes.md punkshell__project_changes}} capability {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap}} parse {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline}} filesystem {{doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} path {{doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} module {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} {doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} {doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path}} punk {{doc/files/project_intro.md punkshell__project_intro} {doc/files/project_changes.md punkshell__project_changes} {doc/files/main.md punkshell}} plugin {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap}}} {{shell doc/files/project_changes.md punkshell__project_changes} . {changelog doc/files/project_changes.md punkshell__project_changes} . {shell doc/files/main.md punkshell} . {text doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {repl doc/files/project_intro.md punkshell__project_intro} . {module doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {plugin doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} . {filesystem doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {path doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {module doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path} . {punk doc/files/project_changes.md punkshell__project_changes} . {shell doc/files/project_intro.md punkshell__project_intro} . {parse doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {punk doc/files/main.md punkshell} . {module doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {repl doc/files/project_changes.md punkshell__project_changes} . {punk doc/files/project_intro.md punkshell__project_intro} . {file doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline} . {repl doc/files/main.md punkshell} . {capability doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap} .} 12 {file file repl repl text text shell shell changelog changelog capability capability parse parse filesystem filesystem path path module module punk punk plugin plugin} |
||||||
@ -1 +1 @@ |
|||||||
doc {doc/toc {{doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap {capability provider and handler plugin system}} {doc/files/project_intro.md punkshell__project_intro {Introduction to punkshell}} {doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path {Filesystem path utilities}} {doc/files/project_changes.md punkshell__project_changes {punkshell Changes}} {doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md punkshell_module_punk::mix::commandset::project {pmix commandset - project}} {doc/files/main.md punkshell {punkshell - Core}}}} |
doc {doc/toc {{doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::fileline {file line-handling utilities}} {doc/files/punk/_module_cap-0.1.0.tm.md punkshell_module_punk::cap {capability provider and handler plugin system}} {doc/files/project_intro.md punkshell__project_intro {Introduction to punkshell}} {doc/files/punk/_module_path-0.1.0.tm.md punkshell_module_punk::path {Filesystem path utilities}} {doc/files/project_changes.md punkshell__project_changes {punkshell Changes}} {doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md punkshell_module_punk::mix::commandset::project {pmix commandset - project}} {doc/files/main.md punkshell {punkshell - Core}}}} |
||||||
@ -1 +1 @@ |
|||||||
kw,capability {index.md capability} punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.md sa,punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {punkshell Changes} doc/files/project_changes.md {Introduction to punkshell} doc/files/project_intro.md punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md sa,punkshell(n) doc/files/main.md filesystem {index.md filesystem} sa,punkshell doc/files/main.md kw,shell {index.md shell} sa,punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.md sa,punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.md sa,punkshell__project_changes(n) doc/files/project_changes.md kw,path {index.md path} kw,module {index.md module} punkshell(n) doc/files/main.md kw,plugin {index.md plugin} punkshell doc/files/main.md punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.md changelog {index.md changelog} punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.md punkshell__project_changes(n) doc/files/project_changes.md sa,punkshell__project_changes doc/files/project_changes.md path {index.md path} sa,punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.md punkshell__project_changes doc/files/project_changes.md kw,filesystem {index.md filesystem} sa,punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md shell {index.md shell} punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.md kw,repl {index.md repl} capability {index.md capability} punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {punkshell - Core} doc/files/main.md {pmix commandset - project} doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {capability provider and handler plugin system} doc/files/punk/_module_cap-0.1.0.tm.md repl {index.md repl} kw,punk {index.md punk} sa,punkshell__project_intro(n) doc/files/project_intro.md sa,punkshell__project_intro doc/files/project_intro.md {Filesystem path utilities} doc/files/punk/_module_path-0.1.0.tm.md sa,punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.md punkshell__project_intro(n) doc/files/project_intro.md punkshell__project_intro doc/files/project_intro.md kw,changelog {index.md changelog} punk {index.md punk} module {index.md module} plugin {index.md plugin} |
kw,capability {index.md capability} punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.md sa,punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {punkshell Changes} doc/files/project_changes.md {Introduction to punkshell} doc/files/project_intro.md sa,punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md sa,punkshell(n) doc/files/main.md filesystem {index.md filesystem} sa,punkshell doc/files/main.md kw,shell {index.md shell} sa,punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.md sa,punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.md kw,parse {index.md parse} sa,punkshell__project_changes(n) doc/files/project_changes.md kw,path {index.md path} kw,module {index.md module} punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.md punkshell(n) doc/files/main.md kw,plugin {index.md plugin} punkshell doc/files/main.md kw,file {index.md file} punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.md changelog {index.md changelog} punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.md punkshell__project_changes(n) doc/files/project_changes.md sa,punkshell__project_changes doc/files/project_changes.md path {index.md path} file {index.md file} sa,punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.md punkshell__project_changes doc/files/project_changes.md kw,filesystem {index.md filesystem} sa,punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md shell {index.md shell} punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.md kw,repl {index.md repl} capability {index.md capability} kw,text {index.md text} parse {index.md parse} sa,punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.md punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {punkshell - Core} doc/files/main.md {pmix commandset - project} doc/files/punk/mix/commandset/_module_project-0.1.0.tm.md {capability provider and handler plugin system} doc/files/punk/_module_cap-0.1.0.tm.md repl {index.md repl} punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.md kw,punk {index.md punk} sa,punkshell__project_intro(n) doc/files/project_intro.md text {index.md text} sa,punkshell__project_intro doc/files/project_intro.md {Filesystem path utilities} doc/files/punk/_module_path-0.1.0.tm.md sa,punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.md punkshell__project_intro(n) doc/files/project_intro.md {file line-handling utilities} doc/files/punk/_module_fileline-0.1.0.tm.md punkshell__project_intro doc/files/project_intro.md kw,changelog {index.md changelog} module {index.md module} punk {index.md punk} plugin {index.md plugin} |
||||||
@ -0,0 +1,353 @@ |
|||||||
|
|
||||||
|
[//000000001]: # (punkshell\_module\_punk::fileline \- punk fileline) |
||||||
|
[//000000002]: # (Generated from file '\_module\_fileline\-0\.1\.0\.tm\.man' by tcllib/doctools with format 'markdown') |
||||||
|
[//000000003]: # (Copyright © 2024) |
||||||
|
[//000000004]: # (punkshell\_module\_punk::fileline\(0\) 0\.1\.0 doc "punk fileline") |
||||||
|
|
||||||
|
<hr> [ <a href="../../../toc.md">Main Table Of Contents</a> | <a |
||||||
|
href="../../toc.md">Table Of Contents</a> | <a |
||||||
|
href="../../../index.md">Keyword Index</a> ] <hr> |
||||||
|
|
||||||
|
# NAME |
||||||
|
|
||||||
|
punkshell\_module\_punk::fileline \- file line\-handling utilities |
||||||
|
|
||||||
|
# <a name='toc'></a>Table Of Contents |
||||||
|
|
||||||
|
- [Table Of Contents](#toc) |
||||||
|
|
||||||
|
- [Synopsis](#synopsis) |
||||||
|
|
||||||
|
- [Description](#section1) |
||||||
|
|
||||||
|
- [Overview](#section2) |
||||||
|
|
||||||
|
- [Concepts](#subsection1) |
||||||
|
|
||||||
|
- [Notes](#subsection2) |
||||||
|
|
||||||
|
- [dependencies](#subsection3) |
||||||
|
|
||||||
|
- [API](#section3) |
||||||
|
|
||||||
|
- [Namespace punk::fileline::class](#subsection4) |
||||||
|
|
||||||
|
- [Namespace punk::fileline](#subsection5) |
||||||
|
|
||||||
|
- [Namespace punk::fileline::lib](#subsection6) |
||||||
|
|
||||||
|
- [Internal](#section4) |
||||||
|
|
||||||
|
- [Namespace punk::fileline::system](#subsection7) |
||||||
|
|
||||||
|
- [Keywords](#keywords) |
||||||
|
|
||||||
|
- [Copyright](#copyright) |
||||||
|
|
||||||
|
# <a name='synopsis'></a>SYNOPSIS |
||||||
|
|
||||||
|
package require punk::fileline |
||||||
|
|
||||||
|
[class::textinfo __constructor__ *datachunk* ?option value\.\.\.?](#1) |
||||||
|
[class::textinfo __chunk__ *chunkstart* *chunkend*](#2) |
||||||
|
[class::textinfo __chunklen__](#3) |
||||||
|
[class::textinfo __linecount__](#4) |
||||||
|
[class::textinfo __regenerate\_lines__](#5) |
||||||
|
[class::textinfo __line__ *lineindex*](#6) |
||||||
|
[class::textinfo __linepayload__ *lineindex*](#7) |
||||||
|
[class::textinfo __linemeta__ *lineindex*](#8) |
||||||
|
[class::textinfo __lineinfo__ *lineindex*](#9) |
||||||
|
[class::textinfo __linerange\_to\_chunkrange__ *startidx* *endidx*](#10) |
||||||
|
[class::textinfo __linerange\_to\_chunk__ *startidx* *endidx*](#11) |
||||||
|
[class::textinfo __lines__ *startidx* *endidx*](#12) |
||||||
|
[class::textinfo __linepayloads__ *startidx* *endidx*](#13) |
||||||
|
[class::textinfo __chunkrange\_to\_linerange__ *chunkstart* *chunkend*](#14) |
||||||
|
[class::textinfo __chunkrange\_to\_lineinfolist__ *chunkstart* *chunkend* ?option value\.\.\.?](#15) |
||||||
|
[class::textinfo __numeric\_linerange__ *startidx* *endidx*](#16) |
||||||
|
[class::textinfo __numeric\_chunkrange__ *startidx* *endidx*](#17) |
||||||
|
[class::textinfo __normalize\_indices__ *startidx* *endidx* *max*](#18) |
||||||
|
[__lib::range\_spans\_chunk\_boundaries__ *start* *end* *chunksize*](#19) |
||||||
|
|
||||||
|
# <a name='description'></a>DESCRIPTION |
||||||
|
|
||||||
|
\- |
||||||
|
|
||||||
|
# <a name='section2'></a>Overview |
||||||
|
|
||||||
|
Utilities for in\-memory analysis of text file data as both line data and |
||||||
|
byte/char\-counted data whilst preserving the line\-endings \(even if mixed\) |
||||||
|
|
||||||
|
This is important for certain text files where examining the number of |
||||||
|
chars/bytes is important |
||||||
|
|
||||||
|
For example \- windows \.cmd/\.bat files need some byte counting to determine if |
||||||
|
labels lie on chunk boundaries and need to be moved\. |
||||||
|
|
||||||
|
Despite including the word 'file', the library doesn't deal with reading/writing |
||||||
|
to the filesystem\. It is for operating on text\-file like data\. |
||||||
|
|
||||||
|
## <a name='subsection1'></a>Concepts |
||||||
|
|
||||||
|
A chunk of textfile data \(possibly representing a whole file \- but usually at |
||||||
|
least a complete set of lines\) is loaded into a punk::fileline::class::textinfo |
||||||
|
instance at object creation\. |
||||||
|
|
||||||
|
package require punk::fileline |
||||||
|
package require fileutil |
||||||
|
set rawdata [fileutil::cat data.txt -translation binary] |
||||||
|
punk::fileline::class::textinfo create obj_data $rawdata |
||||||
|
puts stdout [obj_data linecount] |
||||||
|
|
||||||
|
## <a name='subsection2'></a>Notes |
||||||
|
|
||||||
|
Line records are referred to by a zero\-based index instead of a one\-based index |
||||||
|
as is commonly used when displaying files\. |
||||||
|
|
||||||
|
This is for programming consistency and convenience, and the module user should |
||||||
|
do their own conversion to one\-based indexing for line display or messaging if |
||||||
|
desired\. |
||||||
|
|
||||||
|
No support for lone carriage\-returns being interpreted as line\-endings\. |
||||||
|
|
||||||
|
CR line\-endings that are intended to be interpreted as such should be mapped to |
||||||
|
something else before the data is supplied to this module\. |
||||||
|
|
||||||
|
## <a name='subsection3'></a>dependencies |
||||||
|
|
||||||
|
packages used by punk::fileline |
||||||
|
|
||||||
|
- __Tcl 8\.6__ |
||||||
|
|
||||||
|
# <a name='section3'></a>API |
||||||
|
|
||||||
|
## <a name='subsection4'></a>Namespace punk::fileline::class |
||||||
|
|
||||||
|
class definitions |
||||||
|
|
||||||
|
1. CLASS __textinfo__ |
||||||
|
|
||||||
|
- <a name='1'></a>class::textinfo __constructor__ *datachunk* ?option value\.\.\.? |
||||||
|
|
||||||
|
*METHODS* |
||||||
|
|
||||||
|
Constructor for textinfo object which represents a chunk or all of a |
||||||
|
file |
||||||
|
|
||||||
|
datachunk should be passed with the file data including line\-endings |
||||||
|
as\-is for full functionality\. ie use something like: |
||||||
|
|
||||||
|
fconfigure $fd -translation binary |
||||||
|
set chunkdata [read $fd]] |
||||||
|
or |
||||||
|
set chunkdata [fileutil::cat <filename> -translation binary] |
||||||
|
|
||||||
|
when loading the data |
||||||
|
|
||||||
|
- <a name='2'></a>class::textinfo __chunk__ *chunkstart* *chunkend* |
||||||
|
|
||||||
|
Return a range of bytes from the underlying raw chunk data\. |
||||||
|
|
||||||
|
e\.g The following retrieves the entire chunk |
||||||
|
|
||||||
|
objName chunk 0 end |
||||||
|
|
||||||
|
- <a name='3'></a>class::textinfo __chunklen__ |
||||||
|
|
||||||
|
Number of bytes/characters in the raw data of the file |
||||||
|
|
||||||
|
- <a name='4'></a>class::textinfo __linecount__ |
||||||
|
|
||||||
|
Number of lines in the raw data of the file, counted as per the policy |
||||||
|
in effect |
||||||
|
|
||||||
|
- <a name='5'></a>class::textinfo __regenerate\_lines__ |
||||||
|
|
||||||
|
generate a list of lines from the stored raw data chunk and keep a map |
||||||
|
of line\-endings indexed by lineindex |
||||||
|
|
||||||
|
- <a name='6'></a>class::textinfo __line__ *lineindex* |
||||||
|
|
||||||
|
Reconstructs and returns the raw line using the payload and per\-line |
||||||
|
stored line\-ending metadata |
||||||
|
|
||||||
|
A 'line' may be returned without a line\-ending if the unerlying chunk |
||||||
|
had trailing data without a line\-ending \(or the chunk was loaded under |
||||||
|
a non\-standard \-policy setting\) |
||||||
|
|
||||||
|
Whilst such data may not conform to definitions \(e\.g POSIX\) of the |
||||||
|
terms 'textfile' and 'line' \- it is useful here to represent it as a |
||||||
|
line with metadata le set to "none" |
||||||
|
|
||||||
|
To return just the data which might more commonly be needed for dealing |
||||||
|
with lines, use the __linepayload__ method \- which returns the line |
||||||
|
data minus line\-ending |
||||||
|
|
||||||
|
- <a name='7'></a>class::textinfo __linepayload__ *lineindex* |
||||||
|
|
||||||
|
Return the text of the line indicated by the zero\-based lineindex |
||||||
|
|
||||||
|
The line\-ending is not returned in the data \- but is still stored |
||||||
|
against this lineindex |
||||||
|
|
||||||
|
Line Metadata such as the line\-ending for a particular line and the |
||||||
|
byte/character range it occupies within the chunk can be retrieved with |
||||||
|
the __linemeta__ method |
||||||
|
|
||||||
|
To retrieve both the line text and metadata in a single call the |
||||||
|
__lineinfo__ method can be used |
||||||
|
|
||||||
|
To retrieve an entire line including line\-ending use the __line__ |
||||||
|
method\. |
||||||
|
|
||||||
|
- <a name='8'></a>class::textinfo __linemeta__ *lineindex* |
||||||
|
|
||||||
|
Return a dict of the metadata for the line indicated by the zero\-based |
||||||
|
lineindex |
||||||
|
|
||||||
|
Keys returned include |
||||||
|
|
||||||
|
* le |
||||||
|
|
||||||
|
A string representing the type of line\-ending: crlf|lf|none |
||||||
|
|
||||||
|
* linelen |
||||||
|
|
||||||
|
The number of characters/bytes in the whole line including |
||||||
|
line\-ending if any |
||||||
|
|
||||||
|
* payloadlen |
||||||
|
|
||||||
|
The number of character/bytes in the line excluding line\-ending |
||||||
|
|
||||||
|
* start |
||||||
|
|
||||||
|
The zero\-based index into the associated raw file data indicating |
||||||
|
at which byte/character index this line begins |
||||||
|
|
||||||
|
* end |
||||||
|
|
||||||
|
The zero\-based index into the associated raw file data indicating |
||||||
|
at which byte/character index this line ends |
||||||
|
|
||||||
|
This end\-point corresponds to the last character of the line\-ending |
||||||
|
if any \- not necessarily the last character of the line's payload |
||||||
|
|
||||||
|
- <a name='9'></a>class::textinfo __lineinfo__ *lineindex* |
||||||
|
|
||||||
|
Return a dict of the metadata and text for the line indicated by the |
||||||
|
zero\-based lineindex |
||||||
|
|
||||||
|
This returns the same info as the __linemeta__ with an added key of |
||||||
|
'payload' which is the text of the line without line\-ending\. |
||||||
|
|
||||||
|
The 'payload' value is the same as is returned from the |
||||||
|
__linepayload__ method\. |
||||||
|
|
||||||
|
- <a name='10'></a>class::textinfo __linerange\_to\_chunkrange__ *startidx* *endidx* |
||||||
|
|
||||||
|
- <a name='11'></a>class::textinfo __linerange\_to\_chunk__ *startidx* *endidx* |
||||||
|
|
||||||
|
- <a name='12'></a>class::textinfo __lines__ *startidx* *endidx* |
||||||
|
|
||||||
|
- <a name='13'></a>class::textinfo __linepayloads__ *startidx* *endidx* |
||||||
|
|
||||||
|
- <a name='14'></a>class::textinfo __chunkrange\_to\_linerange__ *chunkstart* *chunkend* |
||||||
|
|
||||||
|
- <a name='15'></a>class::textinfo __chunkrange\_to\_lineinfolist__ *chunkstart* *chunkend* ?option value\.\.\.? |
||||||
|
|
||||||
|
Return a list of dicts each with structure like the result of the |
||||||
|
__lineinfo__ method \- but possibly with extra keys for truncation |
||||||
|
information if \-show\_truncated 1 is supplied |
||||||
|
|
||||||
|
The truncation key in a lineinfo dict may be returned for first and/or |
||||||
|
last line in the resulting list\. |
||||||
|
|
||||||
|
truncation shows the shortened \(missing bytes on left and/or right |
||||||
|
side\) part of the entire line \(potentially including line\-ending or |
||||||
|
even partial line\-ending\) |
||||||
|
|
||||||
|
Note that this truncation info is only in the return value of this |
||||||
|
method \- and will not be reflected in __lineinfo__ queries to the |
||||||
|
main chunk\. |
||||||
|
|
||||||
|
- <a name='16'></a>class::textinfo __numeric\_linerange__ *startidx* *endidx* |
||||||
|
|
||||||
|
A helper to return any Tcl\-style end end\-x values given to startidx or |
||||||
|
endidx; converted to their specific values based on the current state |
||||||
|
of the underlying line data |
||||||
|
|
||||||
|
This is used internally by API functions such as __line__ to enable |
||||||
|
it to accept more expressive indices |
||||||
|
|
||||||
|
- <a name='17'></a>class::textinfo __numeric\_chunkrange__ *startidx* *endidx* |
||||||
|
|
||||||
|
A helper to return any Tcl\-style end end\-x entries supplied to startidx |
||||||
|
or endidx; converted to their specific values based on the current |
||||||
|
state of the underlying chunk data |
||||||
|
|
||||||
|
- <a name='18'></a>class::textinfo __normalize\_indices__ *startidx* *endidx* *max* |
||||||
|
|
||||||
|
A utility to convert some of the of Tcl\-style list\-index expressions |
||||||
|
such as end, end\-1 etc to valid indices in the range 0 to the supplied |
||||||
|
max |
||||||
|
|
||||||
|
Basic addition and subtraction expressions such as 4\-1 5\+2 are accepted |
||||||
|
|
||||||
|
startidx higher than endidx is allowed |
||||||
|
|
||||||
|
Unlike Tcl's index expressions \- we raise an error if the calculated |
||||||
|
index is out of bounds 0 to max |
||||||
|
|
||||||
|
## <a name='subsection5'></a>Namespace punk::fileline |
||||||
|
|
||||||
|
Core API functions for punk::fileline |
||||||
|
|
||||||
|
## <a name='subsection6'></a>Namespace punk::fileline::lib |
||||||
|
|
||||||
|
- <a name='19'></a>__lib::range\_spans\_chunk\_boundaries__ *start* *end* *chunksize* |
||||||
|
|
||||||
|
Takes start and end offset, generally representing bytes or character |
||||||
|
indices, and computes a list of boundaries at multiples of the chunksize |
||||||
|
that are spanned by the start and end range\. |
||||||
|
|
||||||
|
* integer *start* |
||||||
|
|
||||||
|
zero\-based start index of range |
||||||
|
|
||||||
|
* integer *end* |
||||||
|
|
||||||
|
zero\-based end index of range |
||||||
|
|
||||||
|
* integer *chunksize* |
||||||
|
|
||||||
|
Number of bytes/characters in chunk |
||||||
|
|
||||||
|
returns a dict with the keys is\_span and boundaries |
||||||
|
|
||||||
|
is\_span 0|1 indicates if the range specified spans a boundary of chunksize |
||||||
|
|
||||||
|
boundaries contains a list of the spanned boundaries \- which are always |
||||||
|
multiples of the chunksize |
||||||
|
|
||||||
|
e\.g |
||||||
|
|
||||||
|
range_spans_chunk_boundaries 10 1750 512 |
||||||
|
is_span 1 boundaries {512 1024 1536} |
||||||
|
|
||||||
|
This function automatically uses lseq \(if Tcl >= 8\.7\) when number of |
||||||
|
boundaries spanned is approximately greater than 75 |
||||||
|
|
||||||
|
# <a name='section4'></a>Internal |
||||||
|
|
||||||
|
## <a name='subsection7'></a>Namespace punk::fileline::system |
||||||
|
|
||||||
|
Internal functions that are not part of the API |
||||||
|
|
||||||
|
# <a name='keywords'></a>KEYWORDS |
||||||
|
|
||||||
|
[file](\.\./\.\./\.\./index\.md\#file), [module](\.\./\.\./\.\./index\.md\#module), |
||||||
|
[parse](\.\./\.\./\.\./index\.md\#parse), [text](\.\./\.\./\.\./index\.md\#text) |
||||||
|
|
||||||
|
# <a name='copyright'></a>COPYRIGHT |
||||||
|
|
||||||
|
Copyright © 2024 |
||||||
@ -1 +1 @@ |
|||||||
{shell {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} changelog {{doc/files/project_changes.html punkshell__project_changes}} filesystem {{doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} path {{doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} capability {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap}} module {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} {doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} punk {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} plugin {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap}} repl {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}}} {{repl doc/files/main.html punkshell} . {punk doc/files/project_intro.html punkshell__project_intro} . {capability doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {changelog doc/files/project_changes.html punkshell__project_changes} . {shell doc/files/project_changes.html punkshell__project_changes} . {shell doc/files/main.html punkshell} . {repl doc/files/project_intro.html punkshell__project_intro} . {module doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {plugin doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {filesystem doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {path doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {module doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {punk doc/files/project_changes.html punkshell__project_changes} . {shell doc/files/project_intro.html punkshell__project_intro} . {punk doc/files/main.html punkshell} . {repl doc/files/project_changes.html punkshell__project_changes} .} 9 {shell shell changelog changelog filesystem filesystem path path capability capability module module punk punk plugin plugin repl repl} |
{file {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline}} repl {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} text {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline}} shell {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} changelog {{doc/files/project_changes.html punkshell__project_changes}} capability {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap}} parse {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline}} filesystem {{doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} path {{doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} module {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} {doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} {doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path}} punk {{doc/files/project_intro.html punkshell__project_intro} {doc/files/project_changes.html punkshell__project_changes} {doc/files/main.html punkshell}} plugin {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap}}} {{repl doc/files/main.html punkshell} . {file doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {punk doc/files/project_intro.html punkshell__project_intro} . {capability doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {shell doc/files/project_changes.html punkshell__project_changes} . {changelog doc/files/project_changes.html punkshell__project_changes} . {shell doc/files/main.html punkshell} . {text doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {repl doc/files/project_intro.html punkshell__project_intro} . {module doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {path doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {plugin doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap} . {filesystem doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {module doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path} . {shell doc/files/project_intro.html punkshell__project_intro} . {punk doc/files/project_changes.html punkshell__project_changes} . {parse doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {punk doc/files/main.html punkshell} . {module doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline} . {repl doc/files/project_changes.html punkshell__project_changes} .} 12 {file file repl repl text text shell shell changelog changelog capability capability parse parse filesystem filesystem path path module module punk punk plugin plugin} |
||||||
@ -1 +1 @@ |
|||||||
doc {doc/toc {{doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap {capability provider and handler plugin system}} {doc/files/project_intro.html punkshell__project_intro {Introduction to punkshell}} {doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path {Filesystem path utilities}} {doc/files/project_changes.html punkshell__project_changes {punkshell Changes}} {doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html punkshell_module_punk::mix::commandset::project {pmix commandset - project}} {doc/files/main.html punkshell {punkshell - Core}}}} |
doc {doc/toc {{doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::fileline {file line-handling utilities}} {doc/files/punk/_module_cap-0.1.0.tm.html punkshell_module_punk::cap {capability provider and handler plugin system}} {doc/files/project_intro.html punkshell__project_intro {Introduction to punkshell}} {doc/files/punk/_module_path-0.1.0.tm.html punkshell_module_punk::path {Filesystem path utilities}} {doc/files/project_changes.html punkshell__project_changes {punkshell Changes}} {doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html punkshell_module_punk::mix::commandset::project {pmix commandset - project}} {doc/files/main.html punkshell {punkshell - Core}}}} |
||||||
@ -1 +1 @@ |
|||||||
kw,capability {index.html capability} punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.html sa,punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {punkshell Changes} doc/files/project_changes.html {Introduction to punkshell} doc/files/project_intro.html punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html sa,punkshell(n) doc/files/main.html filesystem {index.html filesystem} sa,punkshell doc/files/main.html kw,shell {index.html shell} sa,punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.html sa,punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.html sa,punkshell__project_changes(n) doc/files/project_changes.html kw,path {index.html path} kw,module {index.html module} punkshell(n) doc/files/main.html kw,plugin {index.html plugin} punkshell doc/files/main.html punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.html changelog {index.html changelog} punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.html punkshell__project_changes(n) doc/files/project_changes.html sa,punkshell__project_changes doc/files/project_changes.html path {index.html path} sa,punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.html punkshell__project_changes doc/files/project_changes.html kw,filesystem {index.html filesystem} sa,punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html shell {index.html shell} punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.html kw,repl {index.html repl} capability {index.html capability} punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {punkshell - Core} doc/files/main.html {pmix commandset - project} doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {capability provider and handler plugin system} doc/files/punk/_module_cap-0.1.0.tm.html repl {index.html repl} kw,punk {index.html punk} sa,punkshell__project_intro(n) doc/files/project_intro.html sa,punkshell__project_intro doc/files/project_intro.html {Filesystem path utilities} doc/files/punk/_module_path-0.1.0.tm.html sa,punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.html punkshell__project_intro(n) doc/files/project_intro.html punkshell__project_intro doc/files/project_intro.html kw,changelog {index.html changelog} punk {index.html punk} module {index.html module} plugin {index.html plugin} |
kw,capability {index.html capability} punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.html sa,punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {punkshell Changes} doc/files/project_changes.html {Introduction to punkshell} doc/files/project_intro.html sa,punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::mix::commandset::project(0) doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html sa,punkshell(n) doc/files/main.html filesystem {index.html filesystem} sa,punkshell doc/files/main.html kw,shell {index.html shell} sa,punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.html sa,punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.html kw,parse {index.html parse} sa,punkshell__project_changes(n) doc/files/project_changes.html kw,path {index.html path} kw,module {index.html module} punkshell_module_punk::fileline(0) doc/files/punk/_module_fileline-0.1.0.tm.html punkshell(n) doc/files/main.html kw,plugin {index.html plugin} punkshell doc/files/main.html kw,file {index.html file} punkshell_module_punk::cap doc/files/punk/_module_cap-0.1.0.tm.html changelog {index.html changelog} punkshell_module_punk::cap(0) doc/files/punk/_module_cap-0.1.0.tm.html punkshell__project_changes(n) doc/files/project_changes.html sa,punkshell__project_changes doc/files/project_changes.html path {index.html path} file {index.html file} sa,punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.html punkshell__project_changes doc/files/project_changes.html kw,filesystem {index.html filesystem} sa,punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html shell {index.html shell} punkshell_module_punk::path doc/files/punk/_module_path-0.1.0.tm.html kw,repl {index.html repl} capability {index.html capability} kw,text {index.html text} parse {index.html parse} sa,punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.html punkshell_module_punk::mix::commandset::project doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {punkshell - Core} doc/files/main.html {pmix commandset - project} doc/files/punk/mix/commandset/_module_project-0.1.0.tm.html {capability provider and handler plugin system} doc/files/punk/_module_cap-0.1.0.tm.html repl {index.html repl} punkshell_module_punk::fileline doc/files/punk/_module_fileline-0.1.0.tm.html kw,punk {index.html punk} sa,punkshell__project_intro(n) doc/files/project_intro.html text {index.html text} sa,punkshell__project_intro doc/files/project_intro.html {Filesystem path utilities} doc/files/punk/_module_path-0.1.0.tm.html sa,punkshell_module_punk::path(0) doc/files/punk/_module_path-0.1.0.tm.html punkshell__project_intro(n) doc/files/project_intro.html {file line-handling utilities} doc/files/punk/_module_fileline-0.1.0.tm.html punkshell__project_intro doc/files/project_intro.html kw,changelog {index.html changelog} module {index.html module} punk {index.html punk} plugin {index.html plugin} |
||||||
@ -0,0 +1,326 @@ |
|||||||
|
<!DOCTYPE html><html><head> |
||||||
|
<title>punkshell_module_punk::fileline - punk fileline</title> |
||||||
|
<style type="text/css"><!-- |
||||||
|
HTML { |
||||||
|
background: #FFFFFF; |
||||||
|
color: black; |
||||||
|
} |
||||||
|
BODY { |
||||||
|
background: #FFFFFF; |
||||||
|
color: black; |
||||||
|
} |
||||||
|
DIV.doctools { |
||||||
|
margin-left: 10%; |
||||||
|
margin-right: 10%; |
||||||
|
} |
||||||
|
DIV.doctools H1,DIV.doctools H2 { |
||||||
|
margin-left: -5%; |
||||||
|
} |
||||||
|
H1, H2, H3, H4 { |
||||||
|
margin-top: 1em; |
||||||
|
font-family: sans-serif; |
||||||
|
font-size: large; |
||||||
|
color: #005A9C; |
||||||
|
background: transparent; |
||||||
|
text-align: left; |
||||||
|
} |
||||||
|
H1.doctools_title { |
||||||
|
text-align: center; |
||||||
|
} |
||||||
|
UL,OL { |
||||||
|
margin-right: 0em; |
||||||
|
margin-top: 3pt; |
||||||
|
margin-bottom: 3pt; |
||||||
|
} |
||||||
|
UL LI { |
||||||
|
list-style: disc; |
||||||
|
} |
||||||
|
OL LI { |
||||||
|
list-style: decimal; |
||||||
|
} |
||||||
|
DT { |
||||||
|
padding-top: 1ex; |
||||||
|
} |
||||||
|
UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL { |
||||||
|
font: normal 12pt/14pt sans-serif; |
||||||
|
list-style: none; |
||||||
|
} |
||||||
|
LI.doctools_section, LI.doctools_subsection { |
||||||
|
list-style: none; |
||||||
|
margin-left: 0em; |
||||||
|
text-indent: 0em; |
||||||
|
padding: 0em; |
||||||
|
} |
||||||
|
PRE { |
||||||
|
display: block; |
||||||
|
font-family: monospace; |
||||||
|
white-space: pre; |
||||||
|
margin: 0%; |
||||||
|
padding-top: 0.5ex; |
||||||
|
padding-bottom: 0.5ex; |
||||||
|
padding-left: 1ex; |
||||||
|
padding-right: 1ex; |
||||||
|
width: 100%; |
||||||
|
} |
||||||
|
PRE.doctools_example { |
||||||
|
color: black; |
||||||
|
background: #f5dcb3; |
||||||
|
border: 1px solid black; |
||||||
|
} |
||||||
|
UL.doctools_requirements LI, UL.doctools_syntax LI { |
||||||
|
list-style: none; |
||||||
|
margin-left: 0em; |
||||||
|
text-indent: 0em; |
||||||
|
padding: 0em; |
||||||
|
} |
||||||
|
DIV.doctools_synopsis { |
||||||
|
color: black; |
||||||
|
background: #80ffff; |
||||||
|
border: 1px solid black; |
||||||
|
font-family: serif; |
||||||
|
margin-top: 1em; |
||||||
|
margin-bottom: 1em; |
||||||
|
} |
||||||
|
UL.doctools_syntax { |
||||||
|
margin-top: 1em; |
||||||
|
border-top: 1px solid black; |
||||||
|
} |
||||||
|
UL.doctools_requirements { |
||||||
|
margin-bottom: 1em; |
||||||
|
border-bottom: 1px solid black; |
||||||
|
} |
||||||
|
--></style> |
||||||
|
</head> |
||||||
|
<!-- Generated from file '_module_fileline-0.1.0.tm.man' by tcllib/doctools with format 'html' |
||||||
|
--> |
||||||
|
<!-- Copyright &copy; 2024 |
||||||
|
--> |
||||||
|
<!-- punkshell_module_punk::fileline.0 |
||||||
|
--> |
||||||
|
<body><hr> [ |
||||||
|
<a href="../../../toc.html">Main Table Of Contents</a> |
||||||
|
| <a href="../../toc.html">Table Of Contents</a> |
||||||
|
| <a href="../../../index.html">Keyword Index</a> |
||||||
|
] <hr> |
||||||
|
<div class="doctools"> |
||||||
|
<h1 class="doctools_title">punkshell_module_punk::fileline(0) 0.1.0 doc "punk fileline"</h1> |
||||||
|
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2> |
||||||
|
<p>punkshell_module_punk::fileline - file line-handling utilities</p> |
||||||
|
</div> |
||||||
|
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2> |
||||||
|
<ul class="doctools_toc"> |
||||||
|
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li> |
||||||
|
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li> |
||||||
|
<li class="doctools_section"><a href="#section1">Description</a></li> |
||||||
|
<li class="doctools_section"><a href="#section2">Overview</a> |
||||||
|
<ul> |
||||||
|
<li class="doctools_subsection"><a href="#subsection1">Concepts</a></li> |
||||||
|
<li class="doctools_subsection"><a href="#subsection2">Notes</a></li> |
||||||
|
<li class="doctools_subsection"><a href="#subsection3">dependencies</a></li> |
||||||
|
</ul> |
||||||
|
</li> |
||||||
|
<li class="doctools_section"><a href="#section3">API</a> |
||||||
|
<ul> |
||||||
|
<li class="doctools_subsection"><a href="#subsection4">Namespace punk::fileline::class</a></li> |
||||||
|
<li class="doctools_subsection"><a href="#subsection5">Namespace punk::fileline</a></li> |
||||||
|
<li class="doctools_subsection"><a href="#subsection6">Namespace punk::fileline::lib</a></li> |
||||||
|
</ul> |
||||||
|
</li> |
||||||
|
<li class="doctools_section"><a href="#section4">Internal</a> |
||||||
|
<ul> |
||||||
|
<li class="doctools_subsection"><a href="#subsection7">Namespace punk::fileline::system</a></li> |
||||||
|
</ul> |
||||||
|
</li> |
||||||
|
<li class="doctools_section"><a href="#keywords">Keywords</a></li> |
||||||
|
<li class="doctools_section"><a href="#copyright">Copyright</a></li> |
||||||
|
</ul> |
||||||
|
</div> |
||||||
|
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2> |
||||||
|
<div class="doctools_synopsis"> |
||||||
|
<ul class="doctools_requirements"> |
||||||
|
<li>package require <b class="pkgname">punk::fileline</b></li> |
||||||
|
</ul> |
||||||
|
<ul class="doctools_syntax"> |
||||||
|
<li><a href="#1">class::textinfo <b class="method">constructor</b> <i class="arg">datachunk</i> <span class="opt">?option value...?</span></a></li> |
||||||
|
<li><a href="#2">class::textinfo <b class="method">chunk</b> <i class="arg">chunkstart</i> <i class="arg">chunkend</i></a></li> |
||||||
|
<li><a href="#3">class::textinfo <b class="method">chunklen</b></a></li> |
||||||
|
<li><a href="#4">class::textinfo <b class="method">linecount</b></a></li> |
||||||
|
<li><a href="#5">class::textinfo <b class="method">regenerate_lines</b></a></li> |
||||||
|
<li><a href="#6">class::textinfo <b class="method">line</b> <i class="arg">lineindex</i></a></li> |
||||||
|
<li><a href="#7">class::textinfo <b class="method">linepayload</b> <i class="arg">lineindex</i></a></li> |
||||||
|
<li><a href="#8">class::textinfo <b class="method">linemeta</b> <i class="arg">lineindex</i></a></li> |
||||||
|
<li><a href="#9">class::textinfo <b class="method">lineinfo</b> <i class="arg">lineindex</i></a></li> |
||||||
|
<li><a href="#10">class::textinfo <b class="method">linerange_to_chunkrange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
||||||
|
<li><a href="#11">class::textinfo <b class="method">linerange_to_chunk</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
||||||
|
<li><a href="#12">class::textinfo <b class="method">lines</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
||||||
|
<li><a href="#13">class::textinfo <b class="method">linepayloads</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
||||||
|
<li><a href="#14">class::textinfo <b class="method">chunkrange_to_linerange</b> <i class="arg">chunkstart</i> <i class="arg">chunkend</i></a></li> |
||||||
|
<li><a href="#15">class::textinfo <b class="method">chunkrange_to_lineinfolist</b> <i class="arg">chunkstart</i> <i class="arg">chunkend</i> <span class="opt">?option value...?</span></a></li> |
||||||
|
<li><a href="#16">class::textinfo <b class="method">numeric_linerange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
||||||
|
<li><a href="#17">class::textinfo <b class="method">numeric_chunkrange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
||||||
|
<li><a href="#18">class::textinfo <b class="method">normalize_indices</b> <i class="arg">startidx</i> <i class="arg">endidx</i> <i class="arg">max</i></a></li> |
||||||
|
<li><a href="#19"><b class="function">lib::range_spans_chunk_boundaries</b> <i class="arg">start</i> <i class="arg">end</i> <i class="arg">chunksize</i></a></li> |
||||||
|
</ul> |
||||||
|
</div> |
||||||
|
</div> |
||||||
|
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2> |
||||||
|
<p>-</p> |
||||||
|
</div> |
||||||
|
<div id="section2" class="doctools_section"><h2><a name="section2">Overview</a></h2> |
||||||
|
<p>Utilities for in-memory analysis of text file data as both line data and byte/char-counted data whilst preserving the line-endings (even if mixed)</p> |
||||||
|
<p>This is important for certain text files where examining the number of chars/bytes is important</p> |
||||||
|
<p>For example - windows .cmd/.bat files need some byte counting to determine if labels lie on chunk boundaries and need to be moved.</p> |
||||||
|
<p>Despite including the word 'file', the library doesn't deal with reading/writing to the filesystem. It is for operating on text-file like data.</p> |
||||||
|
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Concepts</a></h3> |
||||||
|
<p>A chunk of textfile data (possibly representing a whole file - but usually at least a complete set of lines) is loaded into a punk::fileline::class::textinfo instance at object creation.</p> |
||||||
|
<pre class="doctools_example"> |
||||||
|
package require punk::fileline |
||||||
|
package require fileutil |
||||||
|
set rawdata [fileutil::cat data.txt -translation binary] |
||||||
|
punk::fileline::class::textinfo create obj_data $rawdata |
||||||
|
puts stdout [obj_data linecount] |
||||||
|
</pre> |
||||||
|
</div> |
||||||
|
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Notes</a></h3> |
||||||
|
<p>Line records are referred to by a zero-based index instead of a one-based index as is commonly used when displaying files.</p> |
||||||
|
<p>This is for programming consistency and convenience, and the module user should do their own conversion to one-based indexing for line display or messaging if desired.</p> |
||||||
|
<p>No support for lone carriage-returns being interpreted as line-endings.</p> |
||||||
|
<p>CR line-endings that are intended to be interpreted as such should be mapped to something else before the data is supplied to this module.</p> |
||||||
|
</div> |
||||||
|
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">dependencies</a></h3> |
||||||
|
<p>packages used by punk::fileline</p> |
||||||
|
<ul class="doctools_itemized"> |
||||||
|
<li><p><b class="package">Tcl 8.6</b></p></li> |
||||||
|
</ul> |
||||||
|
</div> |
||||||
|
</div> |
||||||
|
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2> |
||||||
|
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Namespace punk::fileline::class</a></h3> |
||||||
|
<p>class definitions</p> |
||||||
|
<ol class="doctools_enumerated"> |
||||||
|
<li><p>CLASS <b class="class">textinfo</b></p> |
||||||
|
<dl class="doctools_definitions"> |
||||||
|
<p><em>METHODS</em></p> |
||||||
|
<dt><a name="1">class::textinfo <b class="method">constructor</b> <i class="arg">datachunk</i> <span class="opt">?option value...?</span></a></dt> |
||||||
|
<dd><p>Constructor for textinfo object which represents a chunk or all of a file</p> |
||||||
|
<p>datachunk should be passed with the file data including line-endings as-is for full functionality. ie use something like:</p> |
||||||
|
<pre class="doctools_example"> |
||||||
|
fconfigure $fd -translation binary |
||||||
|
set chunkdata [read $fd]] |
||||||
|
or |
||||||
|
set chunkdata [fileutil::cat <filename> -translation binary] |
||||||
|
</pre> |
||||||
|
<p>when loading the data</p></dd> |
||||||
|
<dt><a name="2">class::textinfo <b class="method">chunk</b> <i class="arg">chunkstart</i> <i class="arg">chunkend</i></a></dt> |
||||||
|
<dd><p>Return a range of bytes from the underlying raw chunk data.</p> |
||||||
|
<p>e.g The following retrieves the entire chunk</p> |
||||||
|
<p>objName chunk 0 end</p></dd> |
||||||
|
<dt><a name="3">class::textinfo <b class="method">chunklen</b></a></dt> |
||||||
|
<dd><p>Number of bytes/characters in the raw data of the file</p></dd> |
||||||
|
<dt><a name="4">class::textinfo <b class="method">linecount</b></a></dt> |
||||||
|
<dd><p>Number of lines in the raw data of the file, counted as per the policy in effect</p></dd> |
||||||
|
<dt><a name="5">class::textinfo <b class="method">regenerate_lines</b></a></dt> |
||||||
|
<dd><p>generate a list of lines from the stored raw data chunk and keep a map of line-endings indexed by lineindex</p></dd> |
||||||
|
<dt><a name="6">class::textinfo <b class="method">line</b> <i class="arg">lineindex</i></a></dt> |
||||||
|
<dd><p>Reconstructs and returns the raw line using the payload and per-line stored line-ending metadata</p> |
||||||
|
<p>A 'line' may be returned without a line-ending if the unerlying chunk had trailing data without a line-ending (or the chunk was loaded under a non-standard -policy setting)</p> |
||||||
|
<p>Whilst such data may not conform to definitions (e.g POSIX) of the terms 'textfile' and 'line' - it is useful here to represent it as a line with metadata le set to "none"</p> |
||||||
|
<p>To return just the data which might more commonly be needed for dealing with lines, use the <b class="method">linepayload</b> method - which returns the line data minus line-ending</p></dd> |
||||||
|
<dt><a name="7">class::textinfo <b class="method">linepayload</b> <i class="arg">lineindex</i></a></dt> |
||||||
|
<dd><p>Return the text of the line indicated by the zero-based lineindex</p> |
||||||
|
<p>The line-ending is not returned in the data - but is still stored against this lineindex</p> |
||||||
|
<p>Line Metadata such as the line-ending for a particular line and the byte/character range it occupies within the chunk can be retrieved with the <b class="method">linemeta</b> method</p> |
||||||
|
<p>To retrieve both the line text and metadata in a single call the <b class="method">lineinfo</b> method can be used</p> |
||||||
|
<p>To retrieve an entire line including line-ending use the <b class="method">line</b> method.</p></dd> |
||||||
|
<dt><a name="8">class::textinfo <b class="method">linemeta</b> <i class="arg">lineindex</i></a></dt> |
||||||
|
<dd><p>Return a dict of the metadata for the line indicated by the zero-based lineindex</p> |
||||||
|
<p>Keys returned include</p> |
||||||
|
<ul class="doctools_itemized"> |
||||||
|
<li><p>le</p> |
||||||
|
<p>A string representing the type of line-ending: crlf|lf|none</p></li> |
||||||
|
<li><p>linelen</p> |
||||||
|
<p>The number of characters/bytes in the whole line including line-ending if any</p></li> |
||||||
|
<li><p>payloadlen</p> |
||||||
|
<p>The number of character/bytes in the line excluding line-ending</p></li> |
||||||
|
<li><p>start</p> |
||||||
|
<p>The zero-based index into the associated raw file data indicating at which byte/character index this line begins</p></li> |
||||||
|
<li><p>end</p> |
||||||
|
<p>The zero-based index into the associated raw file data indicating at which byte/character index this line ends</p> |
||||||
|
<p>This end-point corresponds to the last character of the line-ending if any - not necessarily the last character of the line's payload</p></li> |
||||||
|
</ul></dd> |
||||||
|
<dt><a name="9">class::textinfo <b class="method">lineinfo</b> <i class="arg">lineindex</i></a></dt> |
||||||
|
<dd><p>Return a dict of the metadata and text for the line indicated by the zero-based lineindex</p> |
||||||
|
<p>This returns the same info as the <b class="method">linemeta</b> with an added key of 'payload' which is the text of the line without line-ending.</p> |
||||||
|
<p>The 'payload' value is the same as is returned from the <b class="method">linepayload</b> method.</p></dd> |
||||||
|
<dt><a name="10">class::textinfo <b class="method">linerange_to_chunkrange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
||||||
|
<dd></dd> |
||||||
|
<dt><a name="11">class::textinfo <b class="method">linerange_to_chunk</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
||||||
|
<dd></dd> |
||||||
|
<dt><a name="12">class::textinfo <b class="method">lines</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
||||||
|
<dd></dd> |
||||||
|
<dt><a name="13">class::textinfo <b class="method">linepayloads</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
||||||
|
<dd></dd> |
||||||
|
<dt><a name="14">class::textinfo <b class="method">chunkrange_to_linerange</b> <i class="arg">chunkstart</i> <i class="arg">chunkend</i></a></dt> |
||||||
|
<dd></dd> |
||||||
|
<dt><a name="15">class::textinfo <b class="method">chunkrange_to_lineinfolist</b> <i class="arg">chunkstart</i> <i class="arg">chunkend</i> <span class="opt">?option value...?</span></a></dt> |
||||||
|
<dd><p>Return a list of dicts each with structure like the result of the <b class="method">lineinfo</b> method - but possibly with extra keys for truncation information if -show_truncated 1 is supplied</p> |
||||||
|
<p>The truncation key in a lineinfo dict may be returned for first and/or last line in the resulting list.</p> |
||||||
|
<p>truncation shows the shortened (missing bytes on left and/or right side) part of the entire line (potentially including line-ending or even partial line-ending)</p> |
||||||
|
<p>Note that this truncation info is only in the return value of this method - and will not be reflected in <b class="method">lineinfo</b> queries to the main chunk.</p></dd> |
||||||
|
<dt><a name="16">class::textinfo <b class="method">numeric_linerange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
||||||
|
<dd><p>A helper to return any Tcl-style end end-x values given to startidx or endidx; converted to their specific values based on the current state of the underlying line data</p> |
||||||
|
<p>This is used internally by API functions such as <b class="method">line</b> to enable it to accept more expressive indices</p></dd> |
||||||
|
<dt><a name="17">class::textinfo <b class="method">numeric_chunkrange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
||||||
|
<dd><p>A helper to return any Tcl-style end end-x entries supplied to startidx or endidx; converted to their specific values based on the current state of the underlying chunk data</p></dd> |
||||||
|
<dt><a name="18">class::textinfo <b class="method">normalize_indices</b> <i class="arg">startidx</i> <i class="arg">endidx</i> <i class="arg">max</i></a></dt> |
||||||
|
<dd><p>A utility to convert some of the of Tcl-style list-index expressions such as end, end-1 etc to valid indices in the range 0 to the supplied max</p> |
||||||
|
<p>Basic addition and subtraction expressions such as 4-1 5+2 are accepted</p> |
||||||
|
<p>startidx higher than endidx is allowed</p> |
||||||
|
<p>Unlike Tcl's index expressions - we raise an error if the calculated index is out of bounds 0 to max</p></dd> |
||||||
|
</dl> |
||||||
|
</li> |
||||||
|
</ol> |
||||||
|
</div> |
||||||
|
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Namespace punk::fileline</a></h3> |
||||||
|
<p>Core API functions for punk::fileline</p> |
||||||
|
<dl class="doctools_definitions"> |
||||||
|
</dl> |
||||||
|
</div> |
||||||
|
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Namespace punk::fileline::lib</a></h3> |
||||||
|
<p>Secondary functions that are part of the API</p> |
||||||
|
<dl class="doctools_definitions"> |
||||||
|
<dt><a name="19"><b class="function">lib::range_spans_chunk_boundaries</b> <i class="arg">start</i> <i class="arg">end</i> <i class="arg">chunksize</i></a></dt> |
||||||
|
<dd><p>Takes start and end offset, generally representing bytes or character indices, and computes a list of boundaries at multiples of the chunksize that are spanned by the start and end range.</p> |
||||||
|
<dl class="doctools_arguments"> |
||||||
|
|
||||||
|
<dt>integer <i class="arg">start</i></dt> |
||||||
|
<dd><p>zero-based start index of range</p></dd> |
||||||
|
<dt>integer <i class="arg">end</i></dt> |
||||||
|
<dd><p>zero-based end index of range</p></dd> |
||||||
|
<dt>integer <i class="arg">chunksize</i></dt> |
||||||
|
<dd><p>Number of bytes/characters in chunk</p></dd> |
||||||
|
</dl> |
||||||
|
<p>returns a dict with the keys is_span and boundaries</p> |
||||||
|
<p>is_span 0|1 indicates if the range specified spans a boundary of chunksize</p> |
||||||
|
<p>boundaries contains a list of the spanned boundaries - which are always multiples of the chunksize</p> |
||||||
|
<p>e.g</p> |
||||||
|
<pre class="doctools_example"> |
||||||
|
range_spans_chunk_boundaries 10 1750 512 |
||||||
|
is_span 1 boundaries {512 1024 1536} |
||||||
|
</pre> |
||||||
|
<p>This function automatically uses lseq (if Tcl >= 8.7) when number of boundaries spanned is approximately greater than 75</p></dd> |
||||||
|
</dl> |
||||||
|
</div> |
||||||
|
</div> |
||||||
|
<div id="section4" class="doctools_section"><h2><a name="section4">Internal</a></h2> |
||||||
|
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Namespace punk::fileline::system</a></h3> |
||||||
|
<p>Internal functions that are not part of the API</p> |
||||||
|
</div> |
||||||
|
</div> |
||||||
|
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2> |
||||||
|
<p><a href="../../../index.html#file">file</a>, <a href="../../../index.html#module">module</a>, <a href="../../../index.html#parse">parse</a>, <a href="../../../index.html#text">text</a></p> |
||||||
|
</div> |
||||||
|
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2> |
||||||
|
<p>Copyright © 2024</p> |
||||||
|
</div> |
||||||
|
</div></body></html> |
||||||
@ -0,0 +1,829 @@ |
|||||||
|
# -*- tcl -*- |
||||||
|
# Maintenance Instruction: leave the 999999.xxx.x as is and use 'pmix make' or src/make.tcl to update from <pkg>-buildversion.txt |
||||||
|
# |
||||||
|
# Please consider using a BSD or MIT style license for greatest compatibility with the Tcl ecosystem. |
||||||
|
# Code using preferred Tcl licenses can be eligible for inclusion in Tcllib, Tklib and the punk package repository. |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
# (C) 2024 |
||||||
|
# |
||||||
|
# @@ Meta Begin |
||||||
|
# Application punk::fileline 999999.0a1.0 |
||||||
|
# Meta platform tcl |
||||||
|
# Meta license BSD |
||||||
|
# @@ Meta End |
||||||
|
|
||||||
|
|
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
# doctools header |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
#*** !doctools |
||||||
|
#[manpage_begin punkshell_module_punk::fileline 0 999999.0a1.0] |
||||||
|
#[copyright "2024"] |
||||||
|
#[titledesc {file line-handling utilities}] [comment {-- Name section and table of contents description --}] |
||||||
|
#[moddesc {punk fileline}] [comment {-- Description at end of page heading --}] |
||||||
|
#[require punk::fileline] |
||||||
|
#[keywords module text parse file] |
||||||
|
#[description] |
||||||
|
#[para] - |
||||||
|
|
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[section Overview] |
||||||
|
#[para]Utilities for in-memory analysis of text file data as both line data and byte/char-counted data whilst preserving the line-endings (even if mixed) |
||||||
|
#[para]This is important for certain text files where examining the number of chars/bytes is important |
||||||
|
#[para]For example - windows .cmd/.bat files need some byte counting to determine if labels lie on chunk boundaries and need to be moved. |
||||||
|
#[para]Despite including the word 'file', the library doesn't deal with reading/writing to the filesystem. It is for operating on text-file like data. |
||||||
|
#[subsection Concepts] |
||||||
|
#[para]A chunk of textfile data (possibly representing a whole file - but usually at least a complete set of lines) is loaded into a punk::fileline::class::textinfo instance at object creation. |
||||||
|
#[example_begin] |
||||||
|
# package require punk::fileline |
||||||
|
# package require fileutil |
||||||
|
# set rawdata [lb]fileutil::cat data.txt -translation binary[rb] |
||||||
|
# punk::fileline::class::textinfo create obj_data $rawdata |
||||||
|
# puts stdout [lb]obj_data linecount[rb] |
||||||
|
#[example_end] |
||||||
|
#[subsection Notes] |
||||||
|
#[para]Line records are referred to by a zero-based index instead of a one-based index as is commonly used when displaying files. |
||||||
|
#[para]This is for programming consistency and convenience, and the module user should do their own conversion to one-based indexing for line display or messaging if desired. |
||||||
|
#[para]No support for lone carriage-returns being interpreted as line-endings. |
||||||
|
#[para]CR line-endings that are intended to be interpreted as such should be mapped to something else before the data is supplied to this module. |
||||||
|
|
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
## Requirements |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[subsection dependencies] |
||||||
|
#[para] packages used by punk::fileline |
||||||
|
#[list_begin itemized] |
||||||
|
|
||||||
|
package require Tcl 8.6 |
||||||
|
#*** !doctools |
||||||
|
#[item] [package {Tcl 8.6}] |
||||||
|
|
||||||
|
# #package require frobz |
||||||
|
# #*** !doctools |
||||||
|
# #[item] [package {frobz}] |
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[list_end] |
||||||
|
|
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[section API] |
||||||
|
|
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
# oo::class namespace |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
namespace eval punk::fileline::class { |
||||||
|
namespace export * |
||||||
|
#*** !doctools |
||||||
|
#[subsection {Namespace punk::fileline::class}] |
||||||
|
#[para] class definitions |
||||||
|
if {[info commands [namespace current]::textinfo] eq ""} { |
||||||
|
#*** !doctools |
||||||
|
#[list_begin enumerated] |
||||||
|
|
||||||
|
# oo::class create interface_sample1 { |
||||||
|
# #*** !doctools |
||||||
|
# #[enum] CLASS [class interface_sample1] |
||||||
|
# #[list_begin definitions] |
||||||
|
|
||||||
|
# method test {arg1} { |
||||||
|
# #*** !doctools |
||||||
|
# #[call class::interface_sample1 [method test] [arg arg1]] |
||||||
|
# #[para] test method |
||||||
|
# puts "test: $arg1" |
||||||
|
# } |
||||||
|
|
||||||
|
# #*** !doctools |
||||||
|
# #[list_end] [comment {-- end definitions interface_sample1}] |
||||||
|
# } |
||||||
|
|
||||||
|
|
||||||
|
#uses zero based indexing. Caller can add 1 for line numbers |
||||||
|
oo::class create [namespace current]::textinfo { |
||||||
|
#*** !doctools |
||||||
|
#[enum] CLASS [class textinfo] |
||||||
|
#[list_begin definitions] |
||||||
|
# [para] [emph METHODS] |
||||||
|
|
||||||
|
variable o_chunk |
||||||
|
variable o_chunk_epoch |
||||||
|
variable o_payloadlist |
||||||
|
variable o_linemap |
||||||
|
variable o_line_epoch |
||||||
|
variable o_LF_C |
||||||
|
variable o_CRLF_C |
||||||
|
|
||||||
|
constructor {datachunk args} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method constructor] [arg datachunk] [opt {option value...}]] |
||||||
|
#[para] Constructor for textinfo object which represents a chunk or all of a file |
||||||
|
#[para] datachunk should be passed with the file data including line-endings as-is for full functionality. ie use something like: |
||||||
|
#[example_begin] |
||||||
|
# fconfigure $fd -translation binary |
||||||
|
# set chunkdata [lb]read $fd[rb]] |
||||||
|
#or |
||||||
|
# set chunkdata [lb]fileutil::cat <filename> -translation binary[rb] |
||||||
|
#[example_end] |
||||||
|
#[para] when loading the data |
||||||
|
set o_chunk $datachunk |
||||||
|
set crlf_lf_placeholders [list \uFFFF \uFFFE] ;#defaults - if already exist in file - error out with message |
||||||
|
set defaults [dict create\ |
||||||
|
-substitutionmap {}\ |
||||||
|
-crlf_lf_placeholders $crlf_lf_placeholders\ |
||||||
|
] |
||||||
|
set known_opts [dict keys $defaults] |
||||||
|
foreach {k v} $args { |
||||||
|
if {$k ni $known_opts} { |
||||||
|
error "textinfo::constructor error: unknown option '$k'. Known options: $known_opts" |
||||||
|
} |
||||||
|
} |
||||||
|
set opts [dict merge $defaults $args] |
||||||
|
# -- --- --- --- --- --- --- |
||||||
|
set opt_substitutionmap [dict get $opts -substitutionmap] ;#review - can be done by caller - or a loadable -policy |
||||||
|
set opt_crlf_lf_placeholders [dict get $opts -crlf_lf_placeholders] |
||||||
|
# -- --- --- --- --- --- --- |
||||||
|
|
||||||
|
if {[llength $opt_crlf_lf_placeholders] != 2 || [string length [lindex $opt_crlf_lf_placeholders 0]] !=1 || [string length [lindex $opt_crlf_lf_placeholders 1]] !=1} { |
||||||
|
error "textinfo::constructor error: -crlf_lf_placeholders requires a list of exactly 2 chars" |
||||||
|
} |
||||||
|
lassign $opt_crlf_lf_placeholders o_LF_C o_CRLF_C |
||||||
|
if {[string first $o_LF_C $o_chunk] >=0} { |
||||||
|
set decval [scan $o_LF_C %c] |
||||||
|
if {$decval < 32 || $decval > 127} { |
||||||
|
set char_desc "(decimal value $decval)" |
||||||
|
} else { |
||||||
|
set char_desc "'$o_LF_C' (decimal value $decval)" |
||||||
|
} |
||||||
|
error "textinfo::constructor error: rawfiledata already contains linefeed substitution character $char_desc specified as first element of -crlf_lf_placeholders" |
||||||
|
} |
||||||
|
if {[string first $o_CRLF_C $o_chunk] >=0} { |
||||||
|
set decval [scan $o_CRLF_C %c] |
||||||
|
if {$decval < 32 || $decval > 127} { |
||||||
|
set char_desc "(decimal value $decval)" |
||||||
|
} else { |
||||||
|
set char_desc "'$o_CRLF_C' (decimal value $decval)" |
||||||
|
} |
||||||
|
error "textinfo::constructor error: rawfiledata already contains carriagereturn-linefeed substitution character $char_desc specified as second element of -crlf_lf_placeholders" |
||||||
|
} |
||||||
|
if {$o_LF_C eq $o_CRLF_C} { |
||||||
|
puts stderr "WARNING: same substitution character used for both elements of -crlf_lf_placeholders - byte counting may be off if file contains mixed line-endings" |
||||||
|
} |
||||||
|
set o_chunk_epoch "initial" |
||||||
|
set o_line_epoch "" |
||||||
|
my regenerate_lines |
||||||
|
|
||||||
|
} |
||||||
|
|
||||||
|
method chunk {chunkstart chunkend} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method chunk] [arg chunkstart] [arg chunkend]] |
||||||
|
#[para]Return a range of bytes from the underlying raw chunk data. |
||||||
|
#[para] e.g The following retrieves the entire chunk |
||||||
|
#[para] objName chunk 0 end |
||||||
|
return [string range $o_chunk $chunkstart $chunkend] |
||||||
|
} |
||||||
|
method chunklen {} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method chunklen]] |
||||||
|
#[para] Number of bytes/characters in the raw data of the file |
||||||
|
return [string length $o_chunk] |
||||||
|
} |
||||||
|
method linecount {} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method linecount]] |
||||||
|
#[para] Number of lines in the raw data of the file, counted as per the policy in effect |
||||||
|
return [llength $o_payloadlist] |
||||||
|
} |
||||||
|
|
||||||
|
|
||||||
|
method line {lineindex} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method line] [arg lineindex]] |
||||||
|
#[para]Reconstructs and returns the raw line using the payload and per-line stored line-ending metadata |
||||||
|
#[para]A 'line' may be returned without a line-ending if the unerlying chunk had trailing data without a line-ending (or the chunk was loaded under a non-standard -policy setting) |
||||||
|
#[para]Whilst such data may not conform to definitions (e.g POSIX) of the terms 'textfile' and 'line' - it is useful here to represent it as a line with metadata le set to "none" |
||||||
|
#[para]To return just the data which might more commonly be needed for dealing with lines, use the [method linepayload] method - which returns the line data minus line-ending |
||||||
|
|
||||||
|
lassign [my numeric_linerange $lineindex 0] lineindex |
||||||
|
|
||||||
|
set le [dict get $o_linemap $lineindex le] |
||||||
|
set le_chars [dict get [dict create lf \n crlf \r\n none ""] $le] |
||||||
|
return [lindex $o_payloadlist $lineindex]$le_chars |
||||||
|
} |
||||||
|
method linepayload {lineindex} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method linepayload] [arg lineindex]] |
||||||
|
#[para]Return the text of the line indicated by the zero-based lineindex |
||||||
|
#[para]The line-ending is not returned in the data - but is still stored against this lineindex |
||||||
|
#[para]Line Metadata such as the line-ending for a particular line and the byte/character range it occupies within the chunk can be retrieved with the [method linemeta] method |
||||||
|
#[para]To retrieve both the line text and metadata in a single call the [method lineinfo] method can be used |
||||||
|
#[para]To retrieve an entire line including line-ending use the [method line] method. |
||||||
|
lassign [my numeric_linerange $lineindex 0] lineindex |
||||||
|
return [lindex $o_payloadlist $lineindex] |
||||||
|
} |
||||||
|
method linemeta {lineindex} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method linemeta] [arg lineindex]] |
||||||
|
#[para]Return a dict of the metadata for the line indicated by the zero-based lineindex |
||||||
|
#[para]Keys returned include |
||||||
|
#[list_begin itemized] |
||||||
|
#[item] le |
||||||
|
#[para] A string representing the type of line-ending: crlf|lf|none |
||||||
|
#[item] linelen |
||||||
|
#[para] The number of characters/bytes in the whole line including line-ending if any |
||||||
|
#[item] payloadlen |
||||||
|
#[para] The number of character/bytes in the line excluding line-ending |
||||||
|
#[item] start |
||||||
|
#[para] The zero-based index into the associated raw file data indicating at which byte/character index this line begins |
||||||
|
#[item] end |
||||||
|
#[para] The zero-based index into the associated raw file data indicating at which byte/character index this line ends |
||||||
|
#[para] This end-point corresponds to the last character of the line-ending if any - not necessarily the last character of the line's payload |
||||||
|
#[list_end] |
||||||
|
lassign [my numeric_linerange $lineindex 0] lineindex |
||||||
|
dict get $o_linemap $lineindex |
||||||
|
} |
||||||
|
method lineinfo {lineindex} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method lineinfo] [arg lineindex]] |
||||||
|
#[para]Return a dict of the metadata and text for the line indicated by the zero-based lineindex |
||||||
|
#[para]This returns the same info as the [method linemeta] with an added key of 'payload' which is the text of the line without line-ending. |
||||||
|
#[para]The 'payload' value is the same as is returned from the [method linepayload] method. |
||||||
|
lassign [my numeric_linerange $lineindex 0] lineindex ;#convert lineindex to canonical number e.g 1_000 -> 1000 end -> highest index |
||||||
|
return [dict create lineindex $lineindex {*}[dict get $o_linemap $lineindex] payload [lindex $o_payloadlist $lineindex]] |
||||||
|
} |
||||||
|
method lineinfolist {startidx endidx} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method lineinfolist] [arg startidx] [arg endidx]] |
||||||
|
#[para]Returns list of lineinfo dicts for each line in line index range startidx to endidx |
||||||
|
lassign [my numeric_linerange $startidx $endidx] startidx endidx |
||||||
|
set chunkstart [dict get $o_linemap $startidx start] |
||||||
|
set chunkend [dict get $o_linemap $endidx end] |
||||||
|
set line_list [my chunkrange_to_lineinfolist $chunkstart $chunkend] ;# assert - no need to view truncations as we've picked start and end of complete lines |
||||||
|
#verify sanity |
||||||
|
set l_start [lindex $line_list 0] |
||||||
|
if {[set idx_start [dict get $l_start lineindex]] ne $startidx} { |
||||||
|
error "lineinfolist first lineindex $idx_start doesn't match startidx $startidx" |
||||||
|
} |
||||||
|
set l_end [lindex $line_list end] |
||||||
|
if {[set idx_end [dict get $l_end lineindex]] ne $endidx} { |
||||||
|
error "lineinfolist last lineindex $idx_end doesn't match endidx $endidx" |
||||||
|
} |
||||||
|
return $line_list |
||||||
|
} |
||||||
|
|
||||||
|
method linerange_to_chunkrange {startidx endidx} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method linerange_to_chunkrange] [arg startidx] [arg endidx]] |
||||||
|
|
||||||
|
lassign [my numeric_linerange $startidx $endidx] startidx endidx |
||||||
|
#inclusive range |
||||||
|
return [list [dict get $o_linemap $startidx start] [dict get $o_linemap $endidx end]] |
||||||
|
} |
||||||
|
method linerange_to_chunk {startidx endidx} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method linerange_to_chunk] [arg startidx] [arg endidx]] |
||||||
|
set chunkrange [my linerange_to_chunkrange $startidx $endidx] |
||||||
|
return [string range $o_chunk [lindex $chunkrange 0] [lindex $chunkrange 1]] |
||||||
|
} |
||||||
|
method lines {startidx endidx} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method lines] [arg startidx] [arg endidx]] |
||||||
|
lassign [my numeric_linerange $startidx $endidx] startidx endidx |
||||||
|
set linelist [list] |
||||||
|
set le_map [dict create lf \n crlf \r\n none ""] |
||||||
|
for {set i $startidx} {$i <= $endidx} {incr i} { |
||||||
|
lappend linelist "[lindex $o_payloadlist $i][dict get $le_map [dict get $o_linemap $i le]]" |
||||||
|
} |
||||||
|
return $linelist |
||||||
|
} |
||||||
|
method linepayloads {startidx endidx} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method linepayloads] [arg startidx] [arg endidx]] |
||||||
|
return [lrange $o_payloadlist $startidx $endidx] |
||||||
|
} |
||||||
|
method chunkrange_to_linerange {chunkstart chunkend} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method chunkrange_to_linerange] [arg chunkstart] [arg chunkend]] |
||||||
|
lassign [my numeric_chunkrange $chunkstart $chunkend] chunkstart chunkend |
||||||
|
|
||||||
|
set linestart -1 |
||||||
|
for {set i 0} {$i < [llength $o_payloadlist]} {incr i} { |
||||||
|
if {($chunkstart >= [dict get $o_linemap $i start]) && ($chunkstart <= [dict get $o_linemap $i end])} { |
||||||
|
set linestart $i |
||||||
|
break |
||||||
|
} |
||||||
|
} |
||||||
|
if {$linestart == -1} { |
||||||
|
error "Line with range in chunk spanning start index $chunkstart not found" |
||||||
|
} |
||||||
|
set lineend -1 |
||||||
|
for {set i [expr {[llength $o_payloadlist] -1}]} {$i >=0} {incr i -1} { |
||||||
|
if {($chunkend >= [dict get $o_linemap $i start]) && ($chunkend <= [dict get $o_linemap $i end])} { |
||||||
|
set lineend $i |
||||||
|
break |
||||||
|
} |
||||||
|
} |
||||||
|
if {$lineend == -1} { |
||||||
|
error "Line with range spanning end index $chunkend not found" |
||||||
|
} |
||||||
|
return [list $linestart $lineend] |
||||||
|
} |
||||||
|
method chunkrange_to_lineinfolist {chunkstart chunkend args} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method chunkrange_to_lineinfolist] [arg chunkstart] [arg chunkend] [opt {option value...}]] |
||||||
|
#[para]Return a list of dicts each with structure like the result of the [method lineinfo] method - but possibly with extra keys for truncation information if -show_truncated 1 is supplied |
||||||
|
#[para]The truncation key in a lineinfo dict may be returned for first and/or last line in the resulting list. |
||||||
|
#[para]truncation shows the shortened (missing bytes on left and/or right side) part of the entire line (potentially including line-ending or even partial line-ending) |
||||||
|
#[para]Note that this truncation info is only in the return value of this method - and will not be reflected in [method lineinfo] queries to the main chunk. |
||||||
|
|
||||||
|
lassign [my numeric_chunkrange $chunkstart $chunkend] chunkstart chunkend |
||||||
|
set defaults [dict create\ |
||||||
|
-show_truncated 0\ |
||||||
|
] |
||||||
|
set known_opts [dict keys $defaults] |
||||||
|
foreach {k v} $args { |
||||||
|
if {$k ni $known_opts} { |
||||||
|
error "chunkrange_to_lines error: unknown option '$k'. Known options: $known_opts" |
||||||
|
} |
||||||
|
} |
||||||
|
set opts [dict merge $defaults $args] |
||||||
|
# -- --- --- --- --- --- --- --- |
||||||
|
set opt_show_truncated [dict get $opts -show_truncated] |
||||||
|
# -- --- --- --- --- --- --- --- |
||||||
|
|
||||||
|
set infolist [list] |
||||||
|
set linerange [my chunkrange_to_linerange $chunkstart $chunkend] |
||||||
|
lassign $linerange start_lineindex end_lineindex |
||||||
|
|
||||||
|
#if -show_truncated |
||||||
|
#return extra keys for first and last items (which may be the same item if chunkrange is entirely within a line) |
||||||
|
#add is_truncated 0|1 to all lines |
||||||
|
#Even if the start/end line is not fully within the chunkrange ie truncated - the 'payload' key will contain the original untruncated data |
||||||
|
########################### |
||||||
|
# first line may have payload tail truncated - or just linefeed, or even a split linefeed |
||||||
|
########################### |
||||||
|
set first [dict create lineindex $start_lineindex {*}[dict get $o_linemap $start_lineindex] payload [lindex $o_payloadlist $start_lineindex]] |
||||||
|
set start_info [dict get $o_linemap $start_lineindex] |
||||||
|
if {$opt_show_truncated} { |
||||||
|
#line1 |
||||||
|
if {$chunkstart > [dict get $start_info start]} { |
||||||
|
#there is lhs truncation |
||||||
|
set payload [lindex $o_payloadlist $start_lineindex] |
||||||
|
set line_start [dict get $start_info start] |
||||||
|
set le_chars [dict get [dict create lf \n crlf \r\n none ""] [dict get $start_info le]] |
||||||
|
set payload_and_le "${payload}${le_chars}" |
||||||
|
set split [expr {$chunkstart - $line_start}] |
||||||
|
set truncated [string range $payload_and_le $split end] |
||||||
|
set lhs [string range $payload_and_le 0 $split-1] |
||||||
|
|
||||||
|
dict set first truncated $truncated |
||||||
|
dict set first truncatedside [list left] ;#truncatedside is a list which may have 'right' added if last line is same as first line |
||||||
|
dict set first truncatedleft $lhs |
||||||
|
dict set first is_truncated 1 |
||||||
|
} else { |
||||||
|
dict set first is_truncated 0 |
||||||
|
} |
||||||
|
} |
||||||
|
########################### |
||||||
|
|
||||||
|
########################### |
||||||
|
# middle lines if any - no truncation |
||||||
|
########################### |
||||||
|
#difference in indexes of 1 would only mean 2 items to return |
||||||
|
set middle_list [list] |
||||||
|
if {($end_lineindex - $start_lineindex) > 1} { |
||||||
|
for {set i [expr {$start_lineindex +1}]} {$i <= [expr {$end_lineindex -1}] } {incr i} { |
||||||
|
#lineindex is key into main list |
||||||
|
lappend middle_list [dict create lineindex $i {*}[dict get $o_linemap $i] payload [lindex $o_payloadlist $i] is_truncated 0] |
||||||
|
} |
||||||
|
} |
||||||
|
########################### |
||||||
|
|
||||||
|
########################### |
||||||
|
# tail line may have beginning or all of payload truncated - linefeed may be split if crlf |
||||||
|
# may be same line as first line - in which case truncation at beginning as well |
||||||
|
if {$end_lineindex == $start_lineindex} { |
||||||
|
#same record |
||||||
|
set end_info $start_info |
||||||
|
if {$opt_show_truncated} { |
||||||
|
if {$chunkend < [dict get $end_info end]} { |
||||||
|
#lhere is rhs truncation |
||||||
|
if {[dict get $first is_truncated]} { |
||||||
|
dict set first truncatedside [list left right] |
||||||
|
} else { |
||||||
|
dict set first is_truncated 1 |
||||||
|
dict set first truncatedside [list right] |
||||||
|
} |
||||||
|
#do rhs truncation - possibly in addition to existing lhs truncation |
||||||
|
# ... |
||||||
|
if {"left" ni [dict get $first truncatedside]} { |
||||||
|
#rhs truncation only |
||||||
|
set payload [lindex $o_payloadlist $end_lineindex] |
||||||
|
set line_start [dict get $end_info start] |
||||||
|
set le_chars [dict get [dict create lf \n crlf \r\n none ""] [dict get $end_info le]] |
||||||
|
set payload_and_le "${payload}${le_chars}" |
||||||
|
puts "payload_and_le: $payload_and_le" |
||||||
|
puts "LENGHT: [string length $payload_and_le]" |
||||||
|
#--- |
||||||
|
set split [expr {$chunkend - $line_start}] |
||||||
|
set truncated [string range $payload_and_le 0 $split] |
||||||
|
set rhs [string range $payload_and_le $split+1 end] |
||||||
|
#--- |
||||||
|
dict set first truncated $truncated |
||||||
|
dict set first truncatedside [list right] |
||||||
|
dict set first truncatedright $rhs |
||||||
|
} else { |
||||||
|
#truncated on both sides |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
#no middle or last to append |
||||||
|
lappend infolist $first |
||||||
|
} else { |
||||||
|
set last [dict create lineindex $end_lineindex {*}[dict get $o_linemap $end_lineindex] payload [lindex $o_payloadlist $end_lineindex]] |
||||||
|
set end_info [dict get $o_linemap $end_lineindex] |
||||||
|
if {$opt_show_truncated} { |
||||||
|
if {$chunkend < [dict get $end_info end]} { |
||||||
|
#there is rhs truncation - and last line in range is a different line to first one |
||||||
|
dict set last is_truncated 1 |
||||||
|
set payload [lindex $o_payloadlist $end_lineindex] |
||||||
|
set line_start [dict get $end_info start] |
||||||
|
set line_end [dict get $end_info end] |
||||||
|
set le [dict get $end_info le] |
||||||
|
set le_size [dict get {lf 1 crlf 2 none 0} $le] |
||||||
|
set le_chars [dict get [dict create lf \n crlf \r\n none ""] $le] |
||||||
|
set payload_and_le "${payload}${le_chars}" |
||||||
|
|
||||||
|
set split [expr {$chunkend - $line_start}] |
||||||
|
set truncated [string range $payload_and_le 0 $split] |
||||||
|
set rhs [string range $payload_and_le $split+1 end] |
||||||
|
|
||||||
|
dict set last truncated $truncated |
||||||
|
dict set last truncatedside [list right] |
||||||
|
dict set last truncatedright $rhs |
||||||
|
#this has the effect that truncating the rhs by 1 can result in truncated being larger than original payload for crlf lines - as payload now sees the cr |
||||||
|
#this is a bit unintuitive - but probably best reflects the reality. The truncated value is the truncated 'line' rather than the truncated 'payload' |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
|
||||||
|
lappend infolist $first |
||||||
|
if {[llength $middle_list]} { |
||||||
|
lappend infolist {*}$middle_list |
||||||
|
} |
||||||
|
lappend infolist $last |
||||||
|
} |
||||||
|
########################### |
||||||
|
|
||||||
|
return $infolist |
||||||
|
} |
||||||
|
|
||||||
|
method chunk_le_counts {chunkstart chunkend} { |
||||||
|
set infolines [my chunkrange_to_lineinfolist $chunkstart $chunkend] |
||||||
|
set lf_count 0 |
||||||
|
set crlf_count 0 |
||||||
|
set none_count 0 |
||||||
|
foreach d $infolines { |
||||||
|
set le [dict get $d le] |
||||||
|
if {$le eq "lf"} { |
||||||
|
incr lf_count |
||||||
|
} elseif {$le eq "crlf"} { |
||||||
|
incr crlf_count |
||||||
|
} else { |
||||||
|
incr none_count |
||||||
|
} |
||||||
|
} |
||||||
|
return [dict create lf $lf_count crlf $crlf_count unterminated $none_count] |
||||||
|
} |
||||||
|
|
||||||
|
#todo - test last line and merge as necessary with first line from new chunk - generate line data only for appended chunk |
||||||
|
method append_chunk {rawchunk} { |
||||||
|
error "sorry - unimplemented" |
||||||
|
} |
||||||
|
|
||||||
|
method numeric_linerange {startidx endidx} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method numeric_linerange] [arg startidx] [arg endidx]] |
||||||
|
#[para]A helper to return any Tcl-style end end-x values given to startidx or endidx; converted to their specific values based on the current state of the underlying line data |
||||||
|
#[para]This is used internally by API functions such as [method line] to enable it to accept more expressive indices |
||||||
|
return [my normalize_indices $startidx $endidx [expr {[dict size $o_linemap]-1}]] |
||||||
|
} |
||||||
|
method numeric_chunkrange {startidx endidx} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method numeric_chunkrange] [arg startidx] [arg endidx]] |
||||||
|
#[para]A helper to return any Tcl-style end end-x entries supplied to startidx or endidx; converted to their specific values based on the current state of the underlying chunk data |
||||||
|
return [my normalize_indices $startidx $endidx [expr {[string length $o_chunk]-1}]] |
||||||
|
} |
||||||
|
method normalize_indices {startidx endidx max} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method normalize_indices] [arg startidx] [arg endidx] [arg max]] |
||||||
|
#[para]A utility to convert some of the of Tcl-style list-index expressions such as end, end-1 etc to valid indices in the range 0 to the supplied max |
||||||
|
#[para]Basic addition and subtraction expressions such as 4-1 5+2 are accepted |
||||||
|
#[para]startidx higher than endidx is allowed |
||||||
|
#[para]Unlike Tcl's index expressions - we raise an error if the calculated index is out of bounds 0 to max |
||||||
|
set original_startidx $startidx |
||||||
|
set original_endidx $endidx |
||||||
|
set startidx [string map [list _ ""] $startidx] ;#don't barf on Tcl 8.7+ underscores in numbers - we can't just use expr because it will not handle end-x |
||||||
|
set endidx [string map [list _ ""] $endidx] |
||||||
|
if {![string is digit -strict "$startidx$endidx"]} { |
||||||
|
foreach whichvar [list start end] { |
||||||
|
upvar 0 ${whichvar}idx index |
||||||
|
if {![string is digit -strict $index]} { |
||||||
|
if {"end" eq $index} { |
||||||
|
set index $max |
||||||
|
} elseif {[string match "*-*" $index]} { |
||||||
|
#end-int or int-int - like lrange etc we don't accept arbitrarily complex expressions |
||||||
|
lassign [split $index -] A B |
||||||
|
if {$A eq "end"} { |
||||||
|
set index [expr {$max - $B}] |
||||||
|
} else { |
||||||
|
set index [expr {$A - $B}] |
||||||
|
} |
||||||
|
} elseif {[string match "*+*" $index]} { |
||||||
|
lassign [split $index +] A B |
||||||
|
if {$A eq "end"} { |
||||||
|
#review - this will just result in out of bounds error in final test - as desired |
||||||
|
#By calculating here - we will see the result in the error message - but it's probably not particularly useful - as we don't really need end+ support at all. |
||||||
|
set index [expr {$max + $B}] |
||||||
|
} else { |
||||||
|
set index [expr {$A + $B}] |
||||||
|
} |
||||||
|
} else { |
||||||
|
#May be something like +2 or -0 which braced expr can hanle |
||||||
|
#we would like to avoid unbraced expr here - as we're potentially dealing with ranges that may come from external sources. |
||||||
|
if {[catch {expr {$index}} index]} { |
||||||
|
#could be end+x - but we don't want out of bounds to be valid |
||||||
|
#set it to something that the final bounds expr test can deal with |
||||||
|
set index Inf |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
#Unlike Tcl lrange,lindex etc - we don't want to support out of bound indices. |
||||||
|
#show the supplied index and what it was mapped to in the error message. |
||||||
|
if {$startidx < 0 || $startidx > $max} { |
||||||
|
error "Bad start index '$original_startidx'. $startidx out of bounds 0 - $max" |
||||||
|
} |
||||||
|
if {$endidx < 0 || $endidx > $max} { |
||||||
|
error "Bad end index '$original_endidx'. $endidx out of bounds 0 - $max" |
||||||
|
} |
||||||
|
return [list $startidx $endidx] |
||||||
|
} |
||||||
|
|
||||||
|
method regenerate_lines {} { |
||||||
|
#*** !doctools |
||||||
|
#[call class::textinfo [method regenerate_lines]] |
||||||
|
#[para]generate a list of lines from the current state of the stored raw data chunk and keep a map of line-endings indexed by lineindex |
||||||
|
#[para]This is called automatically by the Constructor during object creation |
||||||
|
#[para]It is exposed in the API experimentally - as chunk and line manipulation functions are considered. |
||||||
|
#[para]TODO - review whether such manual control will be necessary/desirable |
||||||
|
|
||||||
|
#we don't store the actual line-endings as characters (for better layout of debug/display of data) - instead we store names lf|crlf|none |
||||||
|
|
||||||
|
# first split on lf - then crlf. As we've replaced with single substution chars - the order doesn't matter. |
||||||
|
set o_payloadlist [list] |
||||||
|
set o_linemap [dict create] |
||||||
|
set crlf_replace [list \r\n $o_CRLF_C \n $o_LF_C] |
||||||
|
set normalised_data [string map $crlf_replace $o_chunk] |
||||||
|
|
||||||
|
set lf_lines [split $normalised_data $o_LF_C] |
||||||
|
|
||||||
|
set idx 0 |
||||||
|
set lf_count 0 |
||||||
|
set crlf_count 0 |
||||||
|
set filedata_offset 0 |
||||||
|
set i 0 |
||||||
|
set imax [expr {[llength $lf_lines]-1}] |
||||||
|
foreach lfln $lf_lines { |
||||||
|
set crlf_parts [split $lfln $o_CRLF_C] |
||||||
|
if {[llength $crlf_parts] <= 1} { |
||||||
|
#no crlf |
||||||
|
set payloadlen [string length $lfln] |
||||||
|
set le_size 1 |
||||||
|
set le lf |
||||||
|
if {$i == $imax} { |
||||||
|
#no more lf segments - and no crlfs |
||||||
|
if {$payloadlen > 0} { |
||||||
|
#last line in split has chars - therefore there was no trailing line-ending |
||||||
|
set le_size 0 |
||||||
|
set le none |
||||||
|
} else { |
||||||
|
#empty space after last line-ending |
||||||
|
#not really a line - we get here from splitting on our lf-replacement char |
||||||
|
#An editor might display this pseudo-line with a line number - but we won't treat it as one here |
||||||
|
break |
||||||
|
} |
||||||
|
} |
||||||
|
lappend o_payloadlist $lfln |
||||||
|
set linelen [expr {$payloadlen + $le_size}] |
||||||
|
#we include line-ending in byte count for a line. |
||||||
|
dict set o_linemap $idx [list le $le linelen $linelen payloadlen $payloadlen start $filedata_offset end [expr {$filedata_offset + $linelen -1}]] |
||||||
|
incr filedata_offset $linelen |
||||||
|
incr lf_count |
||||||
|
incr idx |
||||||
|
} else { |
||||||
|
foreach crlfpart [lrange $crlf_parts 0 end-1] { |
||||||
|
lappend o_payloadlist $crlfpart |
||||||
|
set payloadlen [string length $crlfpart] |
||||||
|
set linelen [expr {$payloadlen + 2}] |
||||||
|
dict set o_linemap $idx [list le crlf linelen $linelen payloadlen $payloadlen start $filedata_offset end [expr {$filedata_offset + $linelen -1}]] |
||||||
|
incr filedata_offset $linelen |
||||||
|
incr crlf_count |
||||||
|
incr idx |
||||||
|
} |
||||||
|
set lfpart [lindex $crlf_parts end] |
||||||
|
set payloadlen [string length $lfpart] |
||||||
|
if {$i == $imax} { |
||||||
|
#no more lf segments - but we did find crlf in last (or perhaps only) lf line |
||||||
|
#last element must be an empty crlf line or has no le |
||||||
|
if {$payloadlen > 0} { |
||||||
|
set le_size 0 |
||||||
|
set le none |
||||||
|
} else { |
||||||
|
#set le_size 2 |
||||||
|
#set le crlf |
||||||
|
break |
||||||
|
} |
||||||
|
} else { |
||||||
|
#more lf segments to come |
||||||
|
#last element must be an empty lf line or has no le |
||||||
|
if {$payloadlen > 0} { |
||||||
|
set le_size 0 |
||||||
|
set le none |
||||||
|
} else { |
||||||
|
set le_size 1 |
||||||
|
set le lf |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
lappend o_payloadlist $lfpart |
||||||
|
set linelen [expr {$payloadlen + $le_size}] |
||||||
|
dict set o_linemap $idx [list le $le linelen $linelen payloadlen $payloadlen start $filedata_offset end [expr {$filedata_offset + $linelen -1}]] |
||||||
|
incr filedata_offset $linelen |
||||||
|
incr lf_count |
||||||
|
incr idx |
||||||
|
} |
||||||
|
incr i |
||||||
|
#incr filedata_offset ;#move up 1 so start entry for next line is greater than end entry for previous line |
||||||
|
} |
||||||
|
set le_count [expr {$lf_count + $crlf_count}] |
||||||
|
if {$le_count != [llength $o_payloadlist]} { |
||||||
|
puts stderr "fileline::class::textinfo warning. regenerate_lines lf_count: $lf_count + crlf_count: $crlf_count does not equal length of lines stored: [llength $o_payloadlist]" |
||||||
|
} |
||||||
|
|
||||||
|
} |
||||||
|
method regenerate_chunk {} { |
||||||
|
|
||||||
|
} |
||||||
|
|
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[list_end] |
||||||
|
} |
||||||
|
#*** !doctools |
||||||
|
#[list_end] [comment {--- end class enumeration ---}] |
||||||
|
} |
||||||
|
} |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
|
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
# Base namespace |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
namespace eval punk::fileline { |
||||||
|
namespace export * |
||||||
|
#variable xyz |
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[subsection {Namespace punk::fileline}] |
||||||
|
#[para] Core API functions for punk::fileline |
||||||
|
#[list_begin definitions] |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[list_end] [comment {--- end definitions namespace punk::fileline ---}] |
||||||
|
} |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
|
||||||
|
|
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
# Secondary API namespace |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
namespace eval punk::fileline::lib { |
||||||
|
namespace export * |
||||||
|
namespace path [namespace parent] |
||||||
|
#*** !doctools |
||||||
|
#[subsection {Namespace punk::fileline::lib}] |
||||||
|
#[para] Secondary functions that are part of the API |
||||||
|
#[list_begin definitions] |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
proc range_spans_chunk_boundaries {start end chunksize} { |
||||||
|
#*** !doctools |
||||||
|
#[call [fun lib::range_spans_chunk_boundaries] [arg start] [arg end] [arg chunksize]] |
||||||
|
#[para]Takes start and end offset, generally representing bytes or character indices, and computes a list of boundaries at multiples of the chunksize that are spanned by the start and end range. |
||||||
|
#[list_begin arguments] |
||||||
|
# [arg_def integer start] |
||||||
|
# [para] zero-based start index of range |
||||||
|
# [arg_def integer end] |
||||||
|
# [para] zero-based end index of range |
||||||
|
# [arg_def integer chunksize] |
||||||
|
# [para] Number of bytes/characters in chunk |
||||||
|
#[list_end] |
||||||
|
#[para]returns a dict with the keys is_span and boundaries |
||||||
|
#[para]is_span 0|1 indicates if the range specified spans a boundary of chunksize |
||||||
|
#[para]boundaries contains a list of the spanned boundaries - which are always multiples of the chunksize |
||||||
|
#[para]e.g |
||||||
|
#[example_begin] |
||||||
|
# range_spans_chunk_boundaries 10 1750 512 |
||||||
|
# is_span 1 boundaries {512 1024 1536} |
||||||
|
#[example_end] |
||||||
|
#[para] This function automatically uses lseq (if Tcl >= 8.7) when number of boundaries spanned is approximately greater than 75 |
||||||
|
if {[catch {package require Tcl 8.7}]} { |
||||||
|
#only one implementation available for older Tcl |
||||||
|
tailcall punk::fileline::system::_range_spans_chunk_boundaries_tcl $start $end $chunksize |
||||||
|
} |
||||||
|
if {(($end - $start) / $chunksize) < 75} { |
||||||
|
tailcall punk::fileline::system::_range_spans_chunk_boundaries_tcl $start $end $chunksize |
||||||
|
} else { |
||||||
|
tailcall punk::fileline::system::_range_spans_chunk_boundaries_lseq $start $end $chunksize |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[list_end] [comment {--- end definitions namespace punk::fileline::lib ---}] |
||||||
|
} |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
#*** !doctools |
||||||
|
#[section Internal] |
||||||
|
namespace eval punk::fileline::system { |
||||||
|
#*** !doctools |
||||||
|
#[subsection {Namespace punk::fileline::system}] |
||||||
|
#[para] Internal functions that are not part of the API |
||||||
|
|
||||||
|
|
||||||
|
#for 8.7+ using lseq |
||||||
|
#much faster when resultant boundary size is large |
||||||
|
proc _range_spans_chunk_boundaries_lseq {start end chunksize} { |
||||||
|
set smod [expr {$start % $chunksize}] |
||||||
|
if {$smod != 0} { |
||||||
|
set start [expr {$start + ($chunksize - $smod)}] |
||||||
|
if {$start > $end} { |
||||||
|
return [list is_span 0 boundaries {}] |
||||||
|
} |
||||||
|
} |
||||||
|
set boundaries [lseq $start to $end $chunksize] |
||||||
|
return [list is_span [expr {[llength $boundaries]>0}] boundaries $boundaries] |
||||||
|
} |
||||||
|
|
||||||
|
#faster than lseq for small number of resultant boundaries (~< 75) (which is a common use case) |
||||||
|
#gets very slow (comparitively) with large resultsets |
||||||
|
proc _range_spans_chunk_boundaries_tcl {start end chunksize} { |
||||||
|
set is_span 0 |
||||||
|
set smod [expr {$start % $chunksize}] |
||||||
|
if {$smod != 0} { |
||||||
|
set start [expr {$start + ($chunksize - $smod)}] |
||||||
|
} |
||||||
|
set boundaries [list] |
||||||
|
for {set b $start} {$b <= $end} {incr b $chunksize} { |
||||||
|
lappend boundaries $b |
||||||
|
} |
||||||
|
return [list is_span [expr {[llength $boundaries]>0}] boundaries $boundaries] |
||||||
|
} |
||||||
|
|
||||||
|
proc _range_spans_chunk_boundaries_TIMEIT {start end chunksize {repeat 1}} { |
||||||
|
puts "main : [time {punk::fileline::lib::range_spans_chunk_boundaries $start $end $chunksize} $repeat]" |
||||||
|
puts "tcl : [time {punk::fileline::system::_range_spans_chunk_boundaries_tcl $start $end $chunksize} $repeat]" |
||||||
|
if {![catch {package require Tcl 8.7}]} { |
||||||
|
puts "lseq : [time {punk::fileline::system::_range_spans_chunk_boundaries_lseq $start $end $chunksize} $repeat]" |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
|
# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++ |
||||||
|
## Ready |
||||||
|
package provide punk::fileline [namespace eval punk::fileline { |
||||||
|
variable pkg punk::fileline |
||||||
|
variable version |
||||||
|
set version 999999.0a1.0 |
||||||
|
}] |
||||||
|
return |
||||||
|
|
||||||
|
#*** !doctools |
||||||
|
#[manpage_end] |
||||||
|
|
||||||
@ -0,0 +1,3 @@ |
|||||||
|
0.1.0 |
||||||
|
#First line must be a semantic version number |
||||||
|
#all other lines are ignored. |
||||||
Loading…
Reference in new issue