Mirror of forum.nim-lang.org

1860 :: support for compilable examples embedded inside source code

• PV (orginal) [2015-12-08T08:48:35+01:00] view original

  This is half question and half meta-meta-feature request.

  Library writer may like to pepper source code with small but complete and compilable examples of use. Like this:

  # module A
  ...
  proc foo() = ...
  
  EXAMPLE:
    import A
    foo()
  
  EXAMPLE:
    import A
    foo()
    bar()
  Run

  This may be implementable based on simple unit test here http://forum.nim-lang.org/t/653 and compiles function.

  ---

  1. Examples would be always checked during compilation to be syntactically correct (with compiles). This feels as possible right now.

  ---

  2. Every example should be complete, in other words copy-pasting it into empty file should work. As a consequence compiles would need to somehow handle import A within module of the same name. This seems currently impossible.

  ---

  3. One may like to invoke individual example explicitly from command line (in non-release mode). Example could be identified by string, though symbol (no "") feels more fitting. I do not know whether Nim allows to manipulate symbols.

  EXAMPLE "my-example":
    import A
    foo()
  
  # or
  EXAMPLE my-example:
    import A
    foo()
  Run

  called as:

  # hypothetical invocation syntax
  app.exe --run-example:my-example
  Run

  To make it usable probably requires cmdline parsing library being present by default (using -d:some-define feels infeasible here).

  ---

  4. Examples would be spotted by documentation tool and added near to the documentation for specified entity (proc, struct, etc).

  I imagine something like:

  # this example would be shown near docs for foo()
  EXAMPLE "my-example1" (foo):
    foo()
  
  # this example would be presented TWICE, near docs for foo() and for bar() as well
  EXAMPLE "my-example2" (foo, bar):
    foo()
    bar()
  Run

  I had problem to understand the documentation for compiler doc option but it seems hardwired.

  I am also not sure about the ability to specify zero or more valid code symbols and have them verified during compilation (the (foo, bar) part).

  ---

  Frequent solution for examples is to have them as separate project(s) in separate directory somewhere. This destroys close association with source code and they are not referred by programmer documentation. My suggestion here would allow to keep them "alive".

---

• andrea (orginal) [2015-12-09T15:23:08+01:00] view original

  Wouldn't it be enough to put

  when defined("run-examples"):
   foo()
  Run

  and then run them with nim c -r -d:run-examples foo.nim?

---

• PV (orginal) [2015-12-11T03:35:28+01:00] view original

  My idea was to be able to run selected example easily using debugger. That would be very handy for learning. Mass running all of them may be too slow or inconvenient, they have different purpose than unit tests.

---

• Arrrrrrrrr (orginal) [2015-12-11T09:55:02+01:00] view original

  You can define different switchs:

  when defined(example1): # Code for example 1
  when defined(example2): # Code for example 2
  when defined(examplen): # Code for example n
  Run

---