A Beginner's Guide to Implementing Events in Plang

This article explores Plang, an intent-based programming language designed to interpret natural language. For more information, visit plang.is or take your first steps

Welcome to this step-by-step tutorial on implementing and managing events in your Plang applications.

Events in Plang allow you to trigger specific actions at various stages in your application’s lifecycle, during the build process, or under certain conditions. This guide covers setting up events, handling errors, managing builder events, and more.

1. Setting Up Events

To start, you'll need to establish the structure for events in your Plang application:

1. Create an events Directory
   
   Begin by creating a folder named events in your project’s root directory.

2. Create the Events.goal File
   
   Inside the events folder, create a file named Events.goal. This is where you'll define your events.

2. Application Lifecycle Events

Lifecycle events allow you to execute specific actions when your application starts or ends. Here’s how to set them up:

Events
- before app starts, call !AppStarting
- before app ends, call !AppEnding

Next, create AppStarting.goal and AppEnding.goal files in the events folder:

AppStarting.goal:

AppStarting
- write out 'App is starting'

AppEnding.goal:

AppEnding
- write out 'App is ending'

• before app starts: Triggers the AppStarting action before the application starts.
• before app ends: Triggers the AppEnding action before the application shuts down.

Plang is flexible with its syntax. You don’t have to write exactly before app starts; you can phrase it as when the app starts..., on app start..., or any other way that clearly conveys your intent.

3. Events with Goals and Steps

Plang enables you to trigger events before or after specific goals within a directory or globally after each goal:

Events
- before each goal in 'api/*', call !AuthenticateUser
- after each goal, call !Analyze.LogInfoAboutGoal

• Before each goal in 'api/*': Runs AuthenticateUser before any goal in the api directory.
• After each goal: Runs LogInfoAboutGoal after every goal in your project.

4. Error Handling Events

Handling errors effectively is essential. Plang allows you to define events that trigger when errors occur:

Events
- on error in step, call !LoggerStepError
- on error on goal, call !LoggerGoalError

• on error in step: Calls LoggerStepError when an error occurs in any step.
• on error on goal: Calls LoggerGoalError when an error occurs in any goal.

For more detailed error handling, refer to the ErrorHandler documentation.

5. Builder Events

Events related to the Plang builder can be defined in a BuilderEvents.goal file:

BuilderEvents
- before each step, call !AnalyzeCode
- after each step, call !AnalyzeCode

Plang already uses this build event internally to validate all goals. After your first build, you can find this at /events/external/plang/builder/CheckGoals.goal.

• Before and after each step: AnalyzeCode is called before and after each step during the build process, ensuring consistent code analysis.

6. Conditional Events

You may want to trigger events only under certain conditions, such as in debug mode:

Events
- before each step, call !SendDebug, only when start parameter is '--debug'

To trigger this event, run your application with:

plang --debug

The SendDebug event is triggered only if the --debug parameter is passed at startup. Plang’s debugger itself uses this feature, which you can find at /events/external/plang/runtime/SendDebug.goal after your first debug session.

7. Using Available Variables

Within your events, you can access information about the current goal, step, or event using predefined variables:

• %!goal%: Represents the current goal.
• %!step%: Represents the current step.
• %!event%: Represents the current event.

These variables are useful for passing context-sensitive information to your event handlers.

8. External Events

To integrate external events from other sources, place external event files in the following directory structure:

events/external/{appName}/

For example, events related to plang would be placed in events/external/plang/, created automatically when you build or run a debugger.

9. Binding Events to Variables

In Plang, you can bind events to variables to monitor their lifecycle (creation, update, or deletion):

- when %name% is created, call VariableNameIsCreated
- when %email% is changed, call VariableEmailIsChanged
- when %zip% is changed or created, call VariableZipIsChanged
- when %name% is deleted, call VariableNameIsDeleted

This setup allows dynamic event handling based on how variables change in your application.

10. Types of Events in Plang

Plang provides various event types for different scenarios:

• Before and After Events: Trigger actions before or after specific goals or steps.
• Error Events: Handle errors by triggering specific actions when an error occurs.
• Conditional Events: Execute actions based on specific conditions or parameters.
• Build Events: Manage events during the build process.
• Variable Events: Bind actions to changes in variable states.

11. Source Code Reference

If you're interested in exploring the underlying code for event management in Plang, you can check out the following files in the Plang repository:

• EventBuilder.cs: Handles the creation of event files.
• EventRuntime.cs: Manages the runtime execution of events.
• EventBinding.cs: Contains objects used for event management in both the builder and runtime.

These resources will help you gain a deeper understanding of how events are managed in Plang.

More Information

If Plang is interesting to you, you should dig a bit deeper:

• Basic concepts and lessons
• Simple Todo example is a good start
• Check out the GitHub repo
• Meet up on Discord to discuss or get help