Workflow SimpleDemo

Workflow: Testing Grammar with simpleDemo

Step-by-step guide to test your Crodox grammar using the simpleDemo repository.

---

Overview

This workflow teaches you how to:

1. Access the Crodox app
2. Create a simple grammar template
3. Test the grammar on simpleDemo's pseudo-code files
4. Validate syntax parsing and extraction
5. Iterate on your grammar definition

Start here: https://crodox-app.com/home

---

Prerequisites

• Access to Crodox app at https://crodox-app.com/home
• GitHub account (for authentication)
• GitHub access to the simpleDemo repository (automatic if you have GitHub access)

---

Step 1 - Sign In to Crodox

1. Open https://crodox-app.com/home in your browser
2. Enter your email address and request a verification code
3. Check your email and enter the code
4. Authorize the Crodox GitHub app when prompted
5. Complete your profile setup (username, local settings)

You are now logged into Crodox.

---

Step 2 - Create a New Template

1. In the Crodox app, click the Template Editor icon (code brackets <>) in the left sidebar
2. Click the Templates tab
3. Enter a name for your test template (e.g., simpleDemo_Grammar_v1)
4. Click the + button to create the template

The template editor opens with an empty grammar definition.

---

Step 3 - Write a Simple Grammar

In the Grammar Editor (left panel), write a basic grammar to parse pseudo-code:

<~ file.txt ~>
<: define :> <<name>>
<: function :> <<name>> <- variable ->
<: variable :> <<name>>

Explanation:

• <~ file.txt ~> – Target text files
• <: define :> – Recognize "define" statements as visible objects
• <<name>> – Capture the name of each object
• <- variable -> – Functions can contain variables as children

---

Step 4 - Save Your Template

1. Click Save in the template editor (or press Ctrl+S)
2. Crodox validates your grammar
   • ✅ Valid – Template is saved and ready to test
   • ❌ Error – Review the error message and fix your grammar

If valid, proceed to Step 5.

---

Step 5 - Select simpleDemo as Your Test Repository

1. In the Project Explorer (center-left panel), open the Repository dropdown
2. Look for simpleDemo in the list (or search for it)
3. Select simpleDemo (github)

The project explorer now shows the file tree from the simpleDemo repository.

---

Step 6 - Load a Test File

1. In the project explorer, expand the simpleDemo folder structure
2. Click on one of the test files:
   • testFile.txt (recommended for first test)
   • refFile.txt
   • bridgeTest.txt

The file loads in the right-hand preview panel, and your grammar runs against it automatically.

---

Step 7 - Review Extracted Components

In the Trial Extraction Field (center panel), Crodox displays every component your grammar matched:

• Component ID - Unique identifier (e.g., #262)
• Component Type - What your grammar recognized (e.g., define, function)
• Name - The extracted name (e.g., testFunction)
• Source Path - File and line number

Interpretation:

• ✅ Components appear → Your grammar is correctly parsing the file
• ❌ No components → Your grammar did not match the file syntax
  • Review your grammar syntax in the Crodox documentation
  • Check that <: define :>, <: function :> match the actual keywords in the test file
  • Try a different test file

---

Step 8 - Refine Your Grammar

If your grammar didn't extract components:

1. Return to the Grammar Editor (left panel)
2. Review the test file content in the preview (right panel)
3. Adjust your grammar to match the actual keywords and structure
4. Click Save again
5. The extraction updates automatically

Example: If testFile.txt uses procedure instead of function, change your grammar to:

<~ file.txt ~>
<: define :> <<name>>
<: procedure :> <<name>> <- variable ->
<: variable :> <<name>>

---

Step 9 - Test Multiple Files

Repeat Step 6 for other files in simpleDemo:

1. Click a different test file
2. Review extracted components
3. Note any differences in extraction results

This helps you understand how your grammar behaves across different code patterns.

---

Step 10 - Prepare for Workbench

Once your grammar successfully extracts components from simpleDemo files:

1. Your template is validated and ready for production use
2. You can now create a Workbench to analyze your own repositories
3. See Workflow-End-to-End for the next steps

---

Troubleshooting

Issue	Solution
No components extracted	Review grammar syntax; check that keywords match the test file
Unexpected components	Your grammar may be too broad; refine selectors with <: name :> conditions
simpleDemo not visible	Ensure GitHub access is authorized in Settings
File won't load	Try a different test file (e.g., testFile.txt instead of bridgeTest.txt)

---

Next Steps

Once your grammar is working on simpleDemo:

1. Workflow-AngularTemplate – Learn how to build a production template
2. Workflow-End-to-End – Create a workbench on your own repositories
3. Creating-First-Template – Extended guide on template creation
4. Template-Editor – Complete template editor documentation

---

Tips & Best Practices

• Test early, iterate often – Use simpleDemo to validate grammar changes before production use
• Start simple – Begin with basic <: name :> patterns, then add complexity
• Use descriptive names – Name your template after its purpose (e.g., Python_Parser, Vue_Extractor)
• Keep a backup – Export your working grammar before major changes

---

Start testing now: https://crodox-app.com/home

Demo Repository: https://github.com/crodox-app/simpleDemo