GGI

GGI.pm - Gemini Gateway Interface: Support perl-programs on Gemini servers.

SUMMARY

GGI handles the accumulation of multiple parameters in the path-component of the URL through automatic redirects and offers a simple method to access those parameters from the perl program.

GGI supports the generation of all Gemini line types: responses, headers, text, quotes, links and pre-formatted, as well as some convenient methods to generate menus and to print tables with and without ASCII or UniCode frames.

More about the Gemini protocol: https://gemini.circumlunar.space/

VERSION

GGI.pm Version from 2021-03-26

AUTHORS

GGI by Frank Jüdes, http://www.linux4specialists.com

This pod text by Frank Jüdes, Perl by Larry Wall and the perl5-porters.

COPYRIGHT

The GGI module is Copyright (c) 2021 Frank Jüdes, West Virginia, U.S.A. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl 5.10.0 README file.

SUPPORT and WARRANTY

The GGI is free Open Source software. IT COMES WITHOUT WARRANTY OF ANY KIND.

EXAMPLES

Make the output of the ps utility available through a Gemini server

  #!/bin/perl
  use warnings;
  use strict;
  use utf8::all;
  use GGI;

  my $ggi = new GGI;    # Create a new GGI object and print SUCCESS header
  $ggi->H1('ps test');  # Print a header
  my @output=`ps -fA`;  # Run ps and catch all the output
  chomp @output;        # Remove EOLs
  $ggi->Pre(@output);   # Print the output as preformatted text

Collect Parameters into the PATH＿INFO variable

  #!/bin/perl
  use warnings;
  use strict;
  use utf8::all;
  use GGI;

  my $ggi = GGI->new(1);         # New GGI object without writing any header
  if (not defined $ggi->Param) { # No parameter present: Get the amount of parameters wanted
    $ggi->ResponseHeader('INPUT',qq(GGI-Test, ParamTest: How many parameters do you want to test?));
  } # END if

  my $Current = $ggi->Param+1;   # How many parameters are there
  my $Wanted  = $ggi->Param(0);  # How many parameters are wanted?
  if ($Current <= $Wanted) {     # Get the next parameter
    $ggi->ResponseHeader('INPUT',qq(GGI-Test, Paramtest: Please enter a value for Parameter $Current of $Wanted));
  } # END if

  # Done with parameters! - Main program
  $ggi->H1("Hello World!");

  if (defined $ggi->Param) {
    $ggi->H2("The parameters");
    $ggi->List(@{$ggi->Param('*')});
  } else {
    $ggi->H1("No Parameters.");
  } # END if

  $ggi->Link(qq(gemini://h2903872.stratoserver.net/ Go back to the server's home.));

Implemented methods

The following paragraphs explain the implemented methods of this package in great detail.

new([NoPrintHeader]

Create a new GGI object:

• A new object is created, some internal variables initialized.
• If there is a parameter at the end of the URL, the value is added as a path-component and a re-direct to the new URL is sent to the client.
• If there is no parameter attached to the URL, all parameters are being copied from the PATH_INFO into the internal PARAMS array.
• If called without any parameters an OK response-header will be printed automatically and the function will return to the main program. If any TRUE value as parameter is passed, no header will be printed at all and it is the duty of the calling program to print a Gemini response-header if other than SUCCESS should be printed.

BaseURL

Returns the current request URL without the parameters

MyURL

Returns the current request URL - Basically a shortcut for $ENV{GEMINI_URL}.

ServerName

Returns the current request's servername - Basically a shortcut for $ENV{SERVER_NAME}.

ScriptName

Returns the current request's script-name - Basically a shortcut for $ENV{SCRIPT_NAME}.

WashParameter

Removes potentialy dangerous stuff from the parameters, currently for Linux

• Everything attached with a ";" at the end, including the ";" is removed
• Everything between backticks "`", including the back-ticks themselves, is removed
• Everything in '$( )' is removed, including the $-sign and the parentheses

param([Name])

Access to the GGI-parameters:

• If there are no GGI parameters present, undef is returned.
• Called without an index-value in array-mode, a reference to the parameter-array is returned.
• Called without an index-value in scalar-mode the highes index into the parameter array is returned.
• Called with the index-value of "#", the numer of parameters is returned.
• Called with the index-value of "*", a reference to the parameter-array is returned.
• Called with an index-value the value of the indexed parameter is returned if it exists. If no parameter with the given index exists, undef is returned.

print(@Lines)

Print an array of lines with CR/LF at the end

ResponseHeader(StatusCode[,Meta])

Print the response header with the meta-information, if present. The following response status-codes are defined, according to the Gemini protocol documentation:

  - INPUT, SENSITIVE_INPUT
  - SUCCESS
  - REDIRECT_TEMPORARY, REDIRECT_PERMANENT
  - FAILURE_TEMPORARY, SERVER_UNAVAILABLE, CGI_ERROR, PROXY_ERROR, SLOW_DOWN
  - FAILURE_PERMANENT, NOT_FOUND, PROXY_REQUEST_REFUSED, BAD_REQUEST
  - CLIENT_CERTIFICATE_REQUIRED, CERTIFICATE_NOT_AUTHORIZED, CERTIFICATE_NOT_VALID

Input(HeaderText)

Print an Input response header with prompt. This is basically a shortcut for ResponseHeader('INPUT',[Prompttext]);

H[1-3](HeaderText)

Print headerline 1-3

Pre(@Lines)

Print an array of lines as a preformatted block

LabeledPre(Label,@Lines)

Print an array of lines as a labeled preformatted block

List(@Lines)

Print an array of lines as an unsorted list.

Link(@Lines)

Print an array of lines as links

Quote(@Lines)

Print an array of lines as quotes

PrintMenu(Menu,BaseURL,Title,Description)

Print the value of Title as an H1-title if defined. Then print the content of the Description below if defined, followed by the link-menu itself.

Menu is a simple perl-hash with the prompts as keys and the values as content. These values will be appended to the BaseURL as link-targets and the keys will become the link description-texts.

PrintTable(Table,FrameType,Header,Summary,Compact)

Print the content of a two-dimensional table into a pre-formatted block. The Table parameter is a reference to a two-dimensional array.

It is vital that all cells of the table are defined and that there are no holes in the table structure!

This code will center the column headers and pad all other table-cells to equal length in their column with the content left aligned. If you want other formatting, you need to pre-format the content of your table.

Valid values for the FrameType are ASCII, SINGLE, DOUBLE, SHADOW, FLOAT and NONE. Invalid values will default to NONE and no frames will be printed.

The Header and Summary parameters define weather the first line of the table contains column-headers and the last line contains a summary and should be separated from the rest of the table with a horizontal line.

With the Compact parameter the output of horizontal lines between the table data-rows can be supressed. (Compact design).

PrintHash(Hash,Filler,Colon,Quote)

Print the content of a simple perl-hash or a perl-hash of arrays into a pre-formatted block. The Hash parameter is a reference to a simple pearl-hash or a pearl-has of one-dimensional arrays. The hash-keys will be printed, filled to equal length with the value of the Filler character, followed by the value of the Colon parameter, followed by either the hash-value or a list of values should the content of the hash be an array. If the Quote parameter is given, values will be encapulated in this quout character.

Unicode Trickeries

Unicode contains the code-block `Mathematical Alphanumeric Symbols' [U+1D400..U+1D7FF], containing styled letters and digits that look like normal characters from the latin alphabet, just styled in bold, italic, script, outline or gothic.

However those characters will not be recognized as ordinary text by most computer programs, like search engine crawlers for example.

Note that the digits are only available in bold-style.

Warning: This might not be supported