#
# PACKAGE EXAMPLE
#

# This is a Perl defined macro extension module. This file should be placed into the
# directory named 'jamal' under the Perl Module library directory. This is
# C:\Perl\lib\jamal on my Windows NT. On UNIX this is something different.
=pod
=H Example Perl written extension module for jamal
=abstract
This is a sample extension module for jamal written in Perl. Learn this module
or use as a starting point to create your own modules.
=end

This module is not intended for serious Perl usage. This is intended as a learning tool
or as a starting point to develop Perl written jamal extensions.

This module is a jamal compliant extension that tries to show all features of the
jamal interface that jamal provides for its extensions.

See the original source code of this module for explanatory comments.
=cut

package jamal::example;

BEGIN {
$VERSION = '2.0'; #the current module version
&jamal::require('2.0');#require jamal version
$RVERSION = &jamal::version('1.0','2.0');
$RVERSION = $VERSION unless $RVERSION;
# define package specific macros
if( $RVERSION > 1.0 ){
  &jamal::DefineMacro( 'cap' , ',x' , '<font size=+1>x</font>' );
  }
}

# Create a licence text. All characters are capital, but those
# that are capital in the original text are typesetted using
# larger font. Version 1.0 of this module used fix <font size=+1>x</font>
# enlarging scheme. Version 2.0 already uses the macro {::cap/x}
# and the user can redefine it to have different intials. However to
# be 100% compatible with old version if version 1.0 is requested
# we still generate the old <font size=+1>x</font> sequence.
sub licence {
  my $text = shift;
  my $i;
  my $output='';

  $text =~ s/^\s*//;

  for( $i = 0 ; $i < length $text ; $i++ ){
    my $c = substr($text,$i,1);
    if( $c le 'Z' && $c ge 'A' ){
      if( $RVERSION > 1.0 ){
        $output .= &jamal::Open . "example::cap/$c" . &jamal::Close; 
        }else{#remain compatible vith older version
        $output .= "<FONT SIZE=+1>$c</FONT>"; 
        }
      }
    elsif( $c le 'z' && $c ge 'a' ){ $output .= uc $c }
    else{ $output .= $c; }
    }
  return $output;
  }

# just to demonstrate the call of &jamal::verbatim
sub list {
  my $param = shift;
  $fn = &jamal::input($param);
  my $output = '';
  return "***$fn can not be opened!!!***"  unless open(F,"<$fn");
  my $i = 1;
  while( <F> ){
    s/\&/&amp;/g;
    s/\</&lt;/g;
    $output .= sprintf('%03d ',$i) . $_;
    $i++
    }
  &jamal::verbatim;
  return $output;
  }

END {

  }
1;