# $EPIC: xform.txt,v 1.10 2012/07/04 06:30:23 jnelson Exp $
======Synopsis======
$[[xform]]("<encodings>" "<metas>" <text>)

======About string transformations:======
The $xform() function transforms the <text> into some other form.  There are
three types of transformations:

| Encryption  | Convert plain text into encrypted ciphertext |
| Encoding    | Convert any kind of data into a valid C string |
| Hashing     | Convert any kind of data into a message digest |
| Transcoding | Convert a string between different character sets |

Encryption works by taking your plain text and a password key and flipping 
some of the bits, which gives you output that looks like random bytes.  
The only way to recover the original text is to have the password key.

Because encryption usually gives you binary data, which can't be used 
directly in the client, you have to encode it into a usable format. 

Both encryption and encoding are symmetric -- they are fully reversable,
and all of the information in the input data is present in the output data,
but in some different way.

Hashing is different.  Hashing is a form of lossy compression that takes 
any input data and removes all but a little bit of the information.  Because
is lossy compression, it is irreversable.  Unlike encryption, there is no 
way to recover the original text from a hash.

======Supported Transformations:======
The [[xform]] function supports the following encryptions that all take 
one required argument.
^ Name     ^ Description                          ^ Argument type ^
| SED      | Simple Encrypted Data                     | Password |
| BF       | Blowfish-CBC                              | Password |
| CAST     | CAST5-CBC                                 | Password |
| AES      | AES256-CBC                                | Password |
| AESSHA   | AES256-CBC with SHA256 digest of password | Password |
| FISH     | Blowfish-ECB                              | Password |
| DEF      | Default encryption (not supported yet!)   | Password |

The [[xform]] function supports the following encodings that do not take 
arguments.
^ Name     ^ Description ^
| URL      | Perform RFC3986 transformation ("URL encoding") |
| ENC      | Perform Base-16 transformation |
| B64      | Perform RFC1421 transformation ("Base 64") |
| FISH64   | Perform l64a transformation ("FiSH" ascii armoring) |
| CTCP     | Perform CTCP transformation | 
| NONE     | No changes (just copies the string) |
| ALL      | Return all supported transformations (ignores the text) |

The [[xform]] function supports the following transformations that take one
required argument.
^ Name     ^ Description                          ^ Argument type ^
| ICONV    | Iconv charset transformation   | FROM/TO (see below) |

The [[xform]] function supports the folowing digests:
^ Name   ^ Description ^
| SHA256 | SHA256 Message Digest |

=====Description:=====
        $xform("<transformations>" "meta" "meta" text)

You can string together multiple transformations.  Any transformation
that requires a meta value (ie, a cipherkey) should be supplied after
the transformations **in the correct order**.  After this should be the
plain text.  To apply a transformation, prefix its name with a plus sign
("+") and to remove a transformation, prefix its name with a minus sign
("-").  For example, +URL means url encode, and -URL means url decode.

Normally functions do not accept [[what is a word|dwords]] as arguments,
but xform does.  If you want to do multiple transformations at once, you 
must separate them by spaces and surround the whole thing in double quotes.
If the meta values (ie, passwords for encryption) contain spaces, you must 
surround the meta value with double quotes.

======Iconv transformation:======
For the ICONV transformation, the "meta" value is a word that contains
the old encoding and the new encoding separated by a slash ("/").  There
is no guaranteed list of encodings that you can use, because it depends
on your system's iconv(3) facility.  

Example:  To convert a string from iso-8859-1 to utf8, 
	$xform(+ICONV "iso-8859-1/utf8" ...)

======Examples:======
^ If you want to:       ^  Then you should... ^
| URL-encode a string   |  $xform(+URL this is a string) |
| URL-decode a string   |  $xform(-URL this%20is%20a%20string) |
| SED-cipher a string   |  $xform(+SED password this is a string) |
| SED-decipher a string |  $xform(-sed password <whatever>) |
| Iconv transform a string from utf-8 to iso-8859-1 | $xform(ICONV "utf-8/iso-8859-1" $utf8string)|

More practical examples:
  -- Read binary data from a file, encrypt it, and url encode it again.
<file>
	@fd = open(file.txt R)
	@data = read($fd 1024)
	@cipher = xform("-CTCP +SED +URL" password $data)
	@close($fd)
	msg someone $cipher
</file>

Why does this work?
  -- $read() returns ctcp-enquoted data, so -CTCP removes it
  -- Now we have binary data, so +SED will cipher it
  -- Now we have ciphertext, so +URL will url encode it.

We can send this to someone else, and they can put it in $cipher...
<file>
	@newfd = open(newfile.txt W)
	@newdata = xform("-URL -SED +CTCP" password $cipher)
	@writeb($newfd $newdata)
	@close($newfd)
</file>

We did the reverse of the above:
  -- We -URL to recover the binary data
  -- We -SED to decrypt it using the password
  -- We +CTCP to put it in a form we can use with $writeb().

Viola!