Documentation

Site PerlBanjo.com is a web playground for programming language Perl 5.

On this site you can:

• write Perl 5 code
• run the code and see the results (you can run code in one or several Perl 5 versions simultaneously)
• specify the exact command that will be executed
• create project with multiple files
• get the link to share your work

Site PerlBanjo.com optimised not only for desktop, but also for mobile devices.

Every run take place in isolated environment that is created for that run and is destroyed afterwards.

Here are some use cases for this site:

• write a runnable Perl 5 code and share it with colleague
• check on a go some Perl 5 feature
• see how the same code runs in different Perl 5 versions

Usage

The simplest thing you can do with PerlBanjo.com is:

• Open PerlBanjo.com
• Click button "Save for 30 days & run" (without changing anything)

This will run the sample code.

But you can run not only this sample code, but everything you like. Some examples of what can be done:

• create file data.csv and use Perl one-liner to parse it
• add file lib/Project.pm with some sub and a file t/main.t with tests for that sub (and use prove -lv t/ as a command to run tests)
• see how the copyright year changes in different versions of Perl perl --version | grep Copyright

After you press the button "Save for 30 days & run" two things happen:

• the files and their content, the run command, and the Perl versions are saved (all of that settings combined we call project). The result of the save is a string, something like "5cf2a1e8fe" (we name this string project_id, the value is just a random string without any hidden meaning). As soon as the save is complete, under the button the text with share link appear, "Code is saved as https://perlbanjo.com/5cf2a1e8fe" and the site url is set to that value.
• after we have the project_id this project is executed and the results are shown on the site. Under the hood there is a queue. For each project one or more tasks are added to the queue (for every Perl version that is selected in the project the separate task is created). Site checks the status of that tasks and when they are completed the results appear on the screen.

There is no cache. Every time the link is opened the code is executed.

Site interface consists of several main elements:

1. Files tab

This control shows all the files that exist in the current project and allow adding/deleting/renaming files. There can be zero or more files (you may choose not to add files in case everything is specified in the command input). The maximum number of files is five.

By default there is only one file called script.pl.

To rename a file click a tab to make it active and click on a file name.

File name can include a path. The path should be relative. Some examples: bin/script.pl, data/file.tsv, lib/Project.pm, t/Project/work.t.

There are some restrictions for the file names. If you enter invalid file name the system will show the tab in red and the button will be disabled:

All the files created here will be placed in the working directory where the project is run.

2. Code editor

This control shows and allows editing the content of the file that is active in file tab.

We are using Ace editor.

The minimum length of the file is 0 (you can create empty files) and the maximum length of a file is 5120 characters (that is 5 multiplied by 1024).

3. Command input

This is a field where you enter the command that the system will run. The default is perl script.pl, but you can enter something else: perldoc List::Util, prove -lv t/ or something like perl -E 'say join "\n", 1..3' | perl -nalE 'say $_*2'.

The minimum length of the value is 1 character, the maximum length is 1024 characters. If you don't specify the command the error appear and the button will be disabled.

4. Perl versions selector

This is a list of checkboxes. If you need to run your code in some specific Perl 5 version you can select the version. You can even select several versions of Perl 5 to see how the same code runs in different Perl 5 versions. You must select at least one version.

5. The button

The big green button with text "Save for 30 days & run". After you press it the share link is shows, the results appear on the screen and the text of the button is changed to "Run again".

The button does exactly what is written on it. For the 30 days the share link will show the saved project. After 30 days opening that link will give 404 "page not found" error.

There is a hotkey for this button: Ctrl + Enter or Cmd + Enter.

6. Results block

There are as many blocks for results as many Perl 5 versions are selected. In Perl version selector there are only 2 numbers in the version (5.NNN), but in the result block the exact Perl version is shown (5.NNN.NNN). (This is done with the idea of clarification that in share link stores only information about version 5.NNN, and the subversion 5.NNN.NNN is determined only when the link is opened in the browser)

Sometimes there can be errors.

"Stopped execution. Code is running too long." — you will see this message if there is an infinite loop in the code, or there is some other thing that makes the code run long. It is not possible to say exact script duration that is allowed. It is determined not only by the script itself, but by the overall system load. There should be no problem with scripts with execution time around couple of seconds.

"The result it too big. Showing only the beginning." — this error message is shown when the result is more that 51200 characters (1024 * 50).

Perl 5 versions

The Perl 5 programming language version consist of 3 numbers separated with dots (some examples: 5.8.9, 5.25.12, 5.30.0).

• The first number means language family and for the Perl 5 programming language it is always 5
• The second number is called version
• The third number is called subversion

Perl 5 uses the versioning scheme when the even version numbers are production releases and the odd version numbers are development releases. As an example, 5.30.0 is a production release and 5.31.2 is a development release.

Site PerlBanjo.com allows execution of Perl code in all Perl 5 production versions starting from 5.8 and up to 5.38. PerlBanjo.com has only one subversion for every major Perl 5 version. You can specify what Perl 5 version will be used, but you can't specify the exact subversion. Code will be executed with subversion that is available. Here is an example: you create code and specify version 5.30. Code is run in Perl 5.30.0 (for now that is the latest subversion available for 5.30). You save the link to that code and open it later, when the new 5.30.1 appeared. And that run is executed in 5.30.1).

Adding new versions and updating subversion

Site PerlBanjo.com has all the latest Perl 5 versions and uses the latest subversions for all Perl 5 versions that it has. When the new Perl 5 version releases it appears at PerlBanjo.com. When the new subversion for some Perl version is created then that Perl version is updated.

Usually it takes a couple of days between the new release and when it available at PerlBanjo.com.

Telegram bot

You can run Perl code with PerlBanjo.com using our Telegram bot @PerlBanjoBot.

You can message this bot directly:

Or you can add him to your group:

In a group bot responses to messages that start with his name:

The code that bot recieves is appened to the Perl script template:

#!/usr/bin/perl

use utf8;
use strict;
use warnings;
use feature qw(say);
use open qw(:std :utf8);

@PerlBanjoBot replies with the output of the Perl code that he recieves. Ather the output there is a link to this code at PerlBanjo.com to make it possible to continue working on this code in a web browser.

The code expired in 30 days.

Code is executed in the latest Perl version that is available at PerlBanjo.com.

There are some special cases. When there is no output the bot responses with <no output> message:

This is an internal limit for the code execution time. If the code does not finish in that time the bot will kill the code and response <timeout>:

There is also a limit to the maximum length of the output. It should not be more that 4000 characters. If the code output is more that 4000 characters, only 4000 will be shown with the additional message <output is truncated>. (Telegram max message size is 4096 characters).

The backticks Telegram problem and solution

Telegram does not send mackup to the bots, only pure text. You can send:

say 123

or you can send

`say 123`

In both cases @PerlBanjoBot will get the same text say 123 (the backticks will dissappear). So if you send the bot Perl code:

say `ls`

The bot will get the code without backticks — say ls and he will not do what you expected. To send message with backticks you need to enclose all your text to triple backticks:

```
say `ls`
```

Then the bot will recieve the code with the backticks and he will run it.

Privacy

You should consider that everything you place in PerlBanjo.com may be viewed by somebody else. Site administrators regularly reviews entered code to make sure the site works as expected.

There is also a possibility that new features will appear at PerlBanjo.com that will make all the share links visible (something like "The latest code" section). Don't expect this feature to come, but have in mind that this is possible.

You should not store sensitive information at PerlBanjo.com.

You can also check our Terms of Service and Cookie Policy.

Restrictions and limitations

(For the moment all of this is true, but it may change in the future)

• It is not possible to create code that does not expire
• Perl 5 language has lots of libraries. PerlBanjo.com has only the libraries that are shipped with Perl.
• PerlBanjo.com is not interactive. You can't create script that waits for the user input or shows some animation. PerlBanjo.com runs code, waits the code to finish and shows the output.
• The code running in PerlBanjo.com has no access to Internet
• PerlBanjo.com can't show binary output
• There is no public API
• The only way is allowed to use PerlBanjo.com is via web browser by human. It is not allowed to automate work with with site.

How to contact us

If you have any questions, or if you want to submit a bug, or propose a new feature, or anything else, you can always email us at info@perlbanjo.com or mention @PerlBanjo on Twitter.