Current section
Files
Jump to
Current section
Files
doc/readme.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.29.1">
<meta name="project" content="ExPomodoro v1.0.1">
<title>ExPomodoro — ExPomodoro v1.0.1</title>
<link rel="stylesheet" href="dist/html-elixir-V2ETBPMB.css" />
<script src="dist/handlebars.runtime-NWIB6V2M.js"></script>
<script src="dist/handlebars.templates-IV5W3OL2.js"></script>
<script src="dist/sidebar_items-CB79531F.js"></script>
<script src="docs_config.js"></script>
<script async src="dist/html-XN2TSG4M.js"></script>
</head>
<body data-type="extras" class="page-extra">
<script>
try {
var settings = JSON.parse(localStorage.getItem('ex_doc:settings') || '{}');
if (settings.theme === 'dark' ||
((settings.theme === 'system' || settings.theme == null) &&
window.matchMedia('(prefers-color-scheme: dark)').matches)
) {
document.body.classList.add('dark')
}
} catch (error) { }
</script>
<div class="main">
<button class="sidebar-button sidebar-toggle" aria-label="toggle sidebar">
<i class="ri-menu-line ri-lg" title="Collapse/expand sidebar"></i>
</button>
<section class="sidebar">
<form class="sidebar-search" action="search.html">
<button type="submit" class="search-button" aria-label="Submit Search">
<i class="ri-search-2-line" aria-hidden="true" title="Submit search"></i>
</button>
<button type="button" tabindex="-1" class="search-close-button" aria-label="Cancel Search">
<i class="ri-close-line ri-lg" aria-hidden="true" title="Cancel search"></i>
</button>
<label class="search-label">
<p class="sr-only">Search</p>
<input name="q" type="text" class="search-input" placeholder="Search..." aria-label="Input your search terms" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" />
</label>
</form>
<div class="autocomplete">
<div class="autocomplete-results">
</div>
</div>
<div class="sidebar-header">
<div class="sidebar-projectDetails">
<a href="ExPomodoro.html" class="sidebar-projectName" translate="no">
ExPomodoro
</a>
<strong class="sidebar-projectVersion" translate="no">
v1.0.1
</strong>
</div>
<ul class="sidebar-listNav">
<li><a id="extras-list-link" href="#full-list">Pages</a></li>
<li><a id="modules-list-link" href="#full-list">Modules</a></li>
</ul>
</div>
<div class="gradient"></div>
<ul id="full-list" class="sidebar-fullList"></ul>
</section>
<section class="content">
<output role="status" id="toast"></output>
<div class="content-outer">
<div id="content" class="content-inner">
<h1>
<button class="icon-action display-settings">
<i class="ri-settings-3-line"></i>
<span class="sr-only">Settings</span>
</button>
<a href="https://github.com/sgobotta/ex_pomodoro/blob/main/README.md#L1" title="View Source" class="icon-action" rel="help">
<i class="ri-code-s-slash-line" aria-hidden="true"></i>
<span class="sr-only">View Source</span>
</a>
<span>ExPomodoro</span>
</h1>
<p><strong>The <code class="inline">ex_pomodoro</code> program is a simple set of functions that let developers manage pomodoro sessions withing their Elixir applications.</strong></p><h4 align="center"> An Elixir Pomodoro 🍅</h4><p align="center" style="margin-top: 14px;"> <a href="https://github.com/sgobotta/ex_pomodoro/actions/workflows/ci.yml">
<img
src="https://github.com/sgobotta/ex_pomodoro/actions/workflows/ci.yml/badge.svg?branch=main"
alt="CI Status"
>
</a>
<a
href='https://coveralls.io/github/sgobotta/ex_pomodoro?branch=main'
>
<img
src='https://coveralls.io/repos/github/sgobotta/ex_pomodoro/badge.svg?branch=main'
alt='Coverage Status'
/>
</a></p><p align="center" style="margin-top: 14px;"> <a
href="https://github.com/sgobotta/ex_pomodoro/blob/main/LICENSE"
>
<img
src="https://img.shields.io/badge/License-GPL%20v3-white.svg"
alt="License"
>
</a></p><h2 id="introduction" class="section-heading">
<a href="#introduction" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">introduction</p>
</a>
Introduction
</h2>
<blockquote><p><a href="https://en.wikipedia.org/wiki/Pomodoro_Technique">About the Pomodoro technique</a></p></blockquote><p><strong>ExPomodoro</strong> is an Elixir library that let developers easily manage pomodoro sessions by using a simple set of fuctions that can start a pomodoro session, pause a session, get the current session details.</p><p>The motivation behind <strong>ExPomodoro</strong> development was initially driven by HTTP integrations in chat applications, such as <a href="https://en.wikipedia.org/wiki/Mattermost">Mattermost</a> or <a href="https://es.wikipedia.org/wiki/Slack_(software)">Slack</a>, where one could create slash commands that interact to an HTTP server or create bots that send and receive notifications. This library includes only the domain logic for managing pomodoro sessions.</p><h2 id="installation" class="section-heading">
<a href="#installation" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">installation</p>
</a>
Installation
</h2>
<p>If <a href="https://hex.pm/docs/publish">available in Hex</a>, the package can be installed
by adding <code class="inline">ex_pomodoro</code> to your list of dependencies in <code class="inline">mix.exs</code>:</p><pre><code class="makeup elixir" translate="no"><span class="kd">def</span><span class="w"> </span><span class="nf">deps</span><span class="w"> </span><span class="k" data-group-id="8474766604-1">do</span><span class="w">
</span><span class="p" data-group-id="8474766604-2">[</span><span class="w">
</span><span class="p" data-group-id="8474766604-3">{</span><span class="ss">:ex_pomodoro</span><span class="p">,</span><span class="w"> </span><span class="s">"~> 1.0.1"</span><span class="p" data-group-id="8474766604-3">}</span><span class="w">
</span><span class="p" data-group-id="8474766604-2">]</span><span class="w">
</span><span class="k" data-group-id="8474766604-1">end</span></code></pre><p>Otherwise it can be installed using the git remote url:</p><pre><code class="makeup elixir" translate="no"><span class="kd">def</span><span class="w"> </span><span class="nf">deps</span><span class="w"> </span><span class="k" data-group-id="4742893130-1">do</span><span class="w">
</span><span class="p" data-group-id="4742893130-2">[</span><span class="w">
</span><span class="p" data-group-id="4742893130-3">{</span><span class="ss">:ex_pomodoro</span><span class="p">,</span><span class="w">
</span><span class="ss">git</span><span class="p">:</span><span class="w"> </span><span class="s">"git@github.com:sgobotta/ex_pomodoro.git"</span><span class="p">,</span><span class="w"> </span><span class="ss">tag</span><span class="p">:</span><span class="w"> </span><span class="s">"1.0.1"</span><span class="p" data-group-id="4742893130-3">}</span><span class="w">
</span><span class="p" data-group-id="4742893130-2">]</span><span class="w">
</span><span class="k" data-group-id="4742893130-1">end</span></code></pre><h2 id="setup" class="section-heading">
<a href="#setup" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">setup</p>
</a>
Setup
</h2>
<p><strong>ExPomodoro</strong> uses a <a href="https://hexdocs.pm/elixir/Supervisor.html"><code class="inline">Supervisor</code></a> and <a href="https://hexdocs.pm/elixir/GenServer.html"><code class="inline">GenServer</code></a> to perform runtime operations for pomodoros. Add the <a href="ExPomodoro.html"><code class="inline">ExPomodoro</code></a> child spec to your application tree.</p><p><em>application.ex:</em></p><pre><code class="makeup elixir" translate="no"><span class="na">@impl</span><span class="w"> </span><span class="no">true</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">start</span><span class="p" data-group-id="0336402544-1">(</span><span class="c">_type</span><span class="p">,</span><span class="w"> </span><span class="c">_args</span><span class="p" data-group-id="0336402544-1">)</span><span class="w"> </span><span class="k" data-group-id="0336402544-2">do</span><span class="w">
</span><span class="n">children</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p" data-group-id="0336402544-3">[</span><span class="w">
</span><span class="n">...</span><span class="w">
</span><span class="nc">ExPomodoro</span><span class="w"> </span><span class="c1"># <- Add ExPomodoro to the children array</span><span class="w">
</span><span class="p" data-group-id="0336402544-3">]</span><span class="w">
</span><span class="n">opts</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p" data-group-id="0336402544-4">[</span><span class="ss">strategy</span><span class="p">:</span><span class="w"> </span><span class="ss">:one_for_one</span><span class="p">,</span><span class="w"> </span><span class="ss">name</span><span class="p">:</span><span class="w"> </span><span class="nc">MyApp.Supervisor</span><span class="p" data-group-id="0336402544-4">]</span><span class="w">
</span><span class="nc">Supervisor</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="0336402544-5">(</span><span class="n">children</span><span class="p">,</span><span class="w"> </span><span class="n">opts</span><span class="p" data-group-id="0336402544-5">)</span><span class="w">
</span><span class="k" data-group-id="0336402544-2">end</span></code></pre><p>Create a module that implements the following function. This is used to receive callbacks from the lib.</p><p><em>your_callback_module.ex:</em></p><pre><code class="makeup elixir" translate="no"><span class="kd">defmodule</span><span class="w"> </span><span class="nc">MyApp.ExPomodoroClient</span><span class="w"> </span><span class="k" data-group-id="8110694354-1">do</span><span class="w">
</span><span class="na">@moduledoc</span><span class="w"> </span><span class="no">false</span><span class="w">
</span><span class="kn">require</span><span class="w"> </span><span class="nc">Logger</span><span class="w">
</span><span class="na">@doc</span><span class="w"> </span><span class="s">"""
Helper function to test callbacks from the Pomodoro Server.
"""</span><span class="w">
</span><span class="na">@spec</span><span class="w"> </span><span class="n">handle_activity_changed</span><span class="p" data-group-id="8110694354-2">(</span><span class="n">any</span><span class="p" data-group-id="8110694354-3">(</span><span class="p" data-group-id="8110694354-3">)</span><span class="p" data-group-id="8110694354-2">)</span><span class="w"> </span><span class="o">::</span><span class="w"> </span><span class="ss">:ok</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">handle_activity_changed</span><span class="p" data-group-id="8110694354-4">(</span><span class="n">payload</span><span class="p" data-group-id="8110694354-4">)</span><span class="w"> </span><span class="k" data-group-id="8110694354-5">do</span><span class="w">
</span><span class="ss">:ok</span><span class="w"> </span><span class="o">=</span><span class="w">
</span><span class="nc">Logger</span><span class="o">.</span><span class="n">debug</span><span class="p" data-group-id="8110694354-6">(</span><span class="w">
</span><span class="s">"</span><span class="si" data-group-id="8110694354-7">#{</span><span class="bp">__MODULE__</span><span class="si" data-group-id="8110694354-7">}</span><span class="s">.handle_activity_changed payload=</span><span class="si" data-group-id="8110694354-8">#{</span><span class="n">inspect</span><span class="p" data-group-id="8110694354-9">(</span><span class="n">payload</span><span class="p">,</span><span class="w"> </span><span class="ss">pretty</span><span class="p">:</span><span class="w"> </span><span class="no">true</span><span class="p" data-group-id="8110694354-9">)</span><span class="si" data-group-id="8110694354-8">}</span><span class="s">"</span><span class="w">
</span><span class="p" data-group-id="8110694354-6">)</span><span class="w">
</span><span class="k" data-group-id="8110694354-5">end</span><span class="w">
</span><span class="k" data-group-id="8110694354-1">end</span></code></pre><p><em>runtime.exs:</em></p><pre><code class="makeup elixir" translate="no"><span class="n">config</span><span class="w"> </span><span class="ss">:ex_pomodoro</span><span class="p">,</span><span class="w">
</span><span class="ss">callback_module</span><span class="p">:</span><span class="w"> </span><span class="nc">MyApp.ExPomodoroClient</span></code></pre><h2 id="usage" class="section-heading">
<a href="#usage" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">usage</p>
</a>
Usage
</h2>
<p>The <a href="ExPomodoro.html"><code class="inline">ExPomodoro</code></a> is the main module to interact with the APIs using a <code class="inline">Pomodoro</code> struct. There should be no need to use the rest of modules that handle runtime logic.</p><p>A <code class="inline">Pomodoro</code> has four states: <code class="inline">:idle</code>, <code class="inline">:exercise</code>, <code class="inline">:break</code>, <code class="inline">:finished</code></p><p>Calling the APIs affect the state, and return an updated <code class="inline">Pomodoro</code> struct.</p><p>All pomodoro functions are documented, check the <a href="./lib/ex_pomodoro.ex"><code class="inline">ExPomodoro</code></a> for more usage examples.</p><h3 id="start-a-pomodoro-session" class="section-heading">
<a href="#start-a-pomodoro-session" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">start-a-pomodoro-session</p>
</a>
Start a pomodoro session
</h3>
<p>A <code class="inline">%Pomodoro{}</code> is created with an <code class="inline">id</code> that must be unique between sessions. Starting a pomodoro with a non-unique id will cause no effect.</p><p>This command will create a pomodoro with default options. The work time is <code class="inline">25</code> minutes by default, the break time is <code class="inline">5</code> and the number of periods is <code class="inline">4</code>.</p><pre><code class="makeup elixir" translate="no"><span class="gp unselectable">iex> </span><span class="nc">ExPomodoro</span><span class="o">.</span><span class="n">start</span><span class="p" data-group-id="9298424862-1">(</span><span class="s">"some id"</span><span class="p" data-group-id="9298424862-1">)</span><span class="w">
</span><span class="p" data-group-id="9298424862-2">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="9298424862-3">%</span><span class="nc" data-group-id="9298424862-3">ExPomodoro.Pomodoro</span><span class="p" data-group-id="9298424862-3">{</span><span class="w">
</span><span class="ss">id</span><span class="p">:</span><span class="w"> </span><span class="s">"some id"</span><span class="p">,</span><span class="w">
</span><span class="ss">activity</span><span class="p">:</span><span class="w"> </span><span class="ss">:exercise</span><span class="p">,</span><span class="w">
</span><span class="ss">exercise_duration</span><span class="p">:</span><span class="w"> </span><span class="mi">1_500_000</span><span class="p">,</span><span class="w">
</span><span class="ss">break_duration</span><span class="p">:</span><span class="w"> </span><span class="mi">300_000</span><span class="p">,</span><span class="w">
</span><span class="ss">rounds</span><span class="p">:</span><span class="w"> </span><span class="mi">4</span><span class="w">
</span><span class="p" data-group-id="9298424862-3">}</span><span class="p" data-group-id="9298424862-2">}</span></code></pre><p>Check the <a href="./lib/ex_pomodoro.ex"><code class="inline">ExPomodoro</code></a> module docs for examples with options.</p><h3 id="pause-a-pomodoro-session" class="section-heading">
<a href="#pause-a-pomodoro-session" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">pause-a-pomodoro-session</p>
</a>
Pause a pomodoro session
</h3>
<p>A <code class="inline">%Pomodoro{}</code> can be paused by passing the <code class="inline">id</code>.</p><pre><code class="makeup elixir" translate="no"><span class="gp unselectable">iex> </span><span class="nc">ExPomodoro</span><span class="o">.</span><span class="n">pause</span><span class="p" data-group-id="2016769302-1">(</span><span class="s">"some id"</span><span class="p" data-group-id="2016769302-1">)</span><span class="w">
</span><span class="p" data-group-id="2016769302-2">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="2016769302-3">%</span><span class="nc" data-group-id="2016769302-3">Pomodoro</span><span class="p" data-group-id="2016769302-3">{</span><span class="w">
</span><span class="ss">id</span><span class="p">:</span><span class="w"> </span><span class="s">"some id"</span><span class="p">,</span><span class="w">
</span><span class="ss">activity</span><span class="p">:</span><span class="w"> </span><span class="ss">:idle</span><span class="p">,</span><span class="w">
</span><span class="ss">current_duration</span><span class="p">:</span><span class="w"> </span><span class="n">timeleft</span><span class="w">
</span><span class="p" data-group-id="2016769302-3">}</span><span class="p" data-group-id="2016769302-2">}</span></code></pre><h3 id="get-a-pomodoro-session" class="section-heading">
<a href="#get-a-pomodoro-session" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">get-a-pomodoro-session</p>
</a>
Get a pomodoro session
</h3>
<p>A <code class="inline">%Pomodoro{}</code> can be obtained by passing the <code class="inline">id</code>.</p><pre><code class="makeup elixir" translate="no"><span class="gp unselectable">iex> </span><span class="nc">ExPomodoro</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="9279516142-1">(</span><span class="s">"some id"</span><span class="p" data-group-id="9279516142-1">)</span><span class="w">
</span><span class="p" data-group-id="9279516142-2">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="p" data-group-id="9279516142-3">%</span><span class="nc" data-group-id="9279516142-3">ExPomodoro.Pomodoro</span><span class="p" data-group-id="9279516142-3">{</span><span class="ss">id</span><span class="p">:</span><span class="w"> </span><span class="s">"some id"</span><span class="p" data-group-id="9279516142-3">}</span><span class="p" data-group-id="9279516142-2">}</span></code></pre><p>If the session does not exist, the function returns an error tuple.</p><pre><code class="makeup elixir" translate="no"><span class="gp unselectable">iex> </span><span class="nc">ExPomodoro</span><span class="o">.</span><span class="n">get</span><span class="p" data-group-id="3378757627-1">(</span><span class="s">"some other id"</span><span class="p" data-group-id="3378757627-1">)</span><span class="w">
</span><span class="p" data-group-id="3378757627-2">{</span><span class="ss">:error</span><span class="p">,</span><span class="w"> </span><span class="ss">:not_found</span><span class="p" data-group-id="3378757627-2">}</span></code></pre><p>A <code class="inline">Pomodoro</code> has a timeout of 90 minutes. if no interaction is made the <code class="inline">Pomodoro</code> will not be found and it's stats lost.</p><h2 id="development" class="section-heading">
<a href="#development" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">development</p>
</a>
Development
</h2>
<h3 id="requirements" class="section-heading">
<a href="#requirements" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">requirements</p>
</a>
Requirements
</h3>
<ul><li>Elixir <code class="inline">1.11</code> or later. It should work on other versions but it isn't tested.</li></ul><blockquote><p>If you use <code class="inline">asdf</code> just run <code class="inline">asdf install</code> in the root repository to install the required <strong>Elixir</strong> version.</p></blockquote><h3 id="installation-and-setup" class="section-heading">
<a href="#installation-and-setup" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">installation-and-setup</p>
</a>
Installation and setup
</h3>
<p>Install and compile dependencies and library.</p><pre><code class="makeup bash" translate="no"><span class="">make setup
</span></code></pre><p>Run format checks, credo, dialyzer and tests</p><pre><code class="makeup bash" translate="no"><span class="">make check
</span></code></pre><p>Run tests only</p><pre><code class="makeup bash" translate="no"><span class="">make test
</span></code></pre><p>Run test coverage</p><pre><code class="makeup bash" translate="no"><span class="">make test.cover
</span></code></pre><p>Run <code class="inline">make</code> to find a complete list of commands.</p><h2 id="future-features" class="section-heading">
<a href="#future-features" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">future-features</p>
</a>
Future features
</h2>
<ul><li>Allow callbacks on <a href="https://hexdocs.pm/elixir/GenServer.html"><code class="inline">GenServer</code></a> creation to support PubSub subscriptions, message passing, notifications and other real-time features.</li><li>Allow description for pomodoro periods</li></ul><h2 id="license" class="section-heading">
<a href="#license" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
<p class="sr-only">license</p>
</a>
License
</h2>
<p><a href="LICENSE"><strong>GNU General Public License version 3</strong></a></p>
<div class="bottom-actions">
<div class="bottom-actions-item">
<a href="api-reference.html" class="bottom-actions-button" rel="prev">
<span class="subheader">
← Previous Page
</span>
<span class="title">
API Reference
</span>
</a>
</div>
<div class="bottom-actions-item">
</div>
</div>
<footer class="footer">
<p>
<span class="line">
<a href="https://hex.pm/packages/ex_pomodoro/1.0.1" class="footer-hex-package">Hex Package</a>
<a href="https://preview.hex.pm/preview/ex_pomodoro/1.0.1">Hex Preview</a>
(<a href="https://preview.hex.pm/preview/ex_pomodoro/1.0.1/show/README.md">current file</a>)
</span>
<span class="line">
<button class="a-main footer-button display-quick-switch" title="Search HexDocs packages">
Search HexDocs
</button>
<a href="ExPomodoro.epub" title="ePub version">
Download ePub version
</a>
</span>
</p>
<p class="built-using">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener" translate="no">ExDoc</a> (v0.29.1) for the
<a href="https://elixir-lang.org" title="Elixir" target="_blank" translate="no">Elixir programming language</a>
</p>
</footer>
</div>
</div>
</section>
</div>
</body>
</html>