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.
Poem For My BeauI wander shy as a leek,
I shall seep my shy pillow,
And then I feel a little sleek,
And then to sit upon a dough.
Only once did I feel sleek,
I will date and saw my fate,
To reek the liars and then the beak,
Forever now, the foes are late.
Here, upon my shy jackdaw,
I shall flow my spry week,
And then I feel a little sore,
To keep me weak until I reek.
Generated by the Regnus script Rhyming Poem Generator, by
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, 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!)
Note: the Regnus Parser for PHP fully supports UTF-8 character encoding, so scripts parsed using this parser are recommended to be encoded in this format.
Information & Download
- Parser Version
- v1.8.4
- Regnus Specification
- v5.5
- 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.
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 can simply 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
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.
- Protocol
-
- PHP Variable
- $Regnus_FileProtocol
- URI Parameter
- protocol
- Description
- Specifies the protocol (HTTP etc.) by which the script file should be requested. If set, the content of this parameter is prepended to the script address, primarily in order to workaround overzealous server security measures, which can sometimes be triggered by seeing a full URI passed as a parameter.
Attribution
Please feel free to use the following link to let people know that your page is powered by Regnus!
<p>Random content on this page generated by the <a href="http://www.regnus-scripting.info/">Regnus</a> scripting language.</p>
Version History
v1.8.4
- Removed redundant code to improved parser efficiency.
- Fixed bugs causing incorrect behaviour when processing UTF-8-encoded RSF files.
- Improved behaviour of automatic pluralisation function.
v1.8.3
- Fixed bug causing the conditional space AGC not to function correctly.
v1.8.2
- Fixed bug causing exponentiation in dice notation expressions not to function correctly.
v1.8.1
- Fixed bug causing aliases not to function correctly.
v1.8.0
- Fixed bugs causing labels in "RATIO" and "COUNT" entries not to function correctly.
- Implemented support for the Regnus 5.5 "START" qualifier.
- Implemented support for Regnus 5.5 fractional ratios.
- Implemented support for Regnus 5.5 dice notation.
- Improved and corrected code for accuracy of error reporting during parsing of expressions.
- Implemented support for Regnus 5.5 inline entry selection.
- Improved code for accuracy and efficiency.
v1.7.4
- Fixed bug causing numeric values not to be parsed correctly for nested references.
v1.7.3
- Fixed bug causing pluralisation not to work correctly when combined with capitalisation.
- Minor code tidying.
v1.7.2
- Fixed bug causing error due to erroneous case-sensitivity when using the COUNT qualifier.
v1.7.1
- Parser now correctly returns an empty result when seeking an alias for an empty expression.
- Parser now gives priority to longer phrases when using MULTI qualifiers, in order to generate more intuitive output.
v1.7.0
- Added new "protocol" parameter to help workaround overzealous server security interference.
v1.6.0
- Updated parser for compliancy with Regnus specification 5.4.
- Nested hidden text brackets now function correctly.
- Multiple MULTI qualifiers no longer erroneously cause multiple plurals to be returned.
- Fixed variable to correct working of (X)HTML New Lines parameter.
v1.5.0
- Parser updated to support Regnus specification 5.3.
- Parser now reports correct error upon encountering invalid characters within references.
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