updated fmscript skills
This commit is contained in:
1 file changed
+114
-41
@@ -1,63 +1,136 @@
|
||||
# `.fmscript` 0.90 grammar reference
|
||||
|
||||
Source: <https://fmscript.org/spec.html>
|
||||
Source: [https://fmscript.org/spec.html](https://fmscript.org/spec.html)
|
||||
|
||||
This is a concise working reference to the public 0.90 grammar overview. The
|
||||
published page is not yet the complete script-step catalogue. When a particular
|
||||
step or parameter variant is uncertain, use a known-good FileMaker/ai2fm export
|
||||
or validate it with ai2fm; do not infer syntax from another step.
|
||||
This is a concise working reference to the public 0.90 grammar overview. The published page is not yet the complete script-step catalog. When a particular step or parameter variant is uncertain, use the authoritative catalog in `../examples/`, a known-good FileMaker/ai2fm export, or validation with ai2fm; do not infer syntax from another step.
|
||||
|
||||
## Core grammar
|
||||
## Bracket Rule
|
||||
|
||||
- Give a parameterized script step exactly one bracket group containing all of
|
||||
its parameters.
|
||||
- Do not add brackets to a step with no parameters.
|
||||
- Separate main arguments inside the brackets with a semicolon followed by a
|
||||
space. Do not use a comma as the main argument separator.
|
||||
- Use `# ` for a FileMaker comment step.
|
||||
- Continue the same multiline comment step with `#>`.
|
||||
- Use `// ` before a script step to represent a disabled step.
|
||||
- Preserve `//` and `/* */` comments that occur inside FileMaker calculations.
|
||||
- Qualify field references with their table occurrence, for example
|
||||
`Customers::Name`. Do not emit a bare `::Name` reference.
|
||||
- Prefix a local variable with one `$` and a global variable with exactly `$$`.
|
||||
- Keep simple steps on one line.
|
||||
- Preserve multiline calculations and determine their boundary using the known
|
||||
step name, balanced brackets, and continuation structure.
|
||||
Every script step that has parameters is followed by exactly one bracket group containing all parameters. Steps with no parameters have no bracket group.
|
||||
|
||||
## Representative forms
|
||||
Valid:
|
||||
|
||||
```text
|
||||
Set Variable [ $x ; Value: "Hello" ]
|
||||
Show All Records
|
||||
Set Field [ Customers::Name ; "Ada" ]
|
||||
Set Variable [ $name ; Value: Customers::Name ]
|
||||
Perform Script [ Specified:From list; "Normalize Customer"; Parameter: $name ]
|
||||
```
|
||||
|
||||
Invalid:
|
||||
|
||||
```text
|
||||
# Prepare the payload
|
||||
Set Variable [ $payload ; Value: JSONSetElement (
|
||||
"{}" ;
|
||||
[ "id" ; Customers::ID ; JSONString ]
|
||||
) ]
|
||||
Set Variable $x = "Hello"
|
||||
```
|
||||
|
||||
The exact parameter labels and internal punctuation belong to the individual
|
||||
FileMaker step definition. Verify them rather than generalizing from these
|
||||
representative forms.
|
||||
## Semicolon Rule
|
||||
|
||||
Main arguments inside brackets are separated by semicolon plus space. A comma is not a main argument separator.
|
||||
|
||||
Valid:
|
||||
|
||||
```text
|
||||
Set Field [ Customers::Name ; "Ada" ]
|
||||
```
|
||||
|
||||
Invalid:
|
||||
|
||||
```text
|
||||
Set Field [ Customers::Name , "Ada" ]
|
||||
```
|
||||
|
||||
## Comment Rule
|
||||
|
||||
Dedicated script comments use `# `. Disabled script steps use `// `. Multi-line comment steps continue with `#>`. Inside FileMaker calculation bodies, inline `//` and `/* */` comments are valid and must be preserved.
|
||||
|
||||
```text
|
||||
# Explain the next operation
|
||||
# Long comment title
|
||||
#> continuation paragraph that remains part of the same comment step
|
||||
// Perform Script [ Specified:From list; "Legacy Step" ]
|
||||
Set Variable [ $x ; Value: Let ( [
|
||||
a = 1 ; // inline calculation comment
|
||||
b = 2 /* block calculation comment */
|
||||
] ; a + b ) ]
|
||||
```
|
||||
|
||||
## Field Reference Rule
|
||||
|
||||
Field references include both table occurrence and field name. Bare `::FieldName` references are invalid.
|
||||
|
||||
Valid:
|
||||
|
||||
```text
|
||||
Set Field [ Customers::FirstName ; "Ada" ]
|
||||
```
|
||||
|
||||
Invalid:
|
||||
|
||||
```text
|
||||
Set Field [ ::FirstName ; "Ada" ]
|
||||
```
|
||||
|
||||
## Variable Rule
|
||||
|
||||
Local variables start with one `$`. Global variables start with exactly two `$$`.
|
||||
|
||||
Valid:
|
||||
|
||||
```text
|
||||
Set Variable [ $counter ; Value: 1 ]
|
||||
Set Variable [ $$APP_MODE ; Value: "review" ]
|
||||
```
|
||||
|
||||
Invalid:
|
||||
|
||||
```text
|
||||
Set Variable [ counter ; Value: 1 ]
|
||||
```
|
||||
|
||||
## Step Boundary Rule
|
||||
|
||||
Simple script steps are compact, but 0.90 preserves multi-line calculation bodies and multi-line comment steps. Boundaries are determined by known step names, balanced brackets, and continuation tokens, not by blindly flattening every real-world step.
|
||||
|
||||
```text
|
||||
Perform Script [ Specified:From list; "Parse Result"; Parameter: Get ( ActiveLayoutObjectName ) ]
|
||||
Perform Script [ Specified:From list; "Parse JSON"; Parameter: JSONSetElement (
|
||||
"{}" ;
|
||||
[ "id" ; Customers::ID ; JSONString ] ;
|
||||
[ "name" ; Customers::Name ; JSONString ]
|
||||
) ]
|
||||
# Summary
|
||||
#> This paragraph continues the same FileMaker comment step.
|
||||
```
|
||||
|
||||
## Representative syntax.
|
||||
|
||||
The formal catalog covers the complete FileMaker step index. These examples show the public grammar style for common patterns, including 0.90 multi-line preservation.
|
||||
|
||||
`common-patterns.fmscript` — valid
|
||||
|
||||
```text
|
||||
Go to Layout [ "Customers" (Customers) ]
|
||||
New Record/Request
|
||||
Set Field [ Customers::FirstName ; "Ada" ]
|
||||
Set Field [ Customers::LastName ; "Lovelace" ]
|
||||
Commit Records/Requests [ With dialog: Off ]
|
||||
Perform Script [ Specified:From list; "Normalize Customer"; Parameter: JSONSetElement (
|
||||
"{}" ;
|
||||
[ "id" ; Customers::CustomerID ; JSONString ] ;
|
||||
[ "fullName" ; Customers::FirstName & " " & Customers::LastName ; JSONString ]
|
||||
) ]
|
||||
If [ Get ( LastError ) = 0 ]
|
||||
Show Custom Dialog [ "Saved"; "Customer created." ]
|
||||
End If
|
||||
```
|
||||
|
||||
## Review checklist
|
||||
|
||||
- Use an exact, supported FileMaker step name.
|
||||
- Give each parameterized step one balanced outer bracket group.
|
||||
- Give each parameterized step one balanced outer bracket group and give parameterless steps no bracket group.
|
||||
- Keep calculation parentheses and internal brackets balanced.
|
||||
- Use semicolons for main arguments.
|
||||
- Use semicolon plus space for main arguments.
|
||||
- Fully qualify every field reference.
|
||||
- Use `$` and `$$` variables correctly.
|
||||
- Close every structured block with the complete matching FileMaker closing
|
||||
step.
|
||||
- Preserve comment steps, disabled steps, and calculation comments correctly.
|
||||
- Preserve multiline calculation boundaries.
|
||||
- Close every structured block with the complete matching FileMaker closing step.
|
||||
- Preserve comment steps, disabled steps, calculation comments, and multiline calculation boundaries.
|
||||
- Apply the project's formatting, naming, path, and output-only requirements.
|
||||
- Validate uncertain or version-specific syntax through ai2fm or a known-good
|
||||
export before describing the script as round-trip ready.
|
||||
- Validate uncertain or version-specific syntax through ai2fm or a known-good export before describing the script as round-trip ready.
|
||||
Reference in new issue
Block a user