class LeftRegularBand(UniqueRepresentation, Parent):
    r"""
    An example of a finite semigroup

    This class provides a minimal implementation of a finite semigroup.

    EXAMPLES::

        sage: S = FiniteSemigroups().example(); S
        An example of a finite semigroup: the left regular band generated by ('a', 'b', 'c', 'd')

    This is the semigroup generated by::

        sage: S.semigroup_generators()
        Family ('a', 'b', 'c', 'd')

    such that `x^2 = x` and `x y x = xy` for any `x` and `y` in `S`::

        sage: S('dab')
        'dab'
        sage: S('dab') * S('acb')
        'dabc'

    It follows that the elements of `S` are strings without
    repetitions over the alphabet `a`, `b`, `c`, `d`::

        sage: S.list()
        ['a', 'c', 'b', 'bd', 'bda', 'd', 'bdc', 'bc', 'bcd', 'cb',
         'ca', 'ac', 'cba', 'ba', 'cbd', 'bdca', 'db', 'dc', 'cd',
         'bdac', 'ab', 'abd', 'da', 'ad', 'cbad', 'acb', 'abc',
         'abcd', 'acbd', 'cda', 'cdb', 'dac', 'dba', 'dbc', 'dbca',
         'dcb', 'abdc', 'cdab', 'bcda', 'dab', 'acd', 'dabc', 'cbda',
         'bca', 'dacb', 'bad', 'adb', 'bac', 'cab', 'adc', 'cdba',
         'dca', 'cad', 'adbc', 'adcb', 'dbac', 'dcba', 'acdb', 'bacd',
         'cabd', 'cadb', 'badc', 'bcad', 'dcab']

    It also follows that there are finitely many of them::

        sage: S.cardinality()
        64

    Indeed::

        sage: 4 * ( 1 + 3 * (1 + 2 * (1 + 1)))
        64

    As expected, all the elements of `S` are idempotents::

        sage: all( x.is_idempotent() for x in S )
        True

    Now, let us look at the structure of the semigroup::

        sage: S = FiniteSemigroups().example(alphabet = ('a','b','c'))
        sage: S.cayley_graph(side="left", simple=True).plot()
        sage: S.j_transversal_of_idempotents() # random (arbitrary choice)
        ['acb', 'ac', 'ab', 'bc', 'a', 'c', 'b']

    We conclude by running systematic tests on this semigroup::

        sage: TestSuite(S).run(verbose = True)
        running ._test_an_element() . . . pass
        running ._test_associativity() . . . pass
        running ._test_category() . . . pass
        running ._test_elements() . . .
          Running the test suite of self.an_element()
          running ._test_category() . . . pass
          running ._test_eq() . . . pass
          running ._test_not_implemented_methods() . . . pass
          running ._test_pickling() . . . pass
          pass
        running ._test_elements_eq() . . . pass
        running ._test_enumerated_set_contains() . . . pass
        running ._test_enumerated_set_iter_cardinality() . . . pass
        running ._test_enumerated_set_iter_list() . . . pass
        running ._test_eq() . . . pass
        running ._test_not_implemented_methods() . . . pass
        running ._test_pickling() . . . pass
        running ._test_some_elements() . . . pass
    """

    def __init__(self, alphabet=('a','b','c','d')):
        r"""
        A left regular band.

        EXAMPLES::

            sage: S = FiniteSemigroups().example(); S
            An example of a finite semigroup: the left regular band generated by ('a', 'b', 'c', 'd')
            sage: S = FiniteSemigroups().example(alphabet=('x','y')); S
            An example of a finite semigroup: the left regular band generated by ('x', 'y')
            sage: TestSuite(S).run()
        """
        self.alphabet = alphabet
        Parent.__init__(self, category = FiniteSemigroups())

    def _repr_(self):
        r"""
        TESTS::

            sage: S = FiniteSemigroups().example()
            sage: S._repr_()
            "An example of a finite semigroup: the left regular band generated by ('a', 'b', 'c', 'd')"
        """
        return "An example of a finite semigroup: the left regular band generated by %s"%(self.alphabet,)

    def product(self, x, y):
        r"""
        Returns the product of two elements of the semigroup.

        EXAMPLES::

            sage: S = FiniteSemigroups().example()
            sage: S('a') * S('b')
            'ab'
            sage: S('a') * S('b') * S('a')
            'ab'
            sage: S('a') * S('a')
            'a'

        """
        assert x in self
        assert y in self
        x = x.value
        y = y.value
        return self(x + ''.join(c for c in y if c not in x))

    @cached_method
    def semigroup_generators(self):
        r"""
        Returns the generators of the semigroup.

        EXAMPLES::

            sage: S = FiniteSemigroups().example(alphabet=('x','y'))
            sage: S.semigroup_generators()
            Family ('x', 'y')

        """
        return Family([self(i) for i in self.alphabet])

    def an_element(self):
        r"""
        Returns an element of the semigroup.

        EXAMPLES::

            sage: S = FiniteSemigroups().example()
            sage: S.an_element()
            'cdab'

            sage: S = FiniteSemigroups().example(("b"))
            sage: S.an_element()
            'b'
        """

        return self(''.join(self.alphabet[2:]+self.alphabet[0:2]))

    class Element (ElementWrapper):
        wrapped_class = str
        __lt__ = ElementWrapper._lt_by_value

class MyGroupAlgebra(CombinatorialFreeModule):
    r"""
    An of a Hopf algebra with basis: the group algebra of a group

    This class illustrates a minimal implementation of a Hopf algebra with basis.
    """

    def __init__(self, R, G):
        """
        EXAMPLES::

            sage: from sage.categories.examples.hopf_algebras_with_basis import MyGroupAlgebra
            sage: A = MyGroupAlgebra(QQ, DihedralGroup(6))
            sage: A.category()
            Category of hopf algebras with basis over Rational Field
            sage: TestSuite(A).run()
        """
        self._group = G
        CombinatorialFreeModule.__init__(self, R, G, category = HopfAlgebrasWithBasis(R))

    def _repr_(self):
        """
        EXAMPLES::

            sage: HopfAlgebrasWithBasis(QQ).example() # indirect doctest
            An example of Hopf algebra with basis: the group algebra of the Dihedral group of order 6 as a permutation group over Rational Field
        """
        return "An example of Hopf algebra with basis: the group algebra of the %s over %s"%(self._group, self.base_ring())

    @cached_method
    def one_basis(self):
        """
        Returns the one of the group, which index the one of this algebra,
        as per :meth:`AlgebrasWithBasis.ParentMethods.one_basis`.

        EXAMPLES::

            sage: A = HopfAlgebrasWithBasis(QQ).example()
            sage: A.one_basis()
            ()
            sage: A.one()
            B[()]
        """
        return self._group.one()

    def product_on_basis(self, g1, g2):
        r"""
        Product, on basis elements, as per :meth:`AlgebrasWithBasis.ParentMethods.product_on_basis`.

        The product of two basis elements is induced by the product of
        the corresponding elements of the group.

        EXAMPLES::

            sage: A = HopfAlgebrasWithBasis(QQ).example()
            sage: (a, b) = A._group.gens()
            sage: a*b
            (1,2)
            sage: A.product_on_basis(a, b)
            B[(1,2)]
        """
        return self.basis()[g1 * g2]

    @cached_method
    def algebra_generators(self):
        r"""
        The generators of this algebra, as per :meth:`Algebras.ParentMethods.algebra_generators`.

        They correspond to the generators of the group.

        EXAMPLES::

            sage: A = HopfAlgebrasWithBasis(QQ).example(); A
            An example of Hopf algebra with basis: the group algebra of the Dihedral group of order 6 as a permutation group over Rational Field
            sage: A.algebra_generators()
            Finite family {(1,2,3): B[(1,2,3)], (1,3): B[(1,3)]}
        """
        return Family(self._group.gens(), self.monomial)

    def coproduct_on_basis(self, g):
        r"""
        Coproduct, on basis elements, as per :meth:`HopfAlgebrasWithBasis.ParentMethods.coproduct_on_basis`.

        The basis elements are group like: `\Delta(g) = g \otimes g`.

        EXAMPLES::

            sage: A = HopfAlgebrasWithBasis(QQ).example()
            sage: (a, b) = A._group.gens()
            sage: A.coproduct_on_basis(a)
            B[(1,2,3)] # B[(1,2,3)]
        """
        g = self.monomial(g)
        return tensor([g, g])

    def counit_on_basis(self, g):
        r"""
        Counit, on basis elements, as per :meth:`HopfAlgebrasWithBasis.ParentMethods.counit_on_basis`.

        The counit on the basis elements is 1.

        EXAMPLES::

            sage: A = HopfAlgebrasWithBasis(QQ).example()
            sage: (a, b) = A._group.gens()
            sage: A.counit_on_basis(a)
            1
        """
        return self.base_ring().one()

    def antipode_on_basis(self, g):
        r"""
        Antipode, on basis elements, as per :meth:`HopfAlgebrasWithBasis.ParentMethods.antipode_on_basis`.

        It is given, on basis elements, by `\nu(g) = g^{-1}`

        EXAMPLES::

            sage: A = HopfAlgebrasWithBasis(QQ).example()
            sage: (a, b) = A._group.gens()
            sage: A.antipode_on_basis(a)
            B[(1,3,2)]
        """
        return self.monomial(~g)