The Regnus Parser For PHP
About
The Regnus Parser for PHP allows you to use Regnus scripts to generate random text and content on your own webpages. You may notice that the quoted text displayed on the front page of this site is different each time the page is refreshed; this is achieved using the Regnus Parser for PHP.
It was a dark, wet night. The Republican MP meaninglessly walked up to the buck-toothed greengrocer and barked, "I hear that Dublin is cold this time of year." There was a pause. "What's 8 multiplied by 4?" asked the greengrocer. "Do I look like a paedophile?" came the reply.Generated by the Regnus script Something Completely Different, by
There are two ways to use the Regnus Parser for PHP: firstly, you can upload the parser script (a single PHP file) to your webspace, and include it from the PHP scripts controlling your own site's pages. This is the recommended use, as it ensures that the parser will run as fast as your webpages need, especially if your scripts are also hosted on the same server.
Alternatively, you can use our hosted copy of the parser, writing its output to your own webpages. This is of course slower (as it will use further HTTP requests between servers to deliver the content), and will also rely on our server's uptime, but it does have the advantage of being very easy even if you are not experienced in PHP, or even if your server doesn't support PHP in the first place.
In either case, the parser can output content generated from a Regnus script in two different formats: either as an image, or as text. The text method is more powerful, as it allows you to seamlessly transclude Regnus-generated random content into your own page, to be displayed using your own styling rules. However, if you are not familiar with the basics of server-side scripting, or you do not have access to a properly configured server-side scripting language (such as PHP), you may find that the image method is much easier to implement in your site.
The image output method also allows you to generate content in situations where the use of PHP scripts is not possible (for example in a forum signature!)
Information & Download
- Parser Version
- v1.4.5
- Regnus Specification
- v5.2
- Download
Using The Parser
The Regnus parser for PHP is very simple to use, but does require at least some very basic knowledge of PHP, as well as (of course) the use of PHP on your server. If you do not have access to a PHP installation, you will need to use our hosted copy of the parser instead, which is just as powerful, but of course a little slower.
Assuming you do have use of a PHP installation on your server, the first step you will need to take is downloading the Regnus Parser for PHP, unzipping the file, and uploading it to your web server. Once this is done, you simply have to include it from your own scripts in the following fashion:
<?php
$Regnus_Script = "YourScript";
$Regnus_Label = "YourLabel";
@include("PathToYourParser/Regnus.php");
?>
YourScript must include the path and filename of the script you would like to generate text from, and is always calculated from the site root of your webpage, regardless of where the parser itself is located.
Note: YourScript can also be a URI, so if you would like, you can refer to a script located on another server, and the parser will happily access it via HTTP!
YourLabel should of course point to the Label in the script from which you would like to generate text.
Generating Image Output
The parser can also output text drawn onto an image. This is, of course, much more limited in its flexibility than true text content, but can be useful in contexts where it is not possible to call on PHP to generate text (for example in a forum signature).
Generated by the Regnus script Something Completely Different, by
There are two ways to use the Regnus Parser for PHP: firstly, you can upload the parser script (a single PHP file) to your webspace, and include it from the PHP scripts controlling your own site's pages. This is the recommended use, as it ensures that the parser will run as fast as your webpages need, especially if your scripts are also hosted on the same server.
To access the image function of the parser, simply post an image tag in the (X)HTML of your page with its src attribute set to point to the parser, and use command line arguments to set the correct parameters. For example:
<img src="http://YourDomain/PathToParser/Regnus.php?output=image&imagewidth=YourWidth&script=YourScript&label=YourLabel" alt="Random text generated using Regnus: www.regnus-scripting.info" />
As you can see, the parser will accept its parameters from the command line when accessed via HTTP, so simply set the appropriate variables for YourScript (including the path or URI!) and YourLabel, and set YourWidth to the width (in pixels) of the image you would like to produce.
Note: the image has a minimum width of 150 pixels. Its height is determined by the amount of text generated from the script.
Note: if your script or Label names include any spaces, remember that you must replace these with "%20" in the URI.
Note: by default, the image is output in PNG format.
Additional Parameters
The Regnus Parser for PHP supports various parameters to control its behaviour, all of which can be set either using variables when calling the parser from a PHP script, or using command-line arguments in the URI when accessing the parser via HTTP.
The following parameters are supported:
- Script
-
- PHP Variable
- $Regnus_Script
- URI Parameter
- script
- Description
- Contains the path and filename of the Regnus script from which you would like to generate text.
- Label
-
- PHP Variable
- $Regnus_Label
- URI Parameter
- label
- Description
- Contains the name of the Label in the specified script from which you would like to start parsing.
- Script Information
-
- PHP Variable
- $Regnus_Information
- URI Parameter
- information
- Values
-
- blurb
- title
- Description
- If this parameter is set, the parser will output the chosen meta-information (either the script's Title or Blurb) instead of generating text from the specified Label.
- Output Type
-
- PHP Variable
- $Regnus_Output
- URI Parameter
- output
- Values
-
- text
- image
- Description
- Specifies whether the parser should output the generated text as text content or a PNG image. The default if unspecified is "text".
- Image Width
-
- PHP Variable
- $Regnus_ImageWidth
- URI Parameter
- imagewidth
- Description
- This parameter sets the width (in pixels) of the image generated when outputting an image. If unspecified, the default is "150" (the minimum allowed width).
- (X)HTML New Lines
-
- PHP Variable
- $Regnus_NewLines
- URI Parameter
- newlines
- Values
-
- br
- Description
- If this parameter is set to "br", the parser will replace standard new-line characters in the generated text with the (X)HTML tag "<br />", which can be useful if you are displaying the generated text directly on a web document and need to markup the newlines as such.
- Escape Ampersands
-
- PHP Variable
- $Regnus_EscapeAmpersands
- URI Parameter
- escapeampersands
- Values
-
- true
- false
- Description
- If "true", this parameter replaces all ampersands within the generated content with (X)HTML entities. By default, this is "true" if outputting text, and "false" if outputting an image.
- Strip Tags
-
- PHP Variable
- $Regnus_StripTags
- URI Parameter
- striptags
- Values
-
- true
- false
- Description
- If "true", this parameter removes all (X)HTML tags from the generated content. By default, this is "true" if outputting an image, and "false" if outputting text.
Using The Hosted Parser
For those who do not have access to a server equipped with PHP, a hosted copy of the Regnus Parser for PHP is available here for you to use in order to include Regnus-generated content on your pages.
The hosted parser will, of course, be slower than a script running on your own site's server, but using it is nevertheless very simple, and perhaps more convenient for some uses. As the parser itself is hosted here at the Regnus homepage, all you have to do is call it from your own scripts, pass it the appropriate parameters, and the generated content will appear on your pages.
Generating Image Output
In order to include an image on your site displaying random text generated using Regnus, you can simply add an image tag to your (X)HTML with its src attribute set to point to the hosted parser's location on our server.
For example, copy and paste the following code into your page, replacing the highlighted variables with your own parameters:
<img src="http://www.regnus-scripting.info/parsers/php/Regnus.php?output=image&imagewidth=YourWidth&script=YourScript&label=YourLabel" alt="Random text generated using Regnus: www.regnus-scripting.info" />
Note: The example above assumes that your site is marked up with (X)HTML, but the method should be easy enough to convert to another markup language.
YourWidth should be replaced by the width (in pixels) of the image you want to generate. The height of the image is determined automatically by the amount of text generated. YourWidth must be at least 150px. Also, it should always be at least long enough to accomodate the longest single word appearing in the script you want to use. It is recommended that you give the image a width of at least 320px for most scripts.
YourScript should be replaced by the full path of the script which you want to use, which can be a URI (for example if you have uploaded the script you want to use to your own server).
YourLabel should be replaced by the name of the Label in your chosen script from which you would like to generate text.
Note: if your script or Label names include any spaces, you must replace these with "%20" in the URI.
All of the scripts featured in our Script Showcase are available to use this way. For example, if you wanted to generate a 400px-wide image from the "RANDOM PICK" Label of the script Something Completely Different, you could use:
<img src="http://www.regnus-scripting.info/parsers/php/Regnus.php?output=image&imagewidth=400&script=http://www.regnus-scripting.info/scripts/Something%20Completely%20Different.rsf&label=RANDOM%20PICK" alt="Random text generated using Regnus: www.regnus-scripting.info" />
And if you wanted to generate a 600px-wide image from the "Story" Label of the script The Storyteller, you would use:
<img src="http://www.regnus-scripting.info/parsers/php/Regnus.php?output=image&imagewidth=600&script=http://www.regnus-scripting.info/scripts/The%20Storyteller.rsf&label=Story" alt="Random text generated using Regnus: www.regnus-scripting.info" />
Note: by default, the image is output in PNG format.
Note: the hosted parser will, of course, accept any of the parser's usual parameters in its command line. For image output, however, the default options should usually suffice.
Generating Text Output
Remotely generating text content using the hosted Regnus parser is possible using any scripting language which allows content to be requested via HTTP, but for simplicity, the examples given here use PHP (though of course in most cases, if you have access to a PHP installation, you would be better off uploading the parser to your own server and using locally).
Assuming you are using PHP, simply copy the following code into your page wherever you want to generate random content, replacing YourScript with the name of your script, and YourLabel with the name of the Label in that script from which you'd like to generate text:
<?php
@readfile("http://www.regnus-scripting.info/parsers/php/Regnus.php?script=YourScript&label=YourLabel");
?>
The script you specify as YourScript must have a full path, which can be a URI. Assuming that, for example, you want to include text from the script Proverbs on your site, from the Label "Wise Proverb", you could use the following:
<?php
@readfile("http://www.regnus-scripting.info/parsers/php/Regnus.php?output=text&script=http://www.regnus-scripting.info/scripts/Proverbs.rsf&label=Wise%20Proverb");
?>
In fact, if you paste the above code into your page with no changes, you should hopefully see that your page now includes text generated from the Proverbs script.
Note: if your script or Label names include any spaces, you must replace these with "%20" in the URI, as shown above in the example Label "Wise Proverb"!
Note: the hosted parser will, of course, accept any of the parser's usual parameters in its command line to control the output of the text.
Attribution
The PHP Regnus Parser is of course provided for use free of charge. However, if you do use Regnus in your webpage, it would be nice if you could at least please include an attributing link somewhere in your page to www.regnus-scripting.info. Please feel free to use the following text:
<p>Random content on this page generated by the <a href="http://www.regnus-scripting.info/">Regnus</a> scripting language.</p>
We'd love to hear about where and how you're using Regnus! If you'd like to tell us, or you have any other thoughts, questions, comments or suggestions about this parser or the language in general, please feel very welcome to post your messages in the Regnus forums!
Version History
v1.4.5
- The parser now resets the working directory to its initial state on completion.
v1.4.4
- Tidied and commented code.
- Fixed code omission causing the "/" RTC not to function correctly.
- Fixed code typo causing errors in handling of Numeric Expressions.
- Added support for returning the title and blurb information from a script.
- Added support for parser to be installed and run locally.
- Parser now assumes minimum width for images rather than failing if an invalid width is passed.
- Images are now output in PNG format.
v1.4.3
- Improved code efficiency (and therefore parsing speed).
v1.4.2
- Corrected handling of the "$" RTC.
v1.4.1
- Fixed a bug causing the RATIO qualifier to function incorrectly.
v1.4.0
- Updated parser to support Regnus specification 5.2
- Improved helpfulness of script error messages.
- Added function to escape entities from generated text.
v1.3.1
- Fixed a serious bug causing errors when handling RATIO qualifiers.
v1.3.0
- Completely redesigned the file-reading process for improved efficiency.
v1.2.0
- First release compliant with Regnus specification 5.1