Shrimpl Code Challenges

Welcome to the Shrimpl Code Challenges repository.

This repo hosts recurring programming challenges built around the Shrimpl language, covering data, APIs, ML, algorithms, and language features. New challenge sets are released throughout the year and are designed for all skill levels—from beginners to advanced Shrimpl contributors.

All challenges will be published in three languages:

• English (primary)
• Spanish (Español)
• Mandarin (中文)

Each challenge folder will indicate which languages are currently available and may contain subfolders or separate files per language (for example, README.en.md, README.es.md, README.zh.md).

---

Challenge Types

1. Advent of Code (December)

• When: Every year, December 1–24 (or 25).

• Where: advent-of-code/<year>/

• Format:

  • Daily bite-sized puzzles.
  • Each day typically includes one or more HTTP endpoints, data tasks, or mini-algorithms implemented in .shr files.
  • Designed so you can complete a day in 15–60 minutes.

• Goals:

  • Practice Shrimpl syntax and idioms.
  • Work with servers, endpoints, control flow, and small data tasks.
  • Build a habit of coding daily during the Advent period.

• Languages: Each Advent set aims to provide instructions and story text in English, plus Spanish and Mandarin variants where possible.

Example layout:

advent-of-code/
  2025/
    app.shr
    README.en.md
    README.es.md
    README.zh.md
    day01/
    day02/
    ...

---

2. The Monthly Big Pack

• When: Once per month, all year.

• Where: monthly-big-pack/<year>/<month>/

• Format:

  • A larger, themed challenge pack meant to be completed by the end of the month.
  • Multiple related tasks that build on each other (e.g., small API + data + ML pipeline).
  • Often includes starter code, tests, and extension ideas.

• Goals:

  • Practice designing small systems in Shrimpl (not just single endpoints).
  • Combine multiple areas: HTTP, dataframes, ML helpers, algorithms, etc.
  • Encourage refactoring, documentation, and cleaner project structure.

• Languages:

  • Primary documentation in English.
  • Spanish and Mandarin booklets or README variants as they are completed.

Example layout:

monthly-big-pack/
  2025/
    01-january-analytics-lab/
      app.shr
      README.en.md
      README.es.md
      README.zh.md
      data/
      solutions/

---

3. Shrimpl Olympics (Summer – Ultimate Challenge)

• When: Every year, June 1 – August 31.

• Where: shrimpl-olympics/<year>/

• Format:

  • Multi-week, high-difficulty challenge series.

  • Focused on building new functionality for Shrimpl itself or advanced tooling around it.

  • May include:

    • New built-in helpers or standard libraries.
    • Improvements to the interpreter, diagnostics, or API Studio.
    • LSP/editor tooling, devtools, or example applications.

• Goals:

  • Push Shrimpl forward as a language and ecosystem.
  • Encourage deeper understanding of the runtime, parser, and tooling.
  • Provide a path for contributors to get involved with real language features.

• Languages:

  • Core specs and reference docs in English.
  • Spanish and Mandarin write-ups for tracks and tasks whenever possible.

Example layout:

shrimpl-olympics/
  2025/
    track-a-runtime-features/
    track-b-data-ml/
    track-c-editor-tools/
    README.en.md
    README.es.md
    README.zh.md

---

Small Challenges

• When: Occasionally, on a random-day basis.

• Where: small-challenges/

• Format:

  • One-off tasks, mini-puzzles, kata-style exercises, or experimental ideas.
  • Meant to be solved in a single short session (10–30 minutes).

• Goals:

  • Provide quick practice opportunities.
  • Explore niche features or very focused concepts in Shrimpl.
  • Serve as warm-ups before tackling larger events.

• Languages:

  • Usually written in English first.
  • Spanish and Mandarin translations may be added over time.

Example layout:

small-challenges/
  fizzbuzz-endpoint/
    app.shr
    README.en.md
    README.es.md
  tensor-mini-lab/
    app.shr
    README.en.md
    README.zh.md

---

Repository Structure

A typical year might look like this:

.
├─ advent-of-code/
│  └─ 2025/
│     ├─ app.shr
│     ├─ README.en.md
│     ├─ README.es.md
│     └─ README.zh.md
├─ monthly-big-pack/
│  └─ 2025/
│     └─ 01-january-.../
│        ├─ app.shr
│        ├─ README.en.md
│        ├─ README.es.md
│        └─ README.zh.md
├─ shrimpl-olympics/
│  └─ 2025/
│     ├─ track-a-runtime-features/
│     ├─ track-b-data-ml/
│     ├─ track-c-editor-tools/
│     ├─ README.en.md
│     ├─ README.es.md
│     └─ README.zh.md
└─ small-challenges/
   └─ ...

Each subfolder usually contains:

• app.shr – main Shrimpl program for the challenge.
• README.*.md – rules, story, and instructions in multiple languages.
• Optional data/, solutions/, or tests/ folders.

---

Getting Started

1. Install Shrimpl (via Cargo):

   cargo install shrimpl

2. Pick a challenge folder (for example, the current Advent year):

   cd advent-of-code/2025

3. Run the Shrimpl server:

   shrimpl --file app.shr run
   # or
   shr run

4. Open the Shrimpl API Studio in your browser:

   http://localhost:3000/__shrimpl/ui
   

5. Follow the puzzle instructions in the local README.en.md, README.es.md, or README.zh.md depending on your preferred language.

---

Contributing Challenges

Contributions are welcome. Typical ways to contribute:

• Propose or add new small challenges under small-challenges/.
• Suggest new Monthly Big Pack themes or improve existing ones.
• Submit ideas or prototypes for future Shrimpl Olympics tracks.
• Help translate existing challenges into Spanish or Mandarin.
• Improve documentation and in-challenge explanations.

When contributing:

• Keep challenges Shrimpl-first (they should showcase the language).
• Aim for clear instructions, with English as the reference text.
• If possible, provide or update Spanish and/or Mandarin versions.
• Include comments in .shr files explaining the intent of the code, not just the mechanics.

---

License

Unless otherwise noted in a subfolder, challenge content and sample code follow the main Shrimpl project licensing. See the root LICENSE of the Shrimpl organization or the corresponding license file in this repository.