NAME
YATT::Lite::Site - public facade API of YATT::Lite
SYNOPSIS
use YATT::Lite::Site;
# Open the site defined by app.psgi/runyatt.psgi (searched upward).
my $site = YATT::Lite::Site->load(dir => $dir);
# ...or fall back to a plain default site when there is none.
my $site = YATT::Lite::Site->load_or_default(dir => $dir);
# Run one file (tool style; raw die passes through).
my $res = $site->render_file("$dir/hello.yatt", {name => "world"});
print $res->body if $res->is_success;
# Run one web request (100% identical to the real PSGI path).
my $res = $site->request(GET => "/hello", {name => "world"});
printf "%s %s\n%s", $res->status, scalar $res->header('Content-Type')
, $res->content;
# Resolve a filename to its directory handler.
my ($dh, $name) = $site->resolve_file($fn);
# Multi-site tools: one cached site per app root.
my $reg = YATT::Lite::Site::Registry->new;
my $site = $reg->site_for($fn);DESCRIPTION
YATT::Lite::Site is the public facade of YATT::Lite: the official way for programs and tools to open a site and execute one path or one file, without hand-rolling connections, faking %ENV or touching package globals.
It is inserted as a parent class of YATT::Lite::Factory, so every site object satisfies $site->isa('YATT::Lite::Site'). YATT::Lite::WebMVC0::SiteApp is Site + PSGI adapter: the same object, plus to_app/call for the web.
The methods defined (and documented) here are the public API surface; methods of Factory and below are implementation detail unless their own pod says otherwise.
CLASS METHODS
load (dir => $dir, %opts)
Searches app.psgi / runyatt.psgi upward from $dir and loads it, returning the site instance the script created. Dies when no factory script is found.
Defaults to offline => 1 (the error_handler passes raw die through), since this entry is for programs and tools; the web entry point is app.psgi itself.
Like Node's require.cache, one factory script yields one site object per process: loading the same script twice would collide on app_ns anyway, so subsequent load()s return the cached instance (re-configuring any explicitly given %opts onto it).
load_or_default (dir => $dir, %opts)
Like load, but when no factory script is found, synthesizes a plain site (YATT::Lite::WebMVC0::SiteApp by default; override with class => 'My::SiteApp') with doc_root/app_root set to $dir, utf-8 defaults, and an auto-uniquified app_ns so that multiple default sites can coexist in one process.
INSTANCE METHODS
resolve_file ($filename)
my ($dh, $name, $loc) = $site->resolve_file($fn);Resolves a filename to ($dirhandler, $basename [, $location]). Files under doc_root are resolved via their location - exactly like the web does - and other files fall back to the physical directory handler.
request ($method, $path, $args, %opts)
Synthesizes a PSGI env ($args become query parameters for GET, an application/x-www-form-urlencoded body for POST/PUT) and runs it through the real call($env). Path resolution, request sigils, subpath handling, the public check, the __DIE__/__WARN__ traps and the error page: everything behaves exactly as a real web request. Returns a YATT::Lite::Response.
Requires a web-capable site (a SiteApp); $args may be a HASH (ARRAY values become multi-value params), an ARRAY of pairs, or a raw query string.
render_file ($filename, $args, %opts)
Runs one template file. Dispatch (part resolution, sigils, the public check, argument reordering) is identical to the web, but the error policy defaults to tool style: no __DIE__/__WARN__ traps take effect, no error page is rendered - a raw die from the template propagates to the caller untouched, which keeps perl -d fully useful.
Pass error_style => 'web' to get web-equivalent error handling (traps + error page) instead. Returns a YATT::Lite::Response.
EXECUTION CONTRACTS
The cwd of a template is its directory
Every official execution path chdirs into the entry dirhandler's directory, so templates may do file I/O with relative paths. The chdir is a restoring guard (see chdir_guard in YATT::Lite): the previous cwd comes back when the call returns or dies.
Nesting: only the entry dirhandler chdirs. Templates in other directories called via <!yatt:base> or <!yatt:import> do not re-chdir.
Opt-out: no_chdir => 1 (Compatibility option) disables the chdir entirely - for event-loop embedding or threaded hosts, where the process-global cwd must not move.
Error policy by path
The presence of the __DIE__/__WARN__ traps (leading to error_handler and the error page) is an intentional distinction, not an accident:
path chdir SIG traps + error page dirhandler hooks
-------------------------- ----- ---------------------- ----------------
web (call / request) yes yes yes
render_file (default) yes NO - raw die (perl -d) yes
Factory::render (program) yes NO yes"dirhandler hooks" are before/after_dirhandler - where site_config_as_entity and similar site-level setup runs.
$SYS, $YATT and $CON
The three package globals importable via use YATT::Lite qw/*SYS *YATT *CON/ are permanent public API for template and entity code:
$SYS == $CON->system (the site object)
$YATT == $CON->YATT (the dirhandler)
$CON (the current connection)Every official execution entry (call, request, render_file, Factory::render/render_into, run_dirhandler) localizes all three - user code and tools never need to set them up by hand. Conversely, internal per-extension handlers (like _handle_yatt) must never be called directly, because setting these globals is handle's job.
SEE ALSO
YATT::Lite, YATT::Lite::Factory, YATT::Lite::WebMVC0::SiteApp, YATT::Lite::Response
AUTHOR
"KOBAYASI, Hiroaki" <hkoba@cpan.org>