group_constructors.jl

################################################################################
#
#  Some basic constructors
#
################################################################################

_gap_filter(::Type{PermGroup}) = GAP.Globals.IsPermGroup
_gap_filter(::Type{SubPcGroup}) = GAP.Globals.IsPcGroupOrPcpGroup
_gap_filter(::Type{FPGroup}) = GAP.Globals.IsFpGroup
_gap_filter(::Type{SubFPGroup}) = GAP.Globals.IsSubgroupFpGroup

# TODO: matrix group handling usually is more complex: there usually
# is another extra argument then to specify the base field
# `_gap_filter(::Type{MatrixGroup})` is on the file `matrices/MatGrp.jl`

# We use `GAP.Globals.IsPcGroupOrPcpGroup` as `_gap_filter` result for
# both `SubPcGroup` and `PcGroup`.
# Note that `_gap_filter` is used for creating Oscar groups from GAP groups.
# In the case of `PcGroup`, we wrap the result differently in the
# call `PcGroup(G)`.
_gap_filter(::Type{PcGroup}) = GAP.Globals.IsPcGroupOrPcpGroup

"""
    symmetric_group(n::Int)

Return the full symmetric group on the set `{1, 2, ..., n}`.

# Examples
```jldoctest
julia> G = symmetric_group(5)
Sym(5)

julia> order(G)
120

```
"""
function symmetric_group(n::Int)
  @req n >= 1 "n must be a positive integer"
  return PermGroup(GAP.Globals.SymmetricGroup(n)::GapObj)
end

# for functions like perm, cperm or macros like @perm provide a cached
# version of symmetric_group to reduce the overhead for these functions.
const SymmetricGroupID = AbstractAlgebra.CacheDictType{Int, PermGroup}()

function _symmetric_group_cached(n::Int)
  Base.get!(SymmetricGroupID, n) do
    symmetric_group(n)
  end
end

"""
    is_natural_symmetric_group(G::GAPGroup)

Return `true` if `G` is a permutation group acting as the symmetric group
on its moved points, and `false` otherwise.
"""
@gapattribute is_natural_symmetric_group(G::GAPGroup) = GAP.Globals.IsNaturalSymmetricGroup(GapObj(G))::Bool

"""
    is_isomorphic_to_symmetric_group(G::GAPGroup)

Return `true` if `G` is isomorphic to a symmetric group,
and `false` otherwise.
"""
@gapattribute is_isomorphic_to_symmetric_group(G::GAPGroup) = GAP.Globals.IsSymmetricGroup(GapObj(G))::Bool

"""
    alternating_group(n::Int)

Return the full alternating group on the set `{1, 2, ..., n}`..

# Examples
```jldoctest
julia> G = alternating_group(5)
Alt(5)

julia> order(G)
60

```
"""
function alternating_group(n::Int)
  @req n >= 1 "n must be a positive integer"
  return PermGroup(GAP.Globals.AlternatingGroup(n)::GapObj)
end

"""
    is_natural_alternating_group(G::GAPGroup)

Return `true` if `G` is a permutation group acting as the alternating group
on its moved points, and `false` otherwise.
"""
@gapattribute is_natural_alternating_group(G::GAPGroup) = GAP.Globals.IsNaturalAlternatingGroup(GapObj(G))::Bool

"""
    is_isomorphic_to_alternating_group(G::GAPGroup)

Return `true` if `G` is isomorphic to an alternating group,
and `false` otherwise.
"""
@gapattribute is_isomorphic_to_alternating_group(G::GAPGroup) = GAP.Globals.IsAlternatingGroup(GapObj(G))::Bool

"""
    cyclic_group(::Type{T} = PcGroup, n::IntegerUnion)
    cyclic_group(::Type{T} = PcGroup, n::PosInf)

Return the cyclic group of order `n`, as an instance of type `T`.

# Examples
```jldoctest
julia> G = cyclic_group(5)
Pc group of order 5

julia> G = cyclic_group(PermGroup, 5)
Permutation group of degree 5 and order 5

julia> G = cyclic_group(PosInf())
Pc group of infinite order

```
"""
cyclic_group(n::Union{IntegerUnion,PosInf}) = cyclic_group(PcGroup, n)

function cyclic_group(::Type{T}, n::Union{IntegerUnion,PosInf}) where T <: GAPGroup
  @req n > 0 "n must be a positive integer or infinity"
  return T(GAP.Globals.CyclicGroup(_gap_filter(T), GAP.Obj(n))::GapObj)
end

# special handling for pc groups: distinguish on the GAP side
function cyclic_group(::Type{T}, n::Union{IntegerUnion,PosInf}) where T <: Union{PcGroup, SubPcGroup}
  if is_infinite(n)
    return T(GAP.Globals.AbelianPcpGroup(1, GapObj([])))
  elseif n > 0
    return T(GAP.Globals.CyclicGroup(GAP.Globals.IsPcGroup, GAP.Obj(n))::GapObj)
  end
  throw(ArgumentError("n must be a positive even integer or infinity"))
end

"""
    is_cyclic(G::GAPGroup)

Return `true` if `G` is cyclic,
i.e., if `G` can be generated by one element.
"""
@gapattribute is_cyclic(G::GAPGroup) = GAP.Globals.IsCyclic(GapObj(G))::Bool

"""
    cyclic_generator(G::GAPGroup)

Return an element of `G` that generates `G` if `G` is cyclic,
and throw an error otherwise.

# Examples
```jldoctest
julia> g = permutation_group(5, [cperm(1:3), cperm(4:5)])
Permutation group of degree 5

julia> cyclic_generator(g)
(1,2,3)(4,5)
```
"""
function cyclic_generator(G::GAPGroup)
  @req is_cyclic(G) "the group is not cyclic"
  ngens(G) == 1 && return gen(G,1)
  is_finite(G) && order(G) == 1 && return one(G)
  return group_element(G, GAPWrap.MinimalGeneratingSet(GapObj(G))[1])
end

# already defined in Hecke
#=
function abelian_group(v::Vector{Int})
  for i = 1:length(v)
    iszero(v[i]) && error("Cannot represent an infinite group as a polycyclic group")
  end
  v1 = GAP.Obj(v)
  return PcGroup(GAP.Globals.AbelianGroup(v1))
end
=#

@doc raw"""
    abelian_group(::Type{T} = PcGroup, v::Vector{S}) where T <: Group where S <: IntegerUnion

Return the direct product of cyclic groups of the orders
`v[1]`, `v[2]`, $\ldots$, `v[n]`, as an instance of `T`.
Here, `T` must be one of `PermGroup`, `FPGroup`, `SubFPGroup`, `PcGroup`,
or `SubPcGroup`.

The `gens` value of the returned group corresponds to `v`, that is,
the number of generators is equal to `length(v)`
and the order of the `i`-th generator is `v[i]`.

!!! warning
    The type need to be specified in the input of the function `abelian_group`,
    otherwise a group of type `FinGenAbGroup` is returned,
    which is not a GAP group type.
    In future versions of Oscar, this may change.
"""
function abelian_group(::Type{T}, v::Vector{S}) where T <: GAPGroup where S <: IntegerUnion
  vgap = GAP.Obj(v; recursive = true)
  return T(GAP.Globals.AbelianGroup(_gap_filter(T), vgap)::GapObj)
end

# Delegating to the GAP constructor via `_gap_filter` does not work here.
function abelian_group(::Type{TG}, v::Vector{T}) where TG <: Union{PcGroup, SubPcGroup} where T <: IntegerUnion
  if 0 in v
    # if 0 in v || (TG == PcGroup && any(!is_prime, v))
    #TODO: Currently GAP's IsPcpGroup groups run into problems
    #      already in the available Oscar tests,
    #      see https://github.com/gap-packages/polycyclic/issues/88,
    #      so we keep the code from the master branch here.
    # We cannot construct an `IsPcGroup` group if some generator shall have
    # order infinity or 1 or a composed number.
    return TG(GAP.Globals.AbelianPcpGroup(length(v), GapObj(v; recursive = true)))
  elseif TG == PcGroup && any(!is_prime, v)
    # GAP's IsPcGroup groups cannot have generators that correspond to the
    # orders given by `v` and to the defining presentation.
    error("cannot create a PcGroup group with relative orders $v, perhaps try SubPcGroup")
  else
    return TG(GAP.Globals.AbelianGroup(GAP.Globals.IsPcGroup, GapObj(v; recursive = true)))
  end
end

@doc raw"""
    is_abelian(G::Group)

Return `true` if `G` is abelian (commutative),
that is, $x*y = y*x$ holds for all elements $x, y$ in `G`.
"""
@gapattribute is_abelian(G::GAPGroup) = GAP.Globals.IsAbelian(GapObj(G))::Bool


@doc raw"""
    elementary_abelian_group(::Type{T} = PcGroup, n::S) where T <: Group where S <: IntegerUnion

Return the elementary abelian group group of order `n`, as an instance of `T`.
Here, `T` must be one of `PermGroup`, `FPGroup`, `SubFPGroup`, `PcGroup`,
`SubPcGroup`, or `FinGenAbGroup`,
and `n` must be a prime power or 1.

The `gens` vector of the result has minimal length.

# Examples
```jldoctest
julia> g = elementary_abelian_group(27)
Pc group of order 27

julia> g = elementary_abelian_group(PermGroup, 27)
Permutation group of degree 9 and order 27
```
"""
elementary_abelian_group(n::IntegerUnion) = elementary_abelian_group(PcGroup, n)

function elementary_abelian_group(::Type{T}, n::S) where T <: GAPGroup where S <: IntegerUnion
  @req (n == 1 || is_prime_power_with_data(n)[1]) "n must be a prime power or 1"
  return T(GAP.Globals.ElementaryAbelianGroup(_gap_filter(T), GAP.Obj(n))::GapObj)
end

# Delegating to the GAP constructor via `_gap_filter` does not work here.
function elementary_abelian_group(::Type{T}, n::S) where T <: Union{PcGroup, SubPcGroup} where S <: IntegerUnion
  @req (n == 1 || is_prime_power_with_data(n)[1]) "n must be a prime power or 1"
  return T(GAP.Globals.ElementaryAbelianGroup(GAP.Globals.IsPcGroup, GAP.Obj(n))::GapObj)
end

function elementary_abelian_group(::Type{FinGenAbGroup}, n::S) where S <: IntegerUnion
  flag, e, p = is_prime_power_with_data(n)
  @req (n == 1 || flag) "n must be a prime power or 1"
  return abelian_group(fill(p, e))
end

@doc raw"""
    is_elementary_abelian(G::Group)

Return `true` if `G` is a abelian (see [`is_abelian`](@ref))
and if there is a prime `p` such that the order of each element in `G`
divides `p`.

# Examples
```jldoctest
julia> g = alternating_group(5);

julia> is_elementary_abelian(sylow_subgroup(g, 2)[1])
true

julia> g = alternating_group(6);

julia> is_elementary_abelian(sylow_subgroup(g, 2)[1])
false
```
"""
@gapattribute is_elementary_abelian(G::GAPGroup) = GAP.Globals.IsElementaryAbelian(GapObj(G))::Bool

function is_elementary_abelian(G::FinGenAbGroup)
  e = exponent(G)
  return e == 1 || is_prime(e)
end


function mathieu_group(n::Int)
  @req 9 <= n <= 12 || 21 <= n <= 24 "n must be a 9-12 or 21-24"
  return PermGroup(GAP.Globals.MathieuGroup(n), n)
end


################################################################################
#
#  Projective groups obtained from classical groups
#
################################################################################

@doc raw"""
    projective_general_linear_group(n::Int, q::Int)

Return the factor group of [`general_linear_group`](@ref),
called with the same parameters,
by its scalar matrices.
The group is represented as a permutation group.

# Examples
```jldoctest
julia> g = projective_general_linear_group(2, 3)
Permutation group of degree 4 and order 24

julia> order(g)
24
```
"""
function projective_general_linear_group(n::Int, q::Int)
  @req is_prime_power_with_data(q)[1] "The field size must be a prime power"
  return PermGroup(GAP.Globals.PGL(n, q))
end


@doc raw"""
    projective_special_linear_group(n::Int, q::Int)

Return the factor group of [`special_linear_group`](@ref),
called with the same parameters,
by its scalar matrices.
The group is represented as a permutation group.

# Examples
```jldoctest
julia> g = projective_special_linear_group(2, 3)
Permutation group of degree 4 and order 12

julia> order(g)
12
```
"""
function projective_special_linear_group(n::Int, q::Int)
  @req is_prime_power_with_data(q)[1] "The field size must be a prime power"
  return PermGroup(GAP.Globals.PSL(n, q))
end


@doc raw"""
    projective_symplectic_group(n::Int, q::Int)

Return the factor group of [`symplectic_group`](@ref),
called with the same parameters,
by its scalar matrices.
The group is represented as a permutation group.

# Examples
```jldoctest
julia> g = projective_symplectic_group(2, 3)
Permutation group of degree 4 and order 12

julia> order(g)
12
```
"""
function projective_symplectic_group(n::Int, q::Int)
  @req is_prime_power_with_data(q)[1] "The field size must be a prime power"
  @req iseven(n) "The dimension must be even"
  return PermGroup(GAP.Globals.PSp(n, q))
end


@doc raw"""
    projective_unitary_group(n::Int, q::Int)

Return the factor group of [`unitary_group`](@ref),
called with the same parameters,
by its scalar matrices.
The group is represented as a permutation group.

# Examples
```jldoctest
julia> g = projective_unitary_group(2, 3)
Permutation group of degree 10 and order 24

julia> order(g)
24
```
"""
function projective_unitary_group(n::Int, q::Int)
  @req is_prime_power_with_data(q)[1] "The field size must be a prime power"
  return PermGroup(GAP.Globals.PGU(n, q))
end


@doc raw"""
    projective_special_unitary_group(n::Int, q::Int)

Return the factor group of [`special_unitary_group`](@ref),
called with the same parameters,
by its scalar matrices.
The group is represented as a permutation group.

# Examples
```jldoctest
julia> g = projective_special_unitary_group(2, 3)
Permutation group of degree 10 and order 12

julia> order(g)
12
```
"""
function projective_special_unitary_group(n::Int, q::Int)
  @req is_prime_power_with_data(q)[1] "The field size must be a prime power"
  return PermGroup(GAP.Globals.PSU(n, q))
end


"""
    projective_orthogonal_group(e::Int, n::Int, q::Int)

Return the factor group of [`orthogonal_group`](@ref),
called with the same parameters,
by its scalar matrices.

As for `orthogonal_group`, `e` can be omitted if `n` is odd.

# Examples
```jldoctest
julia> g = projective_orthogonal_group(1, 4, 3);  order(g)
576

julia> g = projective_orthogonal_group(3, 3);  order(g)
24
```
"""
function projective_orthogonal_group(e::Int, n::Int, q::Int)
  @req is_prime_power_with_data(q)[1] "The field size must be a prime power"
  if e == 1 || e == -1
    @req iseven(n) "The dimension must be even"
  elseif e == 0
    @req isodd(n) "The dimension must be odd"
  else
    throw(ArgumentError("Invalid description of projective orthogonal group"))
  end
  return PermGroup(GAP.Globals.PGO(e, n, q))
end

projective_orthogonal_group(n::Int, q::Int) = projective_orthogonal_group(0, n, q)


"""
    projective_special_orthogonal_group(e::Int, n::Int, q::Int)

Return the factor group of [`special_orthogonal_group`](@ref),
called with the same parameters,
by its scalar matrices.

As for `special_orthogonal_group`, `e` can be omitted if `n` is odd.

# Examples
```jldoctest
julia> g = projective_special_orthogonal_group(1, 4, 3);  order(g)
288

julia> g = projective_special_orthogonal_group(3, 3);  order(g)
24
```
"""
function projective_special_orthogonal_group(e::Int, n::Int, q::Int)
  @req is_prime_power_with_data(q)[1] "The field size must be a prime power"
  if e == 1 || e == -1
    @req iseven(n) "The dimension must be even"
  elseif e == 0
    @req isodd(n) "The dimension must be odd"
  else
    throw(ArgumentError("Invalid description of projective special orthogonal group"))
  end
  return PermGroup(GAP.Globals.PSO(e, n, q))
end

projective_special_orthogonal_group(n::Int, q::Int) = projective_special_orthogonal_group(0, n, q)


"""
    projective_omega_group(e::Int, n::Int, q::Int)

Return the factor group of [`omega_group`](@ref),
called with the same parameters,
by its scalar matrices.

As for `omega_group`, `e` can be omitted if `n` is odd.

# Examples
```jldoctest
julia> g = projective_omega_group(1, 4, 3);  order(g)
144

julia> g = projective_omega_group(3, 3);  order(g)
12
```
"""
function projective_omega_group(e::Int, n::Int, q::Int)
  @req is_prime_power_with_data(q)[1] "The field size must be a prime power"
  if e == 1 || e == -1
    @req iseven(n) "The dimension must be even"
  elseif e == 0
    @req isodd(n) "The dimension must be odd"
  else
    throw(ArgumentError("Invalid description of projective orthogonal group"))
  end
  return PermGroup(GAP.Globals.POmega(e, n, q))
end

projective_omega_group(n::Int, q::Int) = projective_omega_group(0, n, q)


################################################################################
#
# begin FpGroups
#
################################################################################

@doc raw"""
    free_group(n::Int, s::VarName = :f; eltype::Symbol = :letter) -> FPGroup
    free_group(L::VarName... ; eltype::Symbol = :letter) -> FPGroup
    free_group(varnames_specifiers... ; eltype::Symbol = :letter) -> FPGroup

Return a free group.

The first form returns a free group of rank `n`, where the generators are
printed as `"$s1"`, `"$s2"`, ..., the default being `f1`, `f2`, ...

The second form returns a free group of rank `n`, where `n` is the length of `L`,
and `L` consists of strings, symbols or characters giving the variable names.

In the final form, the argument list consists of a sequence of one or
more of the following:
1. A vector `L` of variable names.
2. A pair of the form `A => B`, where `A` is a `VarName` (so a string, symbol
   or character) and `B` is a range or more generally an `AbstractVector`.
   Then `length(B)` generators are defined whose names derive from a combination
   of `A` and the respective element of `B`.
   For example `:x => 1:3` defines three generators `x[1], x[2], x[3]`.
3. A pair of the form `A => C`, where `A` is again a `VarName`, and `C` is
   a tuple of ranges or v. For example `"a" => (1:2, 1:2)` defines four generators
   `a[1, 1], a[2, 1], a[1, 2], a[2, 2]`.

For the second and third type, optionally the `A` part can contain the
placeholder `#` to modify where the indices are inserted. For example
`"a#" => (1:2, 1:2)` defines four generators `a11, a21, a12, a22`.

Also, instead of a range, any vector can be used. For example `"#" => ([:x,:y], [:A, :B])`
defines four generators `xA, yA, xB, yB`.

In all variants, if the optional keyword argument `eltype` is given and
has the value `:syllable` then each element in the free group is
internally represented by a vector of syllables, whereas a
representation by a vector of integers is chosen in the default case of
`eltype == :letter`.

!!! warning
    Julia variables named like the group generators are *not* created by this function.
    However, the macro [`@free_group`](@ref) does just that.

# Examples
```jldoctest
julia> F = free_group(:a, :b)
Free group of rank 2

julia> w = F[1]^3 * F[2]^F[1] * F[-2]^2
a^2*b*a*b^-2
```

Here we show some of the different ways to create a free group.
```jldoctest
julia> gens(free_group(2))
2-element Vector{FPGroupElem}:
 f1
 f2

julia> gens(free_group(2, :a))
2-element Vector{FPGroupElem}:
 a1
 a2

julia> gens(free_group(:u, :v))
2-element Vector{FPGroupElem}:
 u
 v

julia> gens(free_group([:a, :b], "x" => 1:2, 'y' => (1:2, 1:2)))
8-element Vector{FPGroupElem}:
 a
 b
 x[1]
 x[2]
 y[1, 1]
 y[2, 1]
 y[1, 2]
 y[2, 2]
```
"""
function free_group(L::Vector{<:Symbol}; eltype::Symbol = :letter)
  @req allunique(L) "generator names must be unique"
   J = GapObj(L, recursive = true)
  if eltype == :syllable
     G = FPGroup(GAP.Globals.FreeGroup(J; FreeGroupFamilyType = GapObj("syllable"))::GapObj)
  elseif eltype == :letter
    G = FPGroup(GAP.Globals.FreeGroup(J)::GapObj)
  else
    error("eltype must be :letter or :syllable, not ", eltype)
  end
  GAP.Globals.SetRankOfFreeGroup(GapObj(G), length(J))
  return G
end

# HACK: we want to use `AbstractAlgebra.@varnames_interface` for free groups,
# but by default this requires the "constructor" function to have two return
# values: the ring/group/whatever, and its generator. But `free_group` has
# traditionally just one return value and we can't change that without badly
# breaking backwards compatibility. (Besides, I don't really *want* to change
# this, but that's a different matter).
#
# So we use a trick: we introduce `_free_group` with the right return value,
# and then delegate `free_group` to it, and similarly define the macro
# `@free_group` by delegating to the `@_free_group` macros (plus some extra
# shenigans).
function _free_group(L::Vector{<:Symbol}; eltype::Symbol = :letter)
  G = free_group(L; eltype)
  return G, gens(G)
end

AbstractAlgebra.@varnames_interface _free_group(s)

free_group(L0::VarName, Ls::VarName...; kw...) = free_group([L0, Ls...]; kw...)
free_group(a0, args...; kw...) = _free_group(a0, args...; kw...)[1]
free_group(; kw...) = _free_group(0; kw...)[1]

# HACK to get the default variable name stem `:f` instead of `:x`
# but also to insert validation for `n`.
function free_group(n::Int, s::VarName = :f; kw...)
  @req n >= 0 "n must be a non-negative integer"
  _free_group(n, s; kw...)[1]
end

"""
    @free_group(args...)

Return the free group obtained from `free_group(args...)` and introduce
its generators as Julia variables into the current scope.

# Examples
```jldoctest
julia> F = @free_group(:a, :b)
Free group of rank 2

julia> a^2*b*a*b^-2
a^2*b*a*b^-2
```

Note that the `varname => vector` syntax for specifying a vector or
matrix or general array of variables behaves slightly differently
compared to `free_group`, as the following example demonstrates.
```jldoctest
julia> U1 = free_group("x" => 1:3); gens(U1)
3-element Vector{FPGroupElem}:
 x[1]
 x[2]
 x[3]

julia> U2 = @free_group("x" => 1:3); gens(U2)
3-element Vector{FPGroupElem}:
 x1
 x2
 x3

julia> (x2^x1)^-1
x1^-1*x2^-1*x1
```
"""
macro free_group(args...)
  if all(n -> n isa VarName || (n isa QuoteNode && n.value isa VarName), args)
    # if the arguments are varnames, put them into a vector before delegating
    # to @_free_group
    esc(quote
        Oscar.@_free_group([$(args...)])
    end)
  else
    # by default just delegate to `@_free_group`
    esc(quote
        Oscar.@_free_group($(args...))
    end)
  end
end

macro free_group(n::Int, sym = :f)
  if sym isa QuoteNode
    sym = sym.value
  end
  s = Symbol(sym)::Symbol
  esc(quote
    Oscar.@_free_group($(QuoteNode(s)) => 1:$n)
  end)
end


# FIXME: a function `free_abelian_group` with the same signature is
# already being defined by Hecke
#function free_abelian_group(n::Int)
#  return FPGroup(GAPWrap.FreeAbelianGroup(n))
#end

function free_abelian_group(::Type{FPGroup}, n::Int)
  return FPGroup(GAPWrap.FreeAbelianGroup(n)::GapObj)
end


# for the definition of group modulo relations, see the quo function in the sub.jl section

function free_group(G::FPGroup)
  gapG = GapObj(G)::GapObj
  gapF = GAPWrap.FreeGroupOfFpGroup(gapG)
  if gapF === gapG
    # G is itself a free group
    return G
  else
    return FPGroup(gapF)
  end
end

function underlying_word(g::FPGroupElem)
  G = parent(g)
  F = free_group(G)
  if F === G
    return g
  else
    return FPGroupElem(F, GAPWrap.UnderlyingElement(GapObj(g)))
  end
end


################################################################################
#
# end FpGroups
#
################################################################################

"""
    dihedral_group(::Type{T} = PcGroup, n::Union{IntegerUnion,PosInf})

Return the dihedral group of order `n`, as an instance of `T`,
where `T` is in {`PcGroup`, `SubPcGroup`, `PermGroup`, `FPGroup`, `SubFPGroup`}.

!!! warning

    There are two competing conventions for interpreting the argument `n`:
    In the one we use, the returned group has order `n`, and thus `n` must
    always be even.
    In the other, `n` indicates that the group describes the symmetry of an
    `n`-gon, and thus the group has order `2n`.

# Examples
```jldoctest
julia> dihedral_group(6)
Pc group of order 6

julia> dihedral_group(PermGroup, 6)
Permutation group of degree 3

julia> dihedral_group(PosInf())
Pc group of infinite order

julia> dihedral_group(7)
ERROR: ArgumentError: n must be a positive even integer or infinity
```
"""
dihedral_group(n::Union{IntegerUnion,PosInf}) = dihedral_group(PcGroup, n)

function dihedral_group(::Type{T}, n::Union{IntegerUnion,PosInf}) where T <: GAPGroup
  @req is_infinite(n) || (iseven(n) && n > 0) "n must be a positive even integer or infinity"
  return T(GAP.Globals.DihedralGroup(_gap_filter(T), GAP.Obj(n))::GapObj)
end

# Delegating to the GAP constructor via `_gap_filter` does not work here.
function dihedral_group(::Type{T}, n::Union{IntegerUnion,PosInf}) where T <: Union{PcGroup, SubPcGroup}
  if is_infinite(n)
    return T(GAP.Globals.DihedralPcpGroup(0))
  elseif iseven(n) && n > 0
    return T(GAP.Globals.DihedralGroup(GAP.Globals.IsPcGroup, GAP.Obj(n))::GapObj)
  end
  throw(ArgumentError("n must be a positive even integer or infinity"))
end

@doc raw"""
    is_dihedral_group(G::GAPGroup)

Return `true` if `G` is isomorphic to a dihedral group,
and `false` otherwise.

# Examples
```jldoctest
julia> is_dihedral_group(small_group(8,3))
true

julia> is_dihedral_group(small_group(8,4))
false

```
"""
@gapattribute is_dihedral_group(G::GAPGroup) = GAP.Globals.IsDihedralGroup(GapObj(G))::Bool

"""
    quaternion_group(::Type{T} = PcGroup, n::IntegerUnion)

Return the (generalized) quaternion group of order `n`,
as an instance of `T`,
where `n` is a multiple of 4 and `T` is in
{`PcGroup`, `SubPcGroup`, `PermGroup`,`FPGroup`, `SubFPGroup`}.

This is an alias of `dicyclic_group`.

# Examples
```jldoctest
julia> g = quaternion_group(8)
Pc group of order 8

julia> quaternion_group(PermGroup, 8)
Permutation group of degree 8

julia> g = quaternion_group(FPGroup, 8)
Finitely presented group of order 8

julia> relators(g)
3-element Vector{FPGroupElem}:
 r^2*s^-2
 s^4
 r^-1*s*r*s
```
"""
quaternion_group(n::IntegerUnion) = quaternion_group(PcGroup, n)

quaternion_group(::Type{T}, n::IntegerUnion) where {T<:Union{GAPGroup,PcGroup,SubPcGroup}} =
  dicyclic_group(T, n)

@doc raw"""
    is_quaternion_group(G::GAPGroup)

Return `true` if `G` is isomorphic to a (generalized) quaternion group
of order $2^{k+1}, k \geq 2$, and `false` otherwise.

# Examples
```jldoctest
julia> is_quaternion_group(small_group(8, 3))
false

julia> is_quaternion_group(small_group(8, 4))
true
```
"""
@gapattribute is_quaternion_group(G::GAPGroup) =
  GAP.Globals.IsGeneralisedQuaternionGroup(GapObj(G))::Bool

"""
    dicyclic_group(::Type{T} = PcGroup, n::IntegerUnion)

Return the dicyclic group of order `n`, as an instance of `T`,
where `n` is a multiple of 4 and `T` is in
{`PcGroup`, `SubPcGroup`, `PermGroup`,`FPGroup`, `SubFPGroup`}.

# Examples
```jldoctest
julia> g = dicyclic_group(12)
Pc group of order 12

julia> dicyclic_group(PermGroup, 12)
Permutation group of degree 12

julia> g = dicyclic_group(FPGroup, 12)
Finitely presented group of order 12

julia> relators(g)
3-element Vector{FPGroupElem}:
 r^2*s^-3
 s^6
 r^-1*s*r*s
```
"""
dicyclic_group(n::IntegerUnion) = dicyclic_group(PcGroup, n)

function dicyclic_group(::Type{T}, n::IntegerUnion) where {T<:GAPGroup}
  @assert iszero(mod(n, 4))
  return T(GAP.Globals.DicyclicGroup(_gap_filter(T), n)::GapObj)
end

# Delegating to the GAP constructor via `_gap_filter` does not work here.
function dicyclic_group(::Type{T}, n::IntegerUnion) where {T<:Union{PcGroup,SubPcGroup}}
  @assert iszero(mod(n, 4))
  return T(GAP.Globals.DicyclicGroup(GAP.Globals.IsPcGroup, n)::GapObj)
end

@doc raw"""
    is_dicyclic_group(G::GAPGroup)

Return `true` if `G` is isomorphic to a dicyclic group
of order $4n, n > 1$, and `false` otherwise.

# Examples
```jldoctest
julia> is_dicyclic_group(small_group(8, 3))
false

julia> is_dicyclic_group(small_group(8, 4))
true
```
"""
@gapattribute is_dicyclic_group(G::GAPGroup) =
  GAP.Globals.IsQuaternionGroup(GapObj(G))::Bool