box_readme.md.erb

# <%= name %> programming language

* [Official Referrence of **<%= name %>**](<%= link %>)

This image is a part of [esolang-box 2.4.0](https://github.com/hakatashi/esolang-box).

## About

[**esolang-box project**](https://github.com/hakatashi/esolang-box) aims
to provide easy and normalized interface for many (currently <%= language_count %> (!)) programming languages by Docker,
especially to uncommon [esoteric programming languages](https://en.wikipedia.org/wiki/Esoteric_programming_language).

The implementation and interpreter of language <%= name %> is included in this image and
can be invoked by the simple one command `<%= slug %>`.
(it's also an alias of `script` command, so you can use either.)

This script accepts standard input as the input of program and the first argument as program code file.
The output of the script will be printed into standard output.
This convension is shared between [all esolang-box images](https://hub.docker.com/u/esolang/),
so you can use another language easily.

## Usage example

### Run a single <%= name %> script

Supposing you have hello world script `<%= hello_file %>` in the current directory like this:

<% if hello_content.nil? %>
```
$ ls
<%= hello_file %>
```
<% else %>
```
$ cat <%= hello_file %>
<%= hello_content %>
```
<% end %>

You can execute it with the following command:

```
$ docker run --rm -v "$PWD":/code:ro esolang/<%= slug %> <%= slug %> /code/<%= hello_file %>
<%= hello_out %>
```

### Processing input

```
$ docker run -i --rm -v "$PWD":/code:ro esolang/<%= slug %> <%= slug %> /code/<%= hello_file %> < input.txt
```

### Debug code with shell

```
$ docker run -it --rm -v "$PWD":/code:ro esolang/<%= slug %> sh
# <%= slug %> /code/<%= hello_file %>
<%= hello_out %>
```

### Observing usage of exec syscalls

esolang-box 2.4.0 supports tracing of `execve` and `execveat` syscalls by strace command.
Setting `STRACE_OUTPUT_PATH` environment variables and enabling ptrace will produce strace log to the specified path.

```sh
$ docker run --cap-add=SYS_PTRACE --rm -v "$PWD":/code --env STRACE_OUTPUT_PATH=/code/strace.txt esolang/<%= slug %> <%= slug %> /code/<%= hello_file %>
<%= hello_out %>
```

Some considerations:

* [**Enabling ptrace breaks seccomp filter before kernel 4.8.**](https://bugs.chromium.org/p/project-zero/issues/detail?id=1718) You should be very careful to use `--cap-add=SYS_PTRACE` (especially you must not use it with Xenial).
* Using strace costs a huge performance overhead and syscalls may be 10x slower.

<% if disasm %>
### Disassembly

This image supports disassembly feature. You can use `disasm` script to disassemble any <%= name %> scripts to more readable ones.

```
$ docker run --rm -v "$PWD":/code:ro esolang/<%= slug %> disasm /code/<%= hello_file %>
```
<% end %>