# How-To

Two kinds of task-oriented material live in this section. The
distinction matters because it tells you how much time to put aside
and what you'll walk away with.

**Guides** are long-form and multi-chapter. You read them the way
you read a book - cover to cover, or chapter by chapter with each
chapter building on the last. A guide covers a whole subject in
depth. The regex guide, for instance, takes you from `m//` through
Unicode properties and backtracking performance; the debugging guide
covers everything from attaching `-d` to decoding production stack
traces.

**Tutorials** are narrow and single-sitting. One tutorial, one
topic, one specific question answered. You land on a tutorial with a
task in mind and leave with it done. No larger arc, no required
prior reading.

::::{grid} 1 1 2 2
:gutter: 3

:::{grid-item-card} Guides
:text-align: left

[**PPerl Architecture**](guide/pperl-architecture/index) - how pperl is
built: the JIT, the FFI, native modules, and the concrete differences
from upstream Perl 5.

[**Concurrent Execution**](guide/concurrent-execution/index) - doing
work in parallel: auto-parallelization, the ithreads reality, and
how to choose between them.

[**Regular Expressions**](guide/regular-expression/index) - Perl regex
from first principles through performance tuning.

[**Performance**](guide/performance/index) - making Perl run fast on
pperl: measuring with the right tools, which classic idioms still pay
off, and how to shape a loop so the JIT and parallelizer take it.

[**Object-oriented Programming**](guide/oop/index) - modern
`class`/`field`/`method` first, classical `bless` for maintainers,
migration paths.

[**Debugging**](guide/debugging/index) - finding and fixing bugs:
the `-d` debugger, inspecting live state, production-path tools.

[**One-Liners**](guide/oneliner/index) - `pperl` at the shell:
`-e`, implicit loops, progressive recipes, parameterised aliases,
quoting gotchas.

[**Tying Variables**](guide/tie/index) - making a variable dispatch
through a class: tied scalars, arrays, hashes, and filehandles, with
a complete worked class for each.

[**Coming from another language**](guide/coming-from/index) - Perl by
analogy for developers fluent in another language: each construct you
already know mapped to its Perl counterpart, with the gotcha the
similarity hides. Python first; PHP, Ruby, Lua planned.

[**Graphics**](guide/graphics/index) - two-dimensional graphics in
Perl, from the pixel up: the drawing algorithms, the CPAN toolkits
(Imager, Cairo, Prima), reaching C libraries through pperl's native
FFI, and two runnable capstones (a drawing app and a 2D game).
:::

:::{grid-item-card} Tutorials
:text-align: left

[**Pack & Unpack**](tutorial/pack-unpack/index) - binary data layout:
directives, endianness, network protocols, file formats.

[**Working with I/O Streams**](tutorial/io-streams/index) - the full
`open` story: modes, encoding layers, pipes, in-memory handles,
error handling.

[**Perl References**](tutorial/reference/index) - scalars, arrays,
hashes, code, anonymous and weak references, nested structures.

[**Unicode in Perl**](tutorial/unicode/index) - text vs bytes, source
encoding, PerlIO layers, Unicode regex, common pitfalls.

[**Boolean Logic for Perl Programmers**](tutorial/boolean-logic/index) -
truthiness, all sixteen binary operators, De Morgan, NAND/NOR
completeness, bitwise and regex applications.

[**Interprocess Communication**](tutorial/ipc/index) - runnable IPC
cookbook: subprocesses, FIFOs, TCP and UDP sockets, socket pairs,
System V semaphores and shared memory.
:::

::::

```{toctree}
:hidden:
:maxdepth: 1

guide/pperl-architecture/index
guide/concurrent-execution/index
guide/regular-expression/index
guide/performance/index
guide/oop/index
guide/debugging/index
guide/oneliner/index
guide/tie/index
guide/coming-from/index
guide/graphics/index
tutorial/pack-unpack/index
tutorial/io-streams/index
tutorial/reference/index
tutorial/unicode/index
tutorial/boolean-logic/index
tutorial/ipc/index
```