var ? as alias for doc

[badiku]

hi, totally new user.

just curious:
can I use (var ? doc) or (def ? doc) to set ? as alias for doc ?

or other name

tested, but failed.

though have success with other self function

C:\>janet.exe
Janet 1.37.1-local windows/x64/msvc - '(doc)' for help

repl:1:> (defn functest [] "test")
<function functest>

repl:2:> (functest)
"test"

repl:3:> (var functest2 functest)
<function functest>

repl:4:> functest2
<function functest>

repl:5:> (= functest functest2)
true

repl:6:> (functest2)
"test"

repl:7:> (var doc2 doc)
<function doc>

repl:8:> (= doc doc2)
true

repl:9:> doc2
<function doc>

repl:10:> (doc2 doc)
(<function doc*> (quote <function doc>))

repl:11:> (doc doc)
    macro
    boot.janet on line 3526, column 1
    (doc &opt sym)
    ...

[sogaiu]

How does this seem?

$ janet
Janet 1.37.1-1b49934e linux/x64/gcc - '(doc)' for help
repl:1:> (def ? :macro doc)
<function doc>
repl:2:> (? print)


    cfunction
    src/core/io.c on line 537, column 1

    (print & xs)

    Print values to the console (standard out). Value are converted to 
    strings if they are not already. After printing all values, a 
    newline character is printed. Use the value of (dyn :out stdout) to 
    determine what to push characters to. Expects (dyn :out stdout) to 
    be either a core/file or a buffer. Returns nil.


nil

IIUC, the reason some of the other attempts didn't work as expected is because doc is a macro (as can be seen from the output of (doc doc) above (in the original post)).

Here is an example of a similar use of def with :macro.

Also, this page has a section on def that goes into this a bit:

def can also append metadata and a docstring to the symbol when in the global scope.

---

On a side note, one can also express as (def ? {:macro true} doc).

...and if you aren't familiar with using the key sequence Ctrl-G at janet's repl, please give it a try :)

       Ctrl-G          Show documentation for the current symbol under the
                       cursor.

So for example in this state:

$ janet
Janet 1.37.1-1b49934e linux/x64/gcc - '(doc)' for help
repl:1:> (pp

(so the cursor is after pp), entering Ctrl-G should yield:

$ janet
Janet 1.37.1-1b49934e linux/x64/gcc - '(doc)' for help
repl:1:> (pp


    function
    boot.janet on line 1869, column 1

    (pp x)
    
    Pretty-print to stdout or `(dyn *out*)`. The format string used is
    `(dyn *pretty-format* "%q")`.

[badiku]

it works. thank you very much.

sounds like a hidden feature, not any example in doc. maybe it is not recommended to do so.

macro, and quote unquote quasiquote... powerful interesting new concepts, to be learned.

but, still a bit confused.

why type of both is :function, not :macro?

why they equal, doc == doc2 , but behave differently ?

repl:16:> (type doc)
:function

repl:17:> (type doc2)
:function

repl:18:> (= doc doc2)
true

repl:19:> (doc2 doc)
(<function doc*> (quote <function doc>))
repl:20:>

[sogaiu]

why type of both is :function, not :macro?

I don't know the development history, but perhaps the following bits might help for future memory purposes...

• In Janet, macros are a special kind of function in some sense (see next reply) for more details.

• Currently, type is implemented via janet_type in C. janet_type in turn is defined like this in C which basically can return one of the JanetType enum members...and there is no JANET_MACRO and hence, no :macro for type (^^;

I'll try to answer about doc and doc2 later.

[sogaiu]

why they equal, doc == doc2 , but behave differently ?

IIUC, doc and doc2 are two different symbols that happen to refer to the same function object:

$ janet
Janet 1.37.1-1b49934e linux/x64/gcc - '(doc)' for help

repl:1:> (def doc2 doc)
<function doc>

repl:2:> (dyn 'doc)
@{:doc "(doc &opt sym)\n\...."
  :macro true
  :source-map ("boot.janet" 3548 1)
  :value <function doc>}

repl:3:> (dyn 'doc2)
@{:source-map ("repl" 1 1)
  :value <function doc>}

repl:4:> (= (get (dyn 'doc) :value)
            (get (dyn 'doc2) :value))
true

The information about whether something is to be treated as a macro is stored separately (from the function object itself).

For doc's table above, there is an entry for :macro true, while for doc2's table, there isn't anything for :macro. Both tables have entries for :value where the associated value is the same function object (i.e. <function doc>).

If :macro true is removed from doc's table, I think doc's behavior would change (i.e. it won't be treated as a macro any more):

$ janet
Janet 1.37.1-1b49934e linux/x64/gcc - '(doc)' for help

repl:1:> (doc doc)


    macro
    boot.janet on line 3548, column 1

    (doc &opt sym)

    Shows documentation for the given symbol, or can show a list of 
    available bindings. If sym is a symbol, will look for documentation 
    for that symbol. If sym is a string or is not provided, will show 
    all lexical and dynamic bindings in the current environment 
    containing that string (all bindings will be shown if no string is 
    given).


nil

repl:2:> (setdyn 'doc (put (dyn 'doc) :macro nil))
@{:doc "(doc &opt sym)\n\n..."
  :source-map ("boot.janet" 3548 1)
  :value <function doc>}

repl:3:> (doc doc)
(<function doc*> (quote <function doc>))

---

On a related note, there is some more info on equality in Janet here.

...also, if you haven't come across @ianthehenry's book, please take a look!

[badiku]

thanks for detailed answers.

I would like to make such change:
(type doc) == :macro
and (= doc doc2) == false
and make this work: (def doc2 doc)

or maybe use new name, such as deeptype(), equaldeep(), or === , or setalias()

after long time looking at doc:
https://janet-lang.org/docs/macros.
https://janet.guide/macros-and-metaprogramming/
still I cannot figure it out.

if I can do this, then I woud have deeper understanding of macro and quoting.

repl:196:>  (defmacro deeptype [x]  ~(dyn ,'x)   )
<function deeptype>
repl:197:> (deeptype doc)
repl:197:1: compile error: unknown symbol x
repl:198:>  (defmacro deeptype [x]  ~(dyn ,' ,x)   )
<function deeptype>
repl:199:> (deeptype doc)
repl:198:35: compile error: cannot use unquote here
repl:200:>  (defmacro deeptype [x]  (tuple dyn x)   )
<function deeptype>
repl:201:> (deeptype doc)
nil
repl:202:>  (defmacro deeptype [x]  (tuple dyn 'x)   )
<function deeptype>
repl:203:> (deeptype doc)
repl:203:1: compile error: unknown symbol x
repl:204:>

[sogaiu]

How about something like this?

(defmacro alt-type
  [x]
  ~(if (get (dyn ',x) :macro)
     :macro
     (type ,x)))

(alt-type doc)
# =>
:macro

(alt-type print)
# =>
:cfunction

(alt-type pp)
# =>
:function

(alt-type 123)
# =>
:number

FWIW, I used macex1 [1] in the process of getting the above working (though there may be flaws -- I don't tend to write macros very much).

---

[1] For example, evaluating:

(macex1 '(alt-type doc))

gave something like:

(if (get (dyn (quote doc)) :macro)
  :macro
  (type doc))

[badiku]

at first I thought everything is a function, even operator is function.
but perhaps everything is a macro.
if something is not in the language, one can build it using a macro.
though macro is much difficult than function.
even expert like you can not be sure whether it works as expected

function is easy to extend, once your have a function f(x), then it is easy to get
another function g(f(x)).
but macro seem to be different. there are many quoting and unquoting, not that easy to extend

repl:268:> (defmacro deeptype [x] ~(if (get (dyn ',x) :macro) :macro (type ,x)) )
<function deeptype>
repl:269:> (deeptype doc)   
:macro   # this works 
    
repl:270:> (defmacro deeptype2 [x]  ~(deeptype ',x) )
<function deeptype2>
repl:271:> (deeptype2 doc)
:symbol   # this does not work



repl:296:> (defmacro == [x y] (
repl:297:((>     if (= x y)
repl:298:((>       (= (deeptype ',x)   (deeptype ',y) )
repl:299:((>       false))
<function ==>
    
repl:300:> (defn fa [] )
<function fa>
    
repl:301:>  (def fb fa)
<function fa>
    
repl:302:>  (= fa fb)
true
repl:303:> (==  fa fb)
false  # this does not work ,  should be true
    
repl:304:> (deeptype fa)
:function
repl:305:> (deeptype fb)
:function
    

[ianthehenry]

Some intuition that might help:

Values in Janet can't be macros -- as you can see, the "value" of a macro is just a function. "Macro-ness" is a property of a binding, not an intrinsic property of the function itself. If you think about macro expansion, this kinda makes sense -- the Janet compiler doesn't know the "value" of things deep inside a function at compile time, because the function isn't being called. It only acts on symbols, and there's basically a separate namespace of macros that it knows about.

The standard way to alias a binding is:

(setdyn 'doc2 (dyn 'doc))

If you don't want to write the quotes, you can use a macro like this:

(defmacro alias [dest src]
  ~(setdyn ',dest (dyn ',src)))

Notice that the quotes are in exactly the same place as they are in the un-macrofied version, we just replaced doc2 with ,dest and doc with ,src. But the quotes are not a property of macros, the quotes are there because the whole point of this macro is to automatically quote things for us.

Here's a simpler version:

(defmacro alias [dest src]
  (setdyn dest (dyn src))
  nil)

Instead of returning an AST to mutate the current environment, you can mutate the current environment at macro expansion time and then return nil.

---

(defmacro deeptype [x] ~(if (get (dyn ',x) :macro) :macro (type ,x)) )

You call this macro like this:

(deeptype doc)

That is, you don't quote doc explicitly. But in your deeptype2 macro:

(defmacro deeptype2 [x]  ~(deeptype ',x) )

You added a quote that you don't need. When you call this macro, it's like you're saying:

(deeptype 'doc)

Which gives you :symbol, because 'doc is a symbol, and there is no current environment entry called ['quote 'doc] (which is the AST that the macro sees). You can see this by using macex1 to debug:

repl:11:> (defmacro deeptype2 [x]  ~(deeptype ',x) )
<function deeptype2>
repl:12:> (macex '(deeptype2 doc))
(deeptype (quote doc))

The correct way to write that is:

(defmacro deeptype2 [x]  ~(deeptype ,x) )

i.e., it's exactly the same as the un-abstracted call, except with the parameter replaced.

[badiku]

if I understand correctly, macro is like "statement", macro "do something", and function "return something".

but how can I get the result of a macro in a function?

can this following function be possible :

(defmacro deeptype [x] ~(if (get (dyn ',x) :macro) :macro (type ,x)) )

(defn == [x y] (
    if (= x y)
        (= (deeptype x)  
           (deeptype y))
    false))



repl:377:>   (defn == [x y] (
repl:378:((>     if (= x y)
repl:379:((>         (= (deeptype x)
repl:380:(((>            (deeptype y))
repl:381:((>     false))
<function ==>
repl:382:>
repl:383:> (== doc doc2)
true     # need to be false

repl:384:> x
repl:384:1: compile error: unknown symbol x
    
repl:385:>   (defn == [x y] (
repl:386:((>     if (= x y)
repl:387:((>       (deeptype x)
repl:388:((>     false))
<function ==>
repl:389:> (== doc doc)
:function
   

because I think (= doc doc2) is somehow anti-intuition , they should not be equal and return false

it is a surprise. I try to see if I can check this surprise using a == function.

[ianthehenry]

if I understand correctly, macro is like "statement", macro "do something", and function "return something".

That's not really right -- a macro is a way to run code at compile time that returns new code that can run at runtime. Macros can be statement-y or expression-y, or they can just perform compile-time side effects and not return any interesting code to run at runtime.

The thing that you're looking for doesn't really make sense, because doc and doc2 are the same value. They're just different bindings. You can look at the binding of a symbol like this:

repl:1:> (dyn 'doc)
@{:doc "(doc &opt sym)\n\nShows documentation for the given symbol, or can show a list of available bindings.\nIf `sym` is a symbol, will look for documentation for that symbol. If `sym` is a string\nor is not provided, will show all lexical and dynamic bindings in the current environment\ncontaining that string (all bindings will be shown if no string is given)." :macro true :source-map ("boot.janet" 3522 1) :value <function doc>}

Notice that it has a docstring, a sourcemap, and a flag saying that it's a macro binding. But the :value is a function.

When you alias doc2 like this, you create a new environment entry:

repl:2:> (def doc2 doc)
<function doc>
repl:3:> (dyn 'doc2)
@{:source-map ("repl" 2 1) :value <function doc>}

With a different sourcemap, no docstring, and no macro flag. But the same value!

I think what you want to do is, basically, compare environment entries. Is only the "macro" metadata significant for your comparison? Or are two environment entries with different docstrings different as well? What about other metadata?

You can create an environment entry with any metadata you want:

repl:4:> (def doc3 {:custom-metadata 123} doc)
<function doc>
repl:5:> (dyn 'doc3)
@{:custom-metadata 123 :source-map ("repl" 4 1) :value <function doc>}

But all of these environment entries have the same value -- the only thing that Janet's = cares about. Consider:

repl:6:> (def x {:custom-metadata 123} 10)
10
repl:7:> (def y {:custom-metadata 456} 10)
10
repl:8:> (= x y)
true
repl:9:> (deep= (dyn 'x) (dyn 'y))
false

You can define an == function that compares different aspects of the environment entry. And you can wrap that in a macro so that you don't have to quote the symbols like I've been doing here. But it's... I think it's not clear why you would want to do this. doc and doc2 really are the same value!

[badiku]

same value, different binding... totally new concept, I need some time to get used to this.

thank you very much.