From 8cbe7fc4b609a8852164d819c9bafcb568dbd70a Mon Sep 17 00:00:00 2001 From: FatalErr42O <58855799+FatalError42O@users.noreply.github.com> Date: Mon, 8 Jan 2024 18:16:41 -0800 Subject: [PATCH] general cleanup, documented binary --- docs/index.html | 280 ++++++++++++++++++++++++++++++++++++++++++ docs/ldoc.css | 304 ++++++++++++++++++++++++++++++++++++++++++++++ modlib/binary.lua | 110 +++++++++++------ 3 files changed, 658 insertions(+), 36 deletions(-) create mode 100644 docs/index.html create mode 100644 docs/ldoc.css diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..e0712b8 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,280 @@ + + + + + MTUL core + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module binary

+

read and write (little endian) binary.

+

located in mtul.binary.

+ + +

reading binary inputs

+ + + + + + + + + + + + + + + + + +
read_single (function)read an IEEE 754 single precision (32-bit) floating point number
read_double (function)read an IEEE 754 double-precision (64-bit) floating point number
read_uint (function, int)read an unsigned integer of any given length
read_uint (function, int)read a signed integer of any given length
+

misc binary helpers

+ + + + + +
fround (number)"returns nearest 32-bit single precision float representation of a number" (or something)
+

expected function inputs

+ + + + + + + + + +
read_byte ()read_byte is a param name which refers to a function which reads the next byte- returning a whole number between 0-255.
write_byte ()write_byte is similar to read_byte, however it is given an input and expected to write it to the file.
+ +
+
+ + +

reading binary inputs

+ +
+ read a binary inputs using a read_byte function. +
+
+
+ + read_single (function) +
+
+ read an IEEE 754 single precision (32-bit) floating point number + + +

Parameters:

+ + + + + + +
+
+ + read_double (function) +
+
+ read an IEEE 754 double-precision (64-bit) floating point number + + +

Parameters:

+ + + + + + +
+
+ + read_uint (function, int) +
+
+ read an unsigned integer of any given length + + +

Parameters:

+
    +
  • function + read_byte +
    • +
  • int + length in bytes of unsigned integer +
    • +
+ + + + + +
+
+ + read_uint (function, int) +
+
+ read a signed integer of any given length + + +

Parameters:

+
    +
  • function + read_byte +
    • +
  • int + length in bytes of integer +
    • +
+ + + + + +
+
+

misc binary helpers

+ +
+
+ + fround (number) +
+
+ "returns nearest 32-bit single precision float representation of a number" (or something) + + +

Parameters:

+
    +
  • number + + + +
    • +
+ +

Returns:

+
    + + nearest 32-bit single precision float representation of a number +
+ + + + +
+
+

expected function inputs

+ +
+ functions will expect either a read_byte or write_byte function as inputs +
+
+
+ + read_byte () +
+
+ +

read_byte is a param name which refers to a function which reads the next byte- returning a whole number between 0-255.

+ +
function byte()
+    left = left - 1
+    return assert(file_handle:read(1):byte())
+    --reads the next chracter, and converts it to a "numerical code" using string.byte()
+    --it's important that this function moves forward in the file stream (as :read(1) does)
+end
+
+ + + + +

Returns:

+
    + + a bytecode (an int between 0 and 255.) +
+ + + + +
+
+ + write_byte () +
+
+ write_byte is similar to read_byte, however it is given an input and expected to write it to the file. + (example needed) + + + + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2024-01-08 18:14:41 +
+
+ + diff --git a/docs/ldoc.css b/docs/ldoc.css new file mode 100644 index 0000000..f945ae7 --- /dev/null +++ b/docs/ldoc.css @@ -0,0 +1,304 @@ +/* BEGIN RESET + +Copyright (c) 2010, Yahoo! Inc. All rights reserved. +Code licensed under the BSD License: +http://developer.yahoo.com/yui/license.html +version: 2.8.2r1 +*/ +html { + color: #000; + background: #FFF; +} +body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td { + margin: 0; + padding: 0; +} +table { + border-collapse: collapse; + border-spacing: 0; +} +fieldset,img { + border: 0; +} +address,caption,cite,code,dfn,em,strong,th,var,optgroup { + font-style: inherit; + font-weight: inherit; +} +del,ins { + text-decoration: none; +} +li { + margin-left: 20px; +} +caption,th { + text-align: left; +} +h1,h2,h3,h4,h5,h6 { + font-size: 100%; + font-weight: bold; +} +q:before,q:after { + content: ''; +} +abbr,acronym { + border: 0; + font-variant: normal; +} +sup { + vertical-align: baseline; +} +sub { + vertical-align: baseline; +} +legend { + color: #000; +} +input,button,textarea,select,optgroup,option { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; +} +input,button,textarea,select {*font-size:100%; +} +/* END RESET */ + +body { + margin-left: 1em; + margin-right: 1em; + font-family: arial, helvetica, geneva, sans-serif; + background-color: #ffffff; margin: 0px; +} + +code, tt { font-family: monospace; font-size: 1.1em; } +span.parameter { font-family:monospace; } +span.parameter:after { content:":"; } +span.types:before { content:"("; } +span.types:after { content:")"; } +.type { font-weight: bold; font-style:italic } + +body, p, td, th { font-size: .95em; line-height: 1.2em;} + +p, ul { margin: 10px 0 0 0px;} + +strong { font-weight: bold;} + +em { font-style: italic;} + +h1 { + font-size: 1.5em; + margin: 20px 0 20px 0; +} +h2, h3, h4 { margin: 15px 0 10px 0; } +h2 { font-size: 1.25em; } +h3 { font-size: 1.15em; } +h4 { font-size: 1.06em; } + +a:link { font-weight: bold; color: #004080; text-decoration: none; } +a:visited { font-weight: bold; color: #006699; text-decoration: none; } +a:link:hover { text-decoration: underline; } + +hr { + color:#cccccc; + background: #00007f; + height: 1px; +} + +blockquote { margin-left: 3em; } + +ul { list-style-type: disc; } + +p.name { + font-family: "Andale Mono", monospace; + padding-top: 1em; +} + +pre { + background-color: rgb(245, 245, 245); + border: 1px solid #C0C0C0; /* silver */ + padding: 10px; + margin: 10px 0 10px 0; + overflow: auto; + font-family: "Andale Mono", monospace; +} + +pre.example { + font-size: .85em; +} + +table.index { border: 1px #00007f; } +table.index td { text-align: left; vertical-align: top; } + +#container { + margin-left: 1em; + margin-right: 1em; + background-color: #f0f0f0; +} + +#product { + text-align: center; + border-bottom: 1px solid #cccccc; + background-color: #ffffff; +} + +#product big { + font-size: 2em; +} + +#main { + background-color: #f0f0f0; + border-left: 2px solid #cccccc; +} + +#navigation { + float: left; + width: 14em; + vertical-align: top; + background-color: #f0f0f0; + overflow: visible; +} + +#navigation h2 { + background-color:#e7e7e7; + font-size:1.1em; + color:#000000; + text-align: left; + padding:0.2em; + border-top:1px solid #dddddd; + border-bottom:1px solid #dddddd; +} + +#navigation ul +{ + font-size:1em; + list-style-type: none; + margin: 1px 1px 10px 1px; +} + +#navigation li { + text-indent: -1em; + display: block; + margin: 3px 0px 0px 22px; +} + +#navigation li li a { + margin: 0px 3px 0px -1em; +} + +#content { + margin-left: 14em; + padding: 1em; + width: 700px; + border-left: 2px solid #cccccc; + border-right: 2px solid #cccccc; + background-color: #ffffff; +} + +#about { + clear: both; + padding: 5px; + border-top: 2px solid #cccccc; + background-color: #ffffff; +} + +@media print { + body { + font: 12pt "Times New Roman", "TimeNR", Times, serif; + } + a { font-weight: bold; color: #004080; text-decoration: underline; } + + #main { + background-color: #ffffff; + border-left: 0px; + } + + #container { + margin-left: 2%; + margin-right: 2%; + background-color: #ffffff; + } + + #content { + padding: 1em; + background-color: #ffffff; + } + + #navigation { + display: none; + } + pre.example { + font-family: "Andale Mono", monospace; + font-size: 10pt; + page-break-inside: avoid; + } +} + +table.module_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.module_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.module_list td.name { background-color: #f0f0f0; min-width: 200px; } +table.module_list td.summary { width: 100%; } + + +table.function_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.function_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.function_list td.name { background-color: #f0f0f0; min-width: 200px; } +table.function_list td.summary { width: 100%; } + +ul.nowrap { + overflow:auto; + white-space:nowrap; +} + +dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;} +dl.table h3, dl.function h3 {font-size: .95em;} + +/* stop sublists from having initial vertical space */ +ul ul { margin-top: 0px; } +ol ul { margin-top: 0px; } +ol ol { margin-top: 0px; } +ul ol { margin-top: 0px; } + +/* make the target distinct; helps when we're navigating to a function */ +a:target + * { + background-color: #FF9; +} + + +/* styles for prettification of source */ +pre .comment { color: #558817; } +pre .constant { color: #a8660d; } +pre .escape { color: #844631; } +pre .keyword { color: #aa5050; font-weight: bold; } +pre .library { color: #0e7c6b; } +pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; } +pre .string { color: #8080ff; } +pre .number { color: #f8660d; } +pre .function-name { color: #60447f; } +pre .operator { color: #2239a8; font-weight: bold; } +pre .preprocessor, pre .prepro { color: #a33243; } +pre .global { color: #800080; } +pre .user-keyword { color: #800080; } +pre .prompt { color: #558817; } +pre .url { color: #272fc2; text-decoration: underline; } + diff --git a/modlib/binary.lua b/modlib/binary.lua index 41362dc..2ef3807 100644 --- a/modlib/binary.lua +++ b/modlib/binary.lua @@ -1,37 +1,22 @@ --- Localize globals +--- read and write (little endian) binary. +--- located in `mtul.binary`. +--@module binary + local assert, math_huge, math_frexp, math_floor = assert, math.huge, math.frexp, math.floor local negative_nan = 0/0 local positive_nan = negative_nan ^ 1 ---"returns nearest 32-bit single precision float representation of a number" (or something) -function mtul.binary.fround(number) - if number == 0 or number ~= number then - return number - end - local sign = 1 - if number < 0 then - sign = -1 - number = -number - end - local _, exp = math.frexp(number) - exp = exp - 1 -- we want 2^exponent >= number > 2^(exponent-1) - local powexp = 2 ^ math.max(-126, math.min(exp, 127)) - local leading = exp <= -127 and 0 or 1 -- subnormal number? - local mantissa = math.floor((number / powexp - leading) * 0x800000 + 0.5) - if - mantissa > 0x800000 -- doesn't fit in mantissa - or (exp >= 127 and mantissa == 0x800000) -- fits if the exponent can be increased - then - return sign * inf - end - return sign * powexp * (leading + mantissa / 0x800000) -end +--- reading binary inputs. +-- read a binary inputs using a `read_byte` function. +-- @section reading +-- @see read_byte --- All little endian ---+ Reads an IEEE 754 single-precision floating point number (f32) +--- read an IEEE 754 single precision (32-bit) floating point number +-- @function read_single +-- @param function @{read_byte} function mtul.binary.read_single(read_byte) -- First read the mantissa local mantissa = read_byte() / 0x100 @@ -66,7 +51,9 @@ function mtul.binary.read_single(read_byte) return sign * 2 ^ (exponent - 127) * (1 + mantissa) end ---+ Reads an IEEE 754 double-precision floating point number (f64) +--- read an IEEE 754 double-precision (64-bit) floating point number +-- @function read_double +-- @param function @{read_byte} function mtul.binary.read_double(read_byte) -- First read the mantissa local mantissa = 0 @@ -100,12 +87,10 @@ function mtul.binary.read_double(read_byte) return sign * 2 ^ (exponent - 1023) * (1 + mantissa) end ---+ Reads doubles (f64) or floats (f32) ---: double reads an f64 if true, f32 otherwise -function mtul.binary.read_float(read_byte, double) - return (double and mtul.binary.read_double or mtul.binary.read_single)(read_byte) -end - +--- read an unsigned integer of any given length +-- @function read_uint +-- @param function @{read_byte} +-- @param int length in bytes of unsigned integer function mtul.binary.read_uint(read_byte, bytes) local factor = 1 local uint = 0 @@ -116,6 +101,10 @@ function mtul.binary.read_uint(read_byte, bytes) return uint end +--- read a signed integer of any given length +-- @function read_uint +-- @param function @{read_byte} +-- @param int length in bytes of integer function mtul.binary.read_int(read_byte, bytes) local uint = mtul.binary.read_uint(read_byte, bytes) local max = 0x100 ^ bytes @@ -125,6 +114,10 @@ function mtul.binary.read_int(read_byte, bytes) return uint end +--- writing binary +-- documentation needed +-- @section write +-- @fixme add documentation function mtul.binary.write_uint(write_byte, uint, bytes) for _ = 1, bytes do write_byte(uint % 0x100) @@ -247,10 +240,55 @@ function mtul.binary.write_double(write_byte, number) write_byte(sign_byte) end ---: on_write function(double) ---: double true - f64, false - f32 function mtul.binary.write_float(write_byte, number, double) (double and mtul.binary.write_double or mtul.binary.write_single)(write_byte, number) end --- Export environment \ No newline at end of file +--- misc binary helpers +-- @section misc + +--- "returns nearest 32-bit single precision float representation of a number" (or something) +-- @function fround() +-- @param number +-- @return nearest 32-bit single precision float representation of a number +function mtul.binary.fround(number) + if number == 0 or number ~= number then + return number + end + local sign = 1 + if number < 0 then + sign = -1 + number = -number + end + local _, exp = math.frexp(number) + exp = exp - 1 -- we want 2^exponent >= number > 2^(exponent-1) + local powexp = 2 ^ math.max(-126, math.min(exp, 127)) + local leading = exp <= -127 and 0 or 1 -- subnormal number? + local mantissa = math.floor((number / powexp - leading) * 0x800000 + 0.5) + if + mantissa > 0x800000 -- doesn't fit in mantissa + or (exp >= 127 and mantissa == 0x800000) -- fits if the exponent can be increased + then + return sign * inf + end + return sign * powexp * (leading + mantissa / 0x800000) +end + +--- expected function inputs. +-- functions will expect either a `read_byte` or `write_byte` function as inputs +-- @section input + +--- `read_byte` is a param name which refers to a function which reads the next byte- returning a whole number between 0-255. +-- +-- function byte() +-- left = left - 1 +-- return assert(file_handle:read(1):byte()) +-- --reads the next chracter, and converts it to a "numerical code" using string.byte() +-- --it's important that this function moves forward in the file stream (as :read(1) does) +-- end +-- @function read_byte +-- @return a bytecode (an int between 0 and 255.) + +--- `write_byte` is similar to read_byte, however it is given an input and expected to write it to the file. +-- (example needed) +-- @function write_byte \ No newline at end of file