Header fields

An overview by Dennis C. Bemmann

Header fields - what's that?

The RoboCom Language Standard 3.00 introduces Header fields. These are lines at the beginning of a RoboCom program which do not influence the behavior of the program itself but which can provide information for other people, for the interpreter, for competition servers etc.

Fields such as Name, Author, Country are already known from RoboCom 2.x. The important news in Version 3.00 is:

1. The interpreter ignores unknown header fields. This makes sure that RoboCom interpreters and servers are somewhat future-proof, as new header fields may be introduced.

2. Header fields are clearly marked as header fields. Thus they cannot be mistaken as bad instructions anymore. Vice versa syntax errors in the instructions will still be recognized and not mistaken as unknown header fields.

Syntax

The Syntax of declaring a header field is:
<Type> <Identifier> <Value>

Let's have an example:
Published Author Robert Robot

The field identifier is Author, so this line tells us the name of the person who wrote the program. His name (Robert Robot) follows after the field identifier and goes on until the line ends. Published specifies the type of the field.

Header Types and field names are not case-sensitive.

Types of header fields

A header field always has a type. This serves two purposes. First of all the interpreter recognizes that here comes a header field (and not a bank or an instruction or whatever), and second: the author can specify how the information stored in the field is treated by the interpreter or server. The following three types are recognized:

Published means: the value of this field is readable by anybody who gets the source code. This is the case for most fields.

However, header fields can also be used to identify and authentificate the author (for examle if he wants to delete his program from a server). You wouldn't want to give information like passwords to other people. That's why you simply store it in Secret fields. The value of a secret field is (of course) readable if you distribute the very same source file. However, competition servers and other .ROB-code processors cut all secret fields out when they distribute a program, so you need not worry about this.

You can safely forget about Internal fields. They are not for RoboCom programmers, but for interpreters and servers (to conveniently store internal information directly in the .ROB file). You will probably never get to see any internal fields, because they get cut out as well. They are only mentioned here because Internal is a reserved word in the RoboCom Language Standard. You should not use it in your programs.

Recognized fields

The following table shows all recognized header fields and their meaning. For an up-to-date list, take a look at the RoboCom Homepage.

Field name Meaning
Name The Name of the RoboCom program. Call it what you like :-)
Author The Name of the person who wrote the program.
Language Specifies the RoboCom language standard for which the program was written. The typical value should be RC300 (RoboCom 3.00)
Comment Here you can leave a short message to the RoboCom world.
URL A related internet address. This can be a web page with more RoboCom programs, the homepage of the author, a link to the newest version of the program etc.
Password The file password. If you want to update, overwrite or delete your RoboCom program on a competition server, you have to use the same password as in the existing file! This prevents trouble-makers from messing around with other people's programs. Note: the password should always be a Secret header field.
EMail The author's eMail address.
Country The home country of the author. Note: DO NOT use this field for comments or to send greetings or web addresses! Those can be stored in the appropriate fields (Comment, URL, ...) The Country field should either be used for the country or not be used at all.
Compete Specifies whether the program competes in a competition to enter the charts or just to test it against other programs. Valid values are yes or no.
OpenSource Specifies if a competition server should distribute the source code of the program or just a binary version. Valid values are yes or no. Note: this enables you to publish your program even in non-open-source competitions, but it does not prevent it from being published in competitions which are clearly marked as open-source.
OptionSet Specifies the name of the recommended OptionSet to run the program. If somebody tries to simulate the program with a different OptionSet, the interpreter will display a warning but still simulate it. You should use this field if your program is optimized for special options, like un-usual timing.
OptionSetReq Specifies the name of the OptionSet which is required to run the program. If somebody tries to simulate the program with a different OptionSet, the interpreter will refuse to assemble it. You should use this field if you make use of features like Multitasking which are not enabled in certain OptionSets, or if you use other features that could cause fatal errors in your program if attempted with a different OptionSet.

Example program

The following example program shows how to use headers fields.

Example program: HeadersPro.rob
; RoboCom 3 Example Program for Header fields

Published Name HeadersPro             ; Name of this program
Published Author Dennis C. Bemmann    ; My name
Published EMail dennis@bemmann.de     ; My eMail address
Published Country Germany             ; My home country

Published Language RC300              ; It's a RoboCom3 program
Published OpenSource yes              ; Everybody can see it
Secret    Password rumpelstielzchen   ; For uploading on server

Bank Main
  @Main.Loop
  Create 2, 2, 0
  Trans 1, 1
  Set %Active, 1
  Turn 0
  Jump @Main.Loop