Is there comprehensive documentation available for plurimath-js?

[gwhitney]

In particular, is there an api for directly building a formula object? I am thinking about converting from mathjs expression parse trees to plurimath formulas to replace the current awkward conversion into multiple formats with a single facility to output in any plurimath format. It would be nice to directly translate the one internal representation to the other rather than rendering the mathjs parse tree to say latex and then parsing that again into plurimath. But we'd need a good understanding of plurimath's internal format and exported functions to build up formula objects. I looked on the website but didn't see any comprehensive api documentation. If I missed it, please just direct me to the right place. If at the moment the documentation is just "read the source," then this issue report is to suggest that some documentation of this sort could be helpful.

[ronaldtse]

Thanks @gwhitney for the issue. Indeed documentation for plurimath-js is practically missing, and we should resolve that.

@suleman-uzair (sorry I know you're busy) could you help provide some basic information for @gwhitney to start working off with regarding the Formula object?

I imagine that we should:

• provide example code in both Ruby and JS on plurimath.org
• describe how to work with Formula objects
• how to input/output Formulas in math representation languages.

Question for @hmdne : what's the best way to manage documentation for Opal-ed JS code?

Thanks!

[hmdne]

While porting Plurimath, I treated the formula objects as implementation detail. Therefore, they are stored in a data instance variable of Plurimath object. There is no TypeScript definition for that though. The only interface available and fully supported is for conversion.

While I treated it as internal interface, it's not that it can't be accessed, but the interface will be just like the Ruby functions. For instance:

• Suppose a Plurimath::Document class constant. It can be accessed via Opal.Plurimath.Document.
• To call a method on a given object, let's say, Plurimath::Document.new, the method must be prefixed with a $ sign. Eg. Opal.Plurimath.Document.$new() (so, to create a new object, you don't use the new operator, but $new method).
• To use accessor methods, let's say document.encoding = "utf-8" or document.encoding, you can use respectively document["$encoding="]("utf-8") or document.$encoding(). Similarly, ? methods must be prefixed with $ (and since ? just like = is an invalid identifier character in JS, you must use array access).
• Overloaded methods, like a <=> b -> a["$<=>"](b)
• Attributes of types: String, Number, Array, Function, Boolean can be passed verbatim as arguments (same vice versa with returned values). nil is, in Javascript, Opal.nil
• Hash is mapped to Map (not plain JS object). So, let's say: document.parse(text, quiet: true) would become: document.$parse(text, new Map([["quiet", true]])) (note here that both Ruby String and Symbol are represented the same, as JavaScript string).
• Block passing is hard, but not impossible: obj.m(true) { |s| puts s } => Opal.send(obj, "m", [true], function(s) { console.log(s) })
• I hope I exhausted the most common usecases. This should allow use of all Ruby interfaces of Plurimath. Opal project has this interface documented further though: https://opalrb.com/docs/guides/v1.8.2/compiled_ruby.html

[gwhitney]

Hmm, as someone not familiar with Ruby this sounds like it could be a bit daunting; but anyhow, is there a documentation page for the Ruby interface to build up a formula object?

[suleman-uzair]

is there a documentation page for the Ruby interface to build up a formula object?

@gwhitney, The simple and basic understanding of Plurimath is explained in Using Plurimath. A list of types of classes is available at Plurimath support functions, These are the classes used in the Formula structure. Examples are provided in each of them, just copy an example and Parse it using Plurimath and you will have its Formula structure. For example, you can see the structure of the abs function following below method:

formula = Plurimath::Math.parse("abs(x)", :asciimath)
=> 
#<Plurimath::Math::Formula:0x0000000111e26cf8
 @displaystyle=true,
 @input_string="abs(x)",
 @left_right_wrapper=true,
 @value=[#<Plurimath::Math::Function::Abs:0x0000000111e1fc50 @parameter_one=#<Plurimath::Math::Symbols::Symbol:0x0000000111e0e040 @value="x">>]>

Feel free to let me know if you have any questions.

[hmdne]

@suleman-uzair

What I could suggest is adding documentation or examples to https://www.plurimath.org/functions/sum/ and other pages how to create an object like shown in the first post you linked:

Plurimath::Math::Formula.new([
  Plurimath::Math::Function::Sum.new(
    Plurimath::Math::Formula.new([
      Plurimath::Math::Symbol.new("i"),
      Plurimath::Math::Symbol.new("="),
      Plurimath::Math::Number.new("1")
    ]),
    Plurimath::Math::Symbol.new("n"),
    Plurimath::Math::Function::Power.new(
      Plurimath::Math::Symbol.new("i"),
      Plurimath::Math::Number.new("3")
    )
  )
])

Translated to JavaScript using the rules I described above, this would be:

Opal.Plurimath.Math.Formula.$new([
  Opal.Plurimath.Math.Function.Sum.$new(
    Opal.Plurimath.Math.Formula.$new([
      Opal.Plurimath.Math.Symbol.$new("i"),
      Opal.Plurimath.Math.Symbol.$new("="),
      Opal.Plurimath.Math.Number.$new("1")
    ]),
    Opal.Plurimath.Math.Symbol.$new("n"),
    Opal.Plurimath.Math.Function.Power.$new(
      Opal.Plurimath.Math.Symbol.$new("i"),
      Opal.Plurimath.Math.Number.$new("3")
    )
  )
])

[gwhitney]

Yes, this pointer and the latest example are very helpful, thanks.