`cry d generator name` not working

[Chris Lozac'h]

Unless I'm misunderstanding the docs, the d command isn't working, at least not in the context of the default generator. (If it is working and I've just misunderstood how to use battlecry, maybe this could be considered a documentation bug instead.)

Steps to reproduce:

bash-3.2$ cry g init

🥁  Playing: generate init

   🥁  Playing: generate generator
      ✅  File created: battlecry/generators/component/component.generator.js
      ✅  File created: battlecry/generators/component/templates/__na-me__.txt

   ✅  File created: battlecry/battlecry-setup.js

   🥁  Playing: generate component
      ✅  File created: it-worked/components/test-abc.txt

bash-3.2$ cry g component HelloWorld

🥁  Playing: generate component
   ✅  File created: it-worked/components/hello-world.txt

bash-3.2$ cry d component HelloWorld
Usage: cry <method> <generator> [args] [options]

Options:

  -V, --version  output the version number
  -A, --about    output info about Battlecry contributors
  -h, --help     output usage information

Commands:

  
🥁  generator

   cry g generator name
   Generate a new generator

   cry download generator repository
   Download one or more generators from GitHub
       -d --dir value 	The repository directory where the generators are located

   cry d generator name
   Destroy an existing generator

🥁  init

   cry g init 

🥁  component

   cry g component name
       -s --special 	Special option

⚠️  Command not found. Check the commands available above

bash-3.2$ 

[Pedro Moreira]

Hi @clozach, thanks for opening this issue.

In fact, the destroy (d) method isn't generated by default.

If you wish to delete the HelloWorld generator, the command would be cry d generator HelloWorld. If you think the docs can be improved to clarify this I'd love to hear your ideas.

What comes to my mind is an explanation of what each piece of the command means, such as:
cry g component test

• cry: the battlecry command
• g (alias to generate): the method
• component: the generator
• test: an arg provided to the method

Let me know if you have any other questions.
Cheers!

[Chris Lozac'h]

Hey, @pedsmoreira. Sure thing!

I think my thoughts about this thing you've created are still a bit too tangled for me to make specific recommendations. Instead, here are some questions whose responses would probably help others as well:

• What is the difference between cry g init and cry g generator your_generator_name_here? When would I use one or the other? How do both relate to cry download …?

• How do I use battlecry/battlecry-setup.js? Can you show examples of 1 or 2 primary use cases?

• Can you walk me through a practical scenario for Battlecry, start to finish?

Oh, and one last thing I find really helpful when it's covered in a project's README: What similar tools do you know about, either in js or other languages, and what are some key differences and similarities between them and Battlecry?

Looking forward to giving it another try!
Cheers 🙂

[Pedro Moreira]

These are very good questions @clozach, thanks! Since I'm the one who created the library the docs seem very clear to me, so questions like yours are very helpful when it comes on understanding how to better explain the concepts behind Battlecry.

First Question

Cry g init

cry g init generates a battlecry-setup.js file for you to configure your project, calls cry g generator component and immediately runs this generator as cry g component test-abc. The goal of init is to give an initial view of what battlecry looks like, my idea was that it would be used only once, when you start the project.

Cry g generator

cry g generator creates a generator for you given a name, I'll give you an example. Let's say you just started your application and you have 3 parts: controllers, models and views. Battlecry can help you with generators, so that you don't have to copy and paste files every time you wish to create a new controller, model or view. So you'll create one generator for each one:

cry g generator controller
cry g generator model
cry g generator view

These commands will basically create empty .generator.js files with some empty templates for you to edit. - Fun fact: if you look into battlecry's source code you'll see that there is a generator.generator.js with a generate method in it, which is the command you just called three times.

Now, it's not uncommon for you to want to generate a controllers, model and views, all at once, for a specific resource. Let's say you wish to create a User.js model, a ListUsers.js view, a ShowUser.js view and a UserController.js, you could have a generator call these other generators you just created, so you run one command and it executes a bunch of stuff for you:

cry g generator scaffold // create a new generator
// implement your generator, calling the generators you created before
cry g scaffold user

Cry download generator

Currently there are few projects that offer generators to be download because Battlecry hasn't become mainstream.

Let's say you start using the Redux Ducks pattern, for React. This pattern have a set of rules that have to be applied whenever you wish to create a new module. The ideia is that instead of each person writing these same rules into generators themselves multiple times, they could share the generators in a way that's easy to download.

I personally created a PR for Redux Ducks, so if you start using this pattern, you could just run:

cry download generator erikras/ducks-modular-redux

and these generators would be added to your project, directly from the GitHub repo.

Battlecry-setup

The setup can be used for 3 reasons:

• Loading generators from other folders: Let's say you have multiple projects on your company that share the EXACT SAME generators, I uppercased EXACT because it's very important here. More often than not you'll want to download the generators using cry download generator, so that you can customize the generators for the specific project needs, but if you are in a company that wants to set strict rules for several projects and share these settings in a npm module, you could use battlecry.load(...) to link the npm module instead of download the generators.
• Adding new aliases: by default these are the aliasesg: generate and d: destroy, but you could have your own aliases, such as p for parsing, or l for listing.
• Updating default globOptions: you'll rarely need this, the default configs are pretty much almost always what you need.
  https://github.com/pedsmoreira/battlecry#customizing-your-battlecry-setupjs

Personally I don't use battlecry-setup.js in any of my projects because the default settings are pretty much what I need. My intent was to have a standard way of setting configs for now and the future and give the community some customisation options when using battlecry.

Practical scenario 1

I'll give you the example of the project I'm working right now - Peerfect, and I'm using Ruby on Rails for the API and React on the frontend.

Ruby on Rails already comes with generators, so I didn't write generators for the API myself. For React however, there are no ready-to-to generators, so I created my own.

In this project I have 4 main generators:

• component: creates a component with the files: .js, .scss, .mdx and index.js. This is the generator I use the most, because there are lots of components in the app.
• field: I use one of my libraries - form-for, which uses the idea of connecting fields, so this is similar to the component, but it has a different template and it also needs to be added to a fields/index.js, which holds the list of fields.
• page: Creates a page and adds it to my routes file
• model: Creates a model with the fields and relationships I give it. In this project I'm using both MobX and Form-for that use annotations, so if I run cry g model User name phone:tel email:email, it will generate the User.js model for me with all the annotations and fields I listed, which is very handy.

Additionally I also have a cry g scaffold command that creates a bunch of pages and a model for me :)

Practical scenario 2

Another very good usage of Battlecry is refactoring. I'm no bash expert, so I often use Battlecry to create scripts that rename files and/or update something inside them. Due to the file helpers, it's a lot easier to do this with Battlecry than pure bash, IMHO.

Let's say you want to check all your JS files in a folder and see if all of them have // @flow in the first line. You could create a generator that lists all files and checks that for you.

Comparison and others

I think a comparison table, if respectful to the other libraries in the comparison could be very good :).

Final comments

Let me know if this answer clarifies what Battlecry does, if so, I'll use it in the future as a base to update the README.

If you wish to open a PR, please feel free to do so. Lately my time to work on battlecry has been very limited, as I've been investing most of my time on my Peerfect project. I want to continue improving Battlecry and it's documentation, but it's difficult to do so as fast as I would like to do it.

[Chris Lozac'h]

Hi Pedro,

I finally got around to looking at Battlecry again, and once again found myself unnecessarily confused.

This time, I persevered, browsing your code, docs, and the above response until I truly understood the basics. Then I wrote this fictional tutorial. I say, "fictional" because I'm sure I've made some factual errors, I've left out an entire section, and because I've posited a built-in scaffold generator to replace generator.

Take a look! If you like what you see, let me know. I haven't got a strong use case for cry yet, but it seems worth learning, and I learn best when I'm trying to explain something…all of which is to say, I'm happy to help with the docs if you're interested.

[Pedro Moreira]

Hi @clozach,

I really like what you did there with the tutorial. I'm not a big fan of cry generate generator neither, the words are too similar and it gets confusing, I just hadn't thought of a better name. I like the idea of renaming it to scaffold and getting rid of init.

I can see this format of having multiple tutorials much easier to understand, with different layers of details (basic tutorial for beginners and more advanced ones for those who need customisation).

This week I probably won't have much time to go further on the documentation update, but I'll try to tackle it once I have some time. Once I get to it, I'll create a PR and mention you - I'd love your help with the docs (if you're still interested at the time).