# Peta::FFI::Cairo::Path

📦 std

`Cairo::Path` package plug-in - the tied-array live view onto `cairo_path_t*`. `Cairo::Path` is not a plain blessed pointer like the other cairo objects: it is a **tied ARRAY of tied HASHes of tied ARRAYs** presenting a live view onto a C `cairo_path_t*`. This file is a 1:1 mirror of upstream `CairoPath.xs`; read that alongside this for the semantics. The four Perl-visible packages map to the XS’s four MODULE blocks: - `Cairo::Path` (tied ARRAY) - one element per path command. - `Cairo::Path::Data` (tied HASH) - keys ”type“ / ”points“ for a command. - `Cairo::Path::Points`(tied ARRAY) - the points of one command. - `Cairo::Path::Point` (tied 2-ARRAY)- the (x, y) of one point. ## Magic representation (mirrors `create_tie` / `cairo_perl_mg_get`) `create_tie` (XS lines 41-69) attaches TWO magics to the referent AV/HV: 1. `PERL_MAGIC_tied` (»P«, obj = the blessed RV) so Perl routes element access through this package’s FETCH/STORE/… methods. 2. `PERL_MAGIC_ext` (»~«, mg_ptr = the C object pointer, namlen = 0), with `mg->mg_private = MY_MAGIC_SIG (0xCAFE)` marking it as ours. The C pointer carried in the ext slot IS the element/point offset: the top-level tie carries `cairo_path_t*`; each `Cairo::Path::Data` / `::Points` tie carries the `cairo_path_data_t*` pointing at that command’s header; each `Cairo::Path::Point` tie carries the `cairo_path_data_t*` pointing at that specific point union. There is no separate index stored - the pointer already threads the location, exactly as the XS does (e.g. `newSVCairoPathPoint(&data[index + 1])`, XS line 427/444). Recovery mirrors `cairo_perl_mg_get` (XS lines 29-37): given the invocant blessed RV `sv`, walk `SvRV(sv)`«s magic chain for a `PERL_MAGIC_ext` slot whose `mg_private == 0xCAFE`, and read `mg_ptr`. ## VERSION SCOPE Path is stable cairo API; there is no version gating and no post-1.109 superset here. ## Functions ### Other Functions #### `path_destroy` `$path->DESTROY` -> cairo_path_destroy (XS:283-295). Recover the pointer through the ext-magic slot (via `mg_get`, matching `SvCairoPath`); if present, destroy it. The 5.6.x mg_ptr-unset branch is not mirrored (pperl targets 5.42+, XS lines 289-293 are guarded out). #### `path_fetchsize` `Cairo::Path::FETCHSIZE` (XS:297-305): number of path commands. Walk data[] stepping by `header.length`, counting each command. #### `path_fetch` `Cairo::Path::FETCH` (XS:307-320): the i-th command as a tied `Cairo::Path::Data`. Walk by header.length, counting to `index`; return the tie carrying that command’s `cairo_path_data_t*`, else undef. #### `data_fetch` `Cairo::Path::Data::FETCH` (XS:337-351): key ”type“ -> nickname; ”points“ -> a tied `Cairo::Path::Points`; anything else croaks. #### `data_store` `Cairo::Path::Data::STORE` (XS:353-367): only ”points“ is writable. Rewrite this command’s coordinates from the arrayref value (keeping the existing header.type), and return a fresh tied Points view (matching the XS RETVAL). #### `data_exists` `Cairo::Path::Data::EXISTS` (XS:369-379): true for ”type“/“points“ only. #### `data_firstkey` `Cairo::Path::Data::FIRSTKEY` (XS:381-385): always ”type“. #### `data_nextkey` `Cairo::Path::Data::NEXTKEY` (XS:387-395): ”type“ -> ”points“, else undef. #### `points_fetchsize` `Cairo::Path::Points::FETCHSIZE` (XS:412-419): n_points for this command. #### `points_fetch` `Cairo::Path::Points::FETCH` (XS:421-432): the i-th point of this command as a tied `Cairo::Path::Point` carrying `&data[index + 1]`, else undef. #### `points_store` `Cairo::Path::Points::STORE` (XS:434-454): write x/y of the i-th point back into the C buffer from the [x,y] arrayref value; return a tied Point view. #### `point_fetchsize` `Cairo::Path::Point::FETCHSIZE` (XS:471-475): always 2. #### `point_fetch` `Cairo::Path::Point::FETCH` (XS:477-494): index 0 -> x, 1 -> y, read straight from the C buffer’s point union; else undef. #### `point_store` `Cairo::Path::Point::STORE` (XS:496-513): the LIVE write-back. index 0 sets point.x, 1 sets point.y - straight into the C buffer - and returns the new value as an NV (matching `newSVnv(data->point.x = value)`).