Skip to content

Commit

Permalink
Some simplifications in the documentation of some operators
Browse files Browse the repository at this point in the history
  • Loading branch information
@benoitgaudou
benoitgaudou committed Aug 21, 2020
1 parent 03f3aab commit d496589
Show file tree
Hide file tree
Showing 7 changed files with 29 additions and 88 deletions.
18 changes: 5 additions & 13 deletions msi.gama.core/src/msi/gama/util/IContainer.java
View file
Expand Up @@ -363,17 +363,8 @@ default void addValues(final IScope scope, final IContainer<?, ?> values) {
equals = "1, 2 or 3",
returnType = IKeyword.INT,
test = false),
@example (
value = "[1,2,3] contains i",
returnType = IKeyword.BOOL,
equals = "true",
isTestOnly = true),
@example ("string sMat <- one_of(matrix([[\"c11\",\"c12\",\"c13\"],[\"c21\",\"c22\",\"c23\"]])); // sMat equals \"c11\",\"c12\",\"c13\", \"c21\",\"c22\" or \"c23\""),
@example (
value = "matrix([[\"c11\",\"c12\",\"c13\"],[\"c21\",\"c22\",\"c23\"]]) contains sMat",
returnType = IKeyword.BOOL,
equals = "true",
isTestOnly = true) }),
}),
@usage (
value = "if it is a map, one_of returns one the value of a random pair of the map",
examples = { @example ("int im <- one_of ([2::3, 4::5, 6::7]); // im equals 3, 5 or 7"),
Expand All @@ -387,14 +378,15 @@ default void addValues(final IScope scope, final IContainer<?, ?> values) {
value = "if it is a file, one_of returns one of the elements of the content of the file (that is also a container)"),
@usage (
value = "if it is a population, one_of returns one of the agents of the population",
examples = { @example (
value = "agent b <- one_of(agents);",
isTestOnly = true),
examples = {
@example (
value = "bug b <- one_of(bug); // Given a previously defined species bug, b is one of the created bugs, e.g. bug3",
isExecutable = false) }) },
see = { "contains" })
@test("one_of([]) = nil")
@test("int i <- any([1,2,3]); [1,2,3] contains i")
@test("string sMat <- one_of(matrix([[\"c11\",\"c12\",\"c13\"],[\"c21\",\"c22\",\"c23\"]])); matrix([[\"c11\",\"c12\",\"c13\"],[\"c21\",\"c22\",\"c23\"]]) contains sMat")
@test("agent b <- one_of(agents);")
ValueType anyValue(IScope scope);

}
20 changes: 5 additions & 15 deletions msi.gama.core/src/msi/gaml/operators/Cast.java
View file
Expand Up @@ -372,30 +372,15 @@ public static ISpecies asSpecies(final IScope scope, final Object val) throws Ga
@example (
value = "to_gaml(3.78)",
equals = "'3.78'"),
@example (
value = "to_gaml(true)",
equals = "'true'", isTestOnly = true),
@example (
value = "to_gaml({23, 4.0})",
equals = "'{23.0,4.0,0.0}'"),
@example (
value = "to_gaml(5::34)",
equals = "'5::34'", isTestOnly = true),
@example (
value = "to_gaml(rgb(255,0,125))",
equals = "'rgb (255, 0, 125,255)'"),
@example (
value = "to_gaml('hello')",
equals = "\"'hello'\""),
@example (
value = "to_gaml([1,5,9,3])",
equals = "'[1,5,9,3]'", isTestOnly = true),
@example (
value = "to_gaml(['a'::345, 'b'::13, 'c'::12])",
equals = "\"map([\'a\'::345,\'b\'::13,\'c\'::12])\"", isTestOnly = true),
@example (
value = "to_gaml([[3,5,7,9],[2,4,6,8]])",
equals = "'[[3,5,7,9],[2,4,6,8]]'", isTestOnly = true),
@example (
value = "to_gaml(a_graph)",
equals = "([((1 as node)::(3 as node))::(5 as edge),((0 as node)::(3 as node))::(3 as edge),((1 as node)::(2 as node))::(1 as edge),((0 as node)::(2 as node))::(2 as edge),((0 as node)::(1 as node))::(0 as edge),((2 as node)::(3 as node))::(4 as edge)] as map ) as graph",
Expand All @@ -405,6 +390,11 @@ public static ISpecies asSpecies(final IScope scope, final Object val) throws Ga
equals = " 1 as node",
isExecutable = false) },
see = {})
@test("to_gaml(true) = 'true'")
@test("to_gaml(5::34) = '5::34'")
@test("to_gaml([1,5,9,3]) = '[1,5,9,3]'")
@test("to_gaml(['a'::345, 'b'::13, 'c'::12]) = \"map([\'a\'::345,\'b\'::13,\'c\'::12])\"")
@test("to_gaml([[3,5,7,9],[2,4,6,8]]) = '[[3,5,7,9],[2,4,6,8]]'")
public static String toGaml(final Object val) {
return StringUtils.toGaml(val, false);
}
Expand Down
21 changes: 3 additions & 18 deletions msi.gama.core/src/msi/gaml/operators/Colors.java
View file
Expand Up @@ -247,12 +247,7 @@ public static GamaColor rgb(final int r, final int g, final int b) {
examples = { @example (
value = "rgb (255,0,0,125)",
equals = "a light red color",
test = false),
@example (
value = "rgb (255,0,0,125).alpha",
equals = "125",
returnType = IKeyword.INT,
isTestOnly = true) },
test = false) },
see = "hsb")
@test ("rgb (255,0,0,125).alpha = 125")
public static GamaColor rgb(final int r, final int g, final int b, final int alpha) {
Expand Down Expand Up @@ -342,12 +337,10 @@ public static GamaColor rgb(final IScope scope, final GamaColor s, final double
value = "grayscale (rgb(255,0,0))",
equals = "to a dark grey",
isExecutable = false),
@example (
value = "grayscale (rgb(255,0,0))",
equals = "rgb(76,76,76)",
isTestOnly = true) },
},
see = { "rgb", "hsb" })
@test ("int(grayscale (rgb(255,0,0))) = -11776948")
@test("grayscale (rgb(255,0,0)) = rgb(76,76,76)")
public static GamaColor grayscale(final GamaColor c) {
final int grayValue = (int) (0.299 * c.getRed() + 0.587 * c.getGreen() + 0.114 * c.getBlue());
return new GamaColor(grayValue, grayValue, grayValue, c.getAlpha());
Expand Down Expand Up @@ -402,10 +395,6 @@ public static GamaColor random_color(final IScope scope, final Integer min, fina
value = "Blend two colors with an optional ratio (c1 `*` r + c2 `*` (1 - r)) between 0 and 1",
masterDoc = true,
examples = { @example (
value = "blend(#red, #blue, 0.3)",
equals = "rgb(76,0,178)",
isTestOnly = true),
@example (
value = "blend(#red, #blue, 0.3)",
equals = "to a color between the purple and the blue",
isExecutable = false) },
Expand All @@ -427,10 +416,6 @@ public static GamaColor blend(final GamaColor c1, final GamaColor c2, final doub
usages = @usage (
value = "If the ratio is omitted, an even blend is done",
examples = { @example (
value = "blend(#red, #blue)",
equals = "rgb(127,0,127)",
isTestOnly = true),
@example (
value = "blend(#red, #blue)",
equals = "to a color very close to the purple",
isExecutable = false) }),
Expand Down
8 changes: 4 additions & 4 deletions msi.gama.core/src/msi/gaml/operators/Containers.java
View file
Expand Up @@ -1146,13 +1146,13 @@ public static IMap group_by(final IScope scope, final IContainer c, final IExpre
equals = "(5::6)") }) },
examples = { @example (
value = "[1,2,3,4,5,6,7,8] last_with (each > 3)",
equals = "8"),
equals = "8", returnType = IKeyword.INT),
@example (
value = "graph g2 <- graph([]);",
isTestOnly = true),
@example (
value = "g2 last_with (length(g2 out_edges_of each) = 0 )",
equals = "node11",
equals = "a node",
isExecutable = false),
@example (
value = "(list(node) last_with (round(node(each).location.x) > 32)",
Expand Down Expand Up @@ -1180,10 +1180,10 @@ public static Object last_with(final IScope scope, final IContainer c, final IEx
value = "if the left-operand is a map, the keyword each will contain each value",
examples = { @example (
value = "[1::2, 3::4, 5::6] first_with (each >= 4)",
equals = "4"),
equals = "4", returnType = IKeyword.INT),
@example (
value = "[1::2, 3::4, 5::6].pairs first_with (each.value >= 4)",
equals = "(3::4)") }) },
equals = "(3::4)", returnType = IKeyword.PAIR) }) },
examples = { @example (
value = "[1,2,3,4,5,6,7,8] first_with (each > 3)",
equals = "4"),
Expand Down
7 changes: 4 additions & 3 deletions msi.gama.core/src/msi/gaml/operators/Logic.java
View file
Expand Up @@ -15,6 +15,7 @@
import msi.gama.precompiler.GamlAnnotations.doc;
import msi.gama.precompiler.GamlAnnotations.example;
import msi.gama.precompiler.GamlAnnotations.operator;
import msi.gama.precompiler.GamlAnnotations.test;
import msi.gama.precompiler.IConcept;
import msi.gama.precompiler.IOperatorCategory;
import msi.gama.precompiler.ITypeProvider;
Expand Down Expand Up @@ -63,12 +64,12 @@ public static Boolean xor(final IScope scope, final Boolean left, final Boolean
see = { "bool", "and", "!" },
examples= {
@example(value="true or false", equals="true"),
@example(value="false or false", equals="false", isTestOnly = true),
@example(value="false or true", equals="true", isTestOnly = true),
@example(value="true or true", equals="true", isTestOnly = true),
@example(" int a <-3 ; int b <- 4; int c <- 7;"),
@example(value="((a+b) = c ) or ((a+b) > c )", equals="true"),
})
@test("false or false = false")
@test("false or true")
@test("true or true")
public static Boolean or(final IScope scope, final Boolean left, final IExpression right)
throws GamaRuntimeException {
return left != null && left || right != null && Cast.asBool(scope, right.value(scope));
Expand Down
6 changes: 1 addition & 5 deletions msi.gama.core/src/msi/gaml/operators/Maths.java
View file
Expand Up @@ -133,11 +133,7 @@ public static Double abs(final Double rv) {
equals = "10"),
@example (
value = "abs (10)",
equals = "10"),
@example (
value = "abs (-0)",
equals = "0",
isTestOnly = true) }) })
equals = "10") }) })
@test ("abs(1) = 1")
@test ("abs(-2) = 2")
@test ("abs(0) = 0")
Expand Down
37 changes: 7 additions & 30 deletions msi.gama.core/src/msi/gaml/operators/Spatial.java
View file
Expand Up @@ -600,13 +600,10 @@ public static IShape cube(final IScope scope, final Double side_size) {
examples = { @example (
value = "rectangle({10, 5})",
equals = "a geometry as a rectangle with width = 10 and height = 5.",
test = false),
@example (
value = "rectangle({10, 5}).area",
equals = "50.0",
returnType = "float", isTestOnly = true) },
test = false) },
see = { "around", "circle", "cone", "line", "link", "norm", "point", "polygon", "polyline", "square",
"triangle" })
@test("rectangle({10, 5}).area = 50.0")
public static IShape rectangle(final IScope scope, final GamaPoint p) {
ILocation location;
final IAgent a = scope.getAgent();
Expand All @@ -627,13 +624,10 @@ public static IShape rectangle(final IScope scope, final GamaPoint p) {
examples = { @example (
value = "rectangle(10, 5)",
equals = "a geometry as a rectangle with width = 10 and height = 5.",
test = false),
@example (
value = "rectangle(10, 5).area",
equals = "50.0",
returnType = "float", isTestOnly = true) },
test = false) },
see = { "around", "circle", "cone", "line", "link", "norm", "point", "polygon", "polyline", "square",
"triangle" })
@test("rectangle(10, 5).area = 50.0")
public static IShape rectangle(final IScope scope, final double x, final double y) {
ILocation location;
final IAgent a = scope.getAgent();
Expand All @@ -650,13 +644,10 @@ public static IShape rectangle(final IScope scope, final double x, final double
examples = { @example (
value = "rectangle({0.0,0.0}, {10.0,10.0})",
equals = "a geometry as a rectangle with {1.0,1.0} as the upper-left corner, {10.0,10.0} as the lower-right corner.",
test = false),
@example (
value = "rectangle({0.0,0.0}, {10.0,10.0}).area",
equals = "100.0",
returnType = "float", isTestOnly = true) },
test = false) },
see = { "around", "circle", "cone", "line", "link", "norm", "point", "polygon", "polyline", "square",
"triangle" })
@test("rectangle({0.0,0.0}, {10.0,10.0}).area = 100.0")
public static IShape rectangle(final IScope scope, final GamaPoint upperLeftCorner,
final GamaPoint lowerRightCorner) {
ILocation location;
Expand Down Expand Up @@ -3890,30 +3881,16 @@ public static Boolean overlaps(final IScope scope, final IShape g1, final IShape
@example (
value = "polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps {25,25}",
equals = "false"),
@example (
value = "polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polygon([{35,35},{35,45},{45,45},{45,35}])",
equals = "false", isTestOnly = true),
@example (
value = "polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polyline([{10,10},{20,20}])",
equals = "false")
// @example (
// value = "polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps {15,15}",
// equals = "false"),
// @example (
// value = "polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polygon([{0,0},{0,30},{30,30}, {30,0}])",
// equals = "false"),
// @example (
// value = "polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polygon([{15,15},{15,25},{25,25},{25,15}])",
// equals = "true"),
// @example (
// value = "polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polygon([{10,20},{20,20},{20,30},{10,30}])",
// equals = "false")
},
see = { "disjoint_from", "crosses", "overlaps", "intersects", "touches" })
@test("polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polygon([{0,0},{0,30},{30,30}, {30,0}]) = false")
@test("polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polygon([{15,15},{15,25},{25,25},{25,15}])")
@test("polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polygon([{10,20},{20,20},{20,30},{10,30}]) = false")
@test("polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps {15,15} = false")
@test("polygon([{10,10},{10,20},{20,20},{20,10}]) partially_overlaps polygon([{35,35},{35,45},{45,45},{45,35}]) = false")
public static Boolean partially_overlaps(final IShape g1, final IShape g) {
if (g == null) { return false; }
return g1.getInnerGeometry().overlaps(g.getInnerGeometry());
Expand Down

0 comments on commit d496589

Please sign in to comment.