api in json format

classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|

api in json format

runsun
Hi guys, I'm recently exploring the customization ability of editor SynWrite, especially the python feature (py api) as well as event handlers. I am very close to write up a plugin that can do function parameter hint, like if you type:

cube(

then the log panel or output panel shows you the argument definition.

At this point, a file with function/module in json format will be needed. With that I can just load it into python.

I can picture that such a file will be very useful as a source for other formats of help documentation to fulfill the single-source documentation we've been talking for a while.

I believe we don't have such a file yet. So shall we start one here, like what key/value pairs should be included ?

$ Runsun Pan, PhD
$ libs: scadx, doctest, faces(git), offline doc(git), runscad.py(2,git), editor of choice: CudaText ( OpenSCAD lexer); $ Tips; $ Snippets
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

runsun
Something like:
{
   <unit_name>:
   
      { "type": <mod|func>
      , "tags": <math|operation| ... >
      , "args": { <arg1>: { "val": <val>, "doc":"..." }
                , <arg1>: { "val": <val>, "doc":"..." }
                , ...
                }
      , "short_doc": "..."
      , "long_doc": "..."
      }                      
}
$ Runsun Pan, PhD
$ libs: scadx, doctest, faces(git), offline doc(git), runscad.py(2,git), editor of choice: CudaText ( OpenSCAD lexer); $ Tips; $ Snippets
tp3
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

tp3
In reply to this post by runsun
On 01/02/2016 07:13 PM, runsun wrote:
> I believe we don't have such a file yet. So shall we start one here, like
> what key/value pairs should be included ?
>
I'm not aware of any existing file.

Yes, it would be useful for a number of other cases too, like as input
for https://github.com/openscad/openscad/pull/905 and maybe also for the
cheatsheet.

Some additional data that could be included:

* general
  - version of the description file itself
  - version of OpenSCAD the description refers to

* function/module
  - link to manual

* parameters
  - data type of parameter
  - mandatory / optional parameter

There's also another option, but that's probably too much work for the
short term... add the information to the code itself and let OpenSCAD
generate that info via some special command line switch.

ciao,
  Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

MichaelAtOz
Administrator
Need to consider how the r= r1= r2= d= d1= d2= options would be handled.
Also the positional parameters are somewhat non-intuative sometimes, BTW.
Admin - email* me if you need anything,
or if I've done something stupid...
* click on my MichaelAtOz label, there is a link to email me.

Unless specifically shown otherwise above, my contribution is in the Public Domain; to the extent possible under law, I have waived all copyright and related or neighbouring rights to this work.
Obviously inclusion of works of previous authors is not included in the above.


The TPP is no simple “trade agreement.” Fight it! http://www.ourfairdeal.org/ time is running out!
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

runsun
Thx for the inputs. Will take into considerations.

The journey into SynWrite calltip feature looks promising. I've made this possible: when user type "cube(", the output panel will show it's parameter definition:



I'm still working on how this is gonna play out, but most likely, once it's done, users can have this feature by simply import a python plugin.

Here is the current json structure that I am using. Currently it has only cube() and sphere(). Will keep modifying the structure along the way.

common_args={
  "$fa": { "name": "$fa"
         , "type": "num"
         , "optional": "true"
         , "default":12
         , "doc" :
            [ "Special variable controlling the minimum angle for a fragment. Even a huge circle does not have more fragments than 360 divided by this number. The default value is 12 (i.e. 30 fragments for a full circle). The minimum allowed value is 0.01. Any attempt to set a lower value will cause a warning."
            ]
         }  
 , "$fs": { "name": "$fs"
         , "type": "num"
         , "optional": "true"
         , "default":2
         , "doc" :
            [ "Special variable controlling the minimum size of a fragment. Because of this variable very small circles have a smaller number of fragments than specified using $fa. The default value is 2. The minimum allowed value is 0.01. Any attempt to set a lower value will cause a warning."
            ]
         }  
 , "$fn": { "name": "$fn"
         , "type": "num"
         , "optional": "true"
         , "default": 0
         , "doc" :
            [ "Special variable controlling the number of fragments. Usually 0. When this variable has a value greater than zero, the other two variables are ignored and full circle is rendered using this number of fragments. The default value is 0."
            ]
         }    
}      
     
openscad_api={

  "cube":

  { "type": "mod"
  , "tags": "obj, 3d"
  , "args":
    [
         { "name": "size"
         , "type": "list|num"
         , "optional": "true"
         , "default": [1,1,1]
         , "doc" :
            [ "single value, cube with all sides this length"
            , "3 value array [x,y,z], cube with dimensions x,y,z"
            ]
         }          
      ,  { "name": "center"
         , "type": "bool"
         , "optional":"true"
         , "default": "false"
         , "doc" :
            [ "false: 1st (positive) octant, one corner at (0,0,0)"
            , "true: cube is centered at (0,0,0)"
            ]
         }
    ]
  , "return": ""  
  , "shortdoc": "Creates a cube in the first octant. When center is true, the cube is centered on the origin"
  , "longddoc":""
  , "ver":""  
  , "demo":[]  
  }  
 
  , "sphere":
 
  { "type": "mod"
  , "tags": "obj, 3d"
  , "args":
    [
         { "name": "r"
         , "type": "num"
         , "optional": "true"
         , "default": 1
         , "doc" :
            [ "Radius of the sphere"
            ]
         }          
      ,  { "name": "d"
         , "type": "num"
         , "optional":"true"
         , "doc" :
            [ "Diameter of the sphere. Available in ver >= 2014.03"
            ]
         }
      ,  common_args["$fa"]
      ,  common_args["$fs"]
      ,  common_args["$fn"]

    ]
  , "return": ""  
  , "shortdoc": "Creates a sphere at the origin of the coordinate system"
  , "longddoc":""
  , "ver":""  
  , "demo":[]  
  }                  
}
It's currently written inside the python on_key plugin. Eventually it has to be a stand-alone json file.


 

$ Runsun Pan, PhD
$ libs: scadx, doctest, faces(git), offline doc(git), runscad.py(2,git), editor of choice: CudaText ( OpenSCAD lexer); $ Tips; $ Snippets
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

Neon22
Maybe each function could have a doc method which had this json in it.
This way if users made their own includable scad files they would also be self documenting.

E.g. in python the first line of a function is optionally reserved for a doc string.
def foo():
  " what foo does"
  code...

maybe module foo() "doc string" {
};

Doug - what do you think is right thing to do for openSCAD2 ?
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

doug.moen
This is in response to Neon22's suggestion for a language extension, to add a doc string to function and module definitions.

The "Customizer GUI" project is already defining a syntax for adding a doc string to variable definitions. Check out this example: https://github.com/openscad/openscad/blob/model-meta-data3/examples/Parametric/sign.scad

Following that example, the syntax would be

@Description("doc string")
module foo() {
};

This syntax works fine with OpenSCAD2.

This opens up the question of whether we want to add a syntax for adding doc strings and type annotations to each parameter of a function or module definition.

Type annotations in particular are a big can of worms, especially if you want them to be accurate, given the way some primitive functions and modules are designed. How would you specify the type of 'min'? The arguments are either a variable number of numeric arguments, or a single argument which is a list of numbers. Up to this point, I've considered that adding type annotations to OpenSCAD is not worth it, given the complexity of the type language we'd need.

On 4 January 2016 at 00:49, Neon22 <[hidden email]> wrote:
Maybe each function could have a doc method which had this json in it.
This way if users made their own includable scad files they would also be
self documenting.

E.g. in python the first line of a function is optionally reserved for a doc
string.
def foo():
  " what foo does"
  code...

maybe module foo() "doc string" {
};

Doug - what do you think is right thing to do for openSCAD2 ?



--
View this message in context: http://forum.openscad.org/api-in-json-format-tp15418p15460.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org




_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

runsun
doug.moen wrote
The "Customizer GUI" project is already defining a syntax for adding a doc
string to variable definitions. Check out this example:
https://github.com/openscad/openscad/blob/model-meta-data3/examples/Parametric/sign.scad
That's pretty cool. What is the meaning of

@Parameter([10, 20, 30, 50, 100])

Does it mean only the listed values are allowed ?

Type annotations in particular are a big can of worms, especially if you
want them to be accurate, given the way some primitive functions and
modules are designed. How would you specify the type of 'min'? The
arguments are either a variable number of numeric arguments, or a single
argument which is a list of numbers. Up to this point, I've considered that
adding type annotations to OpenSCAD is not worth it, given the complexity
of the type language we'd need.
How about this:

@type("int")
 
@type("number", "list")

In the api that I wrote in previous post, I use:

  { "name": "size"
  ,  "type": "list|num"
  , "optional": "true"
  , "default": [1,1,1]
  }
to indicate that both list and number are allowed.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
$ Runsun Pan, PhD
$ libs: scadx, doctest, faces(git), offline doc(git), runscad.py(2,git), editor of choice: CudaText ( OpenSCAD lexer); $ Tips; $ Snippets
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

doug.moen
In order for an IDE editor to reliably show you hints about the names and types of parameters, you need a strongly typed language, and you need the IDE to parse and compile the code being edited in order to collect type information for functions you might be calling. OpenSCAD isn't designed to be a strongly typed language, so I'm not optimistic about this kind of project succeeding.

If your only goal is to present information about built-in functions and modules, and you don't worry about presenting hints for functions and modules that are locally defined, or defined via include <f> or use <f>, then the problem is much easier. In this case, we don't need type annotations in the language at all.

In OpenSCAD2, the problem gets harder, because objects are first class values, and you can write obj.f(x). So the IDE needs to know the type of 'obj', which could be passed as a parameter, or returned as a result from another function call.

On 4 January 2016 at 09:40, runsun <[hidden email]> wrote:
doug.moen wrote
> The "Customizer GUI" project is already defining a syntax for adding a doc
> string to variable definitions. Check out this example:
> https://github.com/openscad/openscad/blob/model-meta-data3/examples/Parametric/sign.scad

That's pretty cool. What is the meaning of

@Parameter([10, 20, 30, 50, 100])

Does it mean only the listed values are allowed ?


> Type annotations in particular are a big can of worms, especially if you
> want them to be accurate, given the way some primitive functions and
> modules are designed. How would you specify the type of 'min'? The
> arguments are either a variable number of numeric arguments, or a single
> argument which is a list of numbers. Up to this point, I've considered
> that
> adding type annotations to OpenSCAD is not worth it, given the complexity
> of the type language we'd need.

How about this:

@type("int")

@type("number", "list")

In the api that I wrote in previous post, I use:


>   { "name": "size"
>   ,  "type": "list|num"
>   , "optional": "true"
>   , "default": [1,1,1]
>   }

to indicate that both list and number are allowed.


_______________________________________________
OpenSCAD mailing list
Discuss@.openscad
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org




-----

$  Runsun Pan, PhD

$ libs:

doctest ,

faces ( git ),

offline doc ( git ),

runscad.py( 1 , 2 , git ),


synwrite( 1 , 2 );



 $ tips:

hash( 1 , 2 ),

sweep ,

var( 1 , 2 ),

lerp ,

animGif ,

precision( 1 , 2 ),

xl-control








--
View this message in context: http://forum.openscad.org/api-in-json-format-tp15418p15468.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org




_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

Alan Cox
On Mon, 4 Jan 2016 10:04:51 -0500
doug moen <[hidden email]> wrote:

> In order for an IDE editor to reliably show you hints about the names and
> types of parameters, you need a strongly typed language, and you need the
> IDE to parse and compile the code being edited in order to collect type
> information for functions you might be calling. OpenSCAD isn't designed to
> be a strongly typed language, so I'm not optimistic about this kind of
> project succeeding.

That's an "or" not an "and" I think you'll find.

If you have the parse tree you know the set of valid types for any given
parameter and the resulting returned type. That may be quite a long list
and you may need to sort it by interest or represent it cleverly.

Alan

_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

runsun
This post was updated on .
In reply to this post by doug.moen
@doug, I kind of getting lost about what you said. But, that's ok.  

Don't know if this is helpful but I've been using type inspection, type casting etc in my lib for quite a while:
 type ( x )=str ( tested:18 ) (mode:12)
------------------------------------------------
| 0> type([2, 3])= "arr"
| 1> type([])= "arr"
| 2> type(-4)= "int"
| 3> type(0)= "int"
| 4> type(0.3)= "float"
| 5> type(-0.3)= "float"
| 6> type(2e-6)= "float"
| 7> type(2e3)= "int"
| 8> type(2e-06)= "float"
| 9> type(2e+03)= "int"
| 10> type("a")= "str"
| 11> type("10")= "str"
| 12> type(true)= "bool"
| 13> type(false)= "bool"
| 14> type([1:2:10])= "range" // New 2015.9.10
| 15> type([1:1.5:10])= "range" // New 2015.9.10
| 16> type(undef)= undef
| 17> type(12345678901234500)= "int" // Bugfix 2015.11.17
The type-checking has been a very crucial part of my lib, even geometric stuff like points, lines and planes can be type-checked:
gtype ( x,dim=3 ) =str ( tested:9 ) (mode:12)
------------------------------------------------
| 0> gtype(P)= "pt"
| 1> gtype([P,Q])= "ln"
| 2> gtype([P,Q,R])= "pl"
| 3> gtype("a")= undef
| 4> gtype([P,Q,R,P])= undef
| 5> gtype([[P,Q],1])= "cir"
| 6> gtype([2,[P,Q]])= "cir"
| 7> gtype([P,1])= "ball"
| 8> gtype([0.5,P])= "ball"
$ Runsun Pan, PhD
$ libs: scadx, doctest, faces(git), offline doc(git), runscad.py(2,git), editor of choice: CudaText ( OpenSCAD lexer); $ Tips; $ Snippets
tp3
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

tp3
In reply to this post by runsun
On 01/04/2016 03:40 PM, runsun wrote:
> That's pretty cool. What is the meaning of
>
> @Parameter([10, 20, 30, 50, 100])
>
> Does it mean only the listed values are allowed ?
>
Yes, this is basically the basis for modeling the functionality
that the Thingiverse Customizer provides by adding comments to the
scad script.
See the github comment for short example screencasts
https://github.com/openscad/openscad/issues/722#issuecomment-69521189

The meta data definition would allow a long list of other
use-cases, not only the customizer parameter specification.
I've started to collect some of the use cases for different
types of annotations in the wiki:
https://github.com/openscad/openscad/wiki/Meta-Data-Use-Cases

The prototype implementation in branch model-meta-data3 uses
the Java Annotation like syntax as shown above, if it would
make things easier for other cases (e.g. OpenSCAD2) it should
be quite simple to use a different syntax...

ciao,
  Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
tp3
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

tp3
In reply to this post by Neon22
On 01/04/2016 06:49 AM, Neon22 wrote:
> maybe module foo() "doc string" {
> };
>
> Doug - what do you think is right thing to do for openSCAD2 ?
>
I think that would be possible with current OpenSCAD too, it
would simply require all *new* code that uses it to use the new
OpenSCAD version - which is pretty normal.

It seems to be some kind of convention to use triple " to mark
the docstring, so maybe that would make sense here too.
I guess the idea with that is to allow various markup in that
section, including the use of normal single quotes.

Although for current OpenSCAD, that would probably just allow
the syntax as we have no way for introspection or setting some
object field to make it available at runtime (some simple
solution like a docstring() function returning the doc of the
current module could be added, but I'm not sure that's very
useful).

It still would define a standard way for adding documentation,
which is a good thing to have. It might even allow to use
documentation generation tools like Sphinx to run on OpenSCAD
code.

ciao,
  Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

doug.moen
Hi Torsten.

Sphinx is specifically designed for Python, so it requires the python """ string literal syntax, as you have noted. We'd have to extend the OpenSCAD syntax to make it Sphinx compatible.

Or we could use Doxygen, which should work with OpenSCAD right now, with no language extensions, since Doxygen was designed for C++, and embeds documentation in C++ comments, which comment syntax is also supported by OpenSCAD.

Sphinx uses ReStructuredText as its text markup language: RST is mostly only used by the Python community. Doxygen uses MarkDown, which will be familiar to a lot of OpenSCAD developers since github also uses MarkDown. In fact, Doxygen will even process the README.md file at the root of your project tree, which is also processed by github.

So I think doxygen is a better starting point for an OpenSCAD inline documentation tool.

On 4 January 2016 at 11:25, Torsten Paul <[hidden email]> wrote:
On 01/04/2016 06:49 AM, Neon22 wrote:
> maybe module foo() "doc string" {
> };
>
> Doug - what do you think is right thing to do for openSCAD2 ?
>
I think that would be possible with current OpenSCAD too, it
would simply require all *new* code that uses it to use the new
OpenSCAD version - which is pretty normal.

It seems to be some kind of convention to use triple " to mark
the docstring, so maybe that would make sense here too.
I guess the idea with that is to allow various markup in that
section, including the use of normal single quotes.

Although for current OpenSCAD, that would probably just allow
the syntax as we have no way for introspection or setting some
object field to make it available at runtime (some simple
solution like a docstring() function returning the doc of the
current module could be added, but I'm not sure that's very
useful).

It still would define a standard way for adding documentation,
which is a good thing to have. It might even allow to use
documentation generation tools like Sphinx to run on OpenSCAD
code.

ciao,
  Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org




_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
tp3
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

tp3
On 01/04/2016 08:00 PM, doug moen wrote:
> Sphinx is specifically designed for Python, so it requires the
> python """ string literal syntax, as you have noted. We'd have
> to extend the OpenSCAD syntax to make it Sphinx compatible.
>
Yes, it might need extensions, it's not just for Python though.
The Website claims: "...but C/C++ is already supported as well,
and it is planned to add special support for other languages as
well." so it might not be too complicated to have it handle
OpenSCAD as well.

But yes, it's just an example. If there's a different tool that
maybe just needs some configuration or so, that's perfect.

> So I think doxygen is a better starting point for an OpenSCAD
> inline documentation tool.
>
Cool, why not. I guess MarkDown is a good option. I don't like
that it's not going to be standardized, but it's wide adoption
still makes it a sensible choice.

ciao,
  Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
Reply | Threaded
Open this post in threaded view
|

Re: api in json format

doug.moen
I know the Sphinx documentation claims C++ support, but this is done by invoking Doxygen via Breathe. http://breathe.readthedocs.org/en/latest/

On 4 January 2016 at 14:19, Torsten Paul <[hidden email]> wrote:
On 01/04/2016 08:00 PM, doug moen wrote:
> Sphinx is specifically designed for Python, so it requires the
> python """ string literal syntax, as you have noted. We'd have
> to extend the OpenSCAD syntax to make it Sphinx compatible.
>
Yes, it might need extensions, it's not just for Python though.
The Website claims: "...but C/C++ is already supported as well,
and it is planned to add special support for other languages as
well." so it might not be too complicated to have it handle
OpenSCAD as well.

But yes, it's just an example. If there's a different tool that
maybe just needs some configuration or so, that's perfect.

> So I think doxygen is a better starting point for an OpenSCAD
> inline documentation tool.
>
Cool, why not. I guess MarkDown is a good option. I don't like
that it's not going to be standardized, but it's wide adoption
still makes it a sensible choice.

ciao,
  Torsten.


_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org




_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org