WIP Notes - xandevelop/wigwamdocs GitHub Wiki

WIP - nothing in here is really right yet, just a place to organise some ideas...

WigWam V2 Some features (pre and postconditions for example) were hard to get right in WWV1 and hard to reason about when writing test scripts, so I've decided to deprecate them in favor of namespaces.

New spec: Stage 1 - scanner - read file, trim whitespace, remove comments, prepare for parser. Stage 2 - first pass parser - convert to AST. We don't know at this point if users have used existing functions or not because a function can be used before it's declared. Stage 3 - patchup function calls Stage 4 - code generation

Scanner Spec

Comment = # to EOL
IGNORE WHITESPACE // ignore newlines, space at end of lines, be careful of string rules - trim not remove.  Read underscore as space - _a_ is "a"; _b_c_ is "b c"

Pragma INCLUDE path

Scanner = {Line}
Line = Block { '|' Block }

Language Examples

Note: The difference between param and arg is that a param is Formal Parameter, i.e. Forms part of the signature, defines the way something is called. Argument is a supplied value that fulfils that signature and is supplied by the caller.

Test Cases

Test | Hello World
  echo | message=Hello World
End Test

Rules:

Test
=
  "Test" "|" TestNameArg
  TestBody
  ["End Test"] // Test may also be ended by start of another thing like a function, page, other declaration.

TestNameArg = ["name" ("="|":")] string

TestBody = TestStatement {TestStatement}

TestStatement = FunctionCall    // maybe others - come back to this

Function Declarations

Function | Say hello to user | ${Username}=Joe
  echo | Hello, ${Username}
End Function

test | x
  Say hello to user                 # Expect Hello, Joe
  Say hello to user | bob           # Exp Hello, bob
  Say hello to user | username=ben  # Exp Hello, ben

Function | Say hello
  Say hello to user | Username=world
End Function

Function | Get value | Username
  store | ${Username} | 1
End Function

Function | Show value
  Get value | ${Username}
  echo | ${Username} # expect 1
End Function

Namespaces

A namespace is a complicated idea to explain, so we're going to use "namespace" and also "page" as a synonym for it because that'll be how it's likely to be used (though not always) - we want both words so that we can have things like MyPageWhenLoggedIn and MyPageWhenNotLoggedIn and not be forced to use the page syntax.

E.g.

Page | Home Page

  Function | Say Hello to user | Username
    echo | Hello, ${Username}
  End Function

End Page

Test | I can say hello
  Home Page | Say Hello | Username=Bob
End Test

Can pages contain tests? Why would a namespace contain a test? For grouping them in a related area... Why would a page contain a test? Because we want to keep our tests near our page declaration and avoid name conflicts

Variables

  store | x | 1
  echo | ${x}

Urls

Url | Base | www.example.com
Url | Home Page | ${Base}/home.htm

page | Contact Us
  Url | Url | ${Base}/contact.htm
end page

Url | Article | ${Base}/Article?Id=${id}
  Parameter | name=id | default=0
End Url

test | examples
  echo | ${Base}            # www.example.com
  echo | ${Home Page}       # www.example.com/home.htm
  echo | ${Contact Us Url}  # www.example.com/contact.htm
  echo | ${Article}         # www.example.com/Article?Id=0
  echo | ${Article(5)}      # www.example.com/Article?Id=5
  echo | ${Article(id=10)}      # www.example.com/Article?Id=10
end test

Controls

control | Button | xpath=pathhere

control | Table | id=table

control | Row | xpath=${Table}/tr[${rownum}]
  param | name=rownum | default=0
end control

test | examples
  click | ${Button}     # click on xpath=pathhere

  click | ${Table}      # click on id=table

  click | ${Row}        # click on xpath=id=table/tr[0]

  click | ${Row(1)}     # click on xpath=id=table/tr[1]
end test

Levels of things

Above is mostly Definitions... Definition may be a single line, or a few lines e.g. Url can have params or not.

Pass 1: Scan Pass 2: Work out starts and ends of definitions. Add to a symbol table so pass 3 can detect undefined references Pass 2.5: for each definition, work out what its formal parameters are so pass 3 can check arguments match Pass 3: Compile the inner content of each definition, switching strategy based on which type we're looking at

Pass 3 write an algorithm for each example above...