Document dynamic variables. about janet-lang.org HOT 21 CLOSED

Perhaps all-dynamics is useful for some of this?

$ janet
Janet 1.20.0-40ae2e81 linux/x64 - '(doc)' for help
repl:1:> (all-dynamics)
@[:args :doc-color :err-color :executable :peg-grammar :pretty-format :syspath]
repl:2:> (doc all-dynamics)


    function
    boot.janet on line 2823, column 1

    (all-dynamics &opt env local)

    Get all dynamic bindings in an environment. Defaults to the current 
    fiber's environment. If local is truthy, will not show inherited 
    bindings (from prototype tables).


nil

from janet-lang.org.

Some / more docs would be nice.

For reference, regarding (dyn :args), here are some leads for examining related information:

• janet-lang/janet@9118f2c
• janet-lang/janet@a0e98b9

For :syspath, the current janet man page has this bit:

  -m syspath
         Set the dynamic binding :syspath to the string syspath so that Janet will load
         system modules from a directory different than the default. The default is set
         when Janet is built, and defaults to /usr/local/lib/janet on Linux/Posix,  and
         C:/Janet/Library on Windows. This option supersedes JANET_PATH.

and the jpm man page has a number of references.

Perhaps it's possible to look at those bits of text to come up with something?

On a side note, I've found that in some cases, there are useful bits that turn up via the gitter channel logs so it can be helpful to search there.

In any case, I agree that important dynamic variables being documented appropriately sounds good.

from janet-lang.org.

The specific items identified in the repl output above include:

• :args
• :doc-color
• :err-color
• :executable
• :peg-grammar
• :pretty-format
• :syspath

Links lead to hints about meaning.

from janet-lang.org.

@crocket Here's an example:

$ janet
Janet 1.21.2-a2ba0913 linux/x64 - '(doc)' for help
repl:1:> (doc *args*)


    keyword
    boot.janet on line 3618, column 1

    Dynamic bindings that will contain command line arguments at 
    program start


nil

from janet-lang.org.

Okay, I'm closing it.

from janet-lang.org.

Addition: If it's possible to get a list of all current dynamic variables, could that be documented as well?

If not, maybe it would be nice if calling (dyn) without arguments could return a list of all current dynamic variables?

(= potential issue for the Janet repo, instead of this one)

from janet-lang.org.

The current dynamic variables are all in the current env which you can query.

from janet-lang.org.

all-dynamics outputs a list of dynamic variables, but doesn't explain what they mean.

from janet-lang.org.

Interestingly, that list does not quite match some of the output from (doc):

:args :doc-color :err-color :executable :macro-lints :peg-grammar 
:pretty-format :syspath

Specifically, :macro-lints shows up via (doc), but apparently not via (all-dynamics).

At any rate, there seems to be a reference to :macro-lints here.

from janet-lang.org.

Is it possible to document dynamic variables in source code? Emacs is good at documenting variables.

from janet-lang.org.

Dynamic bindings should indeed be better documented, but it is a bit difficult for auto generated docs since there is no way to tell which code is using a binding.

Guile has a nice wrapper around a similar mechanism that helps solve this problem: https://www.gnu.org/software/guile/manual/html_node/Parameters.html

Edit: the above link is documentation for a guile feature called parameters, which implement dynamic scope but attached to lexically scopes bindings. We could do something similar and do things like (def *pretty-format "dynamic binding for the output of the pp function" :pretty-format). Then code could refer to *pretty-format, which would behave as any normal binding, catch typos, etc.

from janet-lang.org.

With commit 461576e7, there is now a mechanism for documenting dynamic variables in source.

Here is a list of things that make use of it:

• *defdyn-prefix*
• *out*
• *err*
• *macro-form*
• *current-file*
• *pretty-format*
• *macro-lints*
• *err-color*
• *doc-width*
• *doc-color*
• *args*
• *executable*
• *profilepath*

The commit message has documentation on defdyn (with examples) and each element of the list above links to a specific example.

from janet-lang.org.

Things in boot.janet that I didn't see docs provided for by defdyn include:

• :peg-grammar - though default-peg-grammar does have a docstring
• :syspath
• :exit - though it's touched on in the docstring for quit
• :exit-value
• :lint-levels
• :lint-error
• :lint-warn
• :debug
• :redef

from janet-lang.org.

How can I see documentation for dynamic variables now?

from janet-lang.org.

What about the documentation for syspath?

from janet-lang.org.

As I mentioned here I don't see anything in boot.janet for it.

May be a PR to add something like the following would be accepted:

Path of directory to load system modules from.

from janet-lang.org.

@crocket janet-lang/janet#949 has the suggested text and it was merged.

from janet-lang.org.

janet-lang/janet@1aac048 added defdyn forms for:

• *redef*
• *debug*
• *exit*
• *exit-value*
• *lint-error*
• *lint-warn*
• *lint-levels*
• *peg-grammar*

I think that covers everything I noticed.

@crocket How does it seem to you?

from janet-lang.org.

Looks good. Has every dynamic variable been documented?

from janet-lang.org.

@crocket At least everything I noticed in boot.janet including what I see via (all-dynamics) appears to have been covered -- I believe that includes all items mentioned in this issue.

I don't know if there are any others.

from janet-lang.org.

@crocket May be if someone discovers some specific dynamic variables that have not been documented, separate issues / PRs can be made for those and in the mean time this issue can be closed.

What do you think?

from janet-lang.org.