add docs #17

capital-G · 2023-01-20T12:45:35Z

Some docs

Closes #2 by covering most of it

telephon

nice! Just a few small things

telephon · 2023-01-21T19:18:49Z

HelpSource/Classes/JSONlib.schelp

+## does not respect the types of a JSON but instead uses the type of String for every value
+::
+
+An encoder emphasis::simply:: needs to translate the SuperCollider scalars to the set of JSON scalars.


Do you only mean numbers? Booleans, arrays and sub-dictionaries also require translation, no?

thx, data types is probably more fitting

telephon · 2023-01-21T19:19:24Z

HelpSource/Classes/JSONlib.schelp

+Consult the source code on what kind of implicit conversions are made.
+These defaults can be overwritten and extended by providing a  code::customEncoder:: or code::customDecoder:: (see link::Classes/JSONlib#*new::).
+
+The type converion issue is a bit more difficult as it is not possible for us to recover the original types from the JSON explicitly.


telephon · 2023-01-21T19:20:19Z

HelpSource/Classes/JSONlib.schelp

+
+The type converion issue is a bit more difficult as it is not possible for us to recover the original types from the JSON explicitly.
+Was code::"42":: always a string or was it an link::Classes/Integer:: once that got converted by link::Classes/String#-parseJSON:: from an Integer to a link::Classes/String::?
+- so we decided to use implicit casting if the string matches a JSON representation other than String.


casting -> "assignment of an appropriate class ("casting")"

but explicit/implicit casting is a really common term :/

Yes, the word "casting" is never used in SuperCollider, just as "data type". You can take a look in the documentation. Why this is so is a complicated issue that I still try to understand better. I think the reason is this: in the Smalltalk lingo, these terms tend to be confusing, because where they originaly came from, they referred to parts of expressions (a type of a variable, whose data is casted to another variable of another type), and didn't refer to the objects themselves. Now one could argue that in Smalltalk, the type is in the object, but that is potentially misleading, because the object may change its behaviour in radical ways over its lifetime. Well, so much for that. I don't want to insist, we can fix later if you prefer.

HelpSource/Classes/JSONlib.schelp

telephon · 2023-01-21T19:25:42Z

HelpSource/Classes/JSONlib.schelp

+code::null:: is a special value in JSON which emphasis::represents the intentional absence of any object value.:: footnote::https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null::.
+
+SuperColliders equivalent would be link::Classes/Nil:: which gets implemented as an object via code::nil::.
+Yet it is not as easy as that because we can not store code::nil:: as a value in a link::Classes/Dictionary:: as this is the sclang syntax to delete a key-value pair within a dictionary.


as this is the sclang syntax to delete a key-value pair within a dictionary.
->
because nil represents the return value for an empty slot and code::put(key, nil):: is equivalent to removing the object at code::key::.

nice gh conversion :)

telephon · 2023-01-21T19:31:09Z

HelpSource/Classes/JSONlib.schelp

+argument:: customEncoder
+Using a custom encoder allows to specify the encoding an abitrary object into its JSON representation.
+To introduce a custom encoding (e.g. link::Classes/Point:: or link::Classes/Function::) simply provide a function which accepts the object as a first argument and return a non-code::nil:: value if it a custom representation should be used.
+


value if it a custom representation should be used.
->
value if this custom representation should be used. Otherwise, it will be encoded as usual.

telephon · 2023-01-21T19:31:43Z

HelpSource/Classes/JSONlib.schelp

+(
+f = {|object|
+	if(object.class == Point, {
+		[object.x, object.y];


you can drop the colons

yeah, but I prefer to have semicolons everywhere

ok, but then also write [object.x, object.y, ]; :)

Nah, ; is commonly used to terminate a statement, , is used to separate elements :)

so yes, ok if that looks better to you, let's keep this convention in this quark.

telephon · 2023-01-21T19:34:26Z

HelpSource/Classes/JSONlib.schelp

+
+argument:: string
+JSON string one wants to parse.
+Have in mind that any code::":: needs to be escaped with code::\"::, so at least every key needs this.


Have -> Keep

telephon · 2023-01-21T19:37:56Z

HelpSource/Classes/JSONlib.schelp

+j = JSONlib.convertToJSON(e);
+
+// save JSON string on disk as .json file
+(


alternatively:
File.use("~/foo.json".standardizePath, "w", { |f| f.write(j) })

To me this seems more implicit as I have to guess that the provided function is a callback which is called when the file has been opened successfully - and this is where I have to look into the docs. Also to me the .write is more in line with other languages.

ok. use has a protect built in so that it doesn't leave open files when something fails.

BTW, there is a really great concept for this in Python, context managers https://realpython.com/python-with-statement/

HelpSource/Classes/JSONlib.schelp

capital-G

Thx for the really necessary review. Please take a look again if its ok and if so please merge :)

capital-G · 2023-01-21T21:23:52Z

HelpSource/Classes/JSONlib.schelp

+## does not respect the types of a JSON but instead uses the type of String for every value
+::
+
+An encoder emphasis::simply:: needs to translate the SuperCollider scalars to the set of JSON scalars.


thx, data types is probably more fitting

capital-G · 2023-01-21T21:27:18Z

HelpSource/Classes/JSONlib.schelp

+
+The type converion issue is a bit more difficult as it is not possible for us to recover the original types from the JSON explicitly.
+Was code::"42":: always a string or was it an link::Classes/Integer:: once that got converted by link::Classes/String#-parseJSON:: from an Integer to a link::Classes/String::?
+- so we decided to use implicit casting if the string matches a JSON representation other than String.


but explicit/implicit casting is a really common term :/

capital-G · 2023-01-21T21:30:37Z

HelpSource/Classes/JSONlib.schelp

+code::null:: is a special value in JSON which emphasis::represents the intentional absence of any object value.:: footnote::https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null::.
+
+SuperColliders equivalent would be link::Classes/Nil:: which gets implemented as an object via code::nil::.
+Yet it is not as easy as that because we can not store code::nil:: as a value in a link::Classes/Dictionary:: as this is the sclang syntax to delete a key-value pair within a dictionary.


nice gh conversion :)

capital-G · 2023-01-21T21:31:29Z

HelpSource/Classes/JSONlib.schelp

+e[\foo].value
+// -> nil
+
+// you can also use .value on other scalars


switched to data types

capital-G · 2023-01-21T21:36:16Z

HelpSource/Classes/JSONlib.schelp

+(
+f = {|object|
+	if(object.class == Point, {
+		[object.x, object.y];


yeah, but I prefer to have semicolons everywhere

capital-G · 2023-01-21T21:39:42Z

HelpSource/Classes/JSONlib.schelp

+j = JSONlib.convertToJSON(e);
+
+// save JSON string on disk as .json file
+(


To me this seems more implicit as I have to guess that the provided function is a callback which is called when the file has been opened successfully - and this is where I have to look into the docs. Also to me the .write is more in line with other languages.

telephon · 2023-01-22T11:03:43Z

HelpSource/Classes/JSONlib.schelp

+
+The type converion issue is a bit more difficult as it is not possible for us to recover the original types from the JSON explicitly.
+Was code::"42":: always a string or was it an link::Classes/Integer:: once that got converted by link::Classes/String#-parseJSON:: from an Integer to a link::Classes/String::?
+- so we decided to use implicit casting if the string matches a JSON representation other than String.


Yes, the word "casting" is never used in SuperCollider, just as "data type". You can take a look in the documentation. Why this is so is a complicated issue that I still try to understand better. I think the reason is this: in the Smalltalk lingo, these terms tend to be confusing, because where they originaly came from, they referred to parts of expressions (a type of a variable, whose data is casted to another variable of another type), and didn't refer to the objects themselves. Now one could argue that in Smalltalk, the type is in the object, but that is potentially misleading, because the object may change its behaviour in radical ways over its lifetime. Well, so much for that. I don't want to insist, we can fix later if you prefer.

capital-G added 2 commits January 20, 2023 13:43

add docs

5e26709

add empty line at end of file

07619f5

capital-G requested a review from telephon January 20, 2023 12:45

capital-G linked an issue Jan 20, 2023 that may be closed by this pull request

Write documentation #2

Closed

6 tasks

telephon reviewed Jan 21, 2023

View reviewed changes

improve language

7ef5073

capital-G commented Jan 21, 2023

View reviewed changes

capital-G requested a review from telephon January 21, 2023 21:49

telephon approved these changes Jan 22, 2023

View reviewed changes

minor fixes

cb7423a

capital-G merged commit cf03e5d into main Jan 23, 2023

capital-G deleted the 2-write-documentation branch January 23, 2023 16:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add docs #17

add docs #17

capital-G commented Jan 20, 2023

telephon left a comment

telephon Jan 21, 2023

capital-G Jan 21, 2023

telephon Jan 21, 2023

telephon Jan 21, 2023

capital-G Jan 21, 2023

telephon Jan 22, 2023 •

edited

Loading

telephon Jan 21, 2023

capital-G Jan 21, 2023

telephon Jan 22, 2023

telephon Jan 21, 2023

telephon Jan 21, 2023

capital-G Jan 21, 2023

telephon Jan 22, 2023

capital-G Jan 22, 2023

telephon Jan 22, 2023

telephon Jan 21, 2023

telephon Jan 21, 2023

capital-G Jan 21, 2023

telephon Jan 22, 2023

capital-G Jan 23, 2023

capital-G left a comment

capital-G Jan 21, 2023

capital-G Jan 21, 2023

capital-G Jan 21, 2023

capital-G Jan 21, 2023

capital-G Jan 21, 2023

capital-G Jan 21, 2023

telephon Jan 22, 2023 •

edited

Loading

add docs #17

add docs #17

Conversation

capital-G commented Jan 20, 2023

telephon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

telephon Jan 22, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

capital-G left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

telephon Jan 22, 2023 • edited Loading

Choose a reason for hiding this comment

telephon Jan 22, 2023 •

edited

Loading

telephon Jan 22, 2023 •

edited

Loading