Nayyar / နေရာ

Nayyar is created with the intent of providing basic access to State/Regions, Districts or Townships of Myanmar, based on standards of Myanmar's country-wide census of 2014.

15 States are indexed by MIMU's pcode, ISO3166-2:MM and alpha3 codes used in plate numbers by transportation authority. 74 Districts and 413 Townships are indexed by MIMU's pcode.

The current version is and it uses Semantic Versioning

Installation

Add this line to your application's Gemfile:

gem 'nayyar'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nayyar

Usage

States

Find all states using

Nayyar::State.all

Find states using MIMU's pcodes:

Nayyar::State.find_by_pcode("MMR013")
# => <Nayyar::State:0x007fd05cc79e60 @data={:iso=>"MM-06", :pcode=>"MMR013", :alpha3=>"YGN", :name=>"Yangon"}>

Find states using ISO3166-2:MM:

Nayyar::State.find_by_iso("MM-01")
# => #<Nayyar::State:0x007fd05cc7a040 @data={:iso=>"MM-01", :pcode=>"MMR005", :alpha3=>"SGG", :name=>"Sagaing"}>

Find states using alpha3

Nayyar::State.find_by_alpha3("SHN")
# => #<Nayyar::State:0x007fd05cc79e38     @data={:iso=>"MM-17", :pcode=>"MMR222", :alpha3=>"SHN", :name=>"Shan"}>

Or you can use a generic finder with an index

Nayyar::State.find_by(pcode: "MMR013") #or iso: or alpha3:

Use any of the find_by or find_by_**index_name** with a bang ! to trigger Nayyar::StateNotFound error.

Districts

Find all districts using

Nayyar::District.all

Find districts under a certain state using

shan_state = Nayyar::State.find_by_alpha3("SHN")
# get an array of all districts under Shan state using
shan_state.districts
# or
Nayyar::District.of_state(shan_state)

Find a district using pcode

Nayyar::District.find_by_pcode("MMR001D001")
# or
Nayyar::District.find_by(pcode:"MMR001D001")

# => #<Nayyar::District:0x007f9bf5361418 @data={:pcode=>"MMR001D001", :name=>"Myitkyina", :state=>"MMR001"}>

Find the state that a district belongs to using

Nayyar::District.find_by(pcode:"MMR001D001").state

# => <Nayyar::State:0x007f9bf532fc60 @data={:iso=>"MM-11", :pcode=>"MMR001", :alpha3=>"KCN", :name=>"Kachin"}>

Use any of the find_by or find_by_**index_name** with a bang ! to trigger Nayyar::DistrictNotFound error.

Townships

Find all townships using

Nayyar::Townships.all

Find townships under a certain state using

ygn_east = Nayyar::District.find_by_pcode "MMR013D002"
# get an array of all districts under Shan state using
ygn_east.townships
# or
Nayyar::Township.of_district(ygn_east)

Find a township using pcode

Nayyar::Township.find_by_pcode("MMR013017")
# or
Nayyar::Township.find_by(pcode:"MMR013017")

# => #<Nayyar::Township:0x007fb8a5b605e8 @data={:pcode=>"MMR013017", :name=>"Botahtaung", :district=>"MMR013D002"}>

Find the district that a township belongs to using

Nayyar::Township.find_by(pcode:"MMR013017").district

# => <Nayyar::District:0x007fb8a5ad14d8 @data={:pcode=>"MMR013D002", :name=>"Yangon (East)", :state=>"MMR013"}>

Use any of the find_by or find_by_**index_name** with a bang ! to trigger Nayyar::TownshipNotFound error.

Goals

Make it work

Create just enough API to allow creations of dropdowns/multiple-select options in HTML ✓

Make it right

Remove duplicate/similar codes across the three main classes using metaprogramming

Make it fast

Optimize memory footprint by refactoring the way data is stored/read/used

If you feel that I have missed out your use-case or if you wanna add other goals, objectives submit an issue so that I can plan it in.

Contributing

Fork it ( https://github.com/mmhan/nayyar/fork )
Create your feature branch (git checkout -b feature/my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin feature/my-new-feature)
Create a new Pull Request

Documentation

Since, this is a pretty small library, a documentation hasn't been created yet. Nonetheless, here's the rspec output with documentation format.

Nayyar
  has a version number

Nayyar::State
  class methods
    .all
      should be a kind of Array
      contains hashes of state data
    .find_by
      returns state when it finds it
      will return nil if state is not found
      will raise ArgumentError if no argument is provided
      will raise ArgumentError if wrong argument is provided
    .find_by!
      should be a kind of Nayyar::State
      will raise error if the state isn't found
    .find_by_**indices**
      returns state when it finds it
      returns nil when it can't be found
    .find_by_**indices**!
      returns state when it finds it
      raise error when it can't be found
  #initialize
    allows to create a state by providing hash data
  attributes
    allows its attributes to be accessed by methods
    allows its attributes to be accessed as keys
  #districts
    return a list of districts under given state

Nayyar::District
  class methods
    .all
      should return all districts
    .of_state
      return a list of districts under given state
    .find_by
      should be a kind of Nayyar::District
      returns nil if it's not found
    .find_by!
      should be a kind of Nayyar::District
      raise error if it's not found
    .find_by_**indices**
      returns state when it finds it
      returns nil when it can't be found
    .find_by_**indices**!
      returns state when it finds it
      raise error when it can't be found
  #initialize
    allows to create a district by providing hash data
  attributes
    allows its attributes to be accessed by methods
    allows its attributes to be accessed as keys
  #state
    should be a kind of Nayyar::State
    expect it to be a correct state
  .townships
    return a list of districts under given district

Nayyar::Township
  class methods
    .all
      should return all township
    .of_district
      return a list of districts under given district
    .find_by
      should be a kind of Nayyar::Township
      returns nil if it's not found
    .find_by!
      should be a kind of Nayyar::Township
      raise error if it's not found
    .find_by_**indices**
      returns state when it finds it
      returns nil when it can't be found
    .find_by_**indices**!
      returns state when it finds it
      raise error when it can't be found
  #initialize
    allows to create a township by providing hash data
  attributes
    allows its attributes to be accessed by methods
    allows its attributes to be accessed as keys
  #district
    should be a kind of Nayyar::District
    expect it to be a correct state

Finished in 0.1254 seconds (files took 0.1826 seconds to load)
48 examples, 0 failures

phyuphyuei/nayyar