Editing Module:RadioGatun32/doc

{{Module rating|release}}

== Usage ==
This module calculates the [[RadioGatún]][32] sum for a given string, returning it in a format suitable for showing a demonstration sum on a Wikipedia page.  [[RadioGatún]] is a cryptographic hash function from 2006 which remains, as of 2022, unbroken.  

To use:

<code><nowiki>{{</nowiki>#invoke:RadioGatun32|''rg32''|''String to input''<nowiki>}}</nowiki></code>

Or with the template (at [[Template:RadioGatun32]]):

<code><nowiki>{{</nowiki>RadioGatun32|''String to input''<nowiki>}}</nowiki></code>

If there is <nowiki>{{Background color|#888|d}}</nowiki> in the string to input, the calculated sum will be based on a string ''without'' the background color formatting.

=== The rg32hash call ===

It is also possible to show the raw hexadecimal RadioGatun[32] sum of a given string without any formatting:

<code><nowiki>{{#invoke:RadioGatun32|rg32sum|</nowiki>''String to input''<nowiki>}}</nowiki></code>

For example, if we run:

:<code><nowiki>{{#invoke:RadioGatun32|rg32sum|1234}}</nowiki></code>

We will get this:

:{{#invoke:RadioGatun32|rg32sum|1234}}

This should output "9EBDD24F469993796C4AAC6A821735A65A3CDEF8A359944CE71F34E7A08E1182".

== Examples ==

<code><nowiki>{{</nowiki>#invoke:RadioGatun32|rg32|Hello, world<nowiki>}}</nowiki></code>

Will create this output:

 RadioGatun[32]("Hello, world") =
 D91BBD22BE5D01F091F26A16704CDA0E165588E025D9BA6619C5B01550756349

Here is the computed output:

{{#invoke:RadioGatun32|rg32|Hello, world}}

We can have background colors:

<code><nowiki>{{</nowiki>#invoke:RadioGatun32|rg32|<nowiki>{{</nowiki>Background color|#ff8cc0|Li<nowiki>}}{{</nowiki>Background color|#c08dff|fe<nowiki>}}!}}</nowiki></code>

Shows us this:

{{#invoke:RadioGatun32|rg32|{{Background color|#ff8cc0|Li}}{{Background color|#c08dff|fe}}!}}

The above should look exactly like this:

 RadioGatun[32]("{{Background color|#ff8cc0|Li}}{{Background color|#c08dff|fe}}!") =
 80E706E851DCDE1170452EEC6EAD24F40E63B9A07B86D8D32053A1237835E03D

The computed sum will be for the string <code>Life!</code>, as can be seen in the following:

{{#invoke:RadioGatun32|rg32|Life!}}

The above should look like this:

 RadioGatun[32]("Life!") =
 80E706E851DCDE1170452EEC6EAD24F40E63B9A07B86D8D32053A1237835E03D

The background colors do not affect the computed RadioGatun[32] sum.

== Testing ==

=== Testing inside Mediawiki ===

To test this in Mediawiki, go to [[Module talk:RadioGatun32/testcases]], and verify that one sees "All RadioGatun[32] test vectors pass".  One can rerun the test by going to [[Module:RadioGatun32/testcases]], clicking on "edit this page", then in the debug console at the bottom, typing in <code>print(p.test())</code>.  One should then see "All RadioGatun[32] test vectors pass".

Another way to test this is to add <code><nowiki>{{#invoke:RadioGatun32/testcases|test}}</nowiki></code> to a page; wherever RadioGatun32/test is invoked, it should show "All RadioGatun[32] test vectors pass".

=== Testing outside Mediawiki ===

This module can either be run as a Mediawiki Lua module, or as a standalone Lua script.  This very same script is also available on GitHub in a repo which includes automated tests to ensure implementations of RadioGatun[32] generate correct hashes against a number of test inputs, including all official RadioGatun[32] test vectors.

To test this code, in a *NIX compatible environment like Linux, with Git and a version of Lua ''above'' 5.1 and ''below'' 5.4 (Lua 5.4 dropped <code>bit32</code>; a Lua 5.1 implementation with <code>bit32</code> support will also work), do the following:

 git clone https://github.com/samboy/rg32hash
 cd rg32hash/sqa
 ./do.test.sh ../Lua/rg32wiki.sh

== See also ==

* [[Template:RadioGatun32]]