document dot/underline difficulties with objects

2 files changed, 67 insertions, 6 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..8e32954
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,48 @@
+
+### Problems With Python/Julia Syntax Mapping with dot ('.') Operator
+
+*aka, why the annoying underscore syntax is needed*
+
+Using PyCall, we can map python modules to Julia modules with the same syntax:
+
+    python> import os
+    python> os.uname()
+    python> os.O_RDONLY
+
+    julia> using PyCall
+    julia> os = pywrap(pyimport("os"))
+    julia> os.uname()
+    julia> os.O_RDONLY
+
+And using a recursive version of pywrap (`pyrecwrap`), we can get nested
+modules to map also:
+
+    python> import os
+    python> os.path.genericpath.os.uname()
+
+    julia> os = pyrecwrap(pyimport("os"))
+    julia> os.path.genericpath.os.uname()
+
+We can also map python classes to Julia modules:
+
+    python> import pyx.style.linewidth as psl
+    python> psl.THICK
+
+    julia> ps = pywrap(pyimport("pyx.style"))
+    julia> psl = pywrap(ps.linewidth)
+    julia> psl.THICK
+
+However, in Python a class/object can both have members and be called as an
+initializer:
+
+    python> psl.THIN
+    python> psl(0.1)
+
+But in Julia a Module can't act as a function.
+
+Thus, a one-to-one syntax mapping just isn't going to work until (unless?) the
+dot ('.') operator can be overridden (as of Julia 0.4 it may not).
+
+The work around used in this project (PyX.jl) is to use underscores in
+object/function names and dots in object/module names. Eg,
+`style.linewidth(0.2)` vs. `style_linewidth.THICK`.
diff --git a/README.md b/README.md
index 32c6ce7..e55b3ca 100644
--- a/README.md
+++ b/README.md
@@ -74,12 +74,25 @@ All the expected [Julia/Python differences][1] apply:
 Note that the string code snippets that go into `graph_data_function` are still
 Python code, not Julia.
 
-There doesn't seem to be an easy way to handle nested Python modules as nested
-modules in Julia, so there can only be a single `.` separator in variable and
-function names. This has been worked around by using the underscore character
-(`_`) instead of `.` for all but the last separator. So, eg,
-`graph_axis.split()` instead of `graph.axis.split()` and `color_rgb.red`
-instead of `color.rgb.red`.
+Because the Python syntax features for objects (they can both be accessed like
+a module or called like a function) does not map to any Julia type at this
+time, a naming convention is used such that only a single `.` separator is used
+in Julia names and calls, and underscore characters (`_`) are used in
+objects-as-modules to access attributes. For example:
+
+    python> from pyx import style, color, graph
+    python> style.linewidth.THICK
+    python> style.linewidth(0.5)
+    python> color.rgb.red
+    python> graph.axis.split()
+    
+    julia> using PyX
+    julia> style_linewidth.THICK
+    julia> style.linewidth(0.5)
+    julia> color_rgb.red
+    julia> graph_axis.split()
+
+See HACKING for more details.
 
 To avoid namespace collisions or confusion with built-in Julia functions the
 following functions (only) have `pyx_` preprended to the function name: