Uploaded image for project: 'Forge'
  1. Forge
  2. FORGE-944

Establish CLI naming guidelines for Forge 2

    XMLWordPrintable

Details

    Description

      I was talking about having CLI naming conventions on the forum and George and Lincoln suggested to add these ideas on a JIRA. So here is my humble contribution to record all the ideas about renaming commands.

      Disclaimer : I haven't used Forge for a long time, I've just started using it again, so some of the following ideas might not be accurate

      As a new comer in Forge I felt the commands were not that intuitive. I loved the following :

       
      java new-enum-type
      java new-itnerface
      java new-class
      

      So I was expecting to have something similar in all the other techologies, such as JPA :

      jpa new-entity (instead of entity --named)
      jpa new-embedable
      jpa new-mapped-superclass --named Person
      jpa new-entity --named Vet --extends Person
      

      Lincoln suggested having single-level command keywords only such as :

      jpa-new-entity (instead of entity --named)
      jpa-new-embedable
      jpa-new-mapped-superclass --named Person
      jpa-new-entity --named Vet --extends Person
      

      Verbs and keywords

      When you look at the commansd, there are several common verbs and keywords than come often :

      add : ejb-add-transaction-attribute
      new : beans-new-bean, faces-new-view, new-project (prefer project-new)
      list : list-web-resources, beans list-interceptors, beans list-alternatives, list-scaffold-providers
      setup : ejb setup, entity setup
      put : i18n put
      remove : i18n remove, project remove-property
      execute : execute-java
      set : maven set-groupid
      find : forge find-plugin
      install : 
      update : forge update-abort, gitignore update-repo
      run : run-url
      info : analytics info
      

      That brings several thoughts :

      • ls is used as well as list, should this be homogenize (e.g. beans-ls-interceptors)
      • rm is used as well as remove, should this be homogenize (e.g. i18n-rm, project-rm-property)
      • The difference between execute and run is not clear, should this be homogenize and only use one ?
      • Also there is execute and exec, this should be homogenize (e.g. execute-java and exec)
      • Confusion between new and add. You create a new class with java-new-class and shouldn't you add a field and a method to existing class (java-add-field instead of java-new-field)
      • Some confusion between maven and project
      • Is there any difference between set and update ? maven set-artifactid updates the already existing artifactId and gitignore update-repo updates an existing repo
      • we use field (e.g. java-add-field) and then property (constraint Future --onProperty date), it should be fiels (constraint Future --onField date)

      In many commands you find a type argument such as (type, scaffoldType, fieldType :

      scaffold setup --scaffoldType faces
      field manyToMany --named specialties --fieldType ~.model.Specialty.java
      field temporal --type DATE --named date
      

      Why not having only type in all the cases :

      scaffold-setup --type faces
      jpa-add-field manyToMany --named specialties --type ~.model.Specialty.java
      jpa-add-field temporal --named date --type DATE 
      

      Grammar

      The CLI grammar could look like this :

      command = shell | forge command ;
      forge command = technology,-action,[-artifact] [{--argument value}] ;
      
      shell = cat | cd | cp | edit | find | grep | ls ...
      technology = project | scaffold | beans | constraint | java | jpa | i18n | ejb ...
      action = add | new | ls | rm | setup ...
      artifact = providers | interceptors | class | filter...
      argument = named | onField | type | extends
      

      Examples

      So if we take that grammar and apply single-level command keywords, we could have things like that :

      mkdir
      ls
      ls-commands -all
      project-new --named MyPro
      scaffold-ls-providers
      scaffold-templates --scaffoldType faces
      beans-ls-interceptors
      constraint-new-constraint --named MyConstraint
      constraint-add-constraint MyConstraint --onField MyProp
      java-new-class --named MyClass
      java-add-field 'private List<Vet> vets'
      java-add-method 'public List<Vet> getVetList() {return null;}'
      java-add-annotation --type XmlRootElement --onClass MyClass
      java-add-annotation --type XmlAttribute --onField MyProp
      jpa-new-mapped-superclass --named Person
      jpa-new-entity --named Vet --extends Person
      jpa-add-field manyToOne --named owner --type ~.model.Owner.java
      i18n-add-locale --locale PT
      ejb-new-stateless --named MyStateless
      ejb-new-singleton --named MySingleton --implements MyInterface AndAnotherInterface
      ejb-add-transaction-attribute --type NEVER
      ejb-add-transaction-attribute --type NEVER --onMethod MyNeverMethod
      faces-new-view --named MyView
      faces-set-project-stage --stage PRODUCTION
      servlet-new-filter --named MyFilter
      rest-new-endpoint --named MyEndpoint --extends MyRestExtension
      mvn-build --notest
      

      Scaffolding is a bit tricky because it's extendable and you could end up with

      scaffold-ui-from-entity ~.model.*
      scaffold-rest-endpoint-from-entity ~.model.*
      scaffold-dao-from-entity ~.model.*
      scaffold-ejb-service-from-dao ~.dao.*
      scaffold-rest-endpoint-from-dao ~.dao.*
      

      Or something like that

      scaffold --ui --from-entity ~.model.*
      scaffold --rest-endpoint --from-entity ~.model.*
      scaffold --dao --from-entity ~.model.*
      scaffold --ejb-service --from-dao ~.dao.*
      scaffold --rest-endpoint --from-dao ~.dao.*
      

      Here are my 2 cents thoughts on a topic that I'm discovering. As you all know, naming is really important and should be looked at carefully. Let's use this JIRA to exchange ideas.

      Attachments

        Issue Links

          Activity

            People

              Unassigned Unassigned
              agoncal Antonio Goncalves
              Votes:
              2 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: