api in json format
Hi guys, I'm recently exploring the customization ability of editor SynWrite
http://forum.openscad.org/Happy-New-Year-OpenSCAD-syntax-lexer-for-SynWrite-td15402.html
, 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:
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-tp15418.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
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:
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-tp15418p15419.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
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.
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.
Newly minted Admin - PM me if you need anything, or if I've done something stupid...
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!
View this message in context: http://forum.openscad.org/api-in-json-format-tp15418p15422.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
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:
http://forum.openscad.org/file/n15457/synwrite_calltip.png
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:
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-tp15418p15457.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
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.
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 mschafer@wireframe.biz 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
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
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.
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 runsun@gmail.com 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
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
On Mon, 4 Jan 2016 10:04:51 -0500
doug moen doug@moens.org 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