Polyglot.zz

About Polyglot.zz

Polyglot:knowing or using several languages zz:distinctive subset of chars from the word puzzle

Polyglot.zz is a collection of libraries for generating word search puzzles implemented in multiple languages. Each implementation provides conceptually equal interface; omitting language specific syntax differences. The implementation details are internal to each language and are not required to be equal.

See full list of available implementations here »

---

Features

• ability to extend puzzle state (add/remove words over time)
• supports multiple alphabets (default is English)
• supports various board configurations (default is N x N square)
• configurable words directions

---

Motivation

Beyond providing a library for generating word puzzles, this project has a few alternative agendas. The purpose of this project is to provide:

• better understanding of language differences
• fixed standard problem for learning new languages
• semi-interesting problem for optimization
• understanding of best practices and efforts required to maintain a multi-language project

The choice of using word puzzles as the problem to solve is ideal because it requires no servers, network connection, or reuse permission (i.e. expensive licenses). It allows constructing a search problem without any prior dataset and the problem is presented dynamically by applying various constraints to the search space, whereby it is easy to go from a simple problem to a more complex problem by simply changing constraints. Overall, this problem allows focusing on finding an actual solution instead of focusing on the mechanics of networking and interoperability.

Source Code

This project is open source and hosted on Gitlab.

License

MIT

Specs

Each implementation in this library should provide conceptually equal interface; omitting language specific syntax differences. The implementation details are internal to each language and are not required to be equal.

Requirements

Generic API object

• Provide puzzle API

API must provide access to following properties:

• Puzzle words (string array)
• Puzzle problem (2D string array where each cell is a char)
• Puzzle solution (K,V dictionary where K is word, and V its placement on board)
• Current alphabet settings (get and set)
• Current board configuration (get and set)
• Word orientation settings (get and set)

API must provide ability to:

• add words
• remove words
• reset board
• shuffle board (find alternative solution)

Use of shared resources

• Uses /shared json files for default configs, alphabets and boards

Testing

• Must implement unit testing

Docs

• Must document at least usage with examples

Implementations

.NET (C#)

C# implementation of word search puzzle generator. This library generates word search puzzles and solutions.

Usage

Step 1: add nuget packcage

PM> Install-Package Polyglotzz -Version 1.0.0

Basic Example

using System;
using System.Collections.Generic;
using System.Linq;

namespace ConsoleApp
{
    internal class Program
    {
        public static void Main(string[] args)
        {
            // create new puzzle
            var Puzzle = new PuzzleApi();

            // add some words
            Puzzle.Add("orange");
            Puzzle.Add("tomato");
            Puzzle.Add("lime");
            Puzzle.Add("kiwi");

            // output puzzle grid
            for (int r = 0; r < Puzzle.Puzzle.Length; r++)
            {
                Console.WriteLine(" {0} ", string.Join(" ", Puzzle.Puzzle[r]));
            }

            // output puzzle words
            foreach (var word in Puzzle.Solution.Keys)
            {
                Console.WriteLine(word);
            }
        }
    }
}

Sample solution

This sample console application shows simple usage of polyglotzz library.

Step 1. Clone source repository

https://gitlab.com/hemuli/polyglot.zz.git

Step 2. Navigate to polyglot.zz/samples/ConsoleApp and launch ConsoleApp.sln

Step 3. Run the application.

Running the application should result in output similar to the picture below.

Compile Locally

Follow these steps to build and debug polygotzz library locally.

Requirements

1. git
2. IDE with C# compiler, e.g. Visual Studio or Jetbrains Rider

Steps

Clone repo

git clone https://gitlab.com/hemuli/polyglot.zz.git     

Navigate to C# project ./releases/dotnet and launch solution polyglotzz.sln

Install nuget packages

Compile Polyglotzz project, which contains library source code.

Run Tests.cs in Polyglotzz.Test project, which contains library unit tests.

Javascript (ES6)

Javascript (ES6) implementation of word search puzzle generator. This library generates word search puzzles and solutions.

Usage

Step 1: install package:

npm i polyglotzz.js

React component

This example shows how to make a simple react word puzzle component.

import React from 'react';
import Puzzle from 'polyglotzz.js'

class WordSearch extends React.Component {

    renderPuzzleCell = (cell, i) => {
        return <span key={i}>{cell}</span>
    };

    renderPuzzleRow = (row, i) => {
        const cells = row.map(this.renderPuzzleCell);

        return <div key={i}>{cells}</div>
    };

    renderWordClue = (word, i) => {
        return <li key={i}>{word}</li>
    };

    render() {

        // initialize puzzle
        const myPuzzle = new Puzzle();

        // add some words
        myPuzzle.add('apple');
        myPuzzle.add('banana');
        myPuzzle.add('watermelon');
        myPuzzle.add('cherry');

        // word search problem
        const board = myPuzzle.puzzle.map(this.renderPuzzleRow);

        // word search clues
        const clues = myPuzzle.words.map(this.renderWordClue);

        return (
            <div>
                <h1>Word Search</h1>
                <div>{board}</div>
                <ul>{clues}</ul>
            </div>
        );
    }
}

export default WordSearch;

Rendered component with CSS styling

Puzzle API

This document explains how to interact with the library and what methods and properties are available.

class PuzzleApi(config)

Public interface for interacting with puzzle generator

Create new puzzle instance

Arguments:

• config (Object) – Object
• config.language (String) – puzzle alphabet (default: ‘en’)
• config.board (String) – board type (default: ‘square’)
• config.rows (number) – board rows
• config.cols (number) – board columns

PuzzleApi.add(word)

Add word(s) to current puzzle

Arguments:

• word (Array.<string>|string) – one or more words to add; when adding multiple words provide string[] as input After adding words, new board state will be computed using the added words

PuzzleApi.alphabet

Get or set current puzzle alphabet Note: changing alphabet will reset puzzle state

PuzzleApi.board

Get or set board configuration

PuzzleApi.orientation

Get or set word orientation settings

PuzzleApi.puzzle

Get current puzzle problem

PuzzleApi.remove(word)

Remove word(s) from current puzzle note: if you wish to remove all words, reset board instead

Arguments:

• word (Array.<string>|string) – one or more words to remove; when removing multiple words provide string[] as input.

PuzzleApi.reset()

Reset board state; calling this method will clear all words associated with puzzle, clear computed solution and shuffle board letters

PuzzleApi.shuffle()

Keep current board words but change their placement and shuffle filler letters.

PuzzleApi.solution

Get current puzzle solution

PuzzleApi.words

Get list of words added to puzzle

Algorithm

This sections explains how the solver works to generate a word puzzle.

1. Get previous solution state and initialize search space using that solution

2. For each word that remains, shuffle possible word directions

   1. Choose first direction from previous step

   2. Determine possible start indexes that could fit word in selected direction

      1. Choose first index from previous step and try placing word on board
      2. If placement can be made, lock word in that position, then break
      3. If placement cannot be made, choose next index

   3. If word can be placed, break

   4. If word cannot be placed, repeat for next direction

3. If all words can be placed, update solution state

Compile Locally

Follow these steps to build and debug polyglotzz.js locally.

Requirements

1. git
2. node
3. yarn or npm

Steps

Clone repo

git clone https://gitlab.com/hemuli/polyglot.zz.git     

Change dir to javascript project

cd releases/js

Install packages

yarn install        

Compile dev version using webpack (add -w flag to watch)

yarn start   

Run unit tests (add -w flag to watch)

yarn test 

Compile release

yarn build