document syntax of new parameter file parser

Create issue
Issue #1303 closed
Roland Haas created an issue

currently we have no documentation as to what format the new parser accepts. As a matter of fact the documentation in the UsersGuide (see http://einsteintoolkit.org/documentation/UsersGuide/UsersGuidech7.html#x10-37000B3.2) is in contradiction with what the parser will allow:

* The parameter file is read sequentially from top to bottom, this means that if you set the value of a parameter twice in the parameter file, the second value will be used. 
* String parameter values can be specified either as unquoted tokens (not containing any whitespace), or as quoted values. If a quoted string parameter value spans multiple lines, all whitespaces, including newline characters, are preserved.

which will fail. Actually the first one is already incorrect with the current implementation which does not allow a parameter to be set twice (since this is often a sign of a user error).

While this is "just" documentation, I'll still flag it as major since the parser is so fundamental.

Keyword:

Comments (12)

  1. Steven R. Brandt
    • removed comment

    I found this in the docs. What does it mean for unary operators to associate to the left?

    The exponentiation operator ** as well as the unary oper- ators associate to the left which differs from the common convention in mathematics.

  2. Roland Haas reporter
    • removed comment

    For unaries the statement makes no sense. They have to associate to the right since this is the only argument they have. I think my (I added the docs) statement for unary operators is nonsensical since they always have to associate like this (since I don't think I ever supported postfix operators)

    - ++i = -(++i)
    

    which is association to the right. It also allowed (I think) normally disallowed things like:

    a * -b == a * (-b) and
    a + - b == a + (-b)
    

    .For '**' I had

    a**b**c == (a**b)**c
    

    while normally one would have

    a**b**c == a**(b**c)
    

    . I assume your parser does the "normal" ordering anyway. NOTE: the "old" parser is still going to be used for some parts of the code when ParameterSet is called directly.

  3. Erik Schnetter
    • removed comment

    Association of unary operators is related to precedence. Let's take the C expression ++x[0]; here there are the two operators "++" and "[0]" (if we interpret this as operator). The question is which of these two operators is applied first. In C/C++, this order is always right-before-left, so that x[0] is incremented, and not x, i.e. the expression is parsed as ++(x[0]).

    See also http://en.cppreference.com/w/cpp/language/operator_precedence.

  4. Steven R. Brandt
    • removed comment

    I see. Well, this is not so relevant when the only unary operators are !, +, -, and [0] (and ! are not allowed to be combined with + or -).

  5. Ian Hinder
    • removed comment

    Are there at least some example parameter files which can show me how to use this feature?

  6. Roland Haas reporter
    • removed comment

    There is the test parfile in arrangements/CactusTest/TestPar/test/expressions.par which exercises an abundance of features for the expression parser and the array syntax. The expression syntax is described in the users guide. I am not away of documentation on the array syntax.

  7. Steven R. Brandt
    • removed comment

    Sorry for being slow about this. I'll try and get an update to the docs next week.

  8. Log in to comment