PaperForge.Declarative (PaperForge v1.3.0)

Safe compiler for versioned .paperforge declarative documents.

Templates are JSON documents containing data only. PaperForge never evaluates Elixir source from a template. Variables are validated before conditions, loops, and components are expanded into PaperForge.Flow, the public Layout IR used by the existing pagination engine.

Summary

Types

source()

Functions

clear_cache()

Clears the current process's bounded compiled-template cache.

compile(source, data \\ %{}, options \\ [])

Compiles a template and data into validated PaperForge.Flow Layout IR.

compile_cached(source, data \\ %{}, options \\ [])

Compiles with a bounded process-local cache keyed by template, data, and safe options.

load(path, options \\ [])

Loads and parses a .paperforge file.

migrate(template)

Migrates an older declarative map to the current format version.

parse(source)

Parses JSON template content into a normalized map.

render(source, data \\ %{}, options \\ [])

Compiles and renders a declarative template through the normal layout engine.

schema_path()

Returns the packaged JSON Schema path for editor and CI integration.

validate(source, data \\ %{}, options \\ [])

Validates template structure, input data, design references, and blocks.

write(source, data, path, options \\ [])

Renders and writes a declarative document, keeping passwords in write-time options only.

Types

source()

@type source() :: binary() | map()

Functions

clear_cache()

@spec clear_cache() :: :ok

Clears the current process's bounded compiled-template cache.

compile(source, data \\ %{}, options \\ [])

@spec compile(source(), map() | keyword(), keyword()) ::
  {:ok, PaperForge.Declarative.Compiled.t()}
  | {:error, [PaperForge.Declarative.Error.t()]}

Compiles a template and data into validated PaperForge.Flow Layout IR.

compile_cached(source, data \\ %{}, options \\ [])

@spec compile_cached(source(), map() | keyword(), keyword()) ::
  {:ok, PaperForge.Declarative.Compiled.t()}
  | {:error, [PaperForge.Declarative.Error.t()]}

Compiles with a bounded process-local cache keyed by template, data, and safe options.

load(path, options \\ [])

@spec load(
  Path.t(),
  keyword()
) :: {:ok, map()} | {:error, [PaperForge.Declarative.Error.t()]}

Loads and parses a .paperforge file.

migrate(template)

@spec migrate(map()) :: {:ok, map()} | {:error, term()}

Migrates an older declarative map to the current format version.

parse(source)

@spec parse(source()) :: {:ok, map()} | {:error, [PaperForge.Declarative.Error.t()]}

Parses JSON template content into a normalized map.

render(source, data \\ %{}, options \\ [])

@spec render(source(), map() | keyword(), keyword()) ::
  {:ok, PaperForge.Document.t(), map()}
  | {:error, [PaperForge.Declarative.Error.t()]}

Compiles and renders a declarative template through the normal layout engine.

schema_path()

@spec schema_path() :: Path.t()

Returns the packaged JSON Schema path for editor and CI integration.

validate(source, data \\ %{}, options \\ [])

@spec validate(source(), map() | keyword(), keyword()) ::
  :ok | {:error, [PaperForge.Declarative.Error.t()]}

Validates template structure, input data, design references, and blocks.

write(source, data, path, options \\ [])

@spec write(source(), map() | keyword(), Path.t(), keyword()) ::
  {:ok, map()} | {:error, [PaperForge.Declarative.Error.t()] | File.posix()}

Renders and writes a declarative document, keeping passwords in write-time options only.