{"id":21543317,"url":"https://github.com/marinoandrea/hangman-cli","last_synced_at":"2025-10-05T08:53:07.940Z","repository":{"id":235241516,"uuid":"355589361","full_name":"marinoandrea/hangman-cli","owner":"marinoandrea","description":"A thoroughly tested implementation of the hangman game.","archived":false,"fork":false,"pushed_at":"2021-04-24T20:00:38.000Z","size":699,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-03T15:08:20.243Z","etag":null,"topics":["cli","game","hangman-game","python","testing","vrije-universiteit-amsterdam"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marinoandrea.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-04-07T15:10:48.000Z","updated_at":"2024-04-22T17:40:43.000Z","dependencies_parsed_at":"2024-04-22T20:08:27.595Z","dependency_job_id":null,"html_url":"https://github.com/marinoandrea/hangman-cli","commit_stats":null,"previous_names":["marinoandrea/hangman-cli"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/marinoandrea/hangman-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinoandrea%2Fhangman-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinoandrea%2Fhangman-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinoandrea%2Fhangman-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinoandrea%2Fhangman-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marinoandrea","download_url":"https://codeload.github.com/marinoandrea/hangman-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marinoandrea%2Fhangman-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278431565,"owners_count":25985686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","game","hangman-game","python","testing","vrije-universiteit-amsterdam"],"created_at":"2024-11-24T05:13:55.265Z","updated_at":"2025-10-05T08:53:07.904Z","avatar_url":"https://github.com/marinoandrea.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"assets/logo.png\" height=\"150px\" /\u003e\n\n---\n\n[![Build Status](https://www.travis-ci.com/marinoandrea/hangman-cli.svg?token=oQZSVvHp9LbB8M8icK4Z\u0026branch=main)](https://www.travis-ci.com/marinoandrea/hangman-cli)\n[![codecov](https://codecov.io/gh/marinoandrea/hangman-software-testing/branch/main/graph/badge.svg?token=0PZNNSXFL5)](https://codecov.io/gh/marinoandrea/hangman-software-testing)\n\nProject repository for the Software Testing course at VU.\n\n# Choose a topic\n\nIn this project, we chose to create the Hangman Game.\nFor this, we will adopt the Test Driven Development approach in an Agile setting.\n\n# Software Requirements Specification\n\n\u003c!-- This documentation follows the guidelines as specified in the IEEE SRS template, described at: https://canvas.vu.nl/courses/52331/files/3487737?module_item_id=527231 --\u003e\n\n## **Introduction**\n\nHangman is a game that is played with two players.\nOne player (thinker) chooses a word and the other player (guesser) aims to guess what word the player chose, by guessing one character at a time.\nThe guesser knows the length of the word that the thinker chose, and there is a limit on the number of wrong characters that the guesser can guess.\nIf the character is in the word, the thinker fills in all the occurrences of the word.\nIf it is not in the word, it is wrong and the thinker writes down the character.\n\nIn this project, the thinker of the game will be implemented, such that the guesser can guess the words that only the thinker knows.\n\n### Purpose\n\nThe purpose of this SRS document is to define the requirements of a hangman game and the software to interface with the game. The requirements must contain all information required to write an implementation, derive tests for the implementation, and test an implementation.\n\nThis document is intended for implementers(testing and developing) of this specification and for anyone evaluation an implementation implementing this specification.\n\n### Scope\n\nIn this project, there is one software product: the hangman game.\nThis product performs the interaction with the Player and the management of a game.\nThe hangman game does not make use of a leaderboard or any other statistics not required for a game instance.\nIn addition, the game can only be played on one machine and the game product does not make use of any kind of network communication.\n\nThe goal of the hangman game product is to provide an application to play the similarly named game.\n\n### Intended Audience and Reading Suggestions\n\nThe target audience of this document consists mainly of the software testing team, that will use this specification to test the software product.\nA secondary target audience is developers.\nFuture developers may use this documentation to get familiar with the design decisions that were made during the development of this project.\nA ternary target audience is the users that will use this software product.\n\nThis document is structured in the following way.\nFirst, it provides an overview of the software product.\nThis overview specifies how and in what environment the software product should be used.\nSecondly, the external interfaces are described.\nThis specifies how the user will be able to interact with the software product on a high level.\nThirdly, the system features are described.\nLastly, the nonfunctional requirements are described.\nThis specifies how well the software product performs.\n\nAll readers are advised to start reading the definitions following this section.\nThese definitions are used throughout the document and are important for understanding the rest of the document.\nIn addition to this, the overview section is important to understand the intended use of the software product.\n\nA software testing team is advised to continue reading the functional requirements, followed by the nonfunctional requirements.\nThe software testing team can use the external references-section as a reference during the testing of the product.\n\nA developer is advised to continue reading the external interfaces, followed by the functional requirements.\n\nA user is advised to continue reading the section on external interfaces.\n\n### Definitions\n\n- **Player**: The user that will use the system to guess words.\n\n- **Difficulty**: Every word gets as its difficulty value, the sum of the weights of every character in the word. The weight of a character is defined as the inverse of its proportion[1].\n  Proportion describes how common a character is in a word compared to the least occuring character.\n  A higher proportion denotes a higher probability of the character occuring in word, therefore, the inverse gives a lower weight to characters occuring often.\n\n- **Lives**: The limit of the number of wrong guesses that the Player can make.\n\n- **State**: The state of the system describes the to be guessed word, all the guessed characters, the current progress of the word, the number of Lives and the configuration options.\n\n- **Game instance**: A Game instance starts when a word has been chosen by the system and it ends when the Player has either guessed the word or lost all its Lives.\n\n- **Game Character**: A Game Character is defined as an ASCII character in the range 97 - 122.\n\n- **Game Word**: A Game Word is any string containing only Game Characters.\n\n- **Game Dictionary**: A collection of files embedded in the program containing lists of Game Words classified by their Difficulty into three groups(easy, medium, hard).\n  The groups are determined based on the median difficulty of words in one file.\n\n### References\n\n1. The [proportion source](https://www3.nd.edu/~busiforc/handouts/cryptography/letterfrequencies.html) used for determining the character proportion values.\n\n## **Overall description**\n\n### Product perspective\n\nThe hangman game product is completely self-contained. It is based on an already existing game, but the whole program is built from scratch.\n\n### Product Functions\n\nThe Player must be able to perform certain actions in the game, which are as follows:\nBelow, we list the actions the Player can perform:\n\n- Write a letter of the alphabet as a guess, either uppercase or lowercase.\n- Configure the difficulty, with options easy, medium or hard.\n- Configure the minimum and maximum length of a word that the game can choose.\n- Configure the number of lives that a player has ranging from 1 to 10.\n- Restart the game when it is over.\n\n### Userclasses and Characteristics\n\n- People who can speak English. The game is supposed to be played by people who know English.\n  The wordlist we use are of a English dictionary, and can be configured based on difficulty to support various levels of fluency.\n\n### Operating Environment\n\nThe system provides a **Command Line Interface** which will be accessible via a terminal in both the Linux and Windows releases.\nNo particular assumptions are made about the hardware configuration of the user's machine.\nThe system expects both the user's OS kernel and the terminal emulator to be fully functional when running the program, there are no other expectations on external software.\n\n### Design and Implementation Constraints\n\nThe system msut be designed to potentially allow the use of multiple languages, but for its first release it will only use English. The interface documentation, the in-game feedbacks and messages, and the list of words to guess for this release will only be available in English.\n\n### User Documentation\n\nThe user will have access to instructions on the program's configuration settings through the CLI by running the program with the `--help` option.\n\n### Assumptions and Dependencies\n\nIt is assumed that Windows users have a version of Windows 10 installed.\n\nLinux users need to have a version of **GNU C Library** (glibc) greater or equal **v2.29**.\n\n## **External Interface Requirements**\n\nSince the hangman game product is completely self-contained, there are no system interfaces.\n\n#### User interfaces\n\nThe Players will interface with the program using the command line.\nThe Player can start a new game simply by running the binary that will be provided.\n\nThe Player can customize the game using the following command line options:\n\n- `-m --min-length` a number specifying the minimum word length that can be randomly selected. It defaults to 2\n- `-M --max-length` a number specifying the maximum word length that can be randomly selected. It defaults to undefined\n- `-l --lives` a number between 1 and 10 that specifies the number of lives for the next game, defaults to 10\n- `-d --difficulty` a string being either: 'easy', 'medium', or 'hard', defaults to 'medium'\n\n#### Hardware interfaces\n\nThe system is purely made out of software components, and can be interacted with using basic input from a keyboard.\n\n#### Software interfaces\n\nThe system relies on the underlying OS implementation of basic I/O in order to receive `stdinput` via a terminal and to output to the `stdoutput`.\nThe Windows release of the system will work on any machine running Windows 10.\nThe GNU/Linux release of the system will work on any machine running a Linux distribution fulfilling the dependencies.\n\n#### Communications interfaces\n\nThe system relies solely on the CLI in order to provide interactive functionality. It does not require any external protocol in order to execute.\n\n#### Memory constraints\n\nThe user's machine should have a minimum of 100MB of free RAM in order to run this application.\nThis constraint accounts for both the Python runtime size and the program size.\n\n## System Features\n\n### Minimum length\n\nThe minimum length feature allows a user to specify a minimum length for the word to be guessed.\nThis feature has a low priority, because the game can be played without the minimum length feature included.\n\n#### Stimulus/Response\n\nThe Player shall set the minimum length of a word that the game can choose via the `-m` or `--minimum-length` option followed by an integer argument.\nThere is no response from the system, but for the remainder of the program the length of every guess word shall be of atleast the\nspecified length.\n\n#### Functional\n\n- FREQ-1.1: The system must support the parsing of the feature argument.\n- FREQ-1.2: If the provided argument is larger than the _Maximum length_ argument,\n  the system shall produce an error message and gracefully quit.\n- FREQ-1.3: If the provided argument is not an integer bigger than 2,\n  the system shall produce an error message and gracefully quit.\n- FREQ-1.4: If there is no word in the dictionary larger or of equal length as the specified argument,\n  the system shall produce an error message and gracefully quit.\n\n### Maximum length\n\nThe maximum length feature allows a user to specify the maximum length for the word to be guessed in a game instance.\nThis feature has a low priority, because the game is playable without it.\n\n#### Stimulus/Response\n\nThe Player shall set the maximum length of a word that the game can choose via the `-M` or `--maximum-length` option followed by an integer argument.\nThere is no response from the system, but for the remainder of the program the length of every guess word shall be no more\nthan the specified length.\n\n#### Functional\n\n- FREQ-2.1: The system must support the parsing of the feature argument.\n- FREQ-2.2: If the provided argument is not an integer bigger than 2,\n  the system shall produce an error message and gracefully quit.\n\n### Lives\n\nThe lives feature allows a user to specify the number of lives in a game instance. This corresponds to the amount of guesses\na Player has.\nThis feature has a low priority, because the game is playable with a default value.\n\n#### Stimulus/Response\n\nThe Player shall set the lives via the `-l` or `--lives` option followed by an integer argument in the range of 1 to 10.\nThere is no response from the system, but for the remainder of the program the number of lives at the start of a game instance shall be equal to the given argument.\n\n#### Functional\n\n- FREQ-3.1: The system must support the parsing of the feature argument.\n- FREQ-3.2: If the provided argument is not an integer in the range of 1 to 10,\n  the system shall produce an error and gracefully quit.\n- FREQ-3.3: If the provided argument is valid, the system shall for this invocation start\n  any game with the number of lives provided by the argument.\n\n### Difficulty\n\nThe difficulty feature allows a user to specify the difficulty of to be guessed words.\nThis feature has a low priority, because the game is playable with a wordlist not categorised on difficulty.\n\n#### Stimulus/Response\n\nThe Player shall set the difficulty via the `-d` or `--difficulty` option with the argument being one of 'easy', 'medium', or 'hard'.\nThere is no response from the system, but for the remainder of the program the word difficulty shall correspond to the given argument.\n\n#### Functional\n\n- FREQ-4.1: The system must support the parsing of the feature argument.\n- FREQ-4.2: If the provided argument is not one of 'easy', 'medium', or 'hard',\n  the system shall produce an error and gracefully quit.\n- FREQ-4.3: If the provided argument is valid, but there is no words in the difficulty level\n  that adhere to the length requirement, the system shall produce an error and gracefully quit.\n- FREQ-4.4: If the provided argument is valid, the system shall for this invocation\n  only pick words the correspond to the specified difficulty.\n\n### Multiple games\n\nThe multiple games feature allows a user to play multiple games during one invocation of the program.\nThis feature does not allow to play multiple games simultaneously.\nThis feature has a medium priority, because a Player can rerun the executable to start a new game,\nbut the experience is much smoother when a new game can be started during the same invocation.\n\n#### Stimulus/Response\n\nThe system shall ask the Player for an input of either 'y' or 'n'. Based on the provided answer,\nthe system shall stop the program, play a new game, or reask te question.\n\n#### Functional\n\n- FREQ-5.1: After ending a game instance, the system shall\n  ask the player to play another game by asking for command-line input of the form of either 'y' or 'n'.\n- FREQ-5.2: If the provided input is neither 'y' nor 'n', the system shall\n  repeat the question.\n- FREQ-5.3: A Keyboard Interrupt or an EOF character shall be interpreted identical\n  to a 'n' input.\n- FREQ-5.4: If the Player enters 'y', the system shall start a new game instance.\n- FREQ-5.5: If the Player enters 'n', the system shall gracefully exit.\n\n### Game Information\n\nThe game information feature provides information about the current state of the game to the Player during a game instance.\nThis feature has a high priority, because it contains the information to display to the Player which makes\nthe game playable from the Players perspective.\n\n#### Stimulus/Response\n\nThe system shall display the current state on the terminal device. There is no response required from the user.\n\n#### Functional\n\n- FREQ-6.1: The system shall display the current guess, if any; the current word, where correctly guessed character\n  are displayed, and character not yet guessed are displayed as an underscore; and a hangman animation.\n- FREQ-6.2: The hangman animation shall be unique for the amount of lives a Player has.\n- FREQ-6.3: The hangman animation shall become more complete the less lives a Player has.\n- FREQ-6.4: When a Player reaches zero lives the hangman must be complete.\n\n### Player guessing\n\nThe player guessing feature allows a Player to perform a guess for a Game character or a Game word.\nThis feature has a high priority, because without, the Player has no way to input and proceed the\ngame state.\n\n#### Stimulus/Response\n\nThe system shall ask the user for input. The user must respond with a valid Game Character or\nvalid Game String.\n\n#### Functional\n\n- FREQ-7.1: To perform a guess, the system must ask the Player via command-line input.\n- FREQ-7.2: If the guess by the Player is not a valid Game String, Game Character, or\n  upper case Game Character, the system shall inform the Player that it is not and redo the input request.\n- FREQ-7.3: Game Characters in upper case shall be converted to their lower case form by the system,\n  and further processed as a lower case Game Character.\n- FREQ-7.4: If the guess is a valid Game String, but the length of the guess is not equal\n  to the length of the Game String, the system shall inform the Player and redo the input request.\n- FREQ-7.5: If the guess is valid and not a duplicate, but the guessed Game Character is not part of the Game String,\n  the system shall substract one 'life' from the amount of 'lives'.\n- FREQ-7.6: If the guess is valid, a Game String, and not a duplicate, but not equal to the to be guessed Game String,\n  the system shall substract one 'life' from the amount of 'lives'.\n- FREQ-7.7: If the guess is valid, but a duplicate, the system shall inform the player that it is a duplicate and\n  not substract any lives.\n- FREQ-7.8: If the Player inputs a EOF character or performs a Keyboard Interrupt during input, the system\n  shall end the corresponding Game Instance.\n\n### Winner/Loser\n\nThe Winner/Loser feature assign a win-condition to the game.\nThis feature has a high priority, because it transforms the guessing into a game. Without\nthis feature, a Player can make an infinite amount of guesses.\n\n#### Functional\n\n- FREQ-8.1: The win-condition is that the word is completely guessed, either via Game Character guessing\n  or via Game String guessing, before the amount of lives reach zero.\n- FREQ-8.2: If the amount of lives reach zero before the word is guessed, the\n  system shall inform the Player they lost and display the actual word.\n- FREQ-8.3: If the player reaches the win-condition, the system shall inform the\n  Player they won.\n- FREQ-8.4: Reaching win or lose, results in the end of the corresponding Game Instace.\n\n### Graceful exits\n\nThe graceful exits feature provides an indication to the user when the exit was done gracefully.\nThis feature has a low priority, because it does not interfere with the playability of the game.\nHowever, it provides a clear distinction to the Player when the program exists normally and when not.\n\n#### Stimulus/Response\n\nThe player shall get a message on the command-line when the system gracefully exits.\n\n#### Functional\n\n- FREQ-9.1: When the system gracefully exits, it shall thank the Player for playing via\n  a command-line message.\n\n## _Other Nonfunctional Requirements_\n\n### Performance requirements\n\nThe system shall execute the game's logic for each turn in under 2 seconds for input words of length within the range 2-999, on any system with the following minimum configuration, and with available CPU utilization:\n\n- 2 core CPU clocked @2.6Ghz\n- 4GB of DDR3/DDR4 RAM\n- SSD/HDD with 100MB/s write speed\n\n### Security Requirements\n\nThe system shall not use, excluding user input, an amount of memory greater than what specified in the 'Memory Constraints' section and it shall not access unauthorized memory in the user's system.\n\n### Software Quality Attributes\n\nThe system shall be built according to industry standards and its development process shall feature:\n\n- Continuous Integration system\n  - build shall be `passing` before release\n- Code coverage monitoring\n  - test code path coverage shall be over 90% before release\n- reasonable versioning and coding policies including:\n  - meaningful and documented commits\n  - source level documentation for the core functionalities\n  - idiomatic use of the Python language and standard libraries\n  - adherence to PEP8 specification for code formatting\n  - adherence to `flake8` linting specification (no error flags are allowed)\n\n### Business Rules\n\nThe system shall only have one type of user: the Player.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarinoandrea%2Fhangman-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarinoandrea%2Fhangman-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarinoandrea%2Fhangman-cli/lists"}