Skip to content

Commit 84c4420

Browse files
cgaycgay
authored
Merge pull request #3 from cgay/dev
Copy documentation from Open Dylan repo, with history
2 parents 1e06c09 + cf8815c commit 84c4420

File tree

6 files changed

+363
-0
lines changed

6 files changed

+363
-0
lines changed

‎.gitmodules‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "ext/sphinx-extensions"]
2+
path = ext/sphinx-extensions
3+
url = https://github.com/dylan-lang/sphinx-extensions

‎documentation/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎documentation/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎documentation/source/conf.py‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
13+
import os
14+
import sys
15+
sys.path.insert(0, os.path.abspath('../../ext/sphinx-extensions/sphinxcontrib'))
16+
import dylan.themes as dylan_themes
17+
18+
19+
# -- Project information -----------------------------------------------------
20+
21+
project = 'Hash Algorithms'
22+
copyright = '2022, Hannes Mehnert'
23+
author = 'Hannes Mehnert'
24+
25+
# The full version, including alpha/beta/rc tags
26+
release = 'v1.1.0'
27+
28+
29+
# -- General configuration ---------------------------------------------------
30+
31+
# Add any Sphinx extension module names here, as strings. They can be
32+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
33+
# ones.
34+
extensions = [
35+
'dylan.domain',
36+
'sphinx.ext.intersphinx'
37+
]
38+
39+
# Add any paths that contain templates here, relative to this directory.
40+
templates_path = ['_templates']
41+
42+
# List of patterns, relative to source directory, that match files and
43+
# directories to ignore when looking for source files.
44+
# This pattern also affects html_static_path and html_extra_path.
45+
exclude_patterns = ['_build']
46+
47+
# This makes it so that each document doesn't have to use
48+
# .. default-domain:: dylan
49+
# but they probably should anyway, so that they can be built separately
50+
# without depending on this top-level config file.
51+
primary_domain = 'dylan'
52+
53+
# -- Options for HTML output -------------------------------------------------
54+
55+
# The theme to use for HTML and HTML Help pages. See the documentation for
56+
# a list of builtin themes.
57+
html_theme = dylan_themes.get_html_theme_default()
58+
59+
# Theme options are theme-specific and customize the look and feel of a theme
60+
# further. For a list of options available for each theme, see the
61+
# documentation.
62+
html_theme_options = dylan_themes.get_html_theme_options_default()
63+
64+
# Add any paths that contain custom themes here, relative to this directory.
65+
html_theme_path = [dylan_themes.get_html_theme_path()]
66+
67+
# The name for this set of Sphinx documents. If None, it defaults to
68+
# "<project> v<release> documentation".
69+
html_title = "Hash Algorithms"
70+
71+
# Add any paths that contain custom static files (such as style sheets) here,
72+
# relative to this directory. They are copied after the builtin static files,
73+
# so a file named "default.css" will overwrite the builtin "default.css".
74+
html_static_path = ['_static']

‎documentation/source/index.rst‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
***************************
2+
The hash-algorithms Library
3+
***************************
4+
5+
.. current-library:: hash-algorithms
6+
.. current-module:: hash-algorithms
7+
8+
The hash-algorithms library provides consistent access to a variety of
9+
hash algorithms:
10+
11+
* md5
12+
* sha1
13+
* sha224
14+
* sha256
15+
* sha384
16+
* sha512
17+
18+
Hashing an entire string at once can be done via the functions named
19+
after each hash:
20+
21+
.. code-block:: dylan
22+
23+
let digest = sha1("Some text");
24+
25+
If you want a printable digest, use :meth:`hexdigest(<byte-vector>)`:
26+
27+
.. code-block:: dylan
28+
29+
let hexdigest = hexdigest(sha1("Some text"));
30+
31+
If you want to hash multiple strings into a single digest (useful when streaming),
32+
you can use the :gf:`update-hash` and :gf:`digest` functions:
33+
34+
.. code-block:: dylan
35+
36+
let hash = make(<sha1>);
37+
update-hash(hash, "Some");
38+
update-hash(hash, " ");
39+
update-hash(hash, "text");
40+
let digest = digest(hash);
41+
// hexdigest works on hashes as well:
42+
let hexdigest = hexdigest(hash);
43+
44+
The hash-algorithms Module
45+
==========================
46+
47+
.. class:: <hash>
48+
49+
:superclasses: :drm:`<object>`
50+
51+
.. generic-function:: digest-size
52+
53+
Returns the digest size of the hash algorithm.
54+
55+
:signature: digest-size (hash) => (digest-size)
56+
57+
:parameter hash: An instance of :class:`<hash>`.
58+
:value digest-size: An instance of :drm:`<integer>`.
59+
60+
.. generic-function:: block-size
61+
62+
Returns the block size of the hash algorithm.
63+
64+
:signature: block-size (hash) => (block-size)
65+
66+
:parameter hash: An instance of :class:`<hash>`.
67+
:value block-size: An instance of :drm:`<integer>`.
68+
69+
.. generic-function:: update-hash
70+
71+
Add more data to the hash.
72+
73+
:signature: update-hash (hash, input) => ()
74+
75+
:parameter hash: An instance of :class:`<hash>`.
76+
:parameter input: An instance of :drm:`<byte-string>`, :class:`<buffer>` or :class:`collections:byte-vector:<byte-vector>`.
77+
78+
:description:
79+
80+
Add more data to the hash. This is useful when streaming data or the data is
81+
available in multiple strings and you wish to avoid the overhead of concatenation.
82+
83+
Calling ``update-hash`` multiple times is equivalent to calling it once with
84+
a concatenation of the arguments:
85+
86+
.. code-block:: dylan
87+
88+
let hash-separate = make(<sha1>);
89+
update-hash(hash-separate, "Some");
90+
update-hash(hash-separate, " ");
91+
update-hash(hash-separate, "text");
92+
let digest-separate = digest(hash-separate);
93+
94+
let hash-combined = make(<sha1>);
95+
update-hash(hash-combined, "Some text");
96+
let digest-combined = digest(hash-combined);
97+
98+
// digest-separate and digest-combined will be the same
99+
100+
:seealso:
101+
102+
- :gf:`digest`
103+
- :meth:`hexdigest(<hash>)`
104+
- :meth:`hexdigest(<byte-vector>)`
105+
106+
.. generic-function:: digest
107+
108+
:signature: digest (hash) => (digest)
109+
110+
:parameter hash: An instance of :class:`<hash>`.
111+
:value digest: An instance of :class:`collections:byte-vector:<byte-vector>`.
112+
113+
:description:
114+
115+
The return value *digest* is binary data and may include null bytes. To display
116+
this result in text form, use :meth:`hexdigest(<hash>)` or
117+
:meth:`hexdigest(<byte-vector>)`.
118+
119+
Use :gf:`update-hash` to add data to the hash.
120+
121+
:seealso:
122+
123+
- :gf:`update-hash`
124+
- :meth:`hexdigest(<hash>)`
125+
- :meth:`hexdigest(<byte-vector>)`
126+
127+
.. method:: hexdigest
128+
:specializer: <hash>
129+
130+
Returns the digest for the given hash as a hexadecimal string.
131+
132+
:signature: hexdigest (hash) => (hexdigest)
133+
134+
:parameter hash: An instance of :class:`<hash>`.
135+
:value hexdigest: An instance of :drm:`<byte-string>`.
136+
137+
:seealso:
138+
139+
- :gf:`digest`
140+
- :meth:`hexdigest(<byte-vector>)`
141+
142+
.. method:: hexdigest
143+
:specializer: <byte-vector>
144+
145+
Returns the digest given as a hexadecimal string.
146+
147+
:signature: hexdigest (digest) => (hexdigest)
148+
149+
:parameter digest: An instance of :class:`collections:byte-vector:<byte-vector>`.
150+
:value hexdigest: An instance of :drm:`<byte-string>`.
151+
152+
:seealso:
153+
154+
- :gf:`digest`
155+
- :meth:`hexdigest(<hash>)`
156+
157+
MD5
158+
---
159+
160+
.. class:: <md5>
161+
162+
:superclasses: :class:`<hash>`
163+
164+
.. function:: md5
165+
166+
:signature: md5 (input) => (digest)
167+
168+
:parameter input: An instance of :drm:`<byte-string>`, :class:`<buffer>` or :class:`collections:byte-vector:<byte-vector>`.
169+
:value digest: An instance of :class:`collections:byte-vector:<byte-vector>`.
170+
171+
SHA-1
172+
-----
173+
174+
.. class:: <sha1>
175+
176+
:superclasses: :class:`<hash>`
177+
178+
.. function:: sha1
179+
180+
:signature: sha1 (input) => (digest)
181+
182+
:parameter input: An instance of :drm:`<byte-string>`, :class:`<buffer>` or :class:`collections:byte-vector:<byte-vector>`.
183+
:value digest: An instance of :class:`collections:byte-vector:<byte-vector>`.
184+
185+
SHA-2
186+
-----
187+
188+
.. class:: <sha256>
189+
190+
:superclasses: :class:`<hash>`
191+
192+
.. function:: sha256
193+
194+
:signature: sha256 (input) => (digest)
195+
196+
:parameter input: An instance of :drm:`<byte-string>`, :class:`<buffer>` or :class:`collections:byte-vector:<byte-vector>`.
197+
:value digest: An instance of :class:`collections:byte-vector:<byte-vector>`.
198+
199+
.. class:: <sha224>
200+
201+
:superclasses: :class:`<hash>`
202+
203+
.. function:: sha224
204+
205+
:signature: sha224 (input) => (digest)
206+
207+
:parameter input: An instance of :drm:`<byte-string>`, :class:`<buffer>` or :class:`collections:byte-vector:<byte-vector>`.
208+
:value digest: An instance of :class:`collections:byte-vector:<byte-vector>`.
209+
210+
.. class:: <sha384>
211+
212+
:superclasses: :class:`<hash>`
213+
214+
.. function:: sha384
215+
216+
:signature: sha384 (input) => (digest)
217+
218+
:parameter input: An instance of :drm:`<byte-string>`, :class:`<buffer>` or :class:`collections:byte-vector:<byte-vector>`.
219+
:value digest: An instance of :class:`collections:byte-vector:<byte-vector>`.
220+
221+
.. class:: <sha512>
222+
223+
:superclasses: :class:`<hash>`
224+
225+
.. function:: sha512
226+
227+
:signature: sha512 (input) => (digest)
228+
229+
:parameter input: An instance of :drm:`<byte-string>`, :class:`<buffer>` or :class:`collections:byte-vector:<byte-vector>`.
230+
:value digest: An instance of :class:`collections:byte-vector:<byte-vector>`.

‎ext/sphinx-extensions‎

Submodule sphinx-extensions added at 333fdd2

0 commit comments

Comments
 (0)