geordi - C++ eval bot

Geordi

Table of Contents

  1. Introduction
  2. Usage
    1. Request syntax
    2. Flags
    3. Edit commands
    4. Operational notes
  3. Prelude
  4. FAQ
  5. Rules
  6. Minimizing clutter
  7. Download
  8. Known problems
  9. Example snippets

1. Introduction

Geordi is an IRC bot program that compiles and (optionally) runs C++ code snippets. It is intended to be used as a demonstration tool when teaching or discussing C++ on IRC.

A geordi bot by the name "geordi" is present on Freenode in the channels ##iso-c++, ##c++, and #geordi. It is referred to as geordi prime to avoid confusion with the software. This manual was mostly written with geordi prime in mind. Other geordi instances may have altered usage syntaxes, preludes, compiler flags, rules, et cetera.

Geordi is public domain, free software.

2. Usage

2.1 Request syntax

Geordi has 3 main request syntaxes, demonstrated by example below.

  1. Printing things

    To print things, stream things to geordi as if he were std::cout:

    <Eelis> geordi << 3 * 2 << " foo " << (9 > 4)
    <geordi> 6 foo true

    To accommodate the use of nick completion, "geordi" may be followed by a colon or comma.

    The code may be followed by a semicolon followed by more code, which is then placed before the definition of main (where the printing statement is put):

    <Eelis> geordi << f(3); int f(int x) { return x; }
    <geordi> 3

  2. Statement blocks

    To execute a block of statements, say for example:

    <Eelis> geordi { string s = "foo"; cout << s; }
    <geordi> foo

    Here, too, "geordi" may be followed by a colon or comma.

    The closing brace may be followed by more code, which is then placed before the definition of main (where the statement block is put):

    <Eelis> geordi { cout << f(3); } int f(int x) { return x; }
    <geordi> 3

  3. Programs

    To execute programs, say for example:

    <Eelis> geordi: void f(int x) { cout << x; } int main() { f(3); }
    <geordi> 3

    Here, a colon or comma after "geordi" is required if the next non-space character is a letter, an asterisk, a slash, or a single quote.

Line breaks

Whereas in ordinary C++ backslashes (outside of character/string literals) splice physical source lines to form a logical source line, in geordi snippets this behavior is inverted; backslashes split the physical source line into logical source lines.

Translation unit breaks

Two consecutive newlines (i.e. \\) split the snippet into multiple translation units.

2.2 Flags

In all three syntaxes described in the previous section, flags may be passed before any code. For the first two syntaxes, that means before << and {, respectively.

-c / --compile-only

Only compile; do not assemble, link, or run.

<Eelis> geordi -c void f (string & x) { reverse(x.begin(), x.end()); }
<geordi> Success

This better expresses your intent in demonstrations and produces a faster and more appropriate response from geordi. With -c, a main function is optional.

-w / --no-warn

Suppress warnings.

-t / --terse

Terse mode. Adds #include "terse.hpp", which defines shorter names for things.

<Eelis> geordi -tc use ns boost; tmp <tpn T> cls C { expl C (C co &); pvt: stc dub d; pub: void op() (); };
<geordi> Compilation successful

--no-using-std

Omits the otherwise implicitly added "using namespace std;".

-h / --help

Shows URL for this manual.

-v / --version

Shows the GCC version.

--show-compile-flags

Shows the flags passed to GCC.

--make-type <type description>

Shows the type described in C++ syntax.

<Eelis> geordi --make-type pointer to function returning a reference to an array of three pointers to functions taking integers and returning doubles
<geordi> double(*(&(*)())[3])(int)

--precedence <expression>

Shows the given expression with added parentheses to illustrate precedence and associativity of operators.

<Eelis> geordi --precedence a + b - c ? d : e+++f
<geordi> ((a + b) - c) ? d : ((e++) + f)

--resume / -r

Adds the previous snippet's code, except for its main function (if any).

<Eelis> geordi << f(); int f() { return 3; }
<geordi> 3
<Eelis> geordi -r << f() + g(); double g() { return 1.2; }
<geordi> 4.2
<Eelis> geordi, show
<geordi> << f() + g(); int f() { return 3; } double g() { return 1.2; }

2.3 Edit commands

Geordi provides a set of editing commands that modify and then retry the last snippet.

2.3.1 Syntax:

    command = (insert | append | prepend | erase | replace | move | swap | use | make)*

    insert = ("insert" | "add") (... positions* | wrapping ("around" substrs*)*)
    append = "append" ... [positions*]
    prepend = "prepend" (options | ...) [positions*]
    erase = ("erase" | "remove" | "delete" | "cut" | "omit" | "kill") (substrs | options)*
    replace = "replace" (substrs* ("with" | "by") ... | options ("with" | "by") options)*
    move = "move" (substrs "to" position)*
    swap = "swap" (substr "and" substr)*

    use = "use" (options | ... [relative])*
    make = "make" declarator-id* type-description

    wrapping = ... "and" ... | "parentheses" | "parens" | "braces" | "curlies"
      | ("square" | "angle" | "curly" | "round") "brackets"
      | ("single" | "double") "quotes"

    position = limit | befaft (substr [relative])
    positions = in-clause | befaft substrs

    substr = "everything" | [ordinal] (named-entity | ...)
    substrs = (("everything" | rankeds (named-entity | ...)) [relative])*

    befaft = "before" | "after"
    limit = "begin" | "front" | "end" | "back"
    ordinal = "first" | ("second" | "third" | etc) ["last"] | "last"
    rankeds = "all" [("except" | "but") ordinal*] | ["each" | "every" | "any" | ordinal*]

    in-clause = "in" ([ordinal] (named-entity | declarator-id) [relative])*
    named-entity = ("declaration" | "body") "of" declarator-id
    relative = between | befaft [ranked] substr | in-clause
    between = "between" (bound "and" relative-bound | ordinal "and" ordinal ...)
    range = ([["everything"] "from"] bound | "everything") ("till" | "until") relative-bound
    bound = limit | [befaft] substr
    relative-bound = limit | [befaft] substr [relative]

Ellipsis denote simple verbatim strings without escaping, quoting, globbing, etc. The notation  x*  stands for  x ["and" x*] .

2.3.2 Examples:

<Johnny> geordi: string s = "foo"; cin << s; }
<geordi> error: expected constructor, destructor, or type conversion before '<<' token
<Eelis> geordi: prepend { and replace cin with cout
<geordi> foo
<Johnny> Ah, I see!

Fixing longer snippets this way is easier and more to the point than copy&paste-ing.

The last snippet can be edited and re-edited indefinitely. Use the "show" command to show the snippet in its current form:

<Johnny> So, what does the snippet look like with those changes?
<Eelis> geordi: show
<geordi> {string s = "foo"; cout << s;}
<Johnny> Ah, I see!

More examples:

geordi, wrap parentheses around everything and erase second semicolon
geordi, insert << flush before second last << and move int i; to before int j = 3 * i;
geordi, move everything after int main() to front and erase int main()

2.3.3 The "use" edit command

For each given string, the "use" edit command searches the previous snippet for the substring that most resembles the given string, and replaces the former with the latter. This can be used to succinctly fix typos or make small adjustments:

<Johnny> geordi: -c class X { void f() }; void main() { statc X x(); x->f(); }
<geordi> error: expected ';' before '}' token
<Eelis> geordi: use void f(); }
<geordi> error: '::main' must return 'int'
<Eelis> geordi: use int main
<geordi> error: 'statc' was not declared in this scope
<Eelis> geordi: use static
<geordi> error: 'static' specified invalid for function 'x' declared out of global scope
<Eelis> geordi: use X x;
<geordi> error: base operand of '->' has non-pointer type 'X'
<Eelis> geordi: use x.f
<geordi> error: 'void X::f()' is private
<Eelis> geordi: use struct
<geordi> Success
<Eelis> geordi: show
<geordi> -c struct X { void f(); }; int main() { static X x; x.f(); }

Alternatively, these edits could have been specified with a single command:

<Eelis> geordi: use void f(); } and int main and static and X x; and x.f and struct

Geordi and the other users in the channel cannot read your mind, and the heuristics they use to determine which substring to replace are only "best effort". To prevent confusion (among geordi and the other users alike), it is therefore recommended to keep the modifications-to-context ratio of patterns low by being liberal with context, by not trying to simultaneously make multiple changes in a short code fragment, and by not trying to replace partial tokens (the heuristics have a strong bias in favour of whole-token replacements).

2.3.4 The "make" edit command

The "make" edit command changes properties (including type) of declarations:

<Eelis> geordi -c struct X { int i, j; virtual void f(X * p) const = 0; };
<geordi> Success
<Eelis> geordi, make f nonconst inline nonvirtual and make i a static reference to long and make p a const pointer to const
<geordi> Success
<Eelis> geordi, show
<geordi> -c struct X { long static int & i; int j; inline void f(const X *const p) ; };

Property descriptions generally follow the same syntax as with --make-type, with some additions.

"make" edit commands currently have a number of severe limitations:

2.4 Operational notes

3. Prelude

The implicitly included header prelude.hpp includes all standard library headers, some TR1 headers, several Boost headers, some namespace using's and aliases, and assorted miscellaneous utilities.

GCC bug 14940 prevents me from adding more TR1/Boost headers.

Descriptions of a few selected utilities follow.

3.1 Range and tuple printing

Ranges (such as containers) and tuples have been made streamable:

   <Eelis> geordi { vector<int> v { 3, 5, 9, 4, 1 }; cout << v; }
   <geordi> [3, 5, 9, 4, 1]

See more_ostreaming.hpp for details.

3.2 Displaying types

Streaming TYPE<T> prints the type T.

TYPE(e) yields a string representation in C++ syntax of the static type of the expression e.

TYPE_DESC works the same, but yields string representations in verbose English.

Examples:

   <Eelis> geordi << TYPE(&system)
   <geordi> int (*)(const char*)
   <Eelis> geordi << TYPE_DESC< int(&(*)())[5] >
   <geordi> pointer to a function taking no arguments and
     returning a reference to an array of 5 integers

See type_strings.hpp for details.

3.3 Tracked objects

tracked::B is a simple class whose constructors, destructor, assignment operator, etc. print a short message when called. Objects of type tracked::B are also kept track of in a central registry, and leaks are reported if the program exits while tracked::B objects are still around. For example:

   <Eelis> geordi { using tracked::B; B x (3), * y = new B;
     swap(x, *y); y->f(); }
   <geordi>  B0*(3) new(B) B1* B2*(B0) B0=B1 B1=B2 B2~
      B1.f() B0~ || leaked: B1

See tracked.hpp for a full list of tracked operations and additional tracked classes.

3.4 Comma-delimited output

Geordi overloads the comma-operator to make it easy to print comma-delimited values:

   <Eelis> geordi << 3, "oi", sin(3.9)
   <geordi> 3, oi, -0.687766

A slightly less terse but more flexible alternative is del, which can be used either as a manipulator or in place of cout, and which lets one optionally specify the delimiter:

   <Eelis> geordi { cout << del << 3 << sin(3.9) << "oi. ";
     del("; ") << 9 << 'x' << true; }
   <geordi> 3, -0.687766, oi. 9; x; 1

See delimited_ostream.hpp for details.

3.5 Base-2 (binary) integer output.

Geordi adds bin to the std::hex/std::oct/std::dec family of I/O manipulators, with the semantics you would expect:

   <Eelis> geordi << showbase << bin << 38
   <geordi> 0b100110

See bin_iomanip.hpp for details.

3.6 Labeled value display

   <Eelis> geordi { int x = 45, y = x * x; cout << SHOW(x), SHOW(y),
     SHOW(y - x); }
   <geordi> x = 45, y = 2025, y - x = 1980

3.7 [Begin, end)-range shorthand

The RANGE macro expands RANGE(r) to (boost::begin(r)), (boost::end(r)) , which saves some typing for common cases.

   <Eelis> geordi { int a [40]; fill(RANGE(a), 6); cout << a[31]; }
   <geordi> 6

(See Boost.Range.)

3.8 BARK

BARK prints the name and signature of the function in which it appears:

   <Eelis> geordi { f(3.2); f('x'); } void f(int) { BARK; } void f(double) { BARK; }
   <geordi> f(double) f(int)

4. FAQ

  1. How can geordi safely allow execution of arbitrary code?

    The execution of the compiler, assembler, linker, and resulting program is all ptraced to disallow most system calls, is done as user/group nobody in a minimal chroot, and is subjected to strict resource limits and a timeout. Additionally, geordi can be run in sandboxed environments like User-Mode Linux and Xen.

  2. What language is geordi written in?

    Haskell.

  3. Can you make geordi prime join channel #foo?

    First, you can always run your own geordi instance (though setting up geordi can be a pain in the ass). See Download.

    That said, if #foo is a serious programming channel on Freenode that is not just a place to hang out, /join #geordi and talk to Eelis (who hosts geordi prime), and he'll consider having geordi prime join #foo.

  4. Where can I play around with geordi?

    /join #geordi. Please, please, do not spam other channels!

  5. Is geordi suitable for small benchmarks?

    NO! Geordi uses various costly compiler flags and runtime aids to help diagnose ill-behaved code, making any kind of performance measure meaningless.

  6. I bet I can break geordi!

    You are quite welcome to try, but please do so in the #geordi channel.

  7. How can I make a suggestion? / I broke geordi! / I have another question.

    On Freenode, /join #geordi and/or /msg Eelis. Alternatively, mail to <name-of-this-software>@contacts.eelis.net .

5. Rules

  1. Don't spam (i)

    Only pass geordi snippets when you're trying to demonstrate something to somebody (except in #geordi, where you are free to experiment as much as you like).

  2. Don't spam (ii)

    If you make a mistake in your snippet when trying to demonstrate something, give yourself at most one more attempt to get it right. If you fail to get your snippet right in your second attempt, then /join #geordi, work out your snippet there until it works, and then show it in the other channel.

6. Minimizing clutter

Non-syntax-highlighted code with multiple statements all on a single line quickly becomes hard to read. Here are some tips to shave a few tokens off your snippets:

  1. Use the shorthand syntaxes whenever possible. When you must use the "geordi: ..." syntax, don't list main's parameters if you don't need them. Finally, return 0; is implicit for main.

  2. Use the prelude utilities when appropriate.

  3. Don't use std:: qualification; namespace std has been using'd. Yes, this is normally considered poor style, but our unique spatial constraints justify its use for geordi.

  4. Don't bother with endl or flush; geordi only outputs the first line anyway, and cout is flushed automatically at the end of the program.

  5. Stuff values into containers using vector<int> v; v += 4, 3, 6, 2, 5; (this works thanks to Boost.Assign).

  6. Use struct instead of class to avoid having to type public: for bases and members.

7. Download

8. Known problems

Since geordi just uses GCC, it inherits most of its problems. Some of the most annoying ones are listed below.

9. Example snippets