apg-conv

_Deprecated: Use apg-js instead. See apg-js-examples for usage._

apg-conv is a command line data conversion tool.
It is powered by apg-conv-api,
an API with both high- and low-level access to all of the format conversion tools.

The features and design have been specifically built as an aid to apg.html, a web-page-based APG parser generator and tester. It is not meant to compete with more complete tools like iconv and iconv-lite. Nonetheless, for the encodings that it supports, it provides an alternate choice.

The original purpose of apg-conv was a means of getting arbitrary, 32-bit integer character codes in and out of an HTML </code>. The <a href="https://tools.ietf.org/html/rfc5234" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">ABNF</a> syntax that defines the phrases that <strong>APG</strong> parses is capable of defining character codes of arbitrary-sized integers. However, with a web-page-based application, input and output is essentially constrained to the ASCII text of <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><textarea></code> and <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><input></code> HTML tags. (The <a href="https://wicg.github.io/entries-api/" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">HTML5 File and Directory API</a> is not standardized and not considered here.) The encoding and decoding formats and methods neccesary to implement this eventually led to this application.</p><p class="my-3">#### v1.1.0 Release Notes</p><p class="my-3">There are no feature or usage changes from v1.0.0.<br />However, <strong>apg-conv</strong> now has a dependency on <a href="https://github.com/ldthomas/apg-conv-api" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer"><strong>apg-conv-api</strong></a>.<br /><strong>apg-conv</strong> has been split into two parts. First is <strong>apg-conv</strong>, which is now just an I/O shell for converting files.<br />Second, all of the data conversion functionality is now in <strong>apg-conv-api</strong><br />in the form of an API which a) does not use the node.js "fs" module and b) gives a developer better access to all functions.<br />The "fs" module is incompatible with some development frameworks.</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Installation</h2></p><p class="my-3">``<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />npm install -g apg-conv<br />apg-conv -h <em>(displays the help screen)</em><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Documentation:</h2></p><p class="my-3">The documentation is in the code in <a href="https://jashkenas.github.io/docco/" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer"></code>docco<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></a> format.<br />To generate the documentation, from the package directory:</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />npm install -g docco<br />./docco-gen<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3">View </code>docs/index.html<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> in any web browser to get started.</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Usage</h2></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />Usage:<br />apg-conv [options]<br />(--help | -h) display this help screen<br />(--version | -v) display version number<br />(--src | -s) <path>, the file to convert, default stdin<br />(--src-type | -st) type, the source file type, default UTF8<br />(--dst | -d) <path>, the converted file, default stdout<br />(--dst-type | -dt) type, the converted file type, default UTF8<br />(--err | -e) <path>, the error reporting file, default stderr</p><p class="my-3">type - the byte stream encoding: may be one of:<br />UTF8<br />UTF16<br />UTF16BE<br />UTF16LE<br />UTF32<br />UTF32BE<br />UTF32LE<br />UINT7<br />ASCII (alias for UINT7)<br />UINT8<br />BINARY (alias for UINT8)<br />UINT16 (alias for UINT16BE)<br />UINT16BE<br />UINT16LE<br />UINT32 (alias for UINT32BE)<br />UINT32BE<br />UINT32LE<br />ESCAPED</p><p class="my-3">Type notes:<br />- The type names are case insensitive.<br />- Source types may be prefixed with BASE64:.<br /> The input will be treated as base64 encoded.<br /> It will be stripped of white space and control characters (\t, \r, \n),<br /> then base 64 decoded as an initial step.<br />- Destination types may have a :BASE64 suffix.<br /> The output will be base 64 encoded as a final step.<br />- Destination types my be prefixed with CRLF:.<br /> This will cause a line ending transformation prior to decoding.<br /> CRLF(\r\n), CR(\r) or LF(\n) will be interpreted as line ends and transformed to CRLF.<br /> CRLF will be added to the end if the last line end is missing.<br />- Destination types my be prefixed with LF:.<br /> This will cause a line ending transformation prior to decoding.<br /> CRLF(\r\n), CR(\r) or LF(\n) will be interpreted as line ends and transformed to LF.<br /> LF will be added to the end if the last line end is missing.<br />- UTF type input data may have an optional Byte Order Mark (BOM)(*)<br />- UTF output data will not have a BOM.<br />- UTF16 defaults to UTF16BE if there is no BOM.<br />- UTF32 defaults to UTF32BE if there is no BOM.<br />- An exception is thrown if a BOM is present and doesn't match the specified data type.<br />- ASCII is an alias for UINT7, 7-bit unsigned integers.<br />- BINARY is an alias for UINT8, 8-bit unsigned integers.<br />- UINT16 is an alias for UINT16BE, big-endian, 16-bit unsigned integers.<br />- UINT32 is an alias for UINT32BE, big-endian, 32-bit unsigned integers.<br />- The ESCAPED format is identical to JavaScript string escaping except that<br /> the grave accent (</code>) is used instead of the backslash (\).<br /> e.g \xHH -> <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">xHH, \uHHHH -> </code>uHHHH, \u{HHHHHH} -> <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">u{HHHHHH}.<br /> Its design and use is specifically for apg.html(**)</p><p class="my-3">Examples:</p><p class="my-3">apg-conv -s <inpath> -d <outpath> -st BINARY -dt UTF8<br /> Convert a binary (Latin 1 or UINT8) file to UTF8.<br /> That is, any characters > 0x7f will get two-byte, UTF8 encoding.</p><p class="my-3">apg-conv -s <inpath> -d <outpath> -st ASCII -dt CRLF:ASCII<br /> Convert all line ends(CRLF, LF or CR) of the ASCII file to CRLF(\r\n),<br /> including the last even if missing in the input file.</p><p class="my-3">apg-conv -s <inpath> -d <outpath> -st BASE64:UTF8 -dt UTF32<br /> Perform an initial base 64 decoding of the input file,<br /> then convert it from UTF8 to UTF32(BE) encoding.</p><p class="my-3">apg-conv -s <inpath> -d <outpath> -st UTF8 -dt UTF32LE:BASE64<br /> The input file is converted from UTF8 to UTF32LE and base 64 encoded as a final step.</p><p class="my-3">apg-conv -s <inpath> -d <outpath> -st BASE64:UTF8 -dt LF:UTF16:BASE64<br /> The input file is base 64 decoded. All line ends(CRLF, LF or CR) are converted to LF(\n),<br /> then converted to wide characters (UTF16) and finally base64 encoded.<br /></code>``</p><p class="my-3">(\*) See the <a href="http://www.unicode.org/versions/Unicode9.0.0/ch03.pdf" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">Unicode standard</a> (3.10 Unicode Encoding Schemes) for Byte Order Marks.<br /><br />(\<em>\</em>) <a href="https://github.com/ldthomas/apg-js2" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">apg.html</a><br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>