/ 
TXTCOD-4.7.1b
River stage zero No dependents
++
/ TXTCOD

NAME

   TXTCOD - Encoding module using the SAC system.

SYNOPSIS

   use TXTCOD;
   
   TXTCOD::codage($source,
                  $destination,
                  <$file.cod>,
                  <$algorithm.alc>,
                  <$param>);
                  
   $param = TXTCOD::decodage($source,
                             $destination,
                             $file.cod,
                             <$algorithm.alc>);
   $file.cod = TXTCOD::createcod;

DESCRIPTION

   TXTCOD 4.7 encodes files with the SAC system, 2.4 version..
   The SAC system consists in several algorithms : a default algorithm who can be remplaced by user-written algorithms. Every algorithm uses a .cod file generated by the module and who contains a list of random numbers used by the module in order to ensure a maximal protection.
   B<< A file must be encoded with the same algorithm and the same .cod file !!! . >>
   This version of the SAC system can encode any type of file (binary files, text) and recognizes automatically their type.

   In the first part you will see the module's how-to and in the second part how to program an algorithm.

FIRST PART : TXTCOD Module

   These functions will be accessible after you have typed B<< use TXTCOD; >>

1) Encoding

   You call the encoding function by typing :
   TXTCOD::codage($source,
                  $destination,
                  <$file.cod>,
                  <$algorithm.alc>,
                  <$param>);
   This function doesn't return any value.
   
   $source is the file you want to encode.
   $destination is the file where TXTCOD will send the result of the encoding.
   These two parameters are B<< obligatory >>.
   
   $file.cod is the .cod file who is indispensable for the encoding and the decoding. If you don't specify this parameter, will search a "[year].cod" file, for example "2003.cod". A .cod file MUST be changed every year at least in order to assure an optimal protection.
   
   $algorithm.alc is the used algorithm. If you don't put anything, TXTCOD will use the default algorithm.
   
   $param is an user-defined parameter who won't be crypted.

2) Decoding

   You call the decoding function by typing :
   $param = TXTCOD::decodage($source,
                             $destination,
                             $file.cod,
                             <$algorithm.alc>);

   $source in the file you want to decode.
   $destination is the result of the decoding
   $file.cod et $algorithm.alc -> see the encoding function description.
   The returned value is the parameter you optionnally defined while the encoding and which isn't crypted.

3) .cod files creation

   To create a .cod file type :
   $file.cod = TXTCOD::createcod;
   The returned value is the file's name ("[year].cod")

SECOND PART : algorithms

   Writing an algorithm is simple : create a file ended by ".alc". This file will contain one-line commands who will tell the module the way to encode and decode your files.
=head2 1) encoding
  The first part of the file will contain the encoding algorithm.
  This algorithm will have a few variables :
      - X, each encoded letter
      - A,B,C,D,E,F,G,H,I,J, script-defined variables.
      - T,M,P  more secured variables
   There are many operators :
      - addition: "+"
      - subtraction: "-"
      - multiplication: "*"
      - division: "/"
      - power: "**"
   For example, we'll use the line : "X*(A+2)" in order to multiply the variable by (A+2). The compilation will be done internally by the module

2) decoding After the encoding part of the file, we will put a line containing only the word "end" without any blank or invisible character. After this word there is the decoding part. The variables of this part are the same thn in the first part. For example, if in the first part you put "X*(M+2)" you will type in the second part "X/(M+2)" in order to make the X variable becoming what she were before the encoding The root is done by this operation : for a "X**A" in the first part you will put "X**(1/A)" in the second.

3) comments You can comment your algorithm by any line beginning with a sharp #. =head2 4) Notes You should not do operations who will make mubers (initial numbers up to 255) becoming too small or too big : perl will round the final numbers and the decoded letter will be very approximative.

TO DO

* increase the velocity of the users' algorithm which is REALLY slower than the default algorithm :( * correct my poor english faults ;) and comment the script in english