You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
401 lines
25 KiB
401 lines
25 KiB
<!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> |
|
<li class="doctools_subsection"><a href="#subsection4">optional dependencies</a></li> |
|
</ul> |
|
</li> |
|
<li class="doctools_section"><a href="#section3">API</a> |
|
<ul> |
|
<li class="doctools_subsection"><a href="#subsection5">Namespace punk::fileline::class</a></li> |
|
<li class="doctools_subsection"><a href="#subsection6">Namespace punk::fileline</a></li> |
|
<li class="doctools_subsection"><a href="#subsection7">Namespace punk::fileline::lib</a></li> |
|
</ul> |
|
</li> |
|
<li class="doctools_section"><a href="#section4">Internal</a> |
|
<ul> |
|
<li class="doctools_subsection"><a href="#subsection8">Namespace punk::fileline::system</a></li> |
|
<li class="doctools_subsection"><a href="#subsection9">Namespace punk::fileline::ansi</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">chunk_boundary_display</b></a></li> |
|
<li><a href="#5">class::textinfo <b class="method">linecount</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_find_glob</b> <i class="arg">globsearch</i> <span class="opt">?option value...?</span></a></li> |
|
<li><a href="#8">class::textinfo <b class="method">linepayload</b> <i class="arg">lineindex</i></a></li> |
|
<li><a href="#9">class::textinfo <b class="method">linepayloads</b> <i class="arg">startindex</i> <i class="arg">endindex</i></a></li> |
|
<li><a href="#10">class::textinfo <b class="method">linemeta</b> <i class="arg">lineindex</i></a></li> |
|
<li><a href="#11">class::textinfo <b class="method">lineinfo</b> <i class="arg">lineindex</i></a></li> |
|
<li><a href="#12">class::textinfo <b class="method">lineinfolist</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
|
<li><a href="#13">class::textinfo <b class="method">linerange_to_chunkrange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
|
<li><a href="#14">class::textinfo <b class="method">linerange_to_chunk</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
|
<li><a href="#15">class::textinfo <b class="method">lines</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
|
<li><a href="#16">class::textinfo <b class="method">linepayloads</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
|
<li><a href="#17">class::textinfo <b class="method">chunkrange_to_linerange</b> <i class="arg">chunkstart</i> <i class="arg">chunkend</i></a></li> |
|
<li><a href="#18">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="#19">class::textinfo <b class="method">numeric_linerange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
|
<li><a href="#20">class::textinfo <b class="method">numeric_chunkrange</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></li> |
|
<li><a href="#21">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="#22">class::textinfo <b class="method">regenerate_lines</b></a></li> |
|
<li><a href="#23">get_textinfo <span class="opt">?option value...?</span> <span class="opt">?datachunk?</span></a></li> |
|
<li><a href="#24"><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> |
|
<li><a href="#25"><b class="function">ansi::a</b></a></li> |
|
<li><a href="#26"><b class="function">ansi::a+</b></a></li> |
|
<li><a href="#27"><b class="function">ansi::stripansi</b></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>This chunk-size counting will depend on the character encoding.</p> |
|
<p>Despite including the word 'file', the library doesn't necessarily deal with reading/writing to the filesystem -</p> |
|
<p>The raw data can be supplied as a string, or loaded from a file using punk::fileline::get_textinfo -file <filename></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 needed by punk::fileline</p> |
|
<ul class="doctools_itemized"> |
|
<li><p><b class="package">Tcl 8.6-</b></p></li> |
|
<li><p><b class="package">punk::args</b></p></li> |
|
</ul> |
|
</div> |
|
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">optional dependencies</a></h3> |
|
<p>packages that add functionality but aren't strictly required</p> |
|
<ul class="doctools_itemized"> |
|
<li><p><b class="package">punk::ansi</b></p> |
|
<p>- recommended for class::textinfo <b class="method">chunk_boundary_display</b></p></li> |
|
<li><p><b class="package">punk::char</b></p> |
|
<p>- recommended for class::textinfo <b class="method">chunk_boundary_display</b></p></li> |
|
<li><p><b class="package">overtype</b></p> |
|
<p>- recommended for class::textinfo <b class="method">chunk_boundary_display</b></p></li> |
|
</ul> |
|
</div> |
|
</div> |
|
<div id="section3" class="doctools_section"><h2><a name="section3">API</a></h2> |
|
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">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">chunk_boundary_display</b></a></dt> |
|
<dd><p>Returns a string displaying the boundaries at chunksize bytes between chunkstart and chunkend</p> |
|
<p>Defaults to using ansi colour if punk::ansi module is available. Use -ansi 0 to disable colour</p></dd> |
|
<dt><a name="5">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="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_find_glob</b> <i class="arg">globsearch</i> <span class="opt">?option value...?</span></a></dt> |
|
<dd><p>Return a lineinfolist (see <b class="method">lineinfo</b> and <b class="method">lineinfolist</b>) of lines where payload matches the <i class="arg">globsearch</i> string</p> |
|
<p>To limit the returned results use the -limit n option - where -limit 0 means return all matches.</p> |
|
<p>For example: <b class="method">linepayload_find_glob</b> "*test*" -limit 1</p> |
|
<p>The result is always a list of lineinfo dictionaries even if one item is returned</p> |
|
<p>-limitfrom can be start|end</p> |
|
<p>The order of results is always the order as they occur in the data - even if -limitfrom end is specified.</p> |
|
<p>-limitfrom end means that only the last -limit items are returned</p> |
|
<p>Note that as glob accepts [chars]] to mean match any character in the set given by chars, searching for literal square brackets should be done by escaping the bracket with a backslash</p> |
|
<p>This is true even if only a single square bracket is being searched for. e.g {*[file*} will not find the word file followed by a left square-bracket - even though the search didn't close the square brackets.</p> |
|
<p>In the above case - the literal search should be {*\[file*}</p></dd> |
|
<dt><a name="8">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="9">class::textinfo <b class="method">linepayloads</b> <i class="arg">startindex</i> <i class="arg">endindex</i></a></dt> |
|
<dd><p>Return a list of just the payloads in the specified linindex range, with no metadata.</p></dd> |
|
<dt><a name="10">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="11">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="12">class::textinfo <b class="method">lineinfolist</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
|
<dd><p>Returns list of lineinfo dicts for each line in line index range startidx to endidx</p></dd> |
|
<dt><a name="13">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="14">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="15">class::textinfo <b class="method">lines</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
|
<dd></dd> |
|
<dt><a name="16">class::textinfo <b class="method">linepayloads</b> <i class="arg">startidx</i> <i class="arg">endidx</i></a></dt> |
|
<dd></dd> |
|
<dt><a name="17">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="18">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="19">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="20">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="21">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> |
|
<dt><a name="22">class::textinfo <b class="method">regenerate_lines</b></a></dt> |
|
<dd><p>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</p> |
|
<p>This is called automatically by the Constructor during object creation</p> |
|
<p>It is exposed in the API experimentally - as chunk and line manipulation functions are considered.</p> |
|
<p>TODO - review whether such manual control will be necessary/desirable</p></dd> |
|
</dl> |
|
</li> |
|
</ol> |
|
</div> |
|
<div id="subsection6" class="doctools_subsection"><h3><a name="subsection6">Namespace punk::fileline</a></h3> |
|
<p>Core API functions for punk::fileline</p> |
|
<dl class="doctools_definitions"> |
|
<dt><a name="23">get_textinfo <span class="opt">?option value...?</span> <span class="opt">?datachunk?</span></a></dt> |
|
<dd><p>Returns textinfo object instance representing data in string datachunk or if -file filename supplied - data loaded from a file</p> |
|
<p>The encoding used is as specified in the -encoding option - or from the Byte Order Mark (bom) at the beginning of the data</p> |
|
<p>For Tcl 8.6 - encodings such as utf-16le may not be available - so the bytes are swapped appropriately depending on the platform byteOrder and encoding 'unicode' is used.</p> |
|
<p>encoding defaults to utf-8 if no -encoding specified and no BOM was found</p> |
|
<p>Specify -encoding binary to perform no encoding conversion</p> |
|
<p>Whether -encoding was specified or not - by default the BOM characters are not retained in the line-data</p> |
|
<p>If -includebom 1 is specified - the bom will be retained in the stored chunk and the data for line 1, but will undergo the same encoding transformation as the rest of the data</p> |
|
<p>The get_bomid method of the returned object will contain an identifier for any BOM encountered.</p> |
|
<p>e.g utf-8,utf-16be, utf-16le, utf-32be, utf32-le, SCSU, BOCU-1,GB18030, UTF-EBCDIC, utf-1, utf-7</p> |
|
<p>If the encoding specified in the BOM isn't recognised by Tcl - the resulting data is likely to remain as the raw bytes (binary translation)</p> |
|
<p>Currently only utf-8, utf-16* and utf-32* are properly supported even though the other BOMs are detected, reported via get_bomid, and stripped from the data.</p> |
|
<p>GB18030 falls back to cp936/gbk (unless a gb18030 encoding has been installed). Use -encoding binary if this isn't suitable and you need to do your own processing of the raw data.</p></dd> |
|
</dl> |
|
</div> |
|
<div id="subsection7" class="doctools_subsection"><h3><a name="subsection7">Namespace punk::fileline::lib</a></h3> |
|
<p>Secondary functions that are part of the API</p> |
|
<dl class="doctools_definitions"> |
|
<dt><a name="24"><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 - must be positive and > 0</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>The -offset <int> option</p> |
|
<pre class="doctools_example"> |
|
range_spans_chunk_boundaries 10 1750 512 -offset 2 |
|
is_span 1 boundaries {514 1026 1538} |
|
</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="subsection8" class="doctools_subsection"><h3><a name="subsection8">Namespace punk::fileline::system</a></h3> |
|
<p>Internal functions that are not part of the API</p> |
|
</div> |
|
<div id="subsection9" class="doctools_subsection"><h3><a name="subsection9">Namespace punk::fileline::ansi</a></h3> |
|
<p>These are ansi functions imported from punk::ansi - or no-ops if that package is unavailable</p> |
|
<p>See <b class="package">punk::ansi</b> for documentation</p> |
|
<dl class="doctools_definitions"> |
|
<dt><a name="25"><b class="function">ansi::a</b></a></dt> |
|
<dd></dd> |
|
<dt><a name="26"><b class="function">ansi::a+</b></a></dt> |
|
<dd></dd> |
|
<dt><a name="27"><b class="function">ansi::stripansi</b></a></dt> |
|
<dd></dd> |
|
</dl> |
|
</div> |
|
</div> |
|
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2> |
|
<p><a href="../../../index.html#bom">BOM</a>, <a href="../../../index.html#encoding">encoding</a>, <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>
|
|
|