Skip to content

Quick Start

Parse a String

require 'pm'

parsed = PM.parse("---\ntitle: Hello\n---\nContent here")

parsed.metadata.title  #=> "Hello"
parsed.content         #=> "\nContent here\n"

Parse a File

Given greeting.md:

---
title: Greeting
parameters:
  name: null
---
Hello, <%= name %>! Welcome.

# Any of these forms work:
parsed = PM.parse('greeting.md')    # explicit .md extension
parsed = PM.parse(:greeting)        # Symbol — .md appended
parsed = PM.parse('greeting')       # single word — .md appended

parsed.metadata.title       #=> "Greeting"
parsed.metadata.parameters  #=> {"name" => nil}

# Render with parameters
puts parsed.to_s('name' => 'Alice')
#=> "Hello, Alice! Welcome."

When parsing a file, PM also adds directory, name, created_at, and modified_at to the metadata.

Parse a String Directly

PM.parse treats single words as prompt IDs and looks them up as files. To always parse a string as content, use PM.parse_string:

PM.parse('hello')              #=> looks for hello.md in prompts_dir
PM.parse_string('hello')       #=> parses "hello" as string content

parsed = PM.parse_string("---\ntitle: Inline\n---\nSome content")
parsed.metadata.title  #=> "Inline"
parsed.content         #=> "Some content\n"

Parameters

Parameters declared in the YAML front-matter define template variables:

  • null value -- parameter is required; to_s raises ArgumentError if missing
  • Any other value -- used as the default; can be overridden in to_s
parsed = PM.parse("---\nparameters:\n  lang: ruby\n  code: null\n---\n<%= lang %>: <%= code %>")

# Use defaults where available, supply required params
parsed.to_s('code' => 'puts "hi"')  #=> "ruby: puts \"hi\""

# Override defaults
parsed.to_s('code' => 'print("hi")', 'lang' => 'python')

Shell Expansion

Environment variables and commands are expanded at parse time:

---
title: Info
---
User: $USER
Date: $(date +%Y-%m-%d)

parsed = PM.parse('info.md')
parsed.content  #=> "User: dewayne\nDate: 2025-01-15\n"

Next Steps