• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!

View
 

Abbot Spec sc-gen

Page history last edited by Charles Jolley 15 years, 1 month ago

Overview

sc-gen is the Abbot tool used to automatically generate templates files for developers adding new classes, applications, frameworks, etc.  The tool should come with a builtin set of generator templates for SproutCore apps and ideally will also allow the developer to add their own generate templates as well.

 

Goals

The following goals are required for the sc-gen tool:

 

  • Provide compatibility with sc-gen tool found in the older Blue Ribbon-line of build tools.
  • Include builtin templates for common SproutCore file types (described below)
  • Optionally allow developers to define their own additional custom template types in their own projects
  • Avoid adding additional dependencies to the build tools to keep installation simple.

 

Command Line Interface Requirements

The general form of the command line for sc-gen is:

 

sc-gen template Namespace[.ClassName] [--target=TARGET_NAME] [--filename=FILE_NAME]

 

  • template: the type of template to generate.  This can be any one of the built-in or developer-provided templates.

  • Namespace.ClassName: The namespaced classname to use when generating the template.  This may be specified in either CamelCase or snake_case.  The gen tool should normalize the input either way.  Some generators may not require a class name such as adding a language or unit test.  In these cases the tool should simply pass through the passed name specifier here. 

  • TARGET_NAME:  Optionally specify the name of the target where the generated content should go.  If this is not specified explicitly, the target name should be inferred from the passed Namespace.
  • FILE_NAME:  The root filename where the template should be added.  If this is not specified, the filename should be derived from the ClassName.

 

In addition to the above options, the standard options accepted by all sc-* tools (such as --project, etc) should be accepted.

 

The exact method used to map the passed Namespace.ClassName to a target & filename should be consistent where possible between different templates, but each template will need the ability to customize the behavior.  Specific variations on the above general interface will be noted in the specific template requirements defined below.

 

In addition to the above, if the developer passes:

 

sc-gen --help

 

It should list out all of the installed templates.  If the developer passes:

 

sc-gen template_name --help

 

It should list out the contents of any USAGE file found in the template directory.

 

Console Output Requirements

When the sc-gen tool runs, it should build the template according to the passed parameters.  If verbose logging is turned on, it should log the name of the generator it is running and each path it is generating.  If very-verbose logging is turned on, the tool may log any additional information that would be useful for a developer debugging the generator tool or a generator template.

 

Once the tool has finished running, it should display the contents of any README file found in the generator template after passing the README through the standard ERB template processing.  (This allows the template to customize its instructions according to the command line options passed.)

 

EXAMPLE

$ sc-gen view Contacts.MyCustomView -v

~ generating view Contacts.MyCustomView

~   Added apps/contacts/views/my_custom.js

~   Added apps/contacts/tests/views/my_custom/init.js

 

Your new view has been created at:  apps/contacts/views/my_custom.js

Remember to add unit test for every new method as well.

$ _

 

Built-In Templates

The following built-in templates must be provided:

 

sc-gen project project_name --filename=project_name  

 

Generates a new project.  Unlike other templates, you only need to pass the name of the project.  You can optionally specify the --filename, but the --target option will be ignored.  This will generate a new directory with the project following files:

 

project_name/

  Buildfile  <-- the default buildfile

  apps/

    project_name <-- default app.  This should use the 'app' generator defined below

 

sc-gen app|client AppName --filename=app_name --target=targetname

 

Generates a new application target for the project.  To passed AppName can be specified using CamelCase or snake_case.  Either way, the namespace included in the JavaScript should be the AppName version while the default app directory name should be the app_name version. The default will output the following files:

 

project/

 apps/

    app_name/

      core.js  <-- declares basic Namespace

      english.lproj/

        strings.js <-- default strings.js for localization

 

Note that prior versions of SproutCore called apps "clients".  For backwards compatibility both the "app" and "client" template names should be supported.  If "clients" is used, the app should be placed in a "clients" directory instead of "apps".

 

If a target is specified on the command line, then the app should be generated inside the nested target.  For example:

 

sc-gen app TestRunner --target=sproutcore

 

would generate the app at project/frameworks/sproutcore/apps/test_runner

 

sc-gen framework FrameworkName --filename=framework_name 

 

Generates a new framework target for the project, similar to the app target.  This uses the exact same rules and structure as the app generator above except that the files will be placed in a "frameworks" directory instead of "apps".

 

sc-gen theme ThemeName --filename=theme_name

 

Generates a new theme in the themes directory.  This has the same structure as the app target except that it places its files in a "themes" directory instead of "apps".

 

sc-gen language [TargetName] Language --target=target/name

 

Adds a new language directory to the named target.  The target can be named using the --target option or by specifying the target namespace as the first option.  The target namespace can be CamelCase or snake_case and should be normalized.

 

The language can be specified using the long language name or a two/four letter code such as en, fr, de, etc.  If the language name includes ".lproj" at the end, ignore the .lproj. i.e.  sc-gen english + sc-gen english.lproj are treated the same way.

 

SproutCore can work with a few languages using either their long or short names.  If developer specifies the one of: english, french, german, italian, japanese, or spanish on the command line,  then the language name should be the capitalized form of the word (i.e. "English") and the directory name should be the lowercase form (i.e. "english.lproj".)   For all other languages, just use the language name and casing exactly as specified on the command line.  (i.e. en-US becomes en-US.lproj)

 

The default directory structure for this command is:

 

project/

  apps|frameworks|clients|themes/

    target_name/ 

      language_name.lproj/

        strings.js  <- contains default strings file

 

sc-gen model|view|controller AppName.ClassName --filename=FILENAME --target=TARGET_NAME

 

These three generators create templates for common types of classes.  If the filename and target is not specified on the command line explicitly, they should map using the AppName.ClassName using the following rules:

 

GENERATOR CLASS NAME TARGET NAME FILE NAME CLASS NAME
model  Contacts.Contact  contacts  models/contact.js  Contacts.Contact 
  contacts/contact contacts  models/contact.js  Contacts.Contact 
controller  Contacts.detailController  contacts  controllers/detail.js  Contacts.detailController 
  contacts/detail  contacts  controllers/detail.js  Contacts.detailController
view Contacts.AddressView contacts views/address.js Contacts.AddressView
  contacts/address contacts views/address.js Contacts.AddressView

 

The generator should add both the raw class file plus a test file.  For models, a fixture file should be added also:

 

projects/

  apps|frameworks|clients|themes/

    target_name/

      models|controllers|views/

        class_name.js <-- new class

      fixtures/

         class_name.js <-- only for models

      tests/

        models|controllers|views/

          class_name.js <-- default test.

 

sc-gen test AppName.ClassName[.methodName] --target=target_name --filename=file_name

 

Adds a new unit test file.  You can either specify the any AppName/ClassName combination or specify a specific method name you want to test.  If you specify a method name, then a unit test file should be added in a nested directory for the class name.  If the class name ends in 'View' or 'Controllers' place in a views or controllers directory. See the example below:

 

projects/

  apps|frameworks|clients|themes/

    target_name/

      tests/

         models|controllers|view/

           class_name.js <-- if no method name is added

           class_name/

             methodName.js <-- if method name is provided

 

 

Comments (0)

You don't have permission to comment on this page.