jhb563 / oneweekapps

One Week Apps

About OWA

One Week Apps is a template language for mobile development. The goal is to generate large amounts of tedious boilerplate code with clean and easy description of particular elements of a mobile application.

Website

Check it out!

Documentation

More detailed information can be found here.

How does it work?

• To generate code using OWA, you must first have a directory called “app”, and run the OWA executable from within or above this directory.
• OWA will then search the directory for files with specific extensions, such as .colors, .font, or .view files.
• Depending on the extension, OWA will parse the file as a particular kind of element or collection of elements, and generate Objective C code in the app directory corresponding to those elements.
• You can then add the generated code into an XCode project to use it.

Running the Program

1. To run the program, first install GHC Platform and Haskell Stack
2. In the project directory, you should be able to run stack build
3. The executable should be created in .stack-work/dist/x86_64-osx/Cabal-1.24.0.0/build/OneWeekApps
4. It can be run from within the project directory by running stack exec OneWeekApps
5. Moving the executable onto your path will enable you to run stack exec OneWeekApps from anywhere.
6. Run tests with stack test

Features

You can generate code for categories for certain elements which are reusable throughout your app. These include colors, font, alerts, and errors. You can also create multiple files containing localized strings to be compiled into a single Localizable.strings file.

The largest and most important feature is being able to generate code for your own UIView subclasses. You can specify elements within the view and use OWA’s easy layout syntax to generate Autolayout code for Objective C. Basic elements which are currently supported within views include Labels, Buttons, TextFields, ImageViews. You can also make your own custom views subviews of each other, place elements within vanilla UIViews, and embed elements within UIScrollViews.

Version 0.3.0 also introduced code generation for models files. See owa-parse/tests for details on the input format.

OWA also requires that you create a file called “app.info” containing some basic information about your app such as its name, your name as author, the app prefix, and so on. Since version 0.2.3, this file (and a sample XCode project) is created when you run the owa new command.

Examples

To create a category for generic colors to use throughout your app, you can create a file called myapp.colors, containing the following text:

Color labelColor
	Red 10
	Green 10
	Blue 10

Color errorColor
	Red 123
	Green 15
	Blue 15

OWA will create files called UIColor+XXXColors.h, and UIColor+XXXColors.m, where XXX is the app prefix specified in app.info. These files will implement a category on UIColor exposing these generic colors:

@interface UIColor (XXXColors)

- (UIColor*)labelColor;
- (UIColor*)errorColor;

@end

And the .m file would handle implementing these using [UIColor colorWithRed:green:blue:alpha]

See the tests folder for more examples.

Support for Swift

Since version 0.2.3, all features have been supported for Swift as well as Objective C. Note that running the owa new command will generate separate XCode projects, one for Objective C and one for Swift.

Future Goals

For the next release (0.3.1), the main goals are adding code generation for View Controllers and Coordinators, which allow navigation. Once this is done, it should be possibly to create a fully fledged app.

Longer term goals include generating code for more service oriented tasks like network requests. At some point, we will hopefully look at expanding to android code generation.

Bug Fixes and Feature Requests

If you spot a bug, create an issue for it and be sure to add the “Bug” label. If you have an idea for a feature, you can create an issue for that as well, just use the “Feature Request” label. Depending on the request it may get tracked into the current version. Of course if you implement the feature yourself and submit a Pull Request, this is much more likely!

Collaborating

If you are interested in helping out by fixing bugs or adding features, please do! You do not need to be a Haskell wizard to help out! See the collaborating guide for more details. If you fix a bug, be sure to add a log of it to the bug_fixes file for the current version.

oneweekapps's Issues

Change Location of Generated Swift Code

Swift code should now be generated in /swift/AppName/ rather than the current system of /ios/AppName/.

Blocked on #139

Swift Printing Implementation (Fonts)

1. If necessary, add to Swift abstract syntax to allow necessary syntactic structures for creating a UIFont category.
2. Create a class OWAFontSwiftConverter to return a Swift file structure from a list of OWAFonts (and the AppInfo).
3. If necessary, add appropriate code in SwiftPrint module to print any new syntactic structures added.
4. Write tests comparing results of your code to tests written for #68 and resolve any inconsistencies.

Implement Model Parsing

Hook in tests from #131 and #132. Define Model parser so that we can parse the model files in to these tests.

Swift Printing Implementation (Views)

1. If necessary, add to Swift abstract syntax to allow necessary syntactic structures for creating a UIView file.
2. Create a class OWAViewSwiftConverter to return a Swift file structure from a OWAView (and the AppInfo).
3. If necessary, add appropriate code in SwiftPrint module to print any new syntactic structures added.
4. Write tests comparing results of your code to tests written for #71 and #72 and resolve any inconsistencies.

Insufficient Type Information on Placeholders

When generating lazy getters for Text Field views, we see the following compile issues on the placeholder attribute dictionaries:

Type of Expression is Ambiguous Without More Context

We should add more type information to the placeholder dictionary to solve this.

Swift Printing Implementation (Colors)

1. If necessary, add to Swift abstract syntax to allow necessary syntactic structures for creating a UIColor extension.
2. Create a class OWAColorSwiftConverter to return a Swift file structure from a list of OWAColors (and the AppInfo).
3. If necessary, add appropriate code in SwiftPrint module to print any new syntactic structures added.
4. Write tests comparing results of your code to tests written for #67 and resolve any inconsistencies.

Refactor Imports

Currently, all imports are listed alphabetically. I think however, that a better practice would be to separate imports from elsewhere in OWA from Library imports (e.g. Parsec), to make it more clear which imported modules can be found within the repo and which need to be looked up online.

Refactor Tests

Now that the project is refactored, we ought to refactor the tests to match up with the modules.

1. Tests related to parsing should be moved to owa-parse.
2. Tests related to Objc objects and printing should be moved to owa-objc
3. Tests related to Swift objects and printing should be moved to owa-swift.
4. Remaining tests in owa-core should be consolidated into a single test suite, with Integration tests as one sub-section.
5. Common testing code (and test objects) should be moved to owa-utils.
6. Use hpack format for owa-core.

A single test suite per module should suffice for 1-3.

Implement owa new Command (App Info CLI)

Implement the owa new command so that, it prompts the user to enter each field of the app info, and then create the app directory, along with the app.info file itself. Indicate that the required fields are required, and do not permit null entries. However, do not prompt them for date created. Simply use the current date.

Write code verifying that with particular user input streams, the app.info file and OWAAppInfo object created matches our expectations.

Define Expected Swift Model Files

Copy owa-parse/test/Parse/Tests/Models/Objects.hs to owa-swift/test/Swift/Tests/Models/Objects.hs. For each of these objects, define the expected Swift file in owa-objc/test/Objc/Tests/Models/OutputFiles/.

In addition, write the HSpec code for these test cases in owa-swift/test/Swift/Tests/Models/Basic.hs/. Do not hook in these tests yet.

Define API for parsing Model, write testing code.

Define a (stubbed) function parseModelFromFile :: File -> IO (Either [OWAParseError] OWAModel) in owa-parse/src/Parse/ModelParser.hs as our API. Then write owa-parse/test/Parse/Tests/Model/Basic.hs, which should have a case for each parse file, with the expectation that each file matches with the corresponding object.

Note the tests will fail, so don't actually hook them up to the test suite yet.

Block on #129

Swift Test Code (Errors)

Create Swift test files demonstrating expected output for a NSError extension. Ultimately when generating code, the app will generate a single .swift file containing an extension of the NSError class, with type methods corresponding to each of the different errors. Choose certain existing error test objects as the source (see Version 0.1.0 or 0.1.5 tests).

Modularize Project

OneWeekApps.cabal is becoming rather large and unwieldy. Once all features for this version are done, we should refactor the project into distinct modules, each with their own .cabal file. This list may evolve going forward, but for now I image the different modules being:

owa-util (Utilities such as OWAPrintUtil, OWAParseUtil)
owa-swift (Swift converters, data types, and printers)
owa-objc (Objc converters, data types, and printers)
owa-parse (All parsers)
owa-model (Data types, such as OWAColor, OWAAppInfo, etc.)
owa-core (Main running functions)

Again, I might change my mind on this, but for now the test-suites should remain attached to the core library, since this is already a pretty big task. We may, in the future, decide it would be better to use the current version-oriented test suites just for integration tests, while moving feature oriented tests into unit test suites.

Let's hold off on this until integration tests for 0.2.3 are done, so I'm calling this blocked on #83.

.pbxproj instead of .pbxproject

When making a new project, we call one of the files project.pbxproject. This needs to be project.pbxproj instead.

Swift Test Code (Fonts)

Create Swift test files demonstrating expected output for a UIFont extension. Ultimately when generating code, the app will generate a single .swift file containing an extension of the UIFont class, with type methods corresponding to each of the different fonts. Choose certain existing font test objects as the source (see Version 0.1.0 or 0.1.5 tests).

Swift Code Integration and Option

The owa gen command should accept a new option --swift. When run with the swift option, Swift code should be generated instead of Objective C code. When run without this option, Objective C code should be generated.

In order to do this, OWALib.hs will need to be refactored to hook into the Swift generation and printing methods resulting from the appropriate tickets (Issues 73-77).

Note there should be no change in behavior for generating the Localizable.string file. While we call the module OWAStringsObjc, the generated code works perfectly well with Swift code as well.

Additionally, regarding #66, we should track both the latest code generation time for Objective C and Swift. When the user requests Swift code be generated, the generation should happen, even if the relevant files have not been updated since the last Objective C code generation, and vice versa.

Swift Test Code (Colors)

Create Swift test files demonstrating expected output for a UIColor extension. Should resemble the existing Objective C files in structure. Choose certain existing color test objects as the source (see Version 0.1.0 or 0.1.5 tests).

Lazy Code Generation

We should not regenerate code for OWA files which have not changed since the last run of owa gen.

For instance, if no .colors files have been updated since the last run, we need not go through the trouble of parsing them or regenerating code for UIColor+XXXColors.h/m. However, if a single .colors file has been updated since the last run, then the Objective C file will need to be regenerated.

Likewise, if a .view file has not been updated since the last run, it should not be re-parsed, and its corresponding .h and .m files should not be regenerated.

Code Type Arguments for Generate

The owa generate command should only generate certain types of code based on the arguments. There are 6 type arguments:

1. --colors
2. --fonts
3. --alerts
4. --errors
5. --strings
6. --views

If none of these arguments are given, then all different types of code should be generated (identical to current functionality). If any of these arguments are given, then only the code corresponding to the arguments should be generated.

E.g.

On owa gen --colors, only code for .colors files should be generated.

On owa gen --fonts --alerts, code for .fonts and .alerts files should be generated.

Create error test cases for Model types

Just as we have error tests on the other different elements in our system (Colors, Fonts, etc.), we should add some sanity tests around parse failures for the new model objects. We should add the errors files in owa-parse/test/Parse/Tests/Models/ParseFiles and create error objects for those parse failures in a Haskell file owa-parse/test/Parse/Tests/Models/Errors.hs.

Color Documentation and Error Handling

The specified format for how to input colors should be documented better in the HSpec tests and in wiki/web form.

There should also be documentation and additional specs to test error cases when parsing colors.

Implement Swift Printing

Hook in tests from #134. Define any Swift abstract syntax and Swift printing code needed in order to successfully print Swift code to files.

Model File Search

Implement the file search functionality for finding "models" files, just as we find "colors" files and "fonts" etc. Add tests around it. Instead of using the awkward "testenv" setup and teardown functionality of the other file search tests, feel free to actually create the files to search for with the test folder and commit them.

Change location of generated Objective C code

Objective C code should now be generated in a directory like /objc/AppName, instead of the current system where it is /ios/AppName.

Typeclass for Element Name and Type

Each element (Label, Button, etc.) has its own record name for accessing its name and type, so we have to have the methods nameForElement and typeNameForElement. We should instead have a typeclass which provides this interface, as it is more idiomatic and extensible, should we add other common features among elements.

Swift Test Code (View Constraints)

Create Swift test files demonstrating expected output for views, specifically with code related to constraints (setupConstraints method). Should resemble the existing Objective C files in structure. Choose certain existing view test objects as the source (see Version 0.2.0 or 0.2.1 tests). Should cover all major constraint cases (above, below, toRight, etc.), and should cover all orientations of scroll views.

This ticket does NOT need to cover code generated with respect to view properties (text, color, etc.). The sub elements can be as simple as they need to be.

Unwrap Label for buttons.

In any situation (with Swift) where a lazy getter for a UIButton sets something on its title label, we need to forcibly unwrap the title label with !.

In addition, when our extension fonts are unwrapped (say by being used in a text field placeholder), they should be unwrapped.

Swift Printing Implementation (Alerts)

1. If necessary, add to Swift abstract syntax to allow necessary syntactic structures for creating a UIAlertController category.
2. Create a class OWAAlertSwiftConverter to return a Swift file structure from a list of OWAAlerts (and the AppInfo).
3. If necessary, add appropriate code in SwiftPrint module to print any new syntactic structures added.
4. Write tests comparing results of your code to tests written for #69 and resolve any inconsistencies.

Language Option for New

Now that Objective C and Swift generate code in their own directories, the new script should generate the proper directories for each of these different languages.

Test Code for Blank XCode Project

Create test code for what a blank XCode project and supporting files should look like, given particular App Info like App Name, Prefix, author, etc.

Update Executable Name and Basic Behavior

1. The executable generated by stack should be named owa, instead of OneWeekApps
2. The executable should have two sub-commands.

owa gen or owa generate should should have exactly the same behavior as the current OneWeekApps executable, including with the -v(erbose) and -s(ilent) options.

owa new should NOT generate new files, but rather have some basic behavior, such as printing out "Creating new OWA project!"

Any other command should generate a usage error:

owa should give the error "owa: No command entered!"
owa foo should give the error "owa: Unrecognized command "foo""

Define Hspec code for Model Error Tests

Write Hspec cases for the error parse files and errors defined in the Parse tests. Do not hook them in, as they should fail.

Blocked on #128 and #131

Change Location of Generated Code

Instead of being generated in the app directory, generated files should go to the proper code directory for the generated XCode project. Integration tests for previous versions will need to be changed to reflect this.

Depends on #81

Swift Test Code (View Elements)

Create Swift test files demonstrating expected output for views, specifically with code related to sub-elements (lazy getters and property definitions). Should resemble the existing Objective C files in structure. Choose certain existing view test objects as the source (see Version 0.2.0 or 0.2.1 tests). Should cover all subelements (Labels, Button, Textfields, ImageViews, ScrollViews, container views, embedded custom views), and all properties assigned in lazy getters (text, color, placeholders, etc.)

This ticket does NOT need to cover any code generated with respect to constraints (setupConstraints method). The test views should not have any constraints on them.

Create Haskell definition of Model Model and write test Model objects.

In owa-model/src/Model/ create a new Haskell file defining our type for Models. Then in owa-parse/test/Parse/Tests/Models/Objects.hs define the corresponding model object for each parse test.

Swift Printing Implementation (Custom Views, Container Views, Scroll Views)

1. If necessary, add to Swift abstract syntax to allow necessary syntactic structures for letting views contain subviews which are either custom, container, or scroll views.
2. If necessary, add appropriate code in SwiftPrint module to print any new syntactic structures added.
   Write tests comparing results of your code to tests written for #96 and resolve any inconsistencies.

Swift Test Code (Alerts)

Create Swift test files demonstrating expected output for a UIAlertController extension. Ultimately when generating code, the app will generate a single .swift file containing an extension of the UIAlertController class, with type methods corresponding to each of the different alerts. Choose certain existing alert test objects as the source (see Version 0.1.0 or 0.1.5 tests).

Style and Coverage of Lazy Code Gen Tests

First, the tests surrounding Lazy Code Generation are not stylistically very good. It would be better to incorporate the calls to owa generate into HSpec methods, rather than computing all the results before hand.

Second, there are a couple cases missing. For category files which draw from potentially numerous input files, we should test that code is regenerated after modifications to at least 2 source files separately.

Integration Testing on Models

Define Integration tests in owa-core/test/Core/Tests/Integration/Version030 focused specifically on model files. Use examples from the other modules. Hook these tests in, and modify core code so that they files are printed on calls to owa gen.

Blocked on #136 and #137.

List Other Modules in .cabal file.

Fix the warning which occurs when building and testing about non-public modules not being list in the other-modules section of the .cabal file.

Create Examples for Model Files to Parse

We want some example model files that will demonstrate all the different functionality we want to encompass. Broadly speaking, we want types that can have the following fields:

• Integers
• Floats/Doubles
• Strings
• Custom Types (ie use another model type you've defined)
• Optional types of any of the preceding
• Arrays of any type
• Maps/Dictionaries from strings to any type

We should add these sample files as potential tests in owa-parse/test/Parse/Tests/Models/ParseFiles.

Implement owa new Command (XCode project)

Implement the owa new command so that, after the user enters App Info, it creates a directory with a fresh XCode project based on the App Info, with all necessary supporting files.

Write testing code matching output against test code from #78, resolving any inconsistencies.

Requires #80.

Make Equivalent Functionality for Objective C app delegate generation.

Currently, the App Delegate is a Swift file always. Write additional code in owa-objc/src/Objc/XCode.hs that will make an App Delegate Objective C file.

Define Objective C code for Model Cases

Copy owa-parse/test/Parse/Tests/Models/Objects.hs to owa-objc/test/Objc/Tests/Models/Objects.hs. For each of these objects, define the expected Objective C header and implementation file in owa-objc/test/Objc/Tests/Models/OutputFiles/.

In addition, write the HSpec code for these test cases in owa-objc/test/Objc/Tests/Models/Basic.hs/. Do not hook in these tests yet.

Swift Printing Implementation (Errors)

1. If necessary, add to Swift abstract syntax to allow necessary syntactic structures for creating a NSError category.
2. Create a class OWAErrorSwiftConverter to return a Swift file structure from a list of OWAErrors (and the AppInfo).
3. If necessary, add appropriate code in SwiftPrint module to print any new syntactic structures added.
4. Write tests comparing results of your code to tests written for #70 and resolve any inconsistencies.

Deal with spaces within definitions

Most definitions will probably fail if you put a space between lines. Perhaps augment the indentedComment parser with a blank line parser and see if that helps.

Implement Model Objective C

Hook in tests from #133. Define Objective C abstract syntax as needed and printing code as needed in order to fully define printing for these files so that the tests pass.

No spaces in Project Name

It causes a parse error in the .pbxproj file to have a project name with spaces. For now let's disallow spaces in the Project name.

Version 0.2.3 Integration Tests

Write integration tests on end-to-end functionality for all features in Version 0.2.3.

Swift Test Code (Custom Views, Container Views, Scroll Views)

Create Swift test files demonstrating expected output for views, specifically with code related to custom views, container views, and scroll views. Should resemble the existing Objective C files in structure. Choose certain existing view test objects as the source (see Version 0.2.0 or 0.2.1 tests). Should cover all orientations of scroll views, and cases of nested custom and container views.