{"id":17068411,"url":"https://github.com/kylestetz/sentencer","last_synced_at":"2025-04-05T23:08:18.297Z","repository":{"id":21760894,"uuid":"25082967","full_name":"kylestetz/Sentencer","owner":"kylestetz","description":":pencil2: madlibs-style sentence templating in Javascript","archived":false,"fork":false,"pushed_at":"2022-12-03T01:21:02.000Z","size":650,"stargazers_count":381,"open_issues_count":17,"forks_count":38,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-29T22:06:04.298Z","etag":null,"topics":["generative-text","lorem-ipsum","lorem-ipsum-generator","madlibs"],"latest_commit_sha":null,"homepage":"http://kylestetz.github.io/Sentencer","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kylestetz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-11T14:59:50.000Z","updated_at":"2025-02-19T12:22:49.000Z","dependencies_parsed_at":"2023-01-11T21:20:45.387Z","dependency_job_id":null,"html_url":"https://github.com/kylestetz/Sentencer","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylestetz%2FSentencer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylestetz%2FSentencer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylestetz%2FSentencer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylestetz%2FSentencer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kylestetz","download_url":"https://codeload.github.com/kylestetz/Sentencer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411234,"owners_count":20934653,"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","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":["generative-text","lorem-ipsum","lorem-ipsum-generator","madlibs"],"created_at":"2024-10-14T11:13:22.220Z","updated_at":"2025-04-05T23:08:18.282Z","avatar_url":"https://github.com/kylestetz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sentencer\n\n[![Build Status](https://travis-ci.org/kylestetz/Sentencer.svg?branch=master)](https://travis-ci.org/kylestetz/Sentencer)\n\n`sentencer` is a node.js module for madlibs-style sentence templating. It is a simple templating engine that accepts strings with actions embedded in them:\n\n```javascript\n\"This is {{ an_adjective }} sentence.\"\n```\n\nWhere each action returns a random string selected from a list:\n\n```javascript\n\"This is a bankrupt sentence.\"\n```\n\nThink of it as madlibs for Javascript. Want to roll your own lorem ipsum generator? `Sentencer` allows you to write the structure of your sentences and plug in any kind of vocabulary you choose.\n\n`Sentencer` was written for and powers [Metaphorpsum](http://metaphorpsum.com). The noun and adjective lists come from a relatively small curated selection of Ashley Bovan's excellent [Word Lists for Writers](http://www.ashley-bovan.co.uk/words/partsofspeech.html).\n\n### How\n\n`npm install sentencer --save`\n\n```javascript\nvar Sentencer = require('sentencer');\n\nSentencer.make(\"This sentence has {{ a_noun }} and {{ an_adjective }} {{ noun }} in it.\");\n// returns something like \"This sentence has a bat and a finless cinema in it.\"\n```\n\nHere are all of the options, described in detail below.\n\n```javascript\nvar Sentencer = require('sentencer');\n\nSentencer.configure({\n  // the list of nouns to use. Sentencer provides its own if you don't have one!\n  nounList: [],\n\n  // the list of adjectives to use. Again, Sentencer comes with one!\n  adjectiveList: [],\n\n  // additional actions for the template engine to use.\n  // you can also redefine the preset actions here if you need to.\n  // See the \"Add your own actions\" section below.\n  actions: {\n    my_action: function(){\n      return \"something\";\n    }\n  }\n});\n```\n\n### Actions\n\n`Sentencer` works by recognizing \"actions\" within `{{ double_brackets }}`. It replaces these actions with strings. The default actions are `{{ noun }}`, `{{ a_noun }}`, `{{ nouns }}`, `{{ adjective }}`, and `{{ an_adjective }}`, but you can extend `Sentencer` to include any kind of actions you need!\n\nThe default actions will continue to work if you pass in new a `nounList` and/or `adjectiveList` using `Sentencer.configure`.\n\n`Sentencer`'s actions are written semantically so that your sentence template still reads as a sentence. While this was simply a design decision, it does make templates easier to read and you are encouraged to follow this format if you create custom actions.\n\n#### `\"{{ noun }}\"`\n\nReturns a random noun from the noun list.\n\n```javascript\nvar noun = Sentencer.make(\"{{ noun }}\")\n// \"actor\", \"knight\", \"orchid\", \"pizza\", etc.\n```\n\n#### `\"{{ a_noun }}\"`\n\nReturns a random noun from the noun list with \"a\" or \"an\" in front of it.\n\n```javascript\nvar nounWithArticle = Sentencer.make(\"{{ a_noun }}\")\n// \"an actor\", \"a knight\", \"an orchid\", \"a pizza\", etc.\n```\n\n#### `\"{{ nouns }}\"`\n\nReturns the pluralized form of a random noun from the noun list. It's not 100% perfect, but it's probably 97% perfect.\n\n```javascript\nvar pluralNoun = Sentencer.make(\"{{ nouns }}\")\n// \"actors\", \"knights\", \"orchids\", \"pizzas\", etc.\n```\n\n#### `\"{{ adjective }}\"`\n\nReturns a random adjective from the adjective list.\n\n```javascript\nvar adjective = Sentencer.make(\"{{ adjective }}\")\n// \"blending\", \"earthy\", \"rugged\", \"untamed\", etc.\n```\n\n#### `\"{{ an_adjective }}\"`\n\nReturns a random adjective from the adjective list with \"a\" or \"an\" in front of it.\n\n```javascript\nvar adjective = Sentencer.make(\"{{ an_adjective }}\")\n// \"a blending\", \"an earthy\", \"a rugged\", \"an untamed\", etc.\n```\n\n### Add your own actions\n\nWhen configuring `Sentencer` you can provide your own \"actions\", which are just functions that return something. The name of the function that you pass into `actions` is how you will reference it within a sentence template.\n\nHere's an example of an action that returns a random number from 1 to 10.\n\n```javascript\nvar Sentencer = require('sentencer');\n\nSentencer.configure({\n  actions: {\n    number: function() {\n      return Math.floor( Math.random() * 10 ) + 1;\n    }\n  }\n});\n\nconsole.log( Sentencer.make(\"I can count to {{ number }}.\")\n// \"I can count to 5.\"\n```\n\n#### Actions can take arguments\n\nYou can pass arguments into your actions. We can use this to make a smarter version of the random number generator above...\n\n```javascript\nvar Sentencer = require('sentencer');\n\nSentencer.configure({\n  actions: {\n    number: function(min, max) {\n      return Math.floor( Math.random() * (max - min) ) + min;\n    }\n  }\n});\n\nconsole.log( Sentencer.make(\"I can count to {{ number(8, 10) }}.\")\n// \"I can count to 8.\"\n```\n\n### Where are the verbs?\n\nVerb pluralization, singularization, and tense modification are difficult computer science problems. `Sentencer` doesn't aim to solve those problems, however _present tense_ verb pluralization/singularization is an experimental feature of [`natural`](https://github.com/NaturalNode/natural) and could be integrated if necessary.\n\n-----------\n\n`Sentencer` was created and is maintained by [Kyle Stetz](https://github.com/kylestetz). The original prototype came out of [Metaphorpsum](https://github.com/kylestetz/metaphorpsum) but has been rewritten from the ground up.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylestetz%2Fsentencer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkylestetz%2Fsentencer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylestetz%2Fsentencer/lists"}