DOCSEARCHbyAlgolia
Submit Docs

Plain Programming Language

website·Indexed 32 days ago

https://www.plainlang.org/

A language for creating machine-checkable software specifications using .plain files. It features a specialized :Concept: notation to eliminate natural language ambiguity, supporting functional specifications, implementation requirements, acceptance tests, and conformance testing to turn specifications into working code.

Tokens
13.4K
Snippets
77
Records
110
Agent score
56%

What's inside Plain

  1. Overview of the ***plain specification language

    ***plain is a specification language designed for writing software requirements in a clear, structured format. It allows developers to define what software should do (functional specs) and how it should be built (implementation and test requirements) in a way that can be rendered into software code.
    ***implementation reqs***

- :Implementation: should be in Python.

***functional specs***

- Display "hello, world"

  2. Overview of the Plainlang toolkit workflow

    The Plainlang toolkit enables a specification-driven development cycle where software is generated from .plain specs. The workflow consists of three main phases:

    1. Capture: Use plain-forge to describe requirements. The tool interviews the user to author and maintain accurate .plain specifications.
    2. Render: Use pyro to read the specifications, resolve module dependencies, and generate both the implementation code and the corresponding conformance tests.
    3. Evolve: When requirements change, the specification is updated. plain-forge ensures consistency, and pyro regenerates the software. This approach ensures bugs are traced back and fixed in the specification rather than the generated code.

  3. Overview of ***plain specification language

    ***plain is a specification language designed for spec-driven development. It aims to provide a middle ground between the efficiency and readability of natural language and the control and precision typically associated with executable code.

  4. Overview of the ***plain specification language

    ***plain is a specification language used to write software requirements in a clear, structured format. The goal is for these specifications to serve as the single source of truth for software functionality. Specifications are written in textual files, allowing them to be stored in code repositories and managed via standard version control processes like pull requests.

  5. Overview of the ***plain specification language

    ***plain is a specification language designed for writing software requirements in a clear, structured format. It allows developers to define concepts, implementation requirements, testing requirements, and functional specifications that can be rendered into software code.
    ***implementation reqs***

- :Implementation: should be in Python.

***functional specs***

- Display "hello, world"

  6. Overview of the ***plain specification language

    ***plain is a specification language used to write software requirements in a clear, structured format. It is designed to serve as the single source of truth for software functionality. Specifications are written in textual files that can be stored in a code repository, allowing them to be managed via pull requests and standard code review processes.

  7. Structure a concept definitions section

    Concepts must be centralized in a dedicated definitions section, denoted by a special heading (e.g., ***definitions***). This separates the vocabulary from the functional specifications and allows tools to detect typos or missing definitions early.
    ***definitions***

- :App: is a Python console application.
- :Task: describes an activity that needs to be done by the user.

***functional specs***

Write :App: for managing :Task: items.

  8. Understand ***plain specification terminology

    The following terms define the core components and roles within a ***plain specification:

    • Definitions: Declarations of named concepts that serve as the shared domain model and vocabulary for the specification.
    • Concept: A domain entity, artifact, or shared reference that other requirements point to. These are expressed using specific Concept notation.
    • Functional specs: Behavioral requirements describing what the software must do.
    • Implementation reqs: Non-functional requirements and constraints on how the software should be implemented (e.g., language, framework, architecture, or coding rules).
    • Test reqs: Constraints for the spec-compliance test suite, describing how conformance tests should be generated, structured, and executed.
    • Renderer: A tool that transforms a ***plain specification into working software.

  9. Export concepts to other modules

    The exported_concepts: section declares which concepts from the current module are visible to modules that require it. This allows a module to provide shared concept definitions to subsequent modules without needing a separate shared-only file.
    requires:
  - authentication-module
  - database-layer
exported_concepts:
  - :PasswordManagerModule:

  10. Use :Concept: notation to anchor meaning in specifications

    To prevent ambiguity in software specifications, ***plain uses a dedicated notation where concept names are enclosed in colons (e.g., :Concept:). This allows developers to mark specific terms as stable units of meaning while leaving the rest of the prose flexible.

    Constraints:

    • Concept names must not contain spaces.
    • Concept names may only include letters, digits, dots, and underscores.
    • Plurality is not handled automatically; :Task: and :Tasks: are treated as two distinct concepts. Plurality should be expressed in the surrounding text (e.g., :Task: items).
    - :App: is a Python console application.
- :Task: describes an activity that needs to be done by the user.

Write :App: for managing :Task: items.

  11. Understand the Plainlang toolkit workflow

    The Plainlang toolkit consists of two primary tools that automate the transition from requirements to implementation:

    1. plain-forge (Authoring Toolkit): Used to capture requirements. It interviews the user to create .plain specifications and ensures these specs remain accurate as the software evolves.
    2. pyro (Renderer): Packaged as an agent skill. It reads the .plain specifications, resolves module dependencies, and generates the implementation code along with conformance tests to verify the code against the specs.

    Development Lifecycle:

    • Capture: Use plain-forge to write the specification.
    • Render: Use pyro to generate code and tests.
    • Evolve: Update the specification via plain-forge when requirements change; pyro then regenerates the software. Bug fixes are applied to the specification rather than the generated code.

  12. Define concept names in ***plain

    In ***plain, concept names are case-sensitive and must be enclosed in colons (e.g., :Task:). A difference in casing (e.g., :Task: vs :task:) denotes two distinct concepts. Concept names can consist of any combination of the following ASCII characters:

    • Uppercase and lowercase letters (ASCII 65-90, 97-122)
    • Digits (ASCII 48-57)
    • Plus sign (+, ASCII 43)
    • Minus sign (-, ASCII 45)
    • Dot sign (., ASCII 46)
    • Underscore (_, ASCII 95)

    Space characters are prohibited to ensure simple and robust programmatic detection and validation.

    :Task:  // Valid
:user_id: // Valid
:Task-1.0+: // Valid
:My Task: // Invalid (contains space)