{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tutorial\n",
    "\n",
    "This notebook shows some example usage of the [Perlbrew Plugin](https://metacpan.org/pod/Devel::IPerl::Plugin::Perlbrew).\n",
    "\n",
    "### Installation\n",
    "\n",
    "This plugin needs to be [installed](https://metacpan.org/pod/Devel::IPerl::Plugin::Perlbrew#). Once installed, this notebook can be used to experiment with the functionality."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading the plugin\n",
    "\n",
    "The plugin cannot be used until it is loaded into the current notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "use feature 'say';\n",
    "## Load the plugin with this guard\n",
    "IPerl->load_plugin('Perlbrew') unless IPerl->can('perlbrew');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Usage\n",
    "\n",
    "There are a number of [helpers](https://metacpan.org/pod/distribution/Devel-IPerl/lib/IPerl.pm#helper) registered for the plugin. These are available as methods on the `IPerl` class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### perlbrew_lib_create\n",
    "\n",
    "The `perlbrew_lib_create` helper provides a method of creating new libraries in which to install perl modules into. This aims to be identical to `perlbrew lib create` at the command line.\n",
    "\n",
    "This is where we will start in order to create the libraries required for the rest of this tutorial."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "IPerl->perlbrew_lib_create('random');\n",
    "# *change this as required ^^^^^^^^\n",
    "IPerl->perlbrew_lib_create('special');\n",
    "# *change this as required ^^^^^^^^"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### perlbrew_list\n",
    "\n",
    "The `perlbrew_list` helper displays the installed perls and libraries that are available for use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## Run this cell to list the installed perls and perlbrew'ed libraries\n",
    "IPerl->perlbrew_list();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### perlbrew\n",
    "\n",
    "The `perlbrew` helper is an interface to [`perlbrew use`](https://metacpan.org/pod/perlbrew#COMMAND:-USE), designed to be as complementary as possible. The effect is for the rest of the notebook, which may or may not be desirable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## Run this cell to use the library specified (random) - use a library in the list output from previous cell.\n",
    "IPerl->perlbrew('random');\n",
    "# * change this ^^^^^^^^"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Switching libraries for subsequent cells is possible."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## Run this cell to switch to the library specified (special) - use a library in the list output from previous cell.\n",
    "IPerl->perlbrew('special');\n",
    "# * change this ^^^^^^^^"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to load modules in the same cell, the call to `IPerl->perlbrew` must be placed in a `BEGIN` block, thus:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "BEGIN{ IPerl->perlbrew('random'); }\n",
    "# * change this ^^^^^^^^\n",
    "use Mojo::Base -strict;\n",
    "# * change this to load a module that exists"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Switching back to the *\"system\"* perl is possible. \n",
    "\n",
    "Here we use `$ENV{'PERLBREW_PERL'}` as it stores the version of perl in use. To save typing, an alternative would be, `\"perl-5.26.1\"` or otherwise the exact value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "IPerl->perlbrew($ENV{'PERLBREW_PERL'});"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "say $ENV{'PERLBREW_PERL'};"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### perlbrew_list_modules\n",
    "\n",
    "The `perlbrew_list_modules` helper displays the installed perl modules in the currently active *brew*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "IPerl->perlbrew_list_modules();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### perlbrew and unload all previously loaded modules\n",
    "\n",
    "Some users may wish to unload all modules that were previously loaded in library one when loading library two. \n",
    "\n",
    "This behaviour is controlled by the second argument to `perlbrew`. A *true* value results in the modules being unloaded, while a *false* value, the default, keeps the previously loaded modules, loaded.\n",
    "\n",
    "The following cells illustrate this, but require editing to match your environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "BEGIN{ IPerl->perlbrew('random', 1); }\n",
    "# * change this        ^^^^^^^^\n",
    "use Mojo::Base -strict;\n",
    "# * change this to load a module that exists\n",
    "$uninit = 1;"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "IPerl->perlbrew('special', 1);\n",
    "# * change this ^^^^^^^^\n",
    "# modules unloaded will be reported in output."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "IPerl 0.009",
   "language": "perl",
   "name": "iperl"
  },
  "language_info": {
   "file_extension": ".pl",
   "mimetype": "text/x-perl",
   "name": "perl",
   "version": "5.26.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}