Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
doc:pycram:language [2021/07/02 12:09] – created jdechdoc:pycram:language [2021/07/08 10:28] (current) – jdech
Line 13: Line 13:
  
 The next thing you should keep in mind is that you can't directly execute the file which imports the macro of the plan language. Instead you have to create another file which imports the activation method of MacroPy and then executes the code in the file which contains the macro. This can then look like this: The next thing you should keep in mind is that you can't directly execute the file which imports the macro of the plan language. Instead you have to create another file which imports the activation method of MacroPy and then executes the code in the file which contains the macro. This can then look like this:
-<code> +<code>
 import macropy.active import macropy.active
 import demo import demo
Line 21: Line 21:
 ===== Plan Language Expressions =====  ===== Plan Language Expressions ===== 
 There are a total of five expressions available in the plan language adding to this is the error handling which adds more control over the handling of errors than the standard Python way.  There are a total of five expressions available in the plan language adding to this is the error handling which adds more control over the handling of errors than the standard Python way. 
 +The expressions can be categorized in 3 categories, sequential execution, parallel execution and error handling. All expressions will catch errors that may be raised during execution, so the program isn't stopped, and update their state correspondingly. The state of an expression can either be SUCCEEDED or FAILED, the conditions if an expression succeeds or fails are different for every expression. The raised errors can be stored in a list for later inspection of what went wrong. 
 +
 +To store the errors in a list a variable has to be passed to the expression, this is optional and does not have to be done for the expression to work. 
 +
 +==== Sequential Expressions =====
 +=== seq === 
 +The seq expression executes all given statements after another, if one of the statements raises an error the others will not be executed and the state will be updated to FAILED. An example on how to use the seq expression can be seen below. 
 +<code> 
 +from pycram.language import macros, par 
 +
 +errors = []
 +with seq(errors) as state:
 +    statement1
 +    statement2
 +</code>
 +Here you can see that the errors which occur during execution will be saved in a variable which is handed to the expression. The statements will be executed after another so if an error occurs in the execution of statement1 this error will be saved in the errors variable and the expression will be terminated. 
 +
 +It is also possible to use the expression without an error list, an example of this can be seen below. 
 +<code>
 +from pycram.language import macros, par 
 +
 +with seq as state:
 +    statement1
 +    statement2
 +</code>
 +
 +=== try_in_order === 
 +The expression try_in_order executes all given statements in order but unlike seq this expression will stop if one of the given statements succeeds. For this expression there is also the possibility to use a list to store raised errors, this is an optional feature. 
 +The expression is used similar to the seq expression. 
 +<code> 
 +from pycram.language import macros, try_in_order
 +
 +with try_in_order as state:
 +    statement1
 +    statement2
 +</code> 
 +
 +==== Parallel Expressions ==== 
 +=== par === 
 +The expression par executes every given statement in a separate thread, if one of these threads raises an error the state of this expression will be set to failed. However, the other threads will still be finished because Python doesn't support interrupting threads and so the threads can clean up allocated memory. 
 +
 +This expression also supports the possibility of passing a variable to save a list of raised errors. This is, like in all expressions, an optional feature. 
 +
 +<code> 
 +from pycram.language import macros, par
 +
 +with par as state:
 +    statement1 
 +    statement2
 +</code>
 +This will create two new threads and execute statement1 in the first thread and statement2 in the second one. 
 +If you want to group multiple statements together because they should be executed in the same thread you have to put them in a block. For this you can, for example, use the seq expression. 
 +<code> 
 +from pycram.language import macros, par, seq
 +
 +with par as state:
 +    statement1 
 +    with seq as s:
 +        statement2
 +        statement3
 +</code>
 +If you want all statements to be executed and don't want the behaviour of the sequential expressions you can use an if statement. 
 +<code> 
 +from pycram.language import macros, par, seq
 +
 +with par as state:
 +    statement1 
 +    if True:
 +        statement2
 +        statement3
 +</code>
 +**This grouping of statements works for all parallel expressions.**  
 +
 +=== try_all === 
 +This expression will also execute all given statements in separate threads. The state will be set to SUCCEED if one of the statements executes without an error and FAIL if all statements raise an error during execution. 
 +
 +<code>
 +from pycram.language import macros, try_all
 +
 +with try_all as state:
 +    statement1
 +    statement2
 +    statement3
 +</code>
 +The expression will create a separate thread for every statement execute them and afterwards collect them again so the user doesn't have to worry about thread management. 
 +
 +=== pursue === 
 +This expression also creates a thread for every given statement and executes them in parallel. The state will be set to SUCCEEDED if one statement is executed without raising an error and FAILED if one of the statements raises an error during execution. 
 +
 +<code>
 +from pycram.language import macros, pursue
 +
 +with pursue as state:
 +    statement1 
 +    statement2 
 +    statement3
 +</code>
 +
 +
 +==== Error Handling ==== 
 +The PyCRAM plan language comes with its own way of handling errors which is combined with the standard python way and. There are two things which the plan language adds to error handling. Firstly, a retry function which executes the code again, this enables the developer to implement recovery behaviour and to repose the robot and then try the failed code again. 
 +Secondly, a retry counter which determines how often the retry function can be called. If the passed counter is zero, negative or no counter is passed, the retry function can be called an unlimited time.
 +
 +Below you can see examples on the different ways the error handling can be used. 
 +<code>
 +from pycram.language import failure_handling
 +
 +with failure_handling():
 +    try:
 +        statement1
 +    except Exception as e:
 +        retry()
 +</code>
 +
 +The retry function is automatically implemented by the failure handling and can be used within the scope of the failure_handling.
 +
 +<code> 
 +from pycram.language import failure_handling
 +
 +with failure_handling(3):
 +    try:
 +        statement1
 +    except Exception as e:
 +        retry()
 +</code>
 +In this case we pass a number to the failure handling, this number defines the number of retries meaning how often the retry function is maximally called.