Save Time (by Creating Custom Rails Generators)

Become skilled at quickly creating well-tested custom generators and turn those tedious and repetitive ten-minute distractions into ten-second commands—not just for you but for your entire team. With some curated knowledge and insights about custom generators and some advanced warning about the speed bumps, it can save time in far more scenarios than you might think.

Transcript

2. 2 Save Time (with Custom Rails Generators) RailsConf 2024, Detroit, MI
3. 3 Hi. I’m Garrett. Developer GarrettDimon.com Flipper Cloud
4. 4 Before we begin… Disclaimers, caveats, excuses, context, waffling, and being deliberate.
8. 8 Custom Generators can save time and reduce tedium. But just because they can does not mean that they will. Thatʼs up to us.
10. 10 Related Options Great for some scenarios, but they arenʼt entirely dedicated to the process of generating files. Generators – Rake Tasks – Ruby Scripts – Shell Scripts – Prose-based documentation – Snippet Tools – Copy/Paste + Search/Replace – Type from Memory –
11. 11 = Save Time = Speed Bump to Avoid
12. 12 Pay (just a little) attention to the code behind the curtain.
13. 13 Actions + Templates + Inflections + Arguments + Options + Tests + Documentation + Integration generators > sum_of_parts
14. 14 What’s the generator generator generating for us? We can use the generator generator to generate a new generator in seconds.1 Thereʼs also a task , but theyʼre still not generators. 1. generator to quickly create Rake files
16. 16 What’s in a name? A generator by any other name would still override a built-in generator by the same name.
18. 18 Public methods are run by default. Less a speed bump and more just something key to know, but it can be easy to forget early on. no_commands do # or no_tasks # "Hidden" Public Methods end
19. 19 Know where the magic happens. NamedBase or Base for a parent class? Most likely, NamedBase, but not just because itʼs the default.
20. 20 NamedBase generators have a pre- defined “name” argument. Hence Named base and all of the wonderful inflections of the name.
22. 22 NamedBase generators get greedy with “attributes” arguments. They create GeneratedAttribute values so we can create model attributes, so donʼt let that surprise you. price:decimal{10,2} pseudo:string{30} pseudo:string:uniq supplier:references{polymorphic} supplier:references{polymorphic}:index
23. 23 It all boils down to sources, destinations, and high-level file system tools. Rubyʼs built-in file system libraries may as well be Assembly in comparison.
30. 30 Directories are “templates” too! The directory action can recursively generate multiple files and directories with a single call.
33. 33 Templates are powerful. With great power comes the ability to really f*** things up.
34. 34 Templates get access to everything. Not just ERb. Public methods. Private methods. Itʼs all fair game.1 The no_commands and no_tasks blocks can help, but private methods are my preferred approach. 1.
35. 35 Know when to quote ’em. Strings will be “unquoted” when output through ERb, but the quote helper can fix that.
37. 37 What’s whitespace got to do with it? Template whitespace is significant. Leading whitespace and line breaks can get ugly fast. <%- %> # Trim leading whitespace/indent. <% -%> # Trim trailing line break <%- -%> # Trim leading and trailing
38. 38 Don’t sweat the indent. Make the most of the built-in indentation methods to dial it all in cleanly. Get help from optimize_indentation , indentation , and with_indentation
39. 39 You got ERb in your ERb. Escape those delimiters with an extra %. <%% & %%> <%%- & -%%> <%%= <%%#
40. 40 Maximize leverage.
41. 41 Reach for high-level tools first, mid-level second, and low-level almost never. The higher the level, the more leverage. (But also more magic to understand.)
48. 48 Learn the Rails shortcuts. Take advantage of the Rails-centric generator tools even when the benefits seem minor.
51. 51 Discoverability is free leverage. Rails already includes custom generators whenever it lists generators.
52. 52 Familiarity greases the skids. Rails devs already understand how to use generators so thereʼs less need to learn something new.
53. 53 Generators are version-controlled and very shareable. Generators get used more. Team members become significant multipliers for time-savings.
54. 54 Don’t reinvent the generator. Call a generator from a generator. Override and extend. Or just override the templates.
55. 55 Let the generator deal with the command- line. (Most of the time.)
56. 56 Generators have us covered on arguments and options. Arguments for the main stuff. Options for the extras.
58. 58 Don’t unintentionally override key methods with arguments. The errors are usually quite indirect and confusing.
59. 59 Aim for one value argument and one collection argument. A few values can work, but too many arguments means more friction typing the command.
61. 61 Command-line strings become easily accessible Ruby values. Strings, Numeric (Float or Integer), Array, and Hash. (Options can be boolean as well.)
64. 64 The “free” coercion and type error-handling is (usually) enough. When weʼre on the command line everythingʼs a string until the generator steps in.
65. 65 With arrays and hashes, it’s strings all the way down. No hashing with indifferent access. And no coercion either. 1 Options are hashed with indifferent access, but thatʼs it. 1.
66. 66 Shell out with generator actions instead of standard Ruby options. The built-in tools for running system commands are smarter than they look.
69. 69 Always be exiting. If a generator needs to stop, explicitly exit so the generator is a good citizen of the command line. exit(exit_code) 0 Success 1 Failure 126 Permissions Error 127 Command Not Found
70. 70 Ease-of-use saves time while also increasing use.
71. 71 Better documentation leads to increased usage. The defaults are great, but filling in a few blanks (and USAGE file) goes a long way.
76. 76 Be judicious and practical with arguments and options. Usability and convenience are inversely proportional to the length of the documentation.
77. 77 Small generators save time too. If we include the template and tests, the built-in rake task generator only has 30 lines of non-generated code.1 50 if we include generated code and blank lines. 1.
80. 80 Don’t mess with repos. If your generator fails, what state does it leave the repo in?
82. 82 CLI-driven design can help keep commands concise. Write out the command you wouldnʼt mind typing regularly, and then translate it to a generator.
83. 83 Make sure to say stuff. Most built-in actions will handle it, but itʼs still helpful to make sure our custom logic is helpful too.
85. 85 Respect quiet time. Most actions will automatically respect the !"quiet option, but not all.1 We can check options.quiet? to know when a generator should suppress output. 1.
86. 86 Test smarter— not harder.
87. 87 Don’t poke around the file system. The custom assertions are destination_root -aware. assert_file assert_method assert_class_method assert_instance_method
88. 88 Always use the test helpers. The test file sets destination_root , but generator and run_generator are the only methods that care.
90. 90 Take care when straying from the source or destination roots. We mostly donʼt have to think about it, but if we stray, it can get a little messy.
92. 92 Listen to the tests. Stay in the generator wheelhouse. If a generator feels difficult to test, it might be trying to do too much.
93. 93 The tests will clean up for us automatically if we let them. By default, generator tests route generated files to “tmp/generators” and reset it before each test.
94. 94 But just in case, the cleanup happens before tests—not after. So running a single test will leave the generated files in “tmp/generators” for manual inspection.
95. 95 Test interactive bits by pretending. Automated testing canʼt easily test interactive prompts. The !"pretend option can help.
96. 96 Testing & RSpec. Like the rest of Rails, the testing benefits rely on Minitest. RSpec requires a little extra.1 Thoughtbotʼs suspenders gem has some , , and to streamline testing generators with RSpec. 1. custom generator matchers generator test helpers file operations
97. 97 Generate outside the box.
98. 98 Generate any kind of text files. CSV, SVG, YAML, Markdown, HTML, CSS, JavaScript, ERb, Shell Scripts. And more.
103. 103 What else? Site maps, humans.txt , robots.txt , shell scripts, fixtures, release notes, etc.
104. 104 Just because you can doesn’t mean you should.
105. 105 Git wild, but use a light touch. Even within teams, we all have subtly different git workflows.
107. 107 Gather additional input. Relaying status information to the command line. Displaying errors. And requesting additional information.
110. 110 And now the easy part…
113. 113 Thank you. Generators.dev Get the slides railsconf.generators.dev