improved the manual of the GAP package JuliaInterface

[ThomasBreuer]

• added documentation for many GAP functions
• reordered some GAP code such that the ordering fits to the documentation
• added a few JuliaToGAP conversions (which were marked as "TODO")

[codecov]

Codecov Report

Merging #353 into master will decrease coverage by 0.06%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #353      +/-   ##
==========================================
- Coverage   76.65%   76.58%   -0.07%     
==========================================
  Files          62       61       -1     
  Lines        4467     4480      +13     
==========================================
+ Hits         3424     3431       +7     
- Misses       1043     1049       +6     

[fingolfin]

Looks good to me. Some minor comments; but I'd also be fine with merging this right now. We can fill in the TODOs and incomplete parts later, but it is already now a nice improvement. Thanks!

[fingolfin]

How about this (and similar in other exampels)

Suggested change

	#! <Example>
	#! gap> GAPToJulia( 1 );
	#! 1
	#! gap> GAPToJulia( JuliaEvalString( "Rational{Int64}" ), 1 );
	#! &lt;Julia: 1//1>
	#! gap> l:= [ 1, 3, 4 ];;
	#! gap> GAPToJulia( l );
	#! &lt;Julia: Any[1, 3, 4]>
	#! gap> GAPToJulia( JuliaEvalString( "Array{Int,1}" ), l );
	#! &lt;Julia: [1, 3, 4]>
	#! gap> m:= [ [ 1, 2 ], [ 3, 4 ] ];;
	#! gap> GAPToJulia( m );
	#! &lt;Julia: Any[Any[1, 2], Any[3, 4]]>
	#! gap> GAPToJulia( JuliaEvalString( "Array{Int,2}" ), m );
	#! &lt;Julia: [1 2; 3 4]>
	#! gap> r:= rec( a:= 1, b:= [ 1, 2, 3 ] );;
	#! gap> GAPToJulia( r );
	#! &lt;Julia: Dict{Symbol,Any}(:a => 1,:b => Any[1, 2, 3])>
	#! </Example>
	#! <Example><![CDATA[
	#! gap> GAPToJulia( 1 );
	#! 1
	#! gap> GAPToJulia( JuliaEvalString( "Rational{Int64}" ), 1 );
	#! <Julia: 1//1>
	#! gap> l:= [ 1, 3, 4 ];;
	#! gap> GAPToJulia( l );
	#! <Julia: Any[1, 3, 4]>
	#! gap> GAPToJulia( JuliaEvalString( "Array{Int,1}" ), l );
	#! <Julia: [1, 3, 4]>
	#! gap> m:= [ [ 1, 2 ], [ 3, 4 ] ];;
	#! gap> GAPToJulia( m );
	#! <Julia: Any[Any[1, 2], Any[3, 4]]>
	#! gap> GAPToJulia( JuliaEvalString( "Array{Int,2}" ), m );
	#! <Julia: [1 2; 3 4]>
	#! gap> r:= rec( a:= 1, b:= [ 1, 2, 3 ] );;
	#! gap> GAPToJulia( r );
	#! <Julia: Dict{Symbol,Any}(:a => 1,:b => Any[1, 2, 3])>
	#! ]]></Example>

[fingolfin]

Also: not (yet?) clear how to deal with recursive conversions that preserve identity. I.e. converting the GAP list [ ~ ] which contains itself, or something like [ "x", ~[1] ] which contains the same (identical) string twice. Of course for many applications this is irrelevant, but maybe not for some others.

That said, I absolutely think we should offer these constructors, but retain gap_to_julia (at least for now, as people are using it, and it has the above mentioned recursive feature)

[fingolfin]

We also want to be able to efficiently convert between GAP integers and fmpz. See also https://github.com/oscar-system/GAPGroups.jl/issues/3