Skip to content

Commit 653fd51

Browse files
verhasverhas
committed
extended documentation
1 parent b3aa184 commit 653fd51

5 files changed

Lines changed: 172 additions & 16 deletions

File tree

‎site/basic/sentence.md‎

Lines changed: 104 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,4 +30,107 @@ Matching the line against a sentence definition succeeds if the characters, word
3030
defined in the `sentence` commands and the `$expression` placeholders match expressions.
3131

3232
When a sentence is matched the syntax analyzer creates a method call to the named mathod using the expressions as
33-
arguments. The expressions are passed from left to right.
33+
arguments. The expressions are passed from left to right.
34+
35+
## Examples
36+
37+
### Simple sentence
38+
39+
You can define a simple subroutine that asserts that the two arguments are equal and in case they are not then
40+
it signals error:
41+
42+
```
43+
sub assertEquals(a,b)
44+
if a <> b then
45+
error "equality assertion failed"
46+
endif
47+
endsub
48+
```
49+
50+
We can invoke it directly from the code calling the method by the name or we can define a sentence
51+
52+
```
53+
sentence "assert that $expression is the same as $expression" call assertEquals
54+
```
55+
56+
Following this line we can write
57+
58+
```
59+
assert that 13+2 is the same as 15
60+
```
61+
62+
This line will be recognized by the BASIC interpreter and executed as
63+
64+
```
65+
assertEquals 13+2, 15
66+
```
67+
68+
69+
### Start with expression
70+
71+
You can start a sentence with an expression.
72+
73+
```
74+
sentence "$expression is the answer" call isTheAnswer
75+
42 is the answer
76+
77+
78+
sub isTheAnswer( a )
79+
if a <> 42 then
80+
error a + " is not the answer"
81+
endif
82+
endsub
83+
```
84+
85+
will actually work.
86+
87+
You can have many sentences that start with an expression. Together with the previous example you can also have
88+
89+
```
90+
sentence "$expression is exactly the answer" call isTheAnswer
91+
42 is exactly the answer
92+
```
93+
94+
in the same program.
95+
96+
### Start with keyword
97+
98+
You can also start a sentence with a BASIC keyword.
99+
100+
```
101+
sentence "for example $expression " call isTheAnswer
102+
for example 42
103+
```
104+
105+
will just work fine. However it is to note that if there is a syntax error in this line, for example
106+
107+
```
108+
for exampla 42
109+
110+
... There is no '=' after the 'FOR'
111+
112+
```
113+
114+
the syntax analyzer will complain about the missing `=` character it expectes in a `FOR` statement.
115+
116+
A sentence can not start with a `'` character or with the keyword `REM` because these start comment lines and are skipped
117+
by the syntax analysis and such a use of the `sentence` definition is also counterintuitive. Thus if you try
118+
to create a sentence
119+
120+
```
121+
sentence "rem sleep phase start" call StartRemPhase
122+
```
123+
124+
in your sleep monitoring application then you will get an error starting the code (rather than just not calling the
125+
`StartRemPhase` method).
126+
127+
### Start with special character
128+
129+
You can not only include but you can also start a sentence with some special character. For example
130+
131+
```
132+
sentence ". this is $expression" call expression
133+
.this is "a string expression"
134+
```
135+
136+
defines and uses a sentence that starts with a period.

‎src/main/java/com/scriptbasic/syntax/commands/BasicCommandFactory.java‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,15 @@ private Command createFromStartingSymbol(final String commandKeyword)
102102
LOG.debug("Creating command starting with the keyword '{}'",
103103
lowerCaseCommandKeyword);
104104
if (classMap.containsKey(lowerCaseCommandKeyword)) {
105-
return classMap.get(lowerCaseCommandKeyword).analyze();
105+
try {
106+
return classMap.get(lowerCaseCommandKeyword).analyze();
107+
}catch (AnalysisException originalException){
108+
try{
109+
return dslAnalyzer.analyze();
110+
}catch (AnalysisException ignored){
111+
throw originalException;
112+
}
113+
}
106114
}
107115
return dslAnalyzer.analyze();
108116
}

‎src/main/java/com/scriptbasic/syntax/commands/CommandAnalyzerDSL.java‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,15 @@ private void defineDSLRule() throws AnalysisException {
8585
throw new BasicSyntaxException("there should be a function name after the keyword 'call' defining a sentenceó");
8686
}
8787
consumeEndOfLine();
88-
dslLines.add(new DslLine(functionNameLexicalElement.getLexeme(), sentence.split("\\s+")));
88+
final String[] syntaxElements = sentence.split("\\s+");
89+
if( syntaxElements.length == 0 ){
90+
throw new BasicSyntaxException("sentence can not be empty");
91+
}
92+
final String startElement = syntaxElements[0];
93+
if( startElement.equals("'") || startElement.equalsIgnoreCase("rem")){
94+
throw new BasicSyntaxException("sentence should not look like as a comment");
95+
}
96+
dslLines.add(new DslLine(functionNameLexicalElement.getLexeme(), syntaxElements));
8997
}
9098

9199
private class DslLine {

‎src/test/java/com/scriptbasic/testprograms/TestPrograms.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ public void testPrograms() throws Exception {
131131

132132
@Test
133133
public void canDefineAndUseDslSentences() throws Exception {
134-
codeTest("TestDslLines.bas", "OK");
134+
codeTest("TestDslLines.bas", "79OK");
135135
}
136136

137137
@Test

‎src/test/resources/com/scriptbasic/testprograms/TestDslLines.bas‎

Lines changed: 49 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,68 @@
1-
sentence "the $expression is the same as $expression" call myequals
2-
the 13+2 is the same as 15
1+
sentence "for the ( $expression ) and ( $expression )" call nullsub
2+
3+
for the (6) and (7)
4+
5+
sentence "assert that $expression is the same as $expression" call assertEquals
6+
assert that 13+2 is the same as 15
37

48
sentence "message $expression unless $expression is true" call assert
59
message "we have a problem" unless 1=1 is true
610

711

12+
sentence "$expression is the answer" call isTheAnswer
13+
42 is the answer
14+
15+
16+
sub isTheAnswer( a )
17+
if a <> 42 then
18+
error a + " is not the answer"
19+
endif
20+
endsub
21+
22+
23+
sentence "$expression is exactly the answer" call isTheAnswer
24+
42 is exactly the answer
25+
26+
sentence "for example $expression " call isTheAnswer
27+
for example 42
28+
29+
830
sentence "true that 1 $expression has 1 result" call nullsub
931
true that 1 2*2 has 1 result
1032

1133

12-
sentence ". this is $expression $ expression" call expression
34+
sentence ". this is $expression" call expression
35+
.this is "a string expression"
1336

14-
.this is "no way" $expression
37+
38+
sentence "$expression compareTo $expression" call assertEquals
39+
40+
13+2 compareTo 11+4
41+
42+
sentence "$expression" call printFunction
43+
44+
45+
46+
47+
66+13
48+
49+
sub printFunction(e)
50+
PRINT e
51+
endsub
52+
53+
PRINT "OK"
1554

1655
sub expression(xp)
17-
if xp <> "no way" then
56+
if xp <> "a string expression" then
1857
PRINT "Problem"
1958
endif
2059
endsub
2160

22-
sub myequals(a,b)
23-
if a = 15 and b = 15 then
24-
PRINT "OK"
25-
else
26-
PRINT "CALLED BUT THE VALUES ARE", a, " AND ", b
27-
endif
61+
sub assertEquals(a,b)
62+
if a <> b then
63+
error "equality assertion failed"
64+
endif
2865
endsub
2966

30-
sub nullsub(a)
67+
sub nullsub(a,b)
3168
endsub

0 commit comments

Comments
 (0)