calyx 0.11.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3a89c9fc6b0ecc0e8779331da13072f11d810eab
-  data.tar.gz: 8a74d06ae8feb2e547426fbf893a3d2922010f29
+  metadata.gz: 75811b39e9ca016645eb82dea083ff50612f8e2b
+  data.tar.gz: af905efd81c6b0e679e2ed333f571fdad65ee8a8
 SHA512:
-  metadata.gz: c178d2441191f82aa308ae5d8599bb904a68128daa636435830b6ec58443cfa3ea1dd9a8e534b206442d658542f4aae8a5d906b9cd0677e22db7e983116529f9
-  data.tar.gz: 8ba8bb5db4ed05e66d9c1fb19986282607d6cbd10fac4de6ed70a18be5ae08b39367fd3931fd8c485b6bfc7687aae7610817547a6668b6de94a078fb843b240e
+  metadata.gz: 97a47ba2a0dcf0d658641ba1f67b3237731132ca0500c92053b86f54a60b2eba7f3181daef54c43f94d40c725915c39a2ae2898d6a639a0399f3910a4d01116f
+  data.tar.gz: 57341f9c8428917d56b33dedd219dd904bca3252b9f2a7d240bcab1a050f8209f7b61ab26d9402b69f029be53d7ffcfcd29b8342777e2de62733e408607af872

data/README.md

@@ -21,7 +21,7 @@ gem 'calyx'
 
 ## Usage
 
-Require the library and inherit from `Calyx::Grammar` to construct a set of rules to generate a text. All grammars require a `start` rule, which specifies the starting point for generating the text structure.
+Require the library and inherit from `Calyx::Grammar` to construct a set of rules to generate a text.
 
 ```ruby
 require 'calyx'
@@ -39,12 +39,12 @@ hello.generate
 # > "Hello world."
 ```
 
-Obviously, this hardcoded sentence isn’t very interesting by itself. Possible variations can be added to the text using the `rule` constructor to provide a named set of text strings and the rule delimiter syntax (`{}`) within the text strings to substitute the generated content of the rule.
+Obviously, this hardcoded sentence isn’t very interesting by itself. Possible variations can be added to the text by adding additional rules which provide a named set of text strings. The rule delimiter syntax (`{}`) can be used to substitute the generated content of other rules.
 
 ```ruby
 class HelloWorld < Calyx::Grammar
   start '{greeting} world.'
-  rule :greeting, 'Hello', 'Hi', 'Hey', 'Yo'
+  greeting 'Hello', 'Hi', 'Hey', 'Yo'
 end
 ```
 
@@ -63,6 +63,17 @@ hello.generate
 # > "Yo world."
 ```
 
+By convention, the `start` rule specifies the default starting point for generating the final text. You can start from any other named rule by passing it explicitly to the generate method.
+
+```ruby
+class HelloWorld < Calyx::Grammar
+  hello 'Hello world.'
+end
+
+hello = HelloWorld.new
+hello.generate(:hello)
+```
+
 ### Block Constructors
 
 As an alternative to subclassing, you can also construct rules unique to an instance by passing a block when initializing the class:
@@ -70,12 +81,44 @@ As an alternative to subclassing, you can also construct rules unique to an inst
 ```ruby
 hello = Calyx::Grammar.new do
   start '{greeting} world.'
-  rule :greeting, 'Hello', 'Hi', 'Hey', 'Yo'
+  greeting 'Hello', 'Hi', 'Hey', 'Yo'
 end
 
 hello.generate
 ```
 
+### External File Formats
+
+In addition to defining grammars in pure Ruby, you can load them from external JSON and YAML files:
+
+```ruby
+hello = Calyx::Grammar.load('hello.yml')
+hello.generate
+```
+
+The format requires a flat map with keys representing the left-hand side named symbols and the values representing the right hand side substitution rules.
+
+In JSON:
+
+```json
+{
+  "start": "{greeting} world.",
+  "greeting": ["Hello", "Hi", "Hey", "Yo"]
+}
+```
+
+In YAML:
+
+```yaml
+---
+start: "{greeting} world."
+greeting:
+  - Hello
+  - Hi
+  - Hey
+  - Yo
+```
+
 ### Nesting and Substitution
 
 Rules are recursive. They can be arbitrarily nested and connected to generate larger and more complex texts.
@@ -83,10 +126,10 @@ Rules are recursive. They can be arbitrarily nested and connected to generate la
 ```ruby
 class HelloWorld < Calyx::Grammar
   start '{greeting} {world_phrase}.'
-  rule :greeting, 'Hello', 'Hi', 'Hey', 'Yo'
-  rule :world_phrase, '{happy_adj} world', '{sad_adj} world', 'world'
-  rule :happy_adj, 'wonderful', 'amazing', 'bright', 'beautiful'
-  rule :sad_adj, 'cruel', 'miserable'
+  greeting 'Hello', 'Hi', 'Hey', 'Yo'
+  world_phrase '{happy_adj} world', '{sad_adj} world', 'world'
+  happy_adj 'wonderful', 'amazing', 'bright', 'beautiful'
+  sad_adj 'cruel', 'miserable'
 end
 ```
 
@@ -96,18 +139,18 @@ Nesting and hierarchy can be manipulated to balance consistency with novelty. Th
 module HelloWorld
   class Sentiment < Calyx::Grammar
     start '{happy_phrase}', '{sad_phrase}'
-    rule :happy_phrase, '{happy_greeting} {happy_adj} world.'
-    rule :happy_greeting, 'Hello', 'Hi', 'Hey', 'Yo'
-    rule :happy_adj, 'wonderful', 'amazing', 'bright', 'beautiful'
-    rule :sad_phrase, '{sad_greeting} {sad_adj} world.'
-    rule :sad_greeting, 'Goodbye', 'So long', 'Farewell'
-    rule :sad_adj, 'cruel', 'miserable'
+    happy_phrase '{happy_greeting} {happy_adj} world.'
+    happy_greeting 'Hello', 'Hi', 'Hey', 'Yo'
+    happy_adj 'wonderful', 'amazing', 'bright', 'beautiful'
+    sad_phrase '{sad_greeting} {sad_adj} world.'
+    sad_greeting 'Goodbye', 'So long', 'Farewell'
+    sad_adj 'cruel', 'miserable'
   end
 
   class Mixed < Calyx::Grammar
     start '{greeting} {adj} world.'
-    rule :greeting, 'Hello', 'Hi', 'Hey', 'Yo', 'Goodbye', 'So long', 'Farewell'
-    rule :adj, 'wonderful', 'amazing', 'bright', 'beautiful', 'cruel', 'miserable'
+    greeting 'Hello', 'Hi', 'Hey', 'Yo', 'Goodbye', 'So long', 'Farewell'
+    adj 'wonderful', 'amazing', 'bright', 'beautiful', 'cruel', 'miserable'
   end
 end
 ```
@@ -147,7 +190,7 @@ class Roll2D6 < Calyx::Grammar
 end
 ```
 
-Or reproduce Gary Gygax’s famous generation table from the original Dungeon Master’s Guide (page 171):
+Or reproduce Gary Gygax’s famous generation table from the original [Dungeon Master’s Guide](https://en.wikipedia.org/wiki/Dungeon_Master%27s_Guide#Advanced_Dungeons_.26_Dragons) (page 171):
 
 ```ruby
 class ChamberOrRoomContents < Calyx::Grammar
@@ -160,12 +203,12 @@ class ChamberOrRoomContents < Calyx::Grammar
     [:treasure, 0.05]
   )
 
-  rule :empty, 'Empty'
-  rule :monster, 'Monster Only'
-  rule :monster_treasure, 'Monster and Treasure'
-  rule :special, 'Special'
-  rule :trick_trap, 'Trick/Trap.'
-  rule :treasure, 'Treasure'
+  empty 'Empty'
+  monster 'Monster Only'
+  monster_treasure 'Monster and Treasure'
+  special 'Special'
+  trick_trap 'Trick/Trap.'
+  treasure 'Treasure'
 end
 ```
 
@@ -176,8 +219,8 @@ Basic rule substitution uses single curly brackets as delimiters for template ex
 ```ruby
 class Fruit < Calyx::Grammar
   start '{colour} {fruit}'
-  rule :colour, 'red', 'green', 'yellow'
-  rule :fruit, 'apple', 'pear', 'tomato'
+  colour 'red', 'green', 'yellow'
+  fruit 'apple', 'pear', 'tomato'
 end
 ```
 
@@ -188,7 +231,7 @@ Dot-notation is supported in template expressions, allowing you to call any avai
 ```ruby
 class Greeting < Calyx::Grammar
   start '{hello.capitalize} there.', 'Why, {hello} there.'
-  rule :hello, 'hello'
+  hello 'hello'
 end
 
 # => "Hello there."
@@ -206,8 +249,9 @@ class Greeting < Calyx::Grammar
   filter :shoutycaps do |input|
     input.upcase
   end
+
   start '{hello.shoutycaps} there.', 'Why, {hello} there.'
-  rule :hello, 'hello'
+  hello 'hello'
 end
 
 # => "HELLO there."
@@ -222,7 +266,7 @@ The mapping shortcut allows you to specify a map of regex patterns pointing to t
 class GreenBottle < Calyx::Grammar
   mapping :pluralize, /(.+)/ => '\\1s'
   start 'One green {bottle}.', 'Two green {bottle.pluralize}.'
-  rule :bottle, 'bottle'
+  bottle 'bottle'
 end
 
 # => "One green bottle."
@@ -243,7 +287,7 @@ end
 class Hello < Calyx::Grammar
   modifier FullStop
   start '{hello.capitalize.full_stop}'
-  rule :hello, 'hello'
+  hello 'hello'
 end
 
 # => "Hello."
@@ -282,7 +326,7 @@ end
 
 class NounsWithArticles < Calyx::Grammar
   start '{fruit.with_indefinite_article.capitalize.full_stop}'
-  rule :fruit, 'apple', 'orange', 'banana', 'pear'
+  fruit 'apple', 'orange', 'banana', 'pear'
 end
 
 # => "An apple."
@@ -372,7 +416,7 @@ Rough plan for stabilising the API and features for a `1.0` release.
 | `0.8`   | ~~method missing metaclass API~~ |
 | `0.9`   | ~~return grammar tree from `#evaluate`, with flattened string from `#generate` being separate~~ |
 | `0.10`  | ~~inject custom string functions for parameterised rules, transforms and mappings~~ |
-| `0.11`  | support YAML format (and JSON?) |
+| `0.11`  | ~~support YAML format (and JSON?)~~ |
 | `1.0`   | API documentation |
 
 ## Credits

data/examples/faker.rb

@@ -0,0 +1,7 @@
+require 'calyx'
+
+faker = Calyx::Grammar.load(__dir__ + '/faker.yml')
+
+puts faker.generate(:full_name)
+puts faker.generate(:email)
+puts faker.generate(:username)

data/examples/faker.yml

@@ -0,0 +1,42 @@
+email: "{username}@{domain}"
+full_name:
+  - "{first_name} {last_name}"
+  - "{first_name} {first_name.chars.first} {last_name}"
+username:
+  - "{first_name.downcase}"
+  - "{first_name.downcase}{number}"
+first_name: [Aaliyah, Aaron, Abagail, Abbey, Abbie, Abbigail, Abby, Abdiel, Abdul, Abdullah, Abe, Abel, Abelardo, Abigail, Abigale, Abigayle, Abner, Abraham, Ada, Adah, Adalberto, Adaline, Adam, Adan, Addie, Addison, Adela, Adelbert, Adele, Adelia, Adeline, Adell, Adella, Adelle, Aditya, Adolf, Adolfo, Adolph, Adolphus, Adonis, Adrain, Adrian, Adriana, Adrianna, Adriel, Adrien, Adrienne, Afton, Aglae, Agnes, Agustin, Agustina, Ahmad, Ahmed, Aida, Aidan, Aiden, Aileen, Aimee, Aisha, Aiyana, Akeem, Al, Alaina, Alan, Alana, Alanis, Alanna, Alayna, Alba, Albert, Alberta, Albertha, Alberto, Albin, Albina, Alda, Alden, Alec, Aleen, Alejandra, Alejandrin, Alek, Alena, Alene, Alessandra, Alessandro, Alessia, Aletha, Alex, Alexa, Alexander, Alexandra, Alexandre, Alexandrea, Alexandria, Alexandrine, Alexandro, Alexane, Alexanne, Alexie, Alexis, Alexys, Alexzander, Alf, Alfonso, Alfonzo, Alford, Alfred, Alfreda, Alfredo, Ali, Alia, Alice, Alicia, Alisa, Alisha, Alison, Alivia, Aliya, Aliyah, Aliza, Alize, Allan, Allen, Allene, Allie, Allison, Ally, Alphonso, Alta, Althea, Alva, Alvah, Alvena, Alvera, Alverta, Alvina, Alvis, Alyce, Alycia, Alysa, Alysha, Alyson, Alysson, Amalia, Amanda, Amani, Amara, Amari, Amaya, Amber, Ambrose, Amelia, Amelie, Amely, America, Americo, Amie, Amina, Amir, Amira, Amiya, Amos, Amparo, Amy, Amya, Ana, Anabel, Anabelle, Anahi, Anais, Anastacio, Anastasia, Anderson, Andre, Andreane, Andreanne, Andres, Andrew, Andy, Angel, Angela, Angelica, Angelina, Angeline, Angelita, Angelo, Angie, Angus, Anibal, Anika, Anissa, Anita, Aniya, Aniyah, Anjali, Anna, Annabel, Annabell, Annabelle, Annalise, Annamae, Annamarie, Anne, Annetta, Annette, Annie, Ansel, Ansley, Anthony, Antoinette, Antone, Antonetta, Antonette, Antonia, Antonietta, Antonina, Antonio, Antwan, Antwon, Anya, April, Ara, Araceli, Aracely, Arch, Archibald, Ardella, Arden, Ardith, Arely, Ari, Ariane, Arianna, Aric, Ariel, Arielle, Arjun, Arlene, Arlie, Arlo, Armand, Armando, Armani, Arnaldo, Arne, Arno, Arnold, Arnoldo, Arnulfo, Aron, Art, Arthur, Arturo, Arvel, Arvid, Arvilla, Aryanna, Asa, Asha, Ashlee, Ashleigh, Ashley, Ashly, Ashlynn, Ashton, Ashtyn, Asia, Assunta, Astrid, Athena, Aubree, Aubrey, Audie, Audra, Audreanne, Audrey, August, Augusta, Augustine, Augustus, Aurelia, Aurelie, Aurelio, Aurore, Austen, Austin, Austyn, Autumn, Ava, Avery, Avis, Axel, Ayana, Ayden, Ayla, Aylin, Baby, Bailee, Bailey, Barbara, Barney, Baron, Barrett, Barry, Bart, Bartholome, Barton, Baylee, Beatrice, Beau, Beaulah, Bell, Bella, Belle, Ben, Benedict, Benjamin, Bennett, Bennie, Benny, Benton, Berenice, Bernadette, Bernadine, Bernard, Bernardo, Berneice, Bernhard, Bernice, Bernie, Berniece, Bernita, Berry, Bert, Berta, Bertha, Bertram, Bertrand, Beryl, Bessie, Beth, Bethany, Bethel, Betsy, Bette, Bettie, Betty, Bettye, Beulah, Beverly, Bianka, Bill, Billie, Billy, Birdie, Blair, Blaise, Blake, Blanca, Blanche, Blaze, Bo, Bobbie, Bobby, Bonita, Bonnie, Boris, Boyd, Brad, Braden, Bradford, Bradley, Bradly, Brady, Braeden, Brain, Brandi, Brando, Brandon, Brandt, Brandy, Brandyn, Brannon, Branson, Brant, Braulio, Braxton, Brayan, Breana, Breanna, Breanne, Brenda, Brendan, Brenden, Brendon, Brenna, Brennan, Brennon, Brent, Bret, Brett, Bria, Brian, Briana, Brianne, Brice, Bridget, Bridgette, Bridie, Brielle, Brigitte, Brionna, Brisa, Britney, Brittany, Brock, Broderick, Brody, Brook, Brooke, Brooklyn, Brooks, Brown, Bruce, Bryana, Bryce, Brycen, Bryon, Buck, Bud, Buddy, Buford, Bulah, Burdette, Burley, Burnice, Buster, Cade, Caden, Caesar, Caitlyn, Cale, Caleb, Caleigh, Cali, Calista, Callie, Camden, Cameron, Camila, Camilla, Camille, Camren, Camron, Camryn, Camylle, Candace, Candelario, Candice, Candida, Candido, Cara, Carey, Carissa, Carlee, Carleton, Carley, Carli, Carlie, Carlo, Carlos, Carlotta, Carmel, Carmela, Carmella, Carmelo, Carmen, Carmine, Carol, Carolanne, Carole, Carolina, Caroline, Carolyn, Carolyne, Carrie, Carroll, Carson, Carter, Cary, Casandra, Casey, Casimer, Casimir, Casper, Cassandra, Cassandre, Cassidy, Cassie, Catalina, Caterina, Catharine, Catherine, Cathrine, Cathryn, Cathy, Cayla, Ceasar, Cecelia, Cecil, Cecile, Cecilia, Cedrick, Celestine, Celestino, Celia, Celine, Cesar, Chad, Chadd, Chadrick, Chaim, Chance, Chandler, Chanel, Chanelle, Charity, Charlene, Charles, Charley, Charlie, Charlotte, Chase, Chasity, Chauncey, Chaya, Chaz, Chelsea, Chelsey, Chelsie, Chesley, Chester, Chet, Cheyanne, Cheyenne, Chloe, Chris, Christ, Christa, Christelle, Christian, Christiana, Christina, Christine, Christop, Christophe, Christopher, Christy, Chyna, Ciara, Cicero, Cielo, Cierra, Cindy, Citlalli, Clair, Claire, Clara, Clarabelle, Clare, Clarissa, Clark, Claud, Claude, Claudia, Claudie, Claudine, Clay, Clemens, Clement, Clementina, Clementine, Clemmie, Cleo, Cleora, Cleta, Cletus, Cleve, Cleveland, Clifford, Clifton, Clint, Clinton, Clotilde, Clovis, Cloyd, Clyde, Coby, Cody, Colby, Cole, Coleman, Colin, Colleen, Collin, Colt, Colten, Colton, Columbus, Concepcion, Conner, Connie, Connor, Conor, Conrad, Constance, Constantin, Consuelo, Cooper, Cora, Coralie, Corbin, Cordelia, Cordell, Cordia, Cordie, Corene, Corine, Cornelius, Cornell, Corrine, Cortez, Cortney, Cory, Coty, Courtney, Coy, Craig, Crawford, Creola, Cristal, Cristian, Cristina, Cristobal, Cristopher, Cruz, Crystal, Crystel, Cullen, Curt, Curtis, Cydney, Cynthia, Cyril, Cyrus, Dagmar, Dahlia, Daija, Daisha, Daisy, Dakota, Dale, Dallas, Dallin, Dalton, Damaris, Dameon, Damian, Damien, Damion, Damon, Dan, Dana, Dandre, Dane, D'angelo, Dangelo, Danial, Daniela, Daniella, Danielle, Danika, Dannie, Danny, Dante, Danyka, Daphne, Daphnee, Daphney, Darby, Daren, Darian, Dariana, Darien, Dario, Darion, Darius, Darlene, Daron, Darrel, Darrell, Darren, Darrick, Darrin, Darrion, Darron, Darryl, Darwin, Daryl, Dashawn, Dasia, Dave, David, Davin, Davion, Davon, Davonte, Dawn, Dawson, Dax, Dayana, Dayna, Dayne, Dayton, Dean, Deangelo, Deanna, Deborah, Declan, Dedric, Dedrick, Dee, Deion, Deja, Dejah, Dejon, Dejuan, Delaney, Delbert, Delfina, Delia, Delilah, Dell, Della, Delmer, Delores, Delpha, Delphia, Delphine, Delta, Demarco, Demarcus, Demario, Demetris, Demetrius, Demond, Dena, Denis, Dennis, Deon, Deondre, Deontae, Deonte, Dereck, Derek, Derick, Deron, Derrick, Deshaun, Deshawn, Desiree, Desmond, Dessie, Destany, Destin, Destinee, Destiney, Destini, Destiny, Devan, Devante, Deven, Devin, Devon, Devonte, Devyn, Dewayne, Dewitt, Dexter, Diamond, Diana, Dianna, Diego, Dillan, Dillon, Dimitri, Dina, Dino, Dion, Dixie, Dock, Dolly, Dolores, Domenic, Domenica, Domenick, Domenico, Domingo, Dominic, Dominique, Don, Donald, Donato, Donavon, Donna, Donnell, Donnie, Donny, Dora, Dorcas, Dorian, Doris, Dorothea, Dorothy, Dorris, Dortha, Dorthy, Doug, Douglas, Dovie, Doyle, Drake, Drew, Duane, Dudley, Dulce, Duncan, Durward, Dustin, Dusty, Dwight, Dylan, Earl, Earlene, Earline, Earnest, Earnestine, Easter, Easton, Ebba, Ebony, Ed, Eda, Edd, Eddie, Eden, Edgar, Edgardo, Edison, Edmond, Edmund, Edna, Eduardo, Edward, Edwardo, Edwin, Edwina, Edyth, Edythe, Effie, Efrain, Efren, Eileen, Einar, Eino, Eladio, Elaina, Elbert, Elda, Eldon, Eldora, Eldred, Eldridge, Eleanora, Eleanore, Eleazar, Electa, Elena, Elenor, Elenora, Eleonore, Elfrieda, Eli, Elian, Eliane, Elias, Eliezer, Elijah, Elinor, Elinore, Elisa, Elisabeth, Elise, Eliseo, Elisha, Elissa, Eliza, Elizabeth, Ella, Ellen, Ellie, Elliot, Elliott, Ellis, Ellsworth, Elmer, Elmira, Elmo, Elmore, Elna, Elnora, Elody, Eloisa, Eloise, Elouise, Eloy, Elroy, Elsa, Else, Elsie, Elta, Elton, Elva, Elvera, Elvie, Elvis, Elwin, Elwyn, Elyse, Elyssa, Elza, Emanuel, Emelia, Emelie, Emely, Emerald, Emerson, Emery, Emie, Emil, Emile, Emilia, Emiliano, Emilie, Emilio, Emily, Emma, Emmalee, Emmanuel, Emmanuelle, Emmet, Emmett, Emmie, Emmitt, Emmy, Emory, Ena, Enid, Enoch, Enola, Enos, Enrico, Enrique, Ephraim, Era, Eriberto, Eric, Erica, Erich, Erick, Ericka, Erik, Erika, Erin, Erling, Erna, Ernest, Ernestina, Ernestine, Ernesto, Ernie, Ervin, Erwin, Eryn, Esmeralda, Esperanza, Esta, Esteban, Estefania, Estel, Estell, Estella, Estelle, Estevan, Esther, Estrella, Etha, Ethan, Ethel, Ethelyn, Ethyl, Ettie, Eudora, Eugene, Eugenia, Eula, Eulah, Eulalia, Euna, Eunice, Eusebio, Eva, Evalyn, Evan, Evangeline, Evans, Eve, Eveline, Evelyn, Everardo, Everett, Everette, Evert, Evie, Ewald, Ewell, Ezekiel, Ezequiel, Ezra, Fabian, Fabiola, Fae, Fannie, Fanny, Fatima, Faustino, Fausto, Favian, Fay, Faye, Federico, Felicia, Felicita, Felicity, Felipa, Felipe, Felix, Felton, Fermin, Fern, Fernando, Ferne, Fidel, Filiberto, Filomena, Finn, Fiona, Flavie, Flavio, Fleta, Fletcher, Flo, Florence, Florencio, Florian, Florida, Florine, Flossie, Floy, Floyd, Ford, Forest, Forrest, Foster, Frances, Francesca, Francesco, Francis, Francisca, Francisco, Franco, Frank, Frankie, Franz, Fred, Freda, Freddie, Freddy, Frederic, Frederick, Frederik, Frederique, Fredrick, Fredy, Freeda, Freeman, Freida, Frida, Frieda, Friedrich, Fritz, Furman, Gabe, Gabriel, Gabriella, Gabrielle, Gaetano, Gage, Gail, Gardner, Garett, Garfield, Garland, Garnet, Garnett, Garret, Garrett, Garrick, Garrison, Garry, Garth, Gaston, Gavin, Gay, Gayle, Gaylord, Gene, General, Genesis, Genevieve, Gennaro, Genoveva, Geo, Geoffrey, George, Georgette, Georgiana, Georgianna, Geovanni, Geovanny, Geovany, Gerald, Geraldine, Gerard, Gerardo, Gerda, Gerhard, Germaine, German, Gerry, Gerson, Gertrude, Gia, Gianni, Gideon, Gilbert, Gilberto, Gilda, Giles, Gillian, Gina, Gino, Giovani, Giovanna, Giovanni, Giovanny, Gisselle, Giuseppe, Gladyce, Gladys, Glen, Glenda, Glenna, Glennie, Gloria, Godfrey, Golda, Golden, Gonzalo, Gordon, Grace, Gracie, Graciela, Grady, Graham, Grant, Granville, Grayce, Grayson, Green, Greg, Gregg, Gregoria, Gregorio, Gregory, Greta, Gretchen, Greyson, Griffin, Grover, Guadalupe, Gudrun, Guido, Guillermo, Guiseppe, Gunnar, Gunner, Gus, Gussie, Gust, Gustave, Guy, Gwen, Gwendolyn, Hadley, Hailee, Hailey, Hailie, Hal, Haleigh, Haley, Halie, Halle, Hallie, Hank, Hanna, Hannah, Hans, Hardy, Harley, Harmon, Harmony, Harold, Harrison, Harry, Harvey, Haskell, Hassan, Hassie, Hattie, Haven, Hayden, Haylee, Hayley, Haylie, Hazel, Hazle, Heath, Heather, Heaven, Heber, Hector, Heidi, Helen, Helena, Helene, Helga, Hellen, Helmer, Heloise, Henderson, Henri, Henriette, Henry, Herbert, Herman, Hermann, Hermina, Herminia, Herminio, Hershel, Herta, Hertha, Hester, Hettie, Hilario, Hilbert, Hilda, Hildegard, Hillard, Hillary, Hilma, Hilton, Hipolito, Hiram, Hobart, Holden, Hollie, Hollis, Holly, Hope, Horace, Horacio, Hortense, Hosea, Houston, Howard, Howell, Hoyt, Hubert, Hudson, Hugh, Hulda, Humberto, Hunter, Hyman, Ian, Ibrahim, Icie, Ida, Idell, Idella, Ignacio, Ignatius, Ike, Ila, Ilene, Iliana, Ima, Imani, Imelda, Immanuel, Imogene, Ines, Irma, Irving, Irwin, Isaac, Isabel, Isabell, Isabella, Isabelle, Isac, Isadore, Isai, Isaiah, Isaias, Isidro, Ismael, Isobel, Isom, Israel, Issac, Itzel, Iva, Ivah, Ivory, Ivy, Izabella, Izaiah, Jabari, Jace, Jacey, Jacinthe, Jacinto, Jack, Jackeline, Jackie, Jacklyn, Jackson, Jacky, Jaclyn, Jacquelyn, Jacques, Jacynthe, Jada, Jade, Jaden, Jadon, Jadyn, Jaeden, Jaida, Jaiden, Jailyn, Jaime, Jairo, Jakayla, Jake, Jakob, Jaleel, Jalen, Jalon, Jalyn, Jamaal, Jamal, Jamar, Jamarcus, Jamel, Jameson, Jamey, Jamie, Jamil, Jamir, Jamison, Jammie, Jan, Jana, Janae, Jane, Janelle, Janessa, Janet, Janice, Janick, Janie, Janis, Janiya, Jannie, Jany, Jaquan, Jaquelin, Jaqueline, Jared, Jaren, Jarod, Jaron, Jarred, Jarrell, Jarret, Jarrett, Jarrod, Jarvis, Jasen, Jasmin, Jason, Jasper, Jaunita, Javier, Javon, Javonte, Jay, Jayce, Jaycee, Jayda, Jayde, Jayden, Jaydon, Jaylan, Jaylen, Jaylin, Jaylon, Jayme, Jayne, Jayson, Jazlyn, Jazmin, Jazmyn, Jazmyne, Jean, Jeanette, Jeanie, Jeanne, Jed, Jedediah, Jedidiah, Jeff, Jefferey, Jeffery, Jeffrey, Jeffry, Jena, Jenifer, Jennie, Jennifer, Jennings, Jennyfer, Jensen, Jerad, Jerald, Jeramie, Jeramy, Jerel, Jeremie, Jeremy, Jermain, Jermaine, Jermey, Jerod, Jerome, Jeromy, Jerrell, Jerrod, Jerrold, Jerry, Jess, Jesse, Jessica, Jessie, Jessika, Jessy, Jessyca, Jesus, Jett, Jettie, Jevon, Jewel, Jewell, Jillian, Jimmie, Jimmy, Jo, Joan, Joana, Joanie, Joanne, Joannie, Joanny, Joany, Joaquin, Jocelyn, Jodie, Jody, Joe, Joel, Joelle, Joesph, Joey, Johan, Johann, Johanna, Johathan, John, Johnathan, Johnathon, Johnnie, Johnny, Johnpaul, Johnson, Jolie, Jon, Jonas, Jonatan, Jonathan, Jonathon, Jordan, Jordane, Jordi, Jordon, Jordy, Jordyn, Jorge, Jose, Josefa, Josefina, Joseph, Josephine, Josh, Joshua, Joshuah, Josiah, Josiane, Josianne, Josie, Josue, Jovan, Jovani, Jovanny, Jovany, Joy, Joyce, Juana, Juanita, Judah, Judd, Jude, Judge, Judson, Judy, Jules, Julia, Julian, Juliana, Julianne, Julie, Julien, Juliet, Julio, Julius, June, Junior, Junius, Justen, Justice, Justina, Justine, Juston, Justus, Justyn, Juvenal, Juwan, Kacey, Kaci, Kacie, Kade, Kaden, Kadin, Kaela, Kaelyn, Kaia, Kailee, Kailey, Kailyn, Kaitlin, Kaitlyn, Kale, Kaleb, Kaleigh, Kaley, Kali, Kallie, Kameron, Kamille, Kamren, Kamron, Kamryn, Kane, Kara, Kareem, Karelle, Karen, Kari, Kariane, Karianne, Karina, Karine, Karl, Karlee, Karley, Karli, Karlie, Karolann, Karson, Kasandra, Kasey, Kassandra, Katarina, Katelin, Katelyn, Katelynn, Katharina, Katherine, Katheryn, Kathleen, Kathlyn, Kathryn, Kathryne, Katlyn, Katlynn, Katrina, Katrine, Kattie, Kavon, Kay, Kaya, Kaycee, Kayden, Kayla, Kaylah, Kaylee, Kayleigh, Kayley, Kayli, Kaylie, Kaylin, Keagan, Keanu, Keara, Keaton, Keegan, Keeley, Keely, Keenan, Keira, Keith, Kellen, Kelley, Kelli, Kellie, Kelly, Kelsi, Kelsie, Kelton, Kelvin, Ken, Kendall, Kendra, Kendrick, Kenna, Kennedi, Kennedy, Kenneth, Kennith, Kenny, Kenton, Kenya, Kenyatta, Kenyon, Keon, Keshaun, Keshawn, Keven, Kevin, Kevon, Keyon, Keyshawn, Khalid, Khalil, Kian, Kiana, Kianna, Kiara, Kiarra, Kiel, Kiera, Kieran, Kiley, Kim, Kimberly, King, Kip, Kira, Kirk, Kirsten, Kirstin, Kitty, Kobe, Koby, Kody, Kolby, Kole, Korbin, Korey, Kory, Kraig, Kris, Krista, Kristian, Kristin, Kristina, Kristofer, Kristoffer, Kristopher, Kristy, Krystal, Krystel, Krystina, Kurt, Kurtis, Kyla, Kyle, Kylee, Kyleigh, Kyler, Kylie, Kyra, Lacey, Lacy, Ladarius, Lafayette, Laila, Laisha, Lamar, Lambert, Lamont, Lance, Landen, Lane, Laney, Larissa, Laron, Larry, Larue, Laura, Laurel, Lauren, Laurence, Lauretta, Lauriane, Laurianne, Laurie, Laurine, Laury, Lauryn, Lavada, Lavern, Laverna, Laverne, Lavina, Lavinia, Lavon, Lavonne, Lawrence, Lawson, Layla, Layne, Lazaro, Lea, Leann, Leanna, Leanne, Leatha, Leda, Lee, Leif, Leila, Leilani, Lela, Lelah, Leland, Lelia, Lempi, Lemuel, Lenna, Lennie, Lenny, Lenora, Lenore, Leo, Leola, Leon, Leonard, Leonardo, Leone, Leonel, Leonie, Leonor, Leonora, Leopold, Leopoldo, Leora, Lera, Lesley, Leslie, Lesly, Lessie, Lester, Leta, Letha, Letitia, Levi, Lew, Lewis, Lexi, Lexie, Lexus, Lia, Liam, Liana, Libbie, Libby, Lila, Lilian, Liliana, Liliane, Lilla, Lillian, Lilliana, Lillie, Lilly, Lily, Lilyan, Lina, Lincoln, Linda, Lindsay, Lindsey, Linnea, Linnie, Linwood, Lionel, Lisa, Lisandro, Lisette, Litzy, Liza, Lizeth, Lizzie, Llewellyn, Lloyd, Logan, Lois, Lola, Lolita, Loma, Lon, London, Lonie, Lonnie, Lonny, Lonzo, Lora, Loraine, Loren, Lorena, Lorenz, Lorenza, Lorenzo, Lori, Lorine, Lorna, Lottie, Lou, Louie, Louisa, Lourdes, Louvenia, Lowell, Loy, Loyal, Loyce, Lucas, Luciano, Lucie, Lucienne, Lucile, Lucinda, Lucio, Lucious, Lucius, Lucy, Ludie, Ludwig, Lue, Luella, Luigi, Luis, Luisa, Lukas, Lula, Lulu, Luna, Lupe, Lura, Lurline, Luther, Luz, Lyda, Lydia, Lyla, Lynn, Lyric, Lysanne, Mabel, Mabelle, Mable, Mac, Macey, Maci, Macie, Mack, Mackenzie, Macy, Madaline, Madalyn, Maddison, Madeline, Madelyn, Madelynn, Madge, Madie, Madilyn, Madisen, Madison, Madisyn, Madonna, Madyson, Mae, Maegan, Maeve, Mafalda, Magali, Magdalen, Magdalena, Maggie, Magnolia, Magnus, Maia, Maida, Maiya, Major, Makayla, Makenna, Makenzie, Malachi, Malcolm, Malika, Malinda, Mallie, Mallory, Malvina, Mandy, Manley, Manuel, Manuela, Mara, Marc, Marcel, Marcelina, Marcelino, Marcella, Marcelle, Marcellus, Marcelo, Marcia, Marco, Marcos, Marcus, Margaret, Margarete, Margarett, Margaretta, Margarette, Margarita, Marge, Margie, Margot, Margret, Marguerite, Maria, Mariah, Mariam, Marian, Mariana, Mariane, Marianna, Marianne, Mariano, Maribel, Marie, Mariela, Marielle, Marietta, Marilie, Marilou, Marilyne, Marina, Mario, Marion, Marisa, Marisol, Maritza, Marjolaine, Marjorie, Marjory, Mark, Markus, Marlee, Marlen, Marlene, Marley, Marlin, Marlon, Marques, Marquis, Marquise, Marshall, Marta, Martin, Martina, Martine, Marty, Marvin, Mary, Maryam, Maryjane, Maryse, Mason, Mateo, Mathew, Mathias, Mathilde, Matilda, Matilde, Matt, Matteo, Mattie, Maud, Maude, Maudie, Maureen, Maurice, Mauricio, Maurine, Maverick, Mavis, Max, Maxie, Maxime, Maximilian, Maximillia, Maximillian, Maximo, Maximus, Maxine, Maxwell, May, Maya, Maybell, Maybelle, Maye, Maymie, Maynard, Mayra, Mazie, Mckayla, Mckenna, Mckenzie, Meagan, Meaghan, Meda, Megane, Meggie, Meghan, Mekhi, Melany, Melba, Melisa, Melissa, Mellie, Melody, Melvin, Melvina, Melyna, Melyssa, Mercedes, Meredith, Merl, Merle, Merlin, Merritt, Mertie, Mervin, Meta, Mia, Micaela, Micah, Michael, Michaela, Michale, Micheal, Michel, Michele, Michelle, Miguel, Mikayla, Mike, Mikel, Milan, Miles, Milford, Miller, Millie, Milo, Milton, Mina, Minerva, Minnie, Miracle, Mireille, Mireya, Misael, Missouri, Misty, Mitchel, Mitchell, Mittie, Modesta, Modesto, Mohamed, Mohammad, Mohammed, Moises, Mollie, Molly, Mona, Monica, Monique, Monroe, Monserrat, Monserrate, Montana, Monte, Monty, Morgan, Moriah, Morris, Mortimer, Morton, Mose, Moses, Moshe, Mossie, Mozell, Mozelle, Muhammad, Muriel, Murl, Murphy, Murray, Mustafa, Mya, Myah, Mylene, Myles, Myra, Myriam, Myrl, Myrna, Myron, Myrtice, Myrtie, Myrtis, Myrtle, Nadia, Nakia, Name, Nannie, Naomi, Naomie, Napoleon, Narciso, Nash, Nasir, Nat, Natalia, Natalie, Natasha, Nathan, Nathanael, Nathanial, Nathaniel, Nathen, Nayeli, Neal, Ned, Nedra, Neha, Neil, Nelda, Nella, Nelle, Nellie, Nels, Nelson, Neoma, Nestor, Nettie, Neva, Newell, Newton, Nia, Nicholas, Nicholaus, Nichole, Nick, Nicklaus, Nickolas, Nico, Nicola, Nicolas, Nicole, Nicolette, Nigel, Nikita, Nikki, Nikko, Niko, Nikolas, Nils, Nina, Noah, Noble, Noe, Noel, Noelia, Noemi, Noemie, Noemy, Nola, Nolan, Nona, Nora, Norbert, Norberto, Norene, Norma, Norris, Norval, Norwood, Nova, Novella, Nya, Nyah, Nyasia, Obie, Oceane, Ocie, Octavia, Oda, Odell, Odessa, Odie, Ofelia, Okey, Ola, Olaf, Ole, Olen, Oleta, Olga, Olin, Oliver, Ollie, Oma, Omari, Omer, Ona, Onie, Opal, Ophelia, Ora, Oral, Oran, Oren, Orie, Orin, Orion, Orland, Orlando, Orlo, Orpha, Orrin, Orval, Orville, Osbaldo, Osborne, Oscar, Osvaldo, Oswald, Oswaldo, Otha, Otho, Otilia, Otis, Ottilie, Ottis, Otto, Ova, Owen, Ozella, Ozzie, Pablo, Paige, Palma, Pamela, Pansy, Paolo, Paris, Parker, Pascale, Pasquale, Pat, Patience, Patricia, Patrick, Patsy, Pattie, Paul, Paula, Pauline, Paxton, Payton, Pearl, Pearlie, Pearline, Pedro, Peggie, Penelope, Percival, Percy, Perry, Pete, Peter, Petra, Peyton, Philip, Phoebe, Phyllis, Pierce, Pierre, Pietro, Pink, Pinkie, Piper, Polly, Porter, Precious, Presley, Preston, Price, Prince, Princess, Priscilla, Providenci, Prudence, Queen, Queenie, Quentin, Quincy, Quinn, Quinten, Quinton, Rachael, Rachel, Rachelle, Rae, Raegan, Rafael, Rafaela, Raheem, Rahsaan, Rahul, Raina, Raleigh, Ralph, Ramiro, Ramon, Ramona, Randal, Randall, Randi, Randy, Ransom, Raoul, Raphael, Raphaelle, Raquel, Rashad, Rashawn, Rasheed, Raul, Raven, Ray, Raymond, Raymundo, Reagan, Reanna, Reba, Rebeca, Rebecca, Rebeka, Rebekah, Reece, Reed, Reese, Regan, Reggie, Reginald, Reid, Reilly, Reina, Reinhold, Remington, Rene, Renee, Ressie, Reta, Retha, Retta, Reuben, Reva, Rex, Rey, Reyes, Reymundo, Reyna, Reynold, Rhea, Rhett, Rhianna, Rhiannon, Rhoda, Ricardo, Richard, Richie, Richmond, Rick, Rickey, Rickie, Ricky, Rico, Rigoberto, Riley, Rita, River, Robb, Robbie, Robert, Roberta, Roberto, Robin, Robyn, Rocio, Rocky, Rod, Roderick, Rodger, Rodolfo, Rodrick, Rodrigo, Roel, Rogelio, Roger, Rogers, Rolando, Rollin, Roma, Romaine, Roman, Ron, Ronaldo, Ronny, Roosevelt, Rory, Rosa, Rosalee, Rosalia, Rosalind, Rosalinda, Rosalyn, Rosamond, Rosanna, Rosario, Roscoe, Rose, Rosella, Roselyn, Rosemarie, Rosemary, Rosendo, Rosetta, Rosie, Rosina, Roslyn, Ross, Rossie, Rowan, Rowena, Rowland, Roxane, Roxanne, Roy, Royal, Royce, Rozella, Ruben, Rubie, Ruby, Rubye, Rudolph, Rudy, Rupert, Russ, Russel, Russell, Rusty, Ruth, Ruthe, Ruthie, Ryan, Ryann, Ryder, Rylan, Rylee, Ryleigh, Ryley, Sabina, Sabrina, Sabryna, Sadie, Sadye, Sage, Saige, Sallie, Sally, Salma, Salvador, Salvatore, Sam, Samanta, Samantha, Samara, Samir, Sammie, Sammy, Samson, Sandra, Sandrine, Sandy, Sanford, Santa, Santiago, Santina, Santino, Santos, Sarah, Sarai, Sarina, Sasha, Saul, Savanah, Savanna, Savannah, Savion, Scarlett, Schuyler, Scot, Scottie, Scotty, Seamus, Sean, Sebastian, Sedrick, Selena, Selina, Selmer, Serena, Serenity, Seth, Shad, Shaina, Shakira, Shana, Shane, Shanel, Shanelle, Shania, Shanie, Shaniya, Shanna, Shannon, Shanny, Shanon, Shany, Sharon, Shaun, Shawn, Shawna, Shaylee, Shayna, Shayne, Shea, Sheila, Sheldon, Shemar, Sheridan, Sherman, Sherwood, Shirley, Shyann, Shyanne, Sibyl, Sid, Sidney, Sienna, Sierra, Sigmund, Sigrid, Sigurd, Silas, Sim, Simeon, Simone, Sincere, Sister, Skye, Skyla, Skylar, Sofia, Soledad, Solon, Sonia, Sonny, Sonya, Sophia, Sophie, Spencer, Stacey, Stacy, Stan, Stanford, Stanley, Stanton, Stefan, Stefanie, Stella, Stephan, Stephania, Stephanie, Stephany, Stephen, Stephon, Sterling, Steve, Stevie, Stewart, Stone, Stuart, Summer, Sunny, Susan, Susana, Susanna, Susie, Suzanne, Sven, Syble, Sydnee, Sydney, Sydni, Sydnie, Sylvan, Sylvester, Sylvia, Tabitha, Tad, Talia, Talon, Tamara, Tamia, Tania, Tanner, Tanya, Tara, Taryn, Tate, Tatum, Tatyana, Taurean, Tavares, Taya, Taylor, Teagan, Ted, Telly, Terence, Teresa, Terrance, Terrell, Terrence, Terrill, Terry, Tess, Tessie, Tevin, Thad, Thaddeus, Thalia, Thea, Thelma, Theo, Theodora, Theodore, Theresa, Therese, Theresia, Theron, Thomas, Thora, Thurman, Tia, Tiana, Tianna, Tiara, Tierra, Tiffany, Tillman, Timmothy, Timmy, Timothy, Tina, Tito, Titus, Tobin, Toby, Tod, Tom, Tomas, Tomasa, Tommie, Toney, Toni, Tony, Torey, Torrance, Torrey, Toy, Trace, Tracey, Tracy, Travis, Travon, Tre, Tremaine, Tremayne, Trent, Trenton, Tressa, Tressie, Treva, Trever, Trevion, Trevor, Trey, Trinity, Trisha, Tristian, Tristin, Triston, Troy, Trudie, Trycia, Trystan, Turner, Twila, Tyler, Tyra, Tyree, Tyreek, Tyrel, Tyrell, Tyrese, Tyrique, Tyshawn, Tyson, Ubaldo, Ulices, Ulises, Una, Unique, Urban, Uriah, Uriel, Ursula, Vada, Valentin, Valentina, Valentine, Valerie, Vallie, Van, Vance, Vanessa, Vaughn, Veda, Velda, Vella, Velma, Velva, Vena, Verda, Verdie, Vergie, Verla, Verlie, Vern, Verna, Verner, Vernice, Vernie, Vernon, Verona, Veronica, Vesta, Vicenta, Vicente, Vickie, Vicky, Victor, Victoria, Vida, Vidal, Vilma, Vince, Vincent, Vincenza, Vincenzo, Vinnie, Viola, Violet, Violette, Virgie, Virgil, Virginia, Virginie, Vita, Vito, Viva, Vivian, Viviane, Vivianne, Vivien, Vivienne, Vladimir, Wade, Waino, Waldo, Walker, Wallace, Walter, Walton, Wanda, Ward, Warren, Watson, Wava, Waylon, Wayne, Webster, Weldon, Wellington, Wendell, Wendy, Werner, Westley, Weston, Whitney, Wilber, Wilbert, Wilburn, Wiley, Wilford, Wilfred, Wilfredo, Wilfrid, Wilhelm, Wilhelmine, Will, Willa, Willard, William, Willie, Willis, Willow, Willy, Wilma, Wilmer, Wilson, Wilton, Winfield, Winifred, Winnifred, Winona, Winston, Woodrow, Wyatt, Wyman, Xander, Xavier, Xzavier, Yadira, Yasmeen, Yasmin, Yasmine, Yazmin, Yesenia, Yessenia, Yolanda, Yoshiko, Yvette, Yvonne, Zachariah, Zachary, Zachery, Zack, Zackary, Zackery, Zakary, Zander, Zane, Zaria, Zechariah, Zelda, Zella, Zelma, Zena, Zetta, Zion, Zita, Zoe, Zoey, Zoie, Zoila, Zola, Zora, Zula]
+last_name: [Abbott, Abernathy, Abshire, Adams, Altenwerth, Anderson, Ankunding, Armstrong, Auer, Aufderhar, Bahringer, Bailey, Balistreri, Barrows, Bartell, Bartoletti, Barton, Bashirian, Batz, Bauch, Baumbach, Bayer, Beahan, Beatty, Bechtelar, Becker, Bednar, Beer, Beier, Berge, Bergnaum, Bergstrom, Bernhard, Bernier, Bins, Blanda, Blick, Block, Bode, Boehm, Bogan, Bogisich, Borer, Bosco, Botsford, Boyer, Boyle, Bradtke, Brakus, Braun, Breitenberg, Brekke, Brown, Bruen, Buckridge, Carroll, Carter, Cartwright, Casper, Cassin, Champlin, Christiansen, Cole, Collier, Collins, Conn, Connelly, Conroy, Considine, Corkery, Cormier, Corwin, Cremin, Crist, Crona, Cronin, Crooks, Cruickshank, Cummerata, Cummings, Dach, D'Amore, Daniel, Dare, Daugherty, Davis, Deckow, Denesik, Dibbert, Dickens, Dicki, Dickinson, Dietrich, Donnelly, Dooley, Douglas, Doyle, DuBuque, Durgan, Ebert, Effertz, Eichmann, Emard, Emmerich, Erdman, Ernser, Fadel, Fahey, Farrell, Fay, Feeney, Feest, Feil, Ferry, Fisher, Flatley, Frami, Franecki, Friesen, Fritsch, Funk, Gaylord, Gerhold, Gerlach, Gibson, Gislason, Gleason, Gleichner, Glover, Goldner, Goodwin, Gorczany, Gottlieb, Goyette, Grady, Graham, Grant, Green, Greenfelder, Greenholt, Grimes, Gulgowski, Gusikowski, Gutkowski, Gutmann, Haag, Hackett, Hagenes, Hahn, Haley, Halvorson, Hamill, Hammes, Hand, Hane, Hansen, Harber, Harris, Hartmann, Harvey, Hauck, Hayes, Heaney, Heathcote, Hegmann, Heidenreich, Heller, Herman, Hermann, Hermiston, Herzog, Hessel, Hettinger, Hickle, Hilll, Hills, Hilpert, Hintz, Hirthe, Hodkiewicz, Hoeger, Homenick, Hoppe, Howe, Howell, Hudson, Huel, Huels, Hyatt, Jacobi, Jacobs, Jacobson, Jakubowski, Jaskolski, Jast, Jenkins, Jerde, Johns, Johnson, Johnston, Jones, Kassulke, Kautzer, Keebler, Keeling, Kemmer, Kerluke, Kertzmann, Kessler, Kiehn, Kihn, Kilback, King, Kirlin, Klein, Kling, Klocko, Koch, Koelpin, Koepp, Kohler, Konopelski, Koss, Kovacek, Kozey, Krajcik, Kreiger, Kris, Kshlerin, Kub, Kuhic, Kuhlman, Kuhn, Kulas, Kunde, Kunze, Kuphal, Kutch, Kuvalis, Labadie, Lakin, Lang, Langosh, Langworth, Larkin, Larson, Leannon, Lebsack, Ledner, Leffler, Legros, Lehner, Lemke, Lesch, Leuschke, Lind, Lindgren, Littel, Little, Lockman, Lowe, Lubowitz, Lueilwitz, Luettgen, Lynch, Macejkovic, MacGyver, Maggio, Mann, Mante, Marks, Marquardt, Marvin, Mayer, Mayert, McClure, McCullough, McDermott, McGlynn, McKenzie, McLaughlin, Medhurst, Mertz, Metz, Miller, Mills, Mitchell, Moen, Mohr, Monahan, Moore, Morar, Morissette, Mosciski, Mraz, Mueller, Muller, Murazik, Murphy, Murray, Nader, Nicolas, Nienow, Nikolaus, Nitzsche, Nolan, Oberbrunner, O'Connell, O'Conner, O'Hara, O'Keefe, O'Kon, Okuneva, Olson, Ondricka, O'Reilly, Orn, Ortiz, Osinski, Pacocha, Padberg, Pagac, Parisian, Parker, Paucek, Pfannerstill, Pfeffer, Pollich, Pouros, Powlowski, Predovic, Price, Prohaska, Prosacco, Purdy, Quigley, Quitzon, Rath, Ratke, Rau, Raynor, Reichel, Reichert, Reilly, Reinger, Rempel, Renner, Reynolds, Rice, Rippin, Ritchie, Robel, Roberts, Rodriguez, Rogahn, Rohan, Rolfson, Romaguera, Roob, Rosenbaum, Rowe, Ruecker, Runolfsdottir, Runolfsson, Runte, Russel, Rutherford, Ryan, Sanford, Satterfield, Sauer, Sawayn, Schaden, Schaefer, Schamberger, Schiller, Schimmel, Schinner, Schmeler, Schmidt, Schmitt, Schneider, Schoen, Schowalter, Schroeder, Schulist, Schultz, Schumm, Schuppe, Schuster, Senger, Shanahan, Shields, Simonis, Sipes, Skiles, Smith, Smitham, Spencer, Spinka, Sporer, Stamm, Stanton, Stark, Stehr, Steuber, Stiedemann, Stokes, Stoltenberg, Stracke, Streich, Stroman, Strosin, Swaniawski, Swift, Terry, Thiel, Thompson, Tillman, Torp, Torphy, Towne, Toy, Trantow, Tremblay, Treutel, Tromp, Turcotte, Turner, Ullrich, Upton, Vandervort, Veum, Volkman, Von, VonRueden, Waelchi, Walker, Walsh, Walter, Ward, Waters, Watsica, Weber, Wehner, Weimann, Weissnat, Welch, West, White, Wiegand, Wilderman, Wilkinson, Will, Williamson, Willms, Windler, Wintheiser, Wisoky, Wisozk, Witting, Wiza, Wolf, Wolff, Wuckert, Wunsch, Wyman, Yost, Yundt, Zboncak, Zemlak, Ziemann, Zieme, Zulauf]
+number:
+  - "777"
+  - "69"
+  - "34"
+  - "{number}4"
+domain:
+  - "{noun}{tld}"
+  - "{noun}{noun}{tld}"
+noun:
+  - abc
+  - acorn
+  - adze
+  - aphx
+  - bat
+  - ball
+  - beach
+  - bell
+  - cat
+  - chalk
+  - dog
+  - dent
+  - elp
+tld:
+  - .com
+  - .com.au
+  - .co
+  - .co.nz
+  - .org
+  - .info
+  - .co.uk
+  - .tech
+  - .io
+  - .xyz

data/lib/calyx/errors.rb

@@ -1,11 +1,58 @@
 module Calyx
+  # Library-specific error types.
   module Errors
-    class RuleNotFound < StandardError; end
+    # Only rules that exist in the registry can be evaluated. When a
+    # non-existent rule is referenced, this error is raised.
+    #
+    #   grammar = Calyx::Grammar.new do
+    #     start :blank
+    #   end
+    #
+    #   grammar.evaluate
+    #   # => Calyx::Errors::MissingRule: :blank is not registered
+    class MissingRule < RuntimeError;
+      def initialize(msg)
+        super(":#{msg} is not registered")
+      end
+    end
 
-    class DuplicateRule < StandardError
-      def initialize(key)
-        super("Rule already declared in grammar: #{key}")
+    # Raised when a rule passed in via a context map conflicts with an existing
+    # rule in the grammar.
+    #
+    #   grammar = Calyx::Grammar.new do
+    #     start :priority
+    #     priority "(A)"
+    #   end
+    #
+    #   grammar.evaluate(priority: "(B)")
+    #   # => Calyx::Errors::DuplicateRule: :priority is already registered
+    class DuplicateRule < ArgumentError
+      def initialize(msg)
+        super(":#{msg} is already registered")
       end
     end
+
+    # Raised when the client attempts to load a grammar with an unsupported file
+    # extension. Only `.json` and `.yml` are valid.
+    #
+    #   Calyx::Grammar.load("grammar.toml")
+    #   # => Calyx::Errors::UnsupportedFormat: grammar.toml is not a valid JSON or YAML file
+    class UnsupportedFormat < ArgumentError
+      def initialize(msg)
+        super("#{File.basename(msg)} is not a valid JSON or YAML file")
+      end
+    end
+
+    # Raised when a rule defined in a grammar is invalid. This will prevent
+    # the grammar from compiling correctly.
+    #
+    #   Calyx::Grammar.new do
+    #     start '40%' => 0.4, '30%' => 0.3
+    #   end
+    #
+    #   # => Calyx::Errors::InvalidDefinition: Weights must sum to 1
+    #
+    class InvalidDefinition < ArgumentError
+    end
   end
 end

data/lib/calyx/format.rb

@@ -1,5 +1,14 @@
 module Calyx
+  # Helper methods for loading and initializing grammars from static files
+  # on disk.
   module Format
+    # Reads a file and parses its format, based on the given extension.
+    #
+    # Accepts a JSON or YAML file path, identified by its extension (`.json`
+    # or `.yml`).
+    #
+    # @param filename [String]
+    # @return [Calyx::Grammar]
     def self.load(filename)
       file = File.read(filename)
       extension = File.extname(filename)
@@ -8,20 +17,26 @@ module Calyx
       elsif extension == ".json"
         self.load_json(file)
       else
-        raise "Cannot convert #{extension} files."
+        raise Errors::UnsupportedFormat.new(filename)
       end
     end
 
-    def self.load_yml(file)
+    # Converts the given string of YAML data to a grammar instance.
+    #
+    # @param data [String]
+    # @return [Calyx::Grammar]
+    def self.load_yml(data)
       require 'yaml'
-      yaml = YAML.load(file)
-      self.build_grammar(yaml)
+      self.build_grammar(YAML.load(data))
     end
 
-    def self.load_json(file)
+    # Converts the given string of JSON data to a grammar instance.
+    #
+    # @param data [String]
+    # @return [Calyx::Grammar]
+    def self.load_json(data)
       require 'json'
-      json = JSON.parse(file)
-      self.build_grammar(json)
+      self.build_grammar(JSON.parse(data))
     end
 
     private

data/lib/calyx/grammar.rb

@@ -1,43 +1,104 @@
 module Calyx
+  # The main public interface to Calyx. Grammars represent the concept of a
+  # template grammar defined by a set of production rules that can be chained
+  # and nested from a given starting rule.
+  #
+  # Calyx works like a traditional phrase-structured grammar in reverse. Instead
+  # of recognising strings based on a union of possible matches, it generates
+  # strings by representing the union as a choice and randomly picking one
+  # of the options each time the grammar runs.
   class Grammar
     class << self
+      # Access the registry belonging to this grammar class.
+      #
+      # Constructs a new registry if it isn't already available.
+      #
+      # @return [Calyx::Registry]
       def registry
         @registry ||= Registry.new
       end
 
+      # Load a grammar instance from the given file.
+      #
+      # Accepts a JSON or YAML file path, identified by its extension (`.json`
+      # or `.yml`).
+      #
+      # @param filename [String]
+      # @return [Calyx::Grammar]
       def load(filename)
         Format.load(filename)
       end
 
-      def modifier(name)
-        registry.modifier(name)
+      # DSL helper method for registering a modifier module with the grammar.
+      #
+      # @param module_name [Module]
+      def modifier(module_name)
+        registry.modifier(module_name)
       end
 
+      # DSL helper method for registering a paired mapping regex.
+      #
+      # @param name [Symbol]
+      # @param pairs [Hash<Regex,String>]
       def mapping(name, pairs)
         registry.mapping(name, pairs)
       end
 
+      # DSL helper method for registering the given block as a string filter.
+      #
+      # @param name [Symbol]
+      # @block block with a single string argument returning a modified string.
       def filter(name, &block)
         registry.mapping(name, &block)
       end
 
+      # DSL helper method for registering a new grammar rule.
+      #
+      # Not usually used directly, as the method missing API is less verbose.
+      #
+      # @param name [Symbol]
+      # @param productions [Array]
       def rule(name, *productions)
         registry.rule(name, *productions)
       end
 
+      # Augument the grammar with a method missing hook that treats class
+      # method calls as declarations of a new rule.
+      #
+      # This must be bypassed by calling `#rule` directly if the name of the
+      # desired rule clashes with an existing helper method.
+      #
+      # @param name [Symbol]
+      # @param productions [Array]
       def method_missing(name, *productions)
         registry.rule(name, *productions)
       end
 
+      # Hook for combining the registry of a parent grammar into the child that
+      # inherits from it.
+      #
+      # @param child_registry [Calyx::Registry]
       def inherit_registry(child_registry)
         registry.combine(child_registry) unless child_registry.nil?
       end
 
+      # Hook for combining the rules from a parent grammar into the child that
+      # inherits from it.
+      #
+      # This is automatically called by the Ruby engine.
+      #
+      # @param subclass [Class]
       def inherited(subclass)
         subclass.inherit_registry(registry)
       end
     end
 
+    # Create a new grammar instance, passing in a random seed if needed.
+    #
+    # Grammar rules can be constructed on the fly when the passed-in block is
+    # evaluated.
+    #
+    # @param seed [Number]
     def initialize(seed=nil, &block)
       @seed = seed || Random.new_seed
       srand(@seed)
@@ -50,6 +111,11 @@ module Calyx
       end
     end
 
+    # Produces a string as an output of the grammar.
+    #
+    # @param start_symbol [Symbol]
+    # @param rules_map [Hash]
+    # @return [String]
     def generate(*args)
       start_symbol, rules_map = map_default_args(*args)
 
@@ -58,6 +124,11 @@ module Calyx
       end.join(''.freeze)
     end
 
+    # Produces a syntax tree of nested list nodes as an output of the grammar.
+    #
+    # @param start_symbol [Symbol]
+    # @param rules_map [Hash]
+    # @return [Array]
     def evaluate(*args)
       start_symbol, rules_map = map_default_args(*args)
 

data/lib/calyx/modifiers.rb

@@ -1,9 +1,16 @@
 module Calyx
+  # Applies modifiers to the output of a rule in a template substitution.
   class Modifiers
-    def extend_with(name)
-      extend name
-    end
-
+    # Transforms an output string by delegating to the given output function.
+    #
+    # If a registered modifier method is not found, then delegate to the given
+    # string function.
+    #
+    # If an invalid modifier function is given, returns the raw input string.
+    #
+    # @param name [Symbol]
+    # @param value [String]
+    # @return [String]
     def transform(name, value)
       if respond_to?(name)
         send(name, value)

data/lib/calyx/production/choices.rb

@@ -1,6 +1,13 @@
 module Calyx
+  # A type of production rule representing a list of possible rules, one of
+  # which will chosen each time the grammar runs.
   module Production
     class Choices
+      # Parse a list of productions and return a choice node which is the head
+      # of a syntax tree of child nodes.
+      #
+      # @param productions [Array]
+      # @param registry [Calyx::Registry]
       def self.parse(productions, registry)
         choices = productions.map do |choice|
           if choice.is_a?(String)
@@ -18,10 +25,16 @@ module Calyx
         self.new(choices)
       end
 
+      # Initialize a new choice with a list of child nodes.
+      #
+      # @param collection [Array]
       def initialize(collection)
         @collection = collection
       end
 
+      # Evaluate the choice by randomly picking one of its possible options.
+      #
+      # @return [Array]
       def evaluate
         [:choice, @collection.sample.evaluate]
       end

data/lib/calyx/production/concat.rb

@@ -1,11 +1,20 @@
 module Calyx
   module Production
+    # A type of production rule representing a string combining both template
+    # substitutions and raw content.
     class Concat
       EXPRESSION = /(\{[A-Za-z0-9_@\.]+\})/.freeze
       START_TOKEN = '{'.freeze
       END_TOKEN = '}'.freeze
       DEREF_TOKEN = '.'.freeze
 
+      # Parses an interpolated string into fragments combining terminal strings
+      # and non-terminal rules.
+      #
+      # Returns a concat node which is the head of a tree of child nodes.
+      #
+      # @param production [String]
+      # @param registry [Calyx::Registry]
       def self.parse(production, registry)
         expansion = production.split(EXPRESSION).map do |atom|
           if atom.is_a?(String)
@@ -30,10 +39,18 @@ module Calyx
         self.new(expansion)
       end
 
+      # Initialize the concat node with an expansion of terminal and
+      # non-terminal fragments.
+      #
+      # @param expansion [Array]
       def initialize(expansion)
         @expansion = expansion
       end
 
+      # Evaluate all the child nodes of this node and concatenate them together
+      # into a single result.
+      #
+      # @return [Array]
       def evaluate
         concat = @expansion.reduce([]) do |exp, atom|
           exp << atom.evaluate

data/lib/calyx/production/expression.rb

@@ -1,12 +1,23 @@
 module Calyx
   module Production
+    # A type of production rule representing a single template substitution.
     class Expression
+      # Constructs a node representing a single template substitution.
+      #
+      # @param production [#evaluate]
+      # @param methods [Array]
+      # @param registry [Calyx::Registry]
       def initialize(production, methods, registry)
         @production = production
         @methods = methods.map { |m| m.to_sym }
         @registry = registry
       end
 
+      # Evaluate the expression by expanding the non-terminal to produce a
+      # terminal string, then passing it through the given modifier chain and
+      # returning the transformed result.
+      #
+      # @return [Array]
       def evaluate
         terminal = @production.evaluate.flatten.reject { |o| o.is_a?(Symbol) }.join(''.freeze)
         expression = @methods.reduce(terminal) do |value, method|

data/lib/calyx/production/memo.rb

@@ -1,13 +1,23 @@
 module Calyx
   module Production
+    # A type of production rule representing a memoized subsitution which
+    # returns the first value selected on all subsequent lookups.
     class Memo
       SIGIL = '@'.freeze
 
+      # Construct a memoized rule, given the symbol to lookup and the registry
+      # to look it up in.
+      #
+      # @param symbol [Symbol]
+      # @param registry [Calyx::Registry]
       def initialize(symbol, registry)
         @symbol = symbol.slice(1, symbol.length-1).to_sym
         @registry = registry
       end
 
+      # Evaluate the memo, using the registry to handle the expansion.
+      #
+      # @return [Array]
       def evaluate
         [@symbol, @registry.memoize_expansion(@symbol)]
       end

data/lib/calyx/production/non_terminal.rb

@@ -1,11 +1,21 @@
 module Calyx
   module Production
+    # A type of production rule that represents a non-terminal expansion,
+    # linking one rule to another.
     class NonTerminal
+      # Construct a non-terminal node, given the symbol to lookup and the
+      # registry to look it up in.
+      #
+      # @param symbol [Symbol]
+      # @param registry [Calyx::Registry]
       def initialize(symbol, registry)
         @symbol = symbol.to_sym
         @registry = registry
       end
 
+      # Evaluate the non-terminal, using the registry to handle the expansion.
+      #
+      # @return [Array]
       def evaluate
         [@symbol, @registry.expand(@symbol).evaluate]
       end

data/lib/calyx/production/terminal.rb

@@ -1,10 +1,17 @@
 module Calyx
   module Production
+    # A type of production rule that terminates with a resulting string atom.
     class Terminal
+      # Construct a terminal node with the given value.
+      #
+      # @param atom [#to_s]
       def initialize(atom)
         @atom = atom
       end
 
+      # Evaluate the terminal by returning its identity directly.
+      #
+      # @return [Array]
       def evaluate
         [:atom, @atom]
       end

data/lib/calyx/production/weighted_choices.rb

@@ -1,12 +1,20 @@
 module Calyx
   module Production
+    # A type of production rule representing a map of possible rules with
+    # associated weights that define the expected probability of a rule
+    # being chosen.
     class WeightedChoices
+      # Parse a given list or hash of productions into a syntax tree of weighted
+      # choices.
+      #
+      # @param productions [Array<Array>, Hash<#to_s, Float>]
+      # @param registry [Calyx::Registry]
       def self.parse(productions, registry)
         weights_sum = productions.reduce(0) do |memo, choice|
           memo += choice.last
         end
 
-        raise 'Weights must sum to 1' if weights_sum != 1.0
+        raise Errors::InvalidDefinition, 'Weights must sum to 1' if weights_sum != 1.0
 
         choices = productions.map do |choice, weight|
           if choice.is_a?(String)
@@ -19,10 +27,20 @@ module Calyx
         self.new(choices)
       end
 
+      # Initialize a new choice with a list of child nodes.
+      #
+      # @param collection [Array]
       def initialize(collection)
         @collection = collection
       end
 
+      # Evaluate the choice by randomly picking one of its possible options,
+      # balanced according to the given weights.
+      #
+      # The method for selecting weighted probabilities is based on a snippet
+      # of code recommended in the Ruby standard library documentation.
+      #
+      # @return [Array]
       def evaluate
         choice = @collection.max_by do |_, weight|
           rand ** (1.0 / weight)

data/lib/calyx/registry.rb

@@ -1,25 +1,42 @@
 module Calyx
+  # Lookup table of all the available rules in the grammar.
   class Registry
     attr_reader :rules, :transforms, :modifiers
 
+    # Construct an empty registry.
     def initialize
       @rules = {}
       @transforms = {}
       @modifiers = Modifiers.new
     end
 
+    # Hook for defining rules without explicitly calling the `#rule` method.
+    #
+    # @param name [Symbol]
+    # @param productions [Array]
     def method_missing(name, *arguments)
       rule(name, *arguments)
     end
 
+    # Attaches a modifier module to this instance.
+    #
+    # @param module_name [Module]
     def modifier(name)
-      modifiers.extend_with(name)
+      modifiers.extend(name)
     end
 
+    # Registers a paired mapping regex.
+    #
+    # @param name [Symbol]
+    # @param pairs [Hash<Regex,String>]
     def mapping(name, pairs)
       transforms[name.to_sym] = construct_mapping(pairs)
     end
 
+    # Registers the given block as a string filter.
+    #
+    # @param name [Symbol]
+    # @block block with a single string argument returning a modified string.
     def filter(name, callable=nil, &block)
       if block_given?
         transforms[name.to_sym] = block
@@ -28,14 +45,26 @@ module Calyx
       end
     end
 
+    # Registers a new grammar rule.
+    #
+    # @param name [Symbol]
+    # @param productions [Array]
     def rule(name, *productions)
       rules[name.to_sym] = construct_rule(productions)
     end
 
+    # Expands the given rule symbol to its production.
+    #
+    # @param symbol [Symbol]
     def expand(symbol)
       rules[symbol] || context[symbol]
     end
 
+    # Applies the given modifier function to the given value to transform it.
+    #
+    # @param name [Symbol]
+    # @param value [String]
+    # @return [String]
     def transform(name, value)
       if transforms.key?(name)
         transforms[name].call(value)
@@ -44,20 +73,38 @@ module Calyx
       end
     end
 
+    # Expands a memoized rule symbol by evaluating it and storing the result
+    # for later.
+    #
+    # @param symbol [Symbol]
     def memoize_expansion(symbol)
       memos[symbol] ||= expand(symbol).evaluate
     end
 
+    # Merges the given registry instance with the target registry.
+    #
+    # This is only needed at compile time, so that child classes can easily
+    # inherit the set of rules decared by their parent.
+    #
+    # @param registry [Calyx::Registry]
     def combine(registry)
       @rules = rules.merge(registry.rules)
     end
 
+    # Evaluates the grammar defined in this registry, combining it with rules
+    # from the passed in context.
+    #
+    # Produces a syntax tree of nested list nodes.
+    #
+    # @param start_symbol [Symbol]
+    # @param rules_map [Hash]
+    # @return [Array]
     def evaluate(start_symbol=:start, rules_map={})
       reset_evaluation_context
 
       rules_map.each do |key, value|
         if rules.key?(key.to_sym)
-          raise Error::DuplicateRule.new(key)
+          raise Errors::DuplicateRule.new(key)
         end
 
         context[key.to_sym] = if value.is_a?(Array)
@@ -72,7 +119,7 @@ module Calyx
       if expansion.respond_to?(:evaluate)
         [start_symbol, expansion.evaluate]
       else
-        raise Errors::RuleNotFound.new(start_symbol)
+        raise Errors::MissingRule.new(start_symbol)
       end
     end
 

data/lib/calyx/version.rb

@@ -1,3 +1,3 @@
 module Calyx
-  VERSION = '0.11.0'.freeze
+  VERSION = '0.11.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calyx
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.1
 platform: ruby
 authors:
 - Mark Rickerby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-27 00:00:00.000000000 Z
+date: 2016-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,8 @@ files:
 - LICENSE
 - README.md
 - calyx.gemspec
+- examples/faker.rb
+- examples/faker.yml
 - examples/tiny_woodland.rb
 - lib/calyx.rb
 - lib/calyx/errors.rb