🚧`fastn 0.5` syntax #1993

Arpita-Jaiswal · 2024-10-25T07:30:20Z

Arpita-Jaiswal
Oct 25, 2024
Maintainer

The fastn 0.5 syntax builds on fastn 0.4, introducing several key modifications to support complex operations. For those new to fastn 0.4, you may want to review the discussion here to understand its foundational syntax and implementation.

Lets start with simple grammar:

Understanding `fastn 0.5` p-script grammar

Grammar with section body

A basic section definition can include an optional section type, name, caption, multiple headers, and an optional body:
```
-- <section-type>? <section-name>: <caption>?
[<header-type>? <header-name>: <header-value>]*

<body>?
```
Example
```
-- person john: John Doe
age: 10
gender: male

This is John Doe.
He is a software developer.
```
In this example:
- <section-type>: person
- <section-name>: john
- <caption>: John Doe
- Header 1:
  - <header-name>: age
  - <header-value>: 10
- Header 2:
  - <header-name>: gender
  - <header-value>: male
- <body>:
  This is John Doe.
  He is a software developer.
Grammar with subsections

Multiple subsections within a main section are enclosed within the section's start and end tags:
```
-- <section-type>? <section-name>: <caption>?
[<header-type>? <header-name>: <header-value>]*

[<subsection>]*

-- end: <section-name>
```
Example
```
-- team: Development Team
location: San Francisco
industry: Technology

  -- person: Alice Smith
  age: 28
  role: Frontend Developer

  -- person: Bob Jones
  age: 35
  role: Backend Developer
  
-- end: team
```
In this example:
- Main Section:
  - <section-name>: team
  - <caption>: Development Team
  - Header 1:
    - <header-name>: location
    - <header-value>: San Francisco
  - Header 2:
    - <header-name>: industry
    - <header-value>: Technology
  - Subsection 1:
    - <section-name>: person
    - <caption>: Alice Smith
    - Header 1:
      
      <header-name>: age
      
      <header-value>: 28
    - Header 2:
      
      <header-name>: role
      
      <header-value>: Frontend Developer
  - Subsection 2:
    - <section-name>: person
    - <caption>: Bob Jones
    - Header 1:
      
      <header-name>: age
      
      <header-value>: 35
    - Header 2:
      
      <header-name>: role
      
      <header-value>: Backend Developer

Comment

;; <comment>

-- <section-type>? <section-name>: <caption>? ;; <comment>

Example

;; This is a standalone comment explaining the team section

-- team development: Dev Team ;; This section contains team members
location: Remote

Module Doc Comment

Module comments at the beginning of the file provide meta-information. When placed directly above a section, they become section doc comments.

== start of file, ignoring comments and empty lines ==
[;-; <comment>]*

<anything else>

Example

;-; This file contains information about the Development Team.
;-; Each member's information is organized under the 'team' section.

-- team development: Dev Team
location: Remote

Section Doc Comment

Each section can include doc comments to describe its purpose or behavior. It should appear right above the section.

[;-; <comment>]*
-- <section>

Example

;-; Information about the project lead for the team Sarah Lee
-- person lead: Sarah Lee
age: 40
role: Project Manager

Sarah Lee oversees project management and ensures timely delivery.

Symbol Definitions

*: can appear zero or more times.
?: can appear zero or once.
+: must appear one or more times.
[]: encloses list of symbols and tokens
<>: token

Token Definitions:

<section-type>: Alphanumeric characters.
<section-name>: Alphanumeric characters.
<header-type>: Alphanumeric characters.
<header-name>: Alphanumeric characters.
<body>: Any characters.
<subsection>: Follows the same syntax as <section>.
<comment>: Any characters.
<caption> or <header-value>: Can range from a string to complex f-script expressions, including function scripts and nested sections (explained further below).

`<caption> or <header-value>`

These tokens allow complex types. They can include anything from simple strings to f-script function calls or even other nested sections, providing flexibility for various use cases.

1. Passing value in p-script:

You can pass any character

This is a valid caption or header value. It can take emoticons as well 😊.

Example

-- taj-mahal: Taj Mahal is one of the seven wonders. 7️⃣

2. Passing variable reference in p-script:

$name

Example

-- show-name: $name

3. Passing function in p-script:

$full-name(first = $first-name, last = $first-name)

Example

-- show-name: $full-name(first = $first-name, last = $first-name)

4. Passing value in f-script:

Single line value

{ "Hello  ${name}" }

Example

-- greeting: { "Hello  ${name}" }

Multiline value

{
  $"
    Hello  ${name}!
    
    This is your bio.
  "
}

Example

-- greeting: {
  $"
    Hello  ${name}!
    
    This is your bio.
  "
}

Function value

{
  let names = ["Bob", "Alice"]
  let result = ""
  for name in names {
      result = result + " " + name
  }
  result
}

Example

-- greeting: {
    let names = ["Bob", "Alice"]
    let result = ""
    for name in names {
        result = result + " " + name
    }
    result
}

To understand better about string checkout Summarising Position On String

5. Passing sections:

{
     -- person: Ankit
     age: 10
     
     Hi I am Ankit.

     -- person: Anita
     age: 20
     
     Hi I am Anita.
}

Example

-- show-people: {
     -- person: Ankit
     age: 10
     
     Hi I am Ankit.

     -- person: Anita
     age: 20
     
     Hi I am Anita.
}

6. Passing `string-literals`:

Hello { -- warning: $name }! I am {-- highlight: $role }.

Hello { 
      -- warning: $name 
      affect: highlight

      -- decorator:
}! I am {
      -- highlight: $role 
}.

Example

-- about: Hello { -- warning: $name }! I am {-- highlight: $role }.

Introducing new features in `fastn 0.5`

Markup or `string-literal` 🚧

The string with UI is known as string-literal in fastn

Hello { -- warning: $name }! I am {-- highlight: $role }

`if`, `for` and `match` 🚧

-- if $var:

   -- foo: x
   -- bar:

-- end: if

-- for: (x, index) in $list

-- foo: $x
-- bar: $index

-- end: for

-- match: $x

-- case 10: 

    -- show-10:
    -- foo:

-- end: match

More doc:

amitu · 2024-10-25T13:05:44Z

amitu
Oct 25, 2024
Maintainer

I have also started writing grammar.bnf today, mostly inspired by your EBNF.md.

I am trying to use the exact tokens I have in my tokens.rs file. Also, I am not trying to make the grammar a very valid grammar yet, maybe it will not work with the bnf grammar. The idea is I am trying to create readable grammar instead of "strictly correct" grammar.

Maybe we can achieve both readable and correct grammar, but a correct grammar over readable grammar does not really give us anything, given that it is handwritten parser.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fastn-stack

🚧`fastn 0.5` syntax #1993

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 1 comment

{{title}}

Select a reply

fastn-stack

🚧fastn 0.5 syntax #1993

Arpita-Jaiswal Oct 25, 2024 Maintainer

Understanding fastn 0.5 p-script grammar

Symbol Definitions

Token Definitions:

<caption> or <header-value>

1. Passing value in p-script:

2. Passing variable reference in p-script:

3. Passing function in p-script:

4. Passing value in f-script:

5. Passing sections:

6. Passing string-literals:

Introducing new features in fastn 0.5

Markup or string-literal 🚧

if, for and match 🚧

Replies: 1 comment

amitu Oct 25, 2024 Maintainer

🚧`fastn 0.5` syntax #1993

Arpita-Jaiswal
Oct 25, 2024
Maintainer

Understanding `fastn 0.5` p-script grammar

`<caption> or <header-value>`

6. Passing `string-literals`:

Introducing new features in `fastn 0.5`

Markup or `string-literal` 🚧

`if`, `for` and `match` 🚧

amitu
Oct 25, 2024
Maintainer