Save Time (by Creating Custom Rails Generators)

Transcript

1. 1

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.

5. 5

6. 6

7. 7

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.

9. 9

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

15. 15

16. 16 What’s in a name? A generator by any other

    name would still override a built-in generator by the same name.

17. 17

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.

21. 21

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.

24. 24

25. 25

26. 26

27. 27

28. 28

29. 29

30. 30 Directories are “templates” too! The directory action can recursively

    generate multiple files and directories with a single call.

31. 31

32. 32

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.

36. 36

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.)

42. 42

43. 43

44. 44

45. 45

46. 46

47. 47

48. 48 Learn the Rails shortcuts. Take advantage of the Rails-centric

    generator tools even when the benefits seem minor.

49. 49

50. 50

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.

57. 57

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.

60. 60

61. 61 Command-line strings become easily accessible Ruby values. Strings, Numeric

    (Float or Integer), Array, and Hash. (Options can be boolean as well.)

62. 62

63. 63

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.

67. 67

68. 68

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.

72. 72

73. 73

74. 74

75. 75

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.

78. 78

79. 79

80. 80 Don’t mess with repos. If your generator fails, what

    state does it leave the repo in?

81. 81

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.

84. 84

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.

89. 89

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.

91. 91

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.

99. 99

100. 100

101. 101

102. 102

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.

106. 106

107. 107 Gather additional input. Relaying status information to the command

     line. Displaying errors. And requesting additional information.

108. 108

109. 109

110. 110 And now the easy part…

111. 111

112. 112

113. 113 Thank you. Generators.dev Get the slides railsconf.generators.dev