Permalink
Browse files

initial

  • Loading branch information...
0 parents commit 45e2188065c1a998863f6804e83b496fb1b4d993 @joearms committed Feb 27, 2012
Showing with 15,986 additions and 0 deletions.
  1. +76 −0 src/Makefile
  2. +177 −0 src/best.notes
  3. +35 −0 src/book.book
  4. 0 src/chap2html.xsl
  5. +457 −0 src/chap2pdf.xsl
  6. +154 −0 src/design.chap1
  7. +33 −0 src/edit.html
  8. +44 −0 src/elib1_best.erl
  9. +43 −0 src/elib1_blob_store.erl
  10. +356 −0 src/elib1_chunks.erl
  11. +111 −0 src/elib1_content_edit.erl
  12. +110 −0 src/elib1_diff.erl
  13. +60 −0 src/elib1_doc.erl
  14. +452 −0 src/elib1_docmaker.erl
  15. +31 −0 src/elib1_ensure_copyrighted.erl
  16. +191 −0 src/elib1_expand.erl
  17. +129 −0 src/elib1_fast_read.erl
  18. +83 −0 src/elib1_fast_write.erl
  19. +138 −0 src/elib1_file_finder.erl
  20. +134 −0 src/elib1_find.erl
  21. +128 −0 src/elib1_find_reent.erl
  22. +251 −0 src/elib1_gamma.erl
  23. +30 −0 src/elib1_geom.erl
  24. +143 −0 src/elib1_guid_store.erl
  25. +409 −0 src/elib1_html_tokenise.erl
  26. +258 −0 src/elib1_http_driver.erl
  27. +643 −0 src/elib1_indexer.erl
  28. +117 −0 src/elib1_indexer_plugin_erl.erl
  29. +42 −0 src/elib1_indexer_results.erl
  30. +2,538 −0 src/elib1_misc.erl
  31. +370 −0 src/elib1_ml9.erl
  32. +103 −0 src/elib1_ml9_2_html.erl
  33. +38 −0 src/elib1_ml9_parse_header.yrl
  34. +585 −0 src/elib1_mysql.erl
  35. +549 −0 src/elib1_new_webkit.erl
  36. +78 −0 src/elib1_org2latex.erl
  37. +397 −0 src/elib1_parse_dtd.yrl
  38. +378 −0 src/elib1_porter.erl
  39. +429 −0 src/elib1_rfc4627.erl
  40. +185 −0 src/elib1_screen.erl
  41. +26 −0 src/elib1_search.erl
  42. +207 −0 src/elib1_seq_web_server1.erl
  43. +103 −0 src/elib1_sha1.erl
  44. +203 −0 src/elib1_similar.erl
  45. +67 −0 src/elib1_simple_kv_db.erl
  46. +137 −0 src/elib1_spy.erl
  47. +137 −0 src/elib1_spy.erl~
  48. +432 −0 src/elib1_store.erl
  49. +641 −0 src/elib1_tagger.erl
  50. +130 −0 src/elib1_telnet.erl
  51. +89 −0 src/elib1_txt2xml.erl
  52. +576 −0 src/elib1_webkit.erl
  53. +25 −0 src/elib1_webquery.erl
  54. +1,045 −0 src/elib1_xml.erl
  55. +460 −0 src/ezxml.chap1
  56. +119 −0 src/gen_component.erl
  57. +22 −0 src/log
  58. +572 −0 src/log.log
  59. +59 −0 src/lorem.chap
  60. +5 −0 src/mkdoc
  61. +12 −0 src/myapp.app.src
  62. +16 −0 src/myapp_app.erl
  63. +28 −0 src/myapp_sup.erl
  64. +2 −0 src/notes
  65. +12 −0 src/password.erl
  66. +246 −0 src/readme.html
  67. +33 −0 src/slides.ehtml
  68. +3 −0 src/todo
  69. +50 −0 src/tryxform.erl
  70. +44 −0 src/wiki.chap1
@@ -0,0 +1,76 @@
+.SUFFIXES: .erl .beam .yrl
+
+MODS := $(wildcard *.erl)
+YRL := $(wildcard *.yrl)
+CHAPS := $(wildcard *.chap)
+BOOKS := $(wildcard *.book)
+LOGS := $(wildcard *.log)
+
+CWD := $(shell pwd)
+
+../ebin/%.beam: %.erl
+ ## erlc +warn_missing_spec -o ../ebin -W $<
+ ## grep --silent --invert-match "_test"
+ erlc -o ../ebin -W $<
+
+../ebin/%.beam: ../tmp/%.erl
+ erlc -o ../ebin -W $<
+
+../doc/%.html: %.chap
+ @erl -noshell -pa ../ebin -s elib1_docmaker batch $< -s init stop
+
+../doc/%.html: %.log
+ @erl -noshell -pa ../ebin -s elib1_chunks batch $< -s init stop
+
+../doc/%.html: %.erl
+ ./mkdoc $<
+
+../tmp/%.erl: %.yrl
+ erlc -o ../tmp -W $<
+
+../../pdf/%.pdf: %.chap
+ erl -s elib1_doc batch $<
+ fop -xml ../tmp/$*.xml -xsl chap2pdf.xsl -pdf ../../pdf/$*.pdf
+
+# ../../html/%.html: %.chap
+# erl -s elib1_doc batch $<
+# fop -xml ../tmp/$*.xml -xsl chap2html.xsl -txt ../../html/$*.html
+
+all: yecc beam html #chapHTML
+
+test:
+ dialyzer -Wno_return --src -c "."
+
+utest: beam
+ erl -noshell -eval "eunit:test(elib1_misc, [verbose])" -s init stop
+
+edoc:
+ erl -noshell -eval "edoc:application(lib, \".\", [{dir,\"../doc\"}])" \
+ -s init stop
+
+html: ${MODS:%.erl=../doc/%.html}
+
+beam: ${MODS:%.erl=../ebin/%.beam}
+
+yecc: ${YRL:%.yrl=../tmp/%.erl} ${YRL:%.yrl=../ebin/%.beam}
+
+chapPDF: ${CHAPS:%.chap=../../pdf/%.pdf}
+
+# chapHTML: ${CHAPS:%.chap=../../html/%.html}
+
+books: ${BOOKS:%.book=../doc/%.html}
+
+logs: ${LOGS:%.log=../doc/%.html}
+
+clean:
+ rm ../ebin/*.beam
+ rm -rf *.aux *.beam
+ rm -rf *.log *.tmp erl_crash.dump
+
+veryclean:
+ rm ../bin/* ../doc/* ../tmp/*
+
+
+
+
+
@@ -0,0 +1,177 @@
+Best practice for writing documenting and testing code
+
+I'd like to try and define "best practice" for writing documenting and
+testing Erlang code. I want to use:
+
+ - only the tools supplied in the OTP release
+
+So I use:
+
+ - eunit for unit testing
+ - the dialyzer for checking my code
+ - edoc for documenting things
+ - type specifications for specifying types
+
+These tools do not completely "play together" in a satisfactory manner,
+so I'd like to define what I thing is "best practice" and hope that by doing
+so the tools will converge.
+
+Let's suppose I want to define the good 'ol factorial. Here's a module
+called elib1_best.erl. I've written it in such a way that it can be
+processed by erlc,eunit,edoc and the dialyzer - read the footnotes
+in brackets for an explanation.
+
+ -module(elib1_best). %% [1]
+
+ %% elib1_best: Best practice template for library modules [2]
+ %% Time-stamp: <2009-12-02 09:43:12 ejoearm> [3]
+
+ %%----------------------------------------------------------------------
+ %% Copyright (c) 2009 Joe Armstrong <erlang@gmail.com> [4]
+ %% Copyright (c) 2009 Whoomph Software AB
+ %%
+ %% Permission is hereby granted, free of charge, to any person
+ %% obtaining a copy of this software and associated documentation
+ %% files (the "Software"), to deal in the Software without
+ %% restriction, including without limitation the rights to use, copy,
+ %% modify, merge, publish, distribute, sublicense, and/or sell copies
+ %% of the Software, and to permit persons to whom the Software is
+ %% furnished to do so, subject to the following conditions:
+ %%
+ %% The above copyright notice and this permission notice shall be
+ %% included in all copies or substantial portions of the Software.
+ %%
+ %% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ %% EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ %% MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ %% NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ %% BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ %% ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ %% CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ %% SOFTWARE.
+ %%-----------------------------------------------------------------------
+
+ -include_lib("eunit/include/eunit.hrl"). %% [5]
+
+ -export([fac/1]). %% [6]
+
+
+ %% @doc fac(N) computes factorial(N) using a fast
+ %% iterative algorithm. [7]
+
+ -spec fac(integer()) -> integer(). [8]
+
+ fac(N) when is_integer(N), N >= 0 -> fac1(N, 1).
+
+ fac1(0, K) -> K;
+ fac1(N, K) -> fac1(N-1, K*N).
+
+ fac_test() -> %% [9]
+ 6 = fac(3),
+ 24 = fac(4).
+
+ %% Notes:
+ %% [1] - module on line 1
+ %% [2] - module comment
+ %% [3] - Time stamp auto generated by emacs.
+ %% Must be near start of file
+ %% [4] - Copyright (I always forget this, but adding a
+ %% copyright reduces the pain later
+ %% [5] - Needed for eunit
+ %% [6] - use export and NOT compile(export_all)
+ %% [7] - @doc comes first
+ %% [8] - -spec comes immediately *before* the function
+ %% [9] - test cases come immediately after the function
+
+ %% end of module
+...
+
+Now let's see what happens:
+
+ 1) Compiling
+
+ erlc +warn_missing_spec -o ../ebin -W elib1_best.erl
+
+ ./elib1_best.erl:0: Warning: missing specification for function test/0
+ ./elib1_best.erl:44: Warning: missing specification for function fac_test/0
+
+Best practice is to support type specifications for all exported
+functions. But eunit magically adds a function test/0 and I really
+don't want to have to add manual exports and type specs for
+fac_test/0.
+
+ [A fix is needed to erlc here, OR eunit can add type specs,
+ I think the latter is better - erlc should not need to know about eunit]
+
+ 2) Dialyzing
+
+dialyzer --src elib1_best.erl
+ Checking whether the PLT /home/ejoearm/.dialyzer_plt is up-to-date... yes
+ Proceeding with analysis...
+Unknown functions:
+ eunit:test/1
+ done in 0m0.32s
+done (passed successfully)
+
+ This is ok - I could add eunit to my plt if I wanted ...
+ the dialyzer warns for missing functions so I don't need to run
+ xref
+
+ 3) Documentation
+
+ I'll run edoc on everything in the current directory putting the
+results in ../doc
+
+ > erl -noshell -eval "edoc:application(lib, \".\", [{dir,\"../doc\"}])" \
+ -s init stop
+
+ This works fine and ../doc/elib1_best.html has the documentation
+ but now edoc has not found my nice -spec declaration and thinks that
+ fac has type: fac(N) -> any()
+
+ Why: because edoc and erlc don't use the same type parser.
+
+ Current best practice is to use -spec (in code) and
+ not @spec (in edoc comments)
+
+ [A fix is needed here to edoc, to understand -spec's]
+
+4) Testing
+
+ 1> eunit:test(elib1_best, [verbose]).
+ ======================== EUnit ========================
+ elib1_best: fac_test (module 'elib1_best')...ok
+ =======================================================
+ Test passed.
+ ok
+
+ Great ...
+
+Now for questions.
+
+ 1) Does this represent best practice? Is this the best way to
+ write code? - can anybody improve on this?
+
+ [And yes I know about quickcheck, but I'm only concerned
+ with SW in the OTP release]
+
+ 2) If I write like this can I assume that one day edoc
+ and eunit and erlc will converge so that I get correctly displayed
+ types in edoc and no warnings in erlc etc?
+
+ 3) Does anything else have to be fixed?
+
+ 4) Improvements..
+
+ I can think of one. I have some code to convert .erl to
+ .html with correctly colored code and hyperlinks etc.
+ So I can "surf" the code. It would be nice to have hooks
+ into edoc so I can call this code
+
+That's all for now ...
+
+/Joe
+
+
+
+
@@ -0,0 +1,35 @@
+= An Erlang Library
+
+This book describes an Erlang library called ''elib1''.
+
+== Todo (formatting program)
+
+<ul>
++ Add a diagram language (inline svg)
++ ~~Make the Book version~~
++ ~~Make compact lists, so I can leave out the blank line in paragraphs like
+this~~
++ ~~add processing of ''footnotes''~~
++ Make commands for /bin
++ check that all list entries do not end with a dot.
++ Check that all list entries start with a big letter.
++ punctuation check.
++ ~~add "typographic quotes."~~
++ Nice to make paragraphs "clickable-editable" in the browser.
++ Add some nive paragraph hover effect that colors paras as we move over them. Makes text easier to read.
+</ul>
+
+== To do (programs)
+
+<ul>
++ mysql full text searching and metadata
++ go through all old library adding good stuff (example topological sort)
++ javascript slide show from wiki markup
++ move over to GIT
++ xref
+</ul>
+
+<include chapter="design" />
+<include chapter="ezxml" />
+<include chapter="lorum" />
+
No changes.
Oops, something went wrong.

0 comments on commit 45e2188

Please sign in to comment.