Skip to content

Commit

Permalink
added a page
Browse files Browse the repository at this point in the history
  • Loading branch information
@ShawnDriscoll
ShawnDriscoll committed Oct 1, 2017
1 parent 7b36437 commit b5fa63e
Show file tree
Hide file tree
Showing 24 changed files with 425 additions and 412 deletions.
Binary file added docs/build/.doctrees/designers_notes.doctree
View file
Binary file not shown.
Binary file modified docs/build/.doctrees/environment.pickle
View file
Binary file not shown.
Binary file modified docs/build/.doctrees/index.doctree
View file
Binary file not shown.
Binary file removed docs/build/.doctrees/project.doctree
View file
Binary file not shown.
Binary file modified docs/build/.doctrees/tutorial.doctree
View file
Binary file not shown.
Binary file removed docs/build/.doctrees/worm.doctree
View file
Binary file not shown.
91 changes: 91 additions & 0 deletions docs/build/_sources/designers_notes.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
**Designer's Notes**
====================

In the Beginning
----------------
One of the first things I do when learning a new language is to
discovery how it generates random numbers. Older computer languages
from the '70s had their own built-in random number generators. Technically,
they were pseudo-random number generators. But technically, I wanted to
program my Star Trek games anyway no matter what they were called.

In the '80s, I would discover that not all comptuer languages came
with random number generators built in. Many didn't have such a thing
unless some external software library was installed. Both FORTRAN and C
couldn't do random anything out of the box. A math library had to be picked from
the many that were out there. And if none were available, a computer class on campus
was available to teach you how to propgram your own random number generator from scratch.

By the '90s, random number generators were pretty much standardized as
for as how accurately random they were. And they were included in standard
libraries for various languages. By the time Python was being developed, the
C language used to write Python had very robust random number generators.
And because Python was written in C, it just made sense for it to make
use of C libraries.

For those that are curious, *diceroll* uses the ``random.randint()`` module that comes
with CPython. There are stronger random generators out there now, with NumPy being one
of them. But at the time of designing *diceroll*, I didn't quite understand how-all
NumPy worked, or what version of it to install. And for rolling dice, the built-in
random number generator would be just fine.

Lessons Learned
---------------
In the past, when I needed a random number from 1 to say 6 (see 6-sided dice), I would use ``INT(RND(1)*6) + 1``.
And I would be used to doing it that way for probably 15 years or so, because that is
how most BASIC languages did things. Other languages like C required me to wip out the
80286 System Developer's 3-ring binder to find out how ``srand()`` and ``rand()`` worked,
and under what circumstances.

Fast-forward 20 years, and I'm learning CPython without knowing the difference between a CPython
or an RPython or any other Python out there. I figured Python was the same all over, even though
I had a feeling Linux did things differently because of its filepath naming and OS commands. And
of course, the first thing I had to try was Python's ``random`` module, as well as its
ugly-looking ``randint()``.

Right away I noticed the way Python "loaded" modules was going to be a learning experience. I
hadn't really programmed anything huge since my TANDY Color Computer 3 days running OS-9 Level II
and programming in BASIC09 (https://en.wikipedia.org/wiki/BASIC09). Python would reveal different
ways of importing modules the more I read about them, and the more code I poured over.

I would soon find that: ::

import random

print random.randint(1, 6) # roll a 6-sided die

Was the same thing as: ::

from random import randint

print randint(1, 6) # roll a 6-sided die

Which looked a bit cleaner. But I was debating if I wanted to use ``randint()`` at all in
my normal coding.

So while I was learning how to write my own functions, as well as how to go about importing them, I came up with
an idea for *diceroll*. It would included a ``roll()`` function, and a ``die_rolls()`` function as
a "side effect." Even though ``die_rolls()`` had no error-checking, ``roll()`` would call it after
doing its own error-checking.

I was trying to avoid using: ::

from diceroll import die_rolls

print die_rolls(6, 2) # roll two 6-sided dice

For my dice rolls, I wanted something more readable. Something like: ::

from diceroll import roll

print roll('2D6') # roll two 6-sided dice

It was almost less typing. And it was easier to spot what kind of roll was being made in my
code. And the simple addition or subtraction of DMs to such a roll was making the function more appealing: ::

print roll('2D6+3') # roll two 6-sided dice and add a DM of +3 to it




.. versionadded:: 2.2
26 changes: 13 additions & 13 deletions docs/build/_sources/index.txt
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
.. image:: diceroll_cover.png

diceroll 2.2 Manual
===================
**diceroll 2.2 Manual**
=======================

**A dice rolling module**

Requirements
------------

* **Microsoft Windows**
| This code has been tested on versions: XP, 7, 8, and 10. It has
| not been tested on MacOS or Linux.
This code has been tested on Windows versions: XP, 7, 8, and 10.
It has not been tested on MacOS or Linux.
* **Python 2.5**
| This module was written using the C implementation of Python
| version 2.5.4. Also known as CPython. With some doing, this
| module could of course be re-written for Jython, PyPy, or
| IronPython.
|
| Eclypse/PyDev, PyCharm, NetBeans, and IDLE all work fine for
| running this module in.
This module was written using the C implementation of Python
version 2.5.4. Also known as CPython. With some doing, this
module could of course be re-written for Jython, PyPy, or
IronPython.

Eclypse/PyDev, PyCharm, NetBeans, and IDLE all work fine for
running this module in.

.. Warning::
diceroll will not work with Python 2.6+.
*diceroll* will not work with **Python 2.6+**.



Expand All @@ -31,7 +31,7 @@ Contents
.. toctree::
:maxdepth: 2

project
designers_notes
tutorial
diceroll

Expand Down
18 changes: 0 additions & 18 deletions docs/build/_sources/project.txt
View file

This file was deleted.

2 changes: 1 addition & 1 deletion docs/build/_sources/tutorial.txt
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
**diceroll Tutorial**
=================
=====================

This is a short description about how to use diceroll: ::

Expand Down
38 changes: 0 additions & 38 deletions docs/build/_sources/worm.txt
View file

This file was deleted.

186 changes: 186 additions & 0 deletions docs/build/designers_notes.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Designer&#8217;s Notes &mdash; diceroll 2.2 Manual</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2.2.1b',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/diceroll_icon_16x16.ico"/>
<link rel="contents" title="Global table of contents" href="contents.html" />
<link rel="index" title="Global index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="diceroll 2.2 Manual" href="index.html" />
<link rel="next" title="diceroll Tutorial" href="tutorial.html" />
<link rel="prev" title="diceroll 2.2 Manual" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="tutorial.html" title="diceroll Tutorial"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="diceroll 2.2 Manual"
accesskey="P">previous</a> |</li>
<li><a href="index.html">diceroll 2.2 Manual</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">


<div class="section" id="designer-s-notes">
<h1><strong>Designer&#8217;s Notes</strong><a class="headerlink" href="#designer-s-notes" title="Permalink to this headline"></a></h1>
<div class="section" id="in-the-beginning">
<h2>In the Beginning<a class="headerlink" href="#in-the-beginning" title="Permalink to this headline"></a></h2>
<p>One of the first things I do when learning a new language is to
discovery how it generates random numbers. Older computer languages
from the &#8216;70s had their own built-in random number generators. Technically,
they were pseudo-random number generators. But technically, I wanted to
program my Star Trek games anyway no matter what they were called.</p>
<p>In the &#8216;80s, I would discover that not all comptuer languages came
with random number generators built in. Many didn&#8217;t have such a thing
unless some external software library was installed. Both FORTRAN and C
couldn&#8217;t do random anything out of the box. A math library had to be picked from
the many that were out there. And if none were available, a computer class on campus
was available to teach you how to propgram your own random number generator from scratch.</p>
<p>By the &#8216;90s, random number generators were pretty much standardized as
for as how accurately random they were. And they were included in standard
libraries for various languages. By the time Python was being developed, the
C language used to write Python had very robust random number generators.
And because Python was written in C, it just made sense for it to make
use of C libraries.</p>
<p>For those that are curious, <em>diceroll</em> uses the <tt class="docutils literal"><span class="pre">random.randint()</span></tt> module that comes
with CPython. There are stronger random generators out there now, with NumPy being one
of them. But at the time of designing <em>diceroll</em>, I didn&#8217;t quite understand how-all
NumPy worked, or what version of it to install. And for rolling dice, the built-in
random number generator would be just fine.</p>
</div>
<div class="section" id="lessons-learned">
<h2>Lessons Learned<a class="headerlink" href="#lessons-learned" title="Permalink to this headline"></a></h2>
<p>In the past, when I needed a random number from 1 to say 6 (see 6-sided dice), I would use <tt class="docutils literal"><span class="pre">INT(RND(1)*6)</span> <span class="pre">+</span> <span class="pre">1</span></tt>.
And I would be used to doing it that way for probably 15 years or so, because that is
how most BASIC languages did things. Other languages like C required me to wip out the
80286 System Developer&#8217;s 3-ring binder to find out how <tt class="docutils literal"><span class="pre">srand()</span></tt> and <tt class="docutils literal"><span class="pre">rand()</span></tt> worked,
and under what circumstances.</p>
<p>Fast-forward 20 years, and I&#8217;m learning CPython without knowing the difference between a CPython
or an RPython or any other Python out there. I figured Python was the same all over, even though
I had a feeling Linux did things differently because of its filepath naming and OS commands. And
of course, the first thing I had to try was Python&#8217;s <tt class="docutils literal"><span class="pre">random</span></tt> module, as well as its
ugly-looking <tt class="docutils literal"><span class="pre">randint()</span></tt>.</p>
<p>Right away I noticed the way Python &#8220;loaded&#8221; modules was going to be a learning experience. I
hadn&#8217;t really programmed anything huge since my TANDY Color Computer 3 days running OS-9 Level II
and programming in BASIC09 (<a class="reference external" href="https://en.wikipedia.org/wiki/BASIC09">https://en.wikipedia.org/wiki/BASIC09</a>). Python would reveal different
ways of importing modules the more I read about them, and the more code I poured over.</p>
<p>I would soon find that:</p>
<div class="highlight"><pre><span class="kn">import</span> <span class="nn">random</span>

<span class="k">print</span> <span class="n">random</span><span class="o">.</span><span class="n">randint</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">6</span><span class="p">)</span> <span class="c"># roll a 6-sided die</span>
</pre></div>
<p>Was the same thing as:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">random</span> <span class="kn">import</span> <span class="n">randint</span>

<span class="k">print</span> <span class="n">randint</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">6</span><span class="p">)</span> <span class="c"># roll a 6-sided die</span>
</pre></div>
<p>Which looked a bit cleaner. But I was debating if I wanted to use <tt class="docutils literal"><span class="pre">randint()</span></tt> at all in
my normal coding.</p>
<p>So while I was learning how to write my own functions, as well as how to go about importing them, I came up with
an idea for <em>diceroll</em>. It would included a <tt class="docutils literal"><span class="pre">roll()</span></tt> function, and a <tt class="docutils literal"><span class="pre">die_rolls()</span></tt> function as
a &#8220;side effect.&#8221; Even though <tt class="docutils literal"><span class="pre">die_rolls()</span></tt> had no error-checking, <tt class="docutils literal"><span class="pre">roll()</span></tt> would call it after
doing its own error-checking.</p>
<p>I was trying to avoid using:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">diceroll</span> <span class="kn">import</span> <span class="n">die_rolls</span>

<span class="k">print</span> <span class="n">die_rolls</span><span class="p">(</span><span class="mi">6</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> <span class="c"># roll two 6-sided dice</span>
</pre></div>
<p>For my dice rolls, I wanted something more readable. Something like:</p>
<div class="highlight"><pre><span class="kn">from</span> <span class="nn">diceroll</span> <span class="kn">import</span> <span class="n">roll</span>

<span class="k">print</span> <span class="n">roll</span><span class="p">(</span><span class="s">&#39;2D6&#39;</span><span class="p">)</span> <span class="c"># roll two 6-sided dice</span>
</pre></div>
<p>It was almost less typing. And it was easier to spot what kind of roll was being made in my
code. And the simple addition or subtraction of DMs to such a roll was making the function more appealing:</p>
<div class="highlight"><pre><span class="k">print</span> <span class="n">roll</span><span class="p">(</span><span class="s">&#39;2D6+3&#39;</span><span class="p">)</span> <span class="c"># roll two 6-sided dice and add a DM of +3 to it</span>
</pre></div>
<p>
<span class="versionmodified">New in version 2.2.</span></p>
</div>
</div>


</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3>Table Of Contents</h3>
<ul>
<li><a class="reference external" href=""><strong>Designer&#8217;s Notes</strong></a><ul>
<li><a class="reference external" href="#in-the-beginning">In the Beginning</a></li>
<li><a class="reference external" href="#lessons-learned">Lessons Learned</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
<p class="topless"><a href="index.html" title="previous chapter"><strong>diceroll 2.2 Manual</strong></a></p>
<h4>Next topic</h4>
<p class="topless"><a href="tutorial.html" title="next chapter"><strong>diceroll Tutorial</strong></a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/designers_notes.txt">Show Source</a></li>
</ul>
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" /> <input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="tutorial.html" title="diceroll Tutorial"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="diceroll 2.2 Manual"
accesskey="P">previous</a> |</li>
<li><a href="index.html">diceroll 2.2 Manual</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2017, Shawn Driscoll.
Last updated on Oct 01, 2017.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>

0 comments on commit b5fa63e

Please sign in to comment.